{
  "name": "bilt-toolkit",
  "binary": "bilt",
  "version": "1.1.0",
  "description": "Deterministic production-readiness gate for software built with AI coding agents.",
  "license": "MIT",
  "repository": "https://github.com/Samuel-0228/Bilt",
  "homepage": "https://bilt.nogs.dev",
  "documentation": "https://bilt.nogs.dev/docs",
  "llms": "https://bilt.nogs.dev/llms.txt",
  "llmsFull": "https://bilt.nogs.dev/llms-full.txt",
  "packageStructure": {
    "packageName": "bilt-toolkit",
    "cliBinary": "bilt",
    "aliasBinary": "npx bilt",
    "coreModules": {
      "astEngine": "Babel AST parser and traversal engine analyzing syntax trees, call expressions, database persistence sinks, and route handler parameters",
      "entropyScanner": "Shannon-entropy analysis (threshold H > 4.5 bits/char) with 31+ cryptographic token provider signatures",
      "flowTracer": "Control-flow and data-flow tracer mapping route parameters (req.body, req.query, req.params) to database queries without allowed-field boundaries",
      "snapshotEngine": "Sub-2ms atomic state capture engine storing disk rollbacks in .bilt/snapshots/",
      "agentProtocol": "Strict JSON Schema v1 engine outputting deterministic machine contracts (--format agent)",
      "mcpServer": "Native Model Context Protocol implementation over stdio for Claude Desktop, Cursor, and Windsurf"
    },
    "stateAndConfigFiles": {
      "config": ".biltrc.json",
      "agentInstructions": "AGENTS.md",
      "cursorInstructions": ".cursorrules",
      "windsurfInstructions": ".windsurfrules",
      "baseline": ".bilt/baseline.json",
      "riskAcceptance": ".bilt/risk-acceptance.json",
      "loopState": ".bilt/loop-state.json",
      "snapshots": ".bilt/snapshots/"
    }
  },
  "exitCodes": {
    "0": {
      "status": "pass",
      "meaning": "All clear or non-blocking informational items. Verification passed.",
      "agentAction": "Proceed to commit, push, or merge PR."
    },
    "1": {
      "status": "fail",
      "meaning": "Hard security violation, mandatory invariant failed, or config file tampering.",
      "agentAction": "Review findings, inspect finding.agent_action, apply targeted code fix, and re-verify."
    },
    "2": {
      "status": "needs_review",
      "meaning": "Medium-precision heuristic requiring human review (e.g. IDOR, backup verification).",
      "agentAction": "Flag finding to developer. Non-blocking in standard CI unless --strict is enabled."
    },
    "3": {
      "status": "error",
      "meaning": "Tool execution failure, invalid CLI flags, missing files, or parse failure.",
      "agentAction": "Correct command syntax or fix AST syntax errors in codebase."
    },
    "4": {
      "status": "escalate",
      "meaning": "Runaway loop detected (max iterations reached without progress) or anti-tamper violation.",
      "agentAction": "Halt automated retries immediately. Explain situation and blockers to human maintainer."
    }
  },
  "commands": [
    {
      "command": "bilt check [dir]",
      "category": "Gate",
      "purpose": "Evaluates repository against 14-category production readiness taxonomy.",
      "flags": ["--format <text|json|sarif|agent|markdown>", "--changed", "--base <ref>", "--categories <list>", "--strict", "--timeout <ms>"],
      "exitCodes": [0, 1, 2, 3],
      "example": "bilt check --format agent"
    },
    {
      "command": "bilt verify [dir]",
      "category": "Gate",
      "purpose": "Strict diff verification against git base branch with anti-tamper and loop budget.",
      "flags": ["--base <ref>", "--format <format>", "--max-iterations <n>", "--snippets"],
      "exitCodes": [0, 1, 2, 3, 4],
      "example": "bilt verify --base origin/main"
    },
    {
      "command": "bilt scan [dir]",
      "category": "Static Scan",
      "purpose": "Audits source code for secrets, environment variable divergence, and Shannon entropy leaks.",
      "flags": ["--full-history", "--format <format>", "--severity <level>", "--changed"],
      "exitCodes": [0, 1, 2],
      "example": "bilt scan ."
    },
    {
      "command": "bilt api-scan [dir]",
      "category": "Static Scan",
      "purpose": "Static API checks: mass assignment, wildcard HTTP methods, missing tenant boundaries.",
      "flags": ["--json", "--severity <level>", "--verbose", "--quiet"],
      "exitCodes": [0, 1, 2],
      "example": "bilt api-scan src/api"
    },
    {
      "command": "bilt design-check [dir]",
      "category": "Design & UX",
      "purpose": "Audits UI for generic AI patterns, authenticity, UX completeness, and accessibility.",
      "flags": ["--format <format>", "--changed", "--severity <level>"],
      "exitCodes": [0, 1, 2, 4],
      "example": "bilt design-check src/components"
    },
    {
      "command": "bilt fix [dir]",
      "category": "Remediation",
      "purpose": "Applies safe automated repairs and saves atomic snapshots for sub-2ms rollback.",
      "flags": ["--safe", "--dry-run", "--verbose", "--quiet"],
      "exitCodes": [0, 2],
      "example": "bilt fix --safe"
    },
    {
      "command": "bilt undo [dir]",
      "category": "Remediation",
      "purpose": "Instant atomic rollback of the previous fix from .bilt/snapshots/ in sub-2ms.",
      "flags": ["--list"],
      "exitCodes": [0, 2],
      "example": "bilt undo"
    },
    {
      "command": "bilt watch [dir]",
      "category": "Daemon",
      "purpose": "Real-time background file monitor daemon (alias: bilt live).",
      "flags": ["--debounce <ms>", "--poll", "--quiet", "--no-live"],
      "exitCodes": [0, 2],
      "example": "bilt watch"
    },
    {
      "command": "bilt baseline create",
      "category": "Baseline",
      "purpose": "Captures existing technical debt into .bilt/baseline.json so only new issues fail CI.",
      "flags": ["--json"],
      "exitCodes": [0, 2],
      "example": "bilt baseline create"
    },
    {
      "command": "bilt mcp",
      "category": "Protocol",
      "purpose": "Starts Model Context Protocol server for Claude Desktop, Cursor, and Windsurf.",
      "flags": [],
      "exitCodes": [0, 3],
      "example": "npx -y bilt-toolkit mcp"
    },
    {
      "command": "bilt prompt",
      "category": "Agent Setup",
      "purpose": "Prints standardized system instructions for AI coding agents.",
      "flags": ["--agent <claude|cursor|windsurf|default>"],
      "exitCodes": [0, 2],
      "example": "bilt prompt --agent cursor"
    },
    {
      "command": "bilt init [dir]",
      "category": "Scaffolding",
      "purpose": "Scaffolds .biltrc.json, .env.example, and AGENTS.md in the target project.",
      "flags": ["--agent", "--dry-run", "--force"],
      "exitCodes": [0, 2],
      "example": "bilt init"
    },
    {
      "command": "bilt accept-risk <finding-id>",
      "category": "Governance",
      "purpose": "Formally accepts risk for non-mandatory items into .bilt/risk-acceptance.json.",
      "flags": ["--reason <text>", "--owner <email>", "--expires <yyyy-mm-dd>"],
      "exitCodes": [0, 2],
      "example": "bilt accept-risk finding-8392 --reason \"Legacy webhook\" --owner \"dev@example.com\""
    },
    {
      "command": "bilt explain [category]",
      "category": "Education",
      "purpose": "Outputs educational concepts, inspection rules, and guided procedures.",
      "flags": [],
      "exitCodes": [0, 2],
      "example": "bilt explain auth"
    },
    {
      "command": "bilt doctor [dir]",
      "category": "Diagnostics",
      "purpose": "Holistic repository health diagnostics and OWASP Top 10 compliance map.",
      "flags": ["--card", "--owasp", "--fun", "--debug"],
      "exitCodes": [0, 2],
      "example": "bilt doctor"
    },
    {
      "command": "bilt report [dir]",
      "category": "Reporting",
      "purpose": "Exports structured health reports to file or stdout.",
      "flags": ["--format <markdown|json>", "--output <path>", "--stdout"],
      "exitCodes": [0, 2],
      "example": "bilt report --format markdown --output ./readiness-report.md"
    },
    {
      "command": "bilt plugin <action>",
      "category": "Plugins",
      "purpose": "Manages custom AST rules (list, create, install).",
      "flags": ["<action>", "[name]", "--dir <path>"],
      "exitCodes": [0, 2],
      "example": "bilt plugin list"
    },
    {
      "command": "bilt welcome",
      "category": "Onboarding",
      "purpose": "Interactive terminal onboarding walkthrough (aliases: bilt guide, bilt onboarding).",
      "flags": [],
      "exitCodes": [0, 2],
      "example": "bilt welcome"
    },
    {
      "command": "bilt ai & bilt ask",
      "category": "AI Explainer",
      "purpose": "Privacy-first AI explainer with universal token redaction.",
      "flags": ["setup", "status", "switch", "model", "last-request"],
      "exitCodes": [0, 2],
      "example": "bilt ask \"Explain the IDOR risk in routes/users.ts\""
    }
  ],
  "nodeSdk": {
    "exports": [
      {
        "name": "checkReadiness",
        "signature": "checkReadiness(options: CheckOptions): Promise<ReadinessResult>",
        "options": {
          "targetDirectory": "string (optional, default: process.cwd())",
          "format": "'text' | 'json' | 'sarif' | 'agent' | 'markdown'",
          "changed": "boolean (scope to git changes)",
          "base": "string (git base ref e.g. origin/main)",
          "categories": "string[] (subset of 14 categories)",
          "strict": "boolean (treat needs_review as failure)"
        }
      },
      {
        "name": "verifyDiff",
        "signature": "verifyDiff(options: VerifyOptions): Promise<VerifyResult>",
        "options": {
          "baseRef": "string (required, e.g. 'origin/main')",
          "maxIterations": "number (default: 5)",
          "snippets": "boolean",
          "format": "'agent' | 'json' | 'text'"
        }
      },
      {
        "name": "scanSecrets",
        "signature": "scanSecrets(options: ScanOptions): Promise<ScanResult>",
        "options": {
          "targetDirectory": "string",
          "fullHistory": "boolean",
          "severity": "'critical' | 'high' | 'medium' | 'low'"
        }
      },
      {
        "name": "runFix",
        "signature": "runFix(options: FixOptions): Promise<FixResult>",
        "options": {
          "safeOnly": "boolean",
          "dryRun": "boolean"
        }
      },
      {
        "name": "runUndo",
        "signature": "runUndo(options?: UndoOptions): Promise<UndoResult>",
        "options": {
          "snapshotId": "string (optional, defaults to most recent)"
        }
      }
    ]
  },
  "mcpTools": [
    {
      "name": "bilt_check",
      "description": "Run Bilt production readiness gate check against repository",
      "parameters": {
        "dir": { "type": "string", "description": "Target directory" },
        "changed": { "type": "boolean", "description": "Scope to changed files only" }
      }
    },
    {
      "name": "bilt_verify",
      "description": "Strict diff verification against git base branch with loop budget and anti-tamper",
      "parameters": {
        "baseRef": { "type": "string", "description": "Base git ref, e.g. origin/main" },
        "maxIterations": { "type": "number", "description": "Maximum loop retries" }
      }
    },
    {
      "name": "bilt_scan",
      "description": "Scan codebase for secret leaks, entropy anomalies, and env drift",
      "parameters": {
        "dir": { "type": "string", "description": "Target directory" }
      }
    },
    {
      "name": "bilt_fix",
      "description": "Apply safe automated remediations with atomic rollback snapshot",
      "parameters": {
        "safeOnly": { "type": "boolean", "description": "Only apply non-destructive fixes" },
        "dryRun": { "type": "boolean", "description": "Preview fixes without writing to disk" }
      }
    },
    {
      "name": "bilt_explain",
      "description": "Explain a specific readiness category or security rule",
      "parameters": {
        "category": { "type": "string", "description": "Taxonomy category name" }
      }
    }
  ],
  "taxonomy": {
    "mandatory": [
      {
        "id": "secrets-and-env",
        "name": "Secrets & Environment Security",
        "description": "Committed API keys, private keys, database connection strings, client bundle leaks, missing .env.example.",
        "riskAcceptanceAllowed": false
      },
      {
        "id": "auth",
        "name": "Authentication Integrity",
        "description": "Plaintext passwords, weak hashing (MD5/SHA1), unverified JWT decode, missing expiration, auth stubs.",
        "riskAcceptanceAllowed": false
      },
      {
        "id": "authorization",
        "name": "Authorization & Privilege Control",
        "description": "Client-controlled roles (req.body.isAdmin), missing tenancy scoping, privilege escalation vulnerabilities.",
        "riskAcceptanceAllowed": false
      },
      {
        "id": "input-validation",
        "name": "Input Validation & Injection Prevention",
        "description": "SQL injection, command execution, path traversal, unsafe HTML injection, missing body validators.",
        "riskAcceptanceAllowed": false
      },
      {
        "id": "api-abuse-and-cost",
        "name": "API Abuse & Cloud Cost Control",
        "description": "Unauthenticated endpoints invoking expensive LLM APIs (OpenAI, Anthropic), missing rate limiters.",
        "riskAcceptanceAllowed": false
      },
      {
        "id": "database",
        "name": "Database Security & Persistence",
        "description": "Direct client DB driver imports, unencrypted connections, missing automated backup plans.",
        "riskAcceptanceAllowed": false
      }
    ],
    "secondary": [
      { "id": "dependencies", "name": "Dependencies & Supply Chain", "riskAcceptanceAllowed": true },
      { "id": "error-handling-logs", "name": "Error Stacks & Credential Logging", "riskAcceptanceAllowed": true },
      { "id": "transport-and-headers", "name": "Transport & Security Headers", "riskAcceptanceAllowed": true },
      { "id": "deploy-config", "name": "Deployment & Container Config", "riskAcceptanceAllowed": true },
      { "id": "file-uploads", "name": "Unsafe File Uploads & Storage", "riskAcceptanceAllowed": true },
      { "id": "payments", "name": "Payments & Webhook Signatures", "riskAcceptanceAllowed": true },
      { "id": "privacy-and-pii", "name": "Privacy & PII Protection", "riskAcceptanceAllowed": true },
      { "id": "monitoring-rollback", "name": "Monitoring & Rollback Readiness", "riskAcceptanceAllowed": true }
    ]
  }
}