@agent-native/core 0.96.0 → 0.97.0

package/dist/cli/doctor.js

@@ -0,0 +1,277 @@
+/**
+ * `agent-native doctor` — scan an app's source tree for the security-
+ * critical code-safety invariants this monorepo already enforces on
+ * itself via `scripts/guard-*.mjs` (see
+ * `advisor-plans/reports/005-doctor-design.md` for the full design and
+ * `advisor-plans/015-doctor-v1-implementation.md` for the implementation
+ * plan). v1 ships 7 of those guards, ported to work against a single
+ * generated app root instead of this monorepo's multi-template layout —
+ * see `../guards/index.ts`.
+ *
+ * This is a NEW top-level command, deliberately kept separate from the two
+ * existing "doctor" precedents in this CLI:
+ *   - `agent-native upgrade check` (`upgrade.ts`) — dependency-pin health.
+ *   - `agent-native recap doctor` (`recap.ts`) — PR Visual Recap config health.
+ * Each diagnoses a different domain; none are folded into a shared
+ * mega-doctor (see report 005, "Relationship to upgrade doctor and recap
+ * doctor").
+ *
+ * `--fix` is reserved, not implemented in v1 — it prints a message and
+ * exits 2 rather than silently no-op, so a future implementation doesn't
+ * collide with a script already passing the flag.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { scanDbToolScoping, scanDrizzlePush, scanEnvCredentials, scanEnvMutation, scanLocalhostFallback, scanUnscopedCredentials, scanUnscopedQueries, } from "../guards/index.js";
+export const ALL_GUARD_NAMES = [
+    "no-drizzle-push",
+    "no-unscoped-credentials",
+    "no-unscoped-queries",
+    "no-env-credentials",
+    "db-tool-scoping",
+    "no-env-mutation",
+    "no-localhost-fallback",
+];
+const DEFAULT_DOCTOR_CONFIG = {
+    disabledGuards: [],
+    dbToolScopingDenylist: {},
+    failOnBuild: false,
+};
+/**
+ * Reads the optional `"doctor"` key from `<root>/agent-native.json`. All
+ * fields are optional with sane empty defaults — an app needs zero config
+ * to run `agent-native doctor` with every v1 guard enabled.
+ */
+export function readDoctorConfig(root) {
+    const manifestPath = path.join(root, "agent-native.json");
+    if (!fs.existsSync(manifestPath)) {
+        return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };
+    }
+    try {
+        const raw = fs.readFileSync(manifestPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const doctor = parsed.doctor ?? {};
+        const disabledGuards = Array.isArray(doctor.disabledGuards)
+            ? doctor.disabledGuards.filter((v) => typeof v === "string")
+            : [];
+        const dbToolScopingDenylist = doctor.dbToolScopingDenylist &&
+            typeof doctor.dbToolScopingDenylist === "object"
+            ? Object.fromEntries(Object.entries(doctor.dbToolScopingDenylist).filter((entry) => typeof entry[1] === "string"))
+            : {};
+        const failOnBuild = doctor.failOnBuild === true;
+        return { disabledGuards, dbToolScopingDenylist, failOnBuild };
+    }
+    catch {
+        return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };
+    }
+}
+function runGuard(name, root, config) {
+    switch (name) {
+        case "no-drizzle-push":
+            return scanDrizzlePush({ root });
+        case "no-unscoped-credentials":
+            return scanUnscopedCredentials({ root });
+        case "no-unscoped-queries":
+            return scanUnscopedQueries({ root, extraExemptPaths: [] });
+        case "no-env-credentials":
+            return scanEnvCredentials({ root });
+        case "db-tool-scoping":
+            return scanDbToolScoping({
+                root,
+                denylist: config.dbToolScopingDenylist,
+            });
+        case "no-env-mutation":
+            return scanEnvMutation({ root });
+        case "no-localhost-fallback":
+            return scanLocalhostFallback({ root, extraExemptPaths: [] });
+    }
+}
+/** Pure scan orchestrator: runs the selected guards against `root` and
+ * returns a flat report. No I/O beyond reading `agent-native.json` and the
+ * app source tree — no printing, no process.exit. */
+export function runDoctorScan(options) {
+    const root = options.root;
+    const config = readDoctorConfig(root);
+    let names;
+    if (options.only && options.only.length > 0) {
+        const knownOnly = options.only.filter((n) => ALL_GUARD_NAMES.includes(n));
+        names = knownOnly;
+    }
+    else {
+        names = ALL_GUARD_NAMES.filter((n) => !config.disabledGuards.includes(n));
+    }
+    const findings = [];
+    for (const name of names) {
+        const result = runGuard(name, root, config);
+        for (const f of result.findings) {
+            findings.push({
+                guard: name,
+                file: f.file,
+                line: f.line,
+                message: f.message,
+            });
+        }
+    }
+    return { ok: findings.length === 0, findings, guardsRun: names };
+}
+/** Pure escalation rule shared by the CLI (`--strict`) and the `build`
+ * pre-step (`--strict` / `agent-native.json` `doctor.failOnBuild`). Doctor
+ * findings never fail anything on their own — only `strict` or
+ * `failOnBuild` turn findings into a hard failure. */
+export function shouldFailBuild(hasFindings, opts) {
+    return hasFindings && Boolean(opts.strict || opts.failOnBuild);
+}
+const defaultIo = {
+    log: (message) => console.log(message),
+    err: (message) => console.error(message),
+};
+function formatDoctorHuman(report, root) {
+    const lines = [];
+    lines.push(`agent-native doctor: ${root}`);
+    lines.push(`Guards run: ${report.guardsRun.join(", ") || "(none)"}`);
+    if (report.findings.length === 0) {
+        lines.push("Clean — no findings.");
+    }
+    else {
+        lines.push(`${report.findings.length} finding(s):`);
+        for (const f of report.findings) {
+            lines.push(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function parseDoctorArgs(argv) {
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            opts.help = true;
+        }
+        else if (arg === "--json") {
+            opts.json = true;
+        }
+        else if (arg === "--strict") {
+            opts.strict = true;
+        }
+        else if (arg === "--fix") {
+            opts.fix = true;
+        }
+        else if (arg === "--cwd" && argv[i + 1] !== undefined) {
+            opts.cwd = argv[++i];
+        }
+        else if (arg.startsWith("--cwd=")) {
+            opts.cwd = arg.slice("--cwd=".length);
+        }
+        else if (arg === "--only" && argv[i + 1] !== undefined) {
+            opts.only = splitGuardList(argv[++i]);
+        }
+        else if (arg.startsWith("--only=")) {
+            opts.only = splitGuardList(arg.slice("--only=".length));
+        }
+    }
+    return opts;
+}
+function splitGuardList(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function printDoctorHelp(io = defaultIo) {
+    io.log([
+        "Usage:",
+        "  agent-native doctor                        Scan app source for security-critical guard violations",
+        "  agent-native doctor --json                 Machine-readable report: { ok, findings, guardsRun }",
+        "  agent-native doctor --only <guard,guard>   Run only the named guard(s)",
+        "  agent-native doctor --strict                Escalate findings to a hard failure when used by `agent-native build --strict`",
+        "  agent-native doctor --cwd <dir>             Run against a project root other than the current directory",
+        "  agent-native doctor --fix                   Not implemented in this version",
+        "  agent-native doctor --help                  Show this help",
+        "",
+        `Guards: ${ALL_GUARD_NAMES.join(", ")}`,
+        "",
+        "Exit codes: 0 clean, 1 findings present, 2 usage/execution error.",
+        "",
+        "`agent-native build` runs doctor as a warn-only pre-step by default — it",
+        "never fails the build unless `agent-native build --strict` is passed or",
+        'agent-native.json sets { "doctor": { "failOnBuild": true } }.',
+        "",
+        "For dependency-pin health (framework overrides/patches, stale",
+        "@agent-native/* pins), run `agent-native upgrade check` instead.",
+    ].join("\n"));
+}
+/** `agent-native doctor` CLI entrypoint. Returns the process exit code —
+ * callers are responsible for calling `process.exit(code)`. */
+export async function runDoctor(argv, io = defaultIo) {
+    const opts = parseDoctorArgs(argv);
+    if (opts.help) {
+        printDoctorHelp(io);
+        return 0;
+    }
+    if (opts.fix) {
+        io.err("agent-native doctor --fix is not implemented in this version. Fix findings manually and re-run `agent-native doctor`.");
+        return 2;
+    }
+    const root = path.resolve(opts.cwd ?? process.cwd());
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        const message = `--cwd path does not exist or is not a directory: ${root}`;
+        if (opts.json)
+            io.err(JSON.stringify({ ok: false, message }, null, 2));
+        else
+            io.err(message);
+        return 2;
+    }
+    if (opts.only) {
+        const unknown = opts.only.filter((n) => !ALL_GUARD_NAMES.includes(n));
+        if (unknown.length > 0) {
+            const message = `Unknown guard name(s) in --only: ${unknown.join(", ")}. Known guards: ${ALL_GUARD_NAMES.join(", ")}`;
+            if (opts.json)
+                io.err(JSON.stringify({ ok: false, message }, null, 2));
+            else
+                io.err(message);
+            return 2;
+        }
+    }
+    const report = runDoctorScan({ root, only: opts.only });
+    if (opts.json) {
+        const sink = report.ok ? io.log : io.err;
+        sink(JSON.stringify({ ...report, strict: Boolean(opts.strict) }, null, 2));
+    }
+    else {
+        io.log(formatDoctorHuman(report, root));
+        if (!report.ok) {
+            io.err("");
+            io.err("agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.");
+        }
+    }
+    return report.ok ? 0 : 1;
+}
+/**
+ * `agent-native build`'s doctor pre-step. Always runs every enabled guard
+ * and always prints findings (as warnings) to `io.err` — never silent.
+ * Never causes the build to fail unless `strict` was passed or
+ * `agent-native.json` sets `doctor.failOnBuild: true` (see report 005,
+ * "Where it runs" — the v1 doctor has zero field mileage against arbitrary
+ * app layouts, so shipping fail-by-default would risk breaking a first
+ * deploy on a false positive).
+ */
+export async function runDoctorBuildHook(options, io = defaultIo) {
+    const root = path.resolve(options.cwd);
+    const config = readDoctorConfig(root);
+    const report = runDoctorScan({ root });
+    if (report.findings.length > 0) {
+        io.err(`\n[doctor] ${report.findings.length} finding(s) from \`agent-native doctor\` — run it directly for details. This does not fail the build unless --strict was passed or agent-native.json's doctor.failOnBuild is true.`);
+        for (const f of report.findings) {
+            io.err(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);
+        }
+    }
+    const fail = shouldFailBuild(report.findings.length > 0, {
+        strict: options.strict,
+        failOnBuild: config.failOnBuild,
+    });
+    if (fail) {
+        io.err(`\n[doctor] Failing build: ${options.strict ? "--strict was passed" : "agent-native.json's doctor.failOnBuild is true"}.`);
+    }
+    return { ok: !fail, report };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAY5B,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,iBAAiB;IACjB,yBAAyB;IACzB,qBAAqB;IACrB,oBAAoB;IACpB,iBAAiB;IACjB,iBAAiB;IACjB,uBAAuB;CACxB,CAAC;AAQF,MAAM,qBAAqB,GAAiB;IAC1C,cAAc,EAAE,EAAE;IAClB,qBAAqB,EAAE,EAAE;IACzB,WAAW,EAAE,KAAK;CACnB,CAAC;AAeF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,GAAG,qBAAqB,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyC,CAAC;QACvE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC;YACzD,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YACzE,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,qBAAqB,GACzB,MAAM,CAAC,qBAAqB;YAC5B,OAAO,MAAM,CAAC,qBAAqB,KAAK,QAAQ;YAC9C,CAAC,CAAE,MAAM,CAAC,WAAW,CACjB,MAAM,CAAC,OAAO,CACZ,MAAM,CAAC,qBAAgD,CACxD,CAAC,MAAM,CACN,CAAC,KAAK,EAA6B,EAAE,CACnC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ,CAC/B,CACyB;YAC9B,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,KAAK,IAAI,CAAC;QAChD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,qBAAqB,EAAE,qBAAqB,EAAE,EAAE,EAAE,CAAC;IACjE,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CACf,IAAe,EACf,IAAY,EACZ,MAAoB;IAEpB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,iBAAiB;YACpB,OAAO,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,KAAK,yBAAyB;YAC5B,OAAO,uBAAuB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,KAAK,qBAAqB;YACxB,OAAO,mBAAmB,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7D,KAAK,oBAAoB;YACvB,OAAO,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,KAAK,iBAAiB;YACpB,OAAO,iBAAiB,CAAC;gBACvB,IAAI;gBACJ,QAAQ,EAAE,MAAM,CAAC,qBAAqB;aACvC,CAAC,CAAC;QACL,KAAK,iBAAiB;YACpB,OAAO,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,KAAK,uBAAuB;YAC1B,OAAO,qBAAqB,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAWD;;qDAEqD;AACrD,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEtC,IAAI,KAAkB,CAAC;IACvB,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CACzD,eAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAC1C,CAAC;QACF,KAAK,GAAG,SAAS,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACnE,CAAC;AAED;;;sDAGsD;AACtD,MAAM,UAAU,eAAe,CAC7B,WAAoB,EACpB,IAAiD;IAEjD,OAAO,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC;AACjE,CAAC;AAOD,MAAM,SAAS,GAAa;IAC1B,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IACtC,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;CACzC,CAAC;AAEF,SAAS,iBAAiB,CAAC,MAAoB,EAAE,IAAY;IAC3D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,eAAe,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACrC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,cAAc,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAWD,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,MAAM,IAAI,GAAqB,EAAE,CAAC;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;aAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;QAClB,CAAC;aAAM,IAAI,GAAG,KAAK,OAAO,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YACxD,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACvB,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxC,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAE,GAA0B,SAAS;IACnE,EAAE,CAAC,GAAG,CACJ;QACE,QAAQ;QACR,qGAAqG;QACrG,mGAAmG;QACnG,0EAA0E;QAC1E,8HAA8H;QAC9H,2GAA2G;QAC3G,+EAA+E;QAC/E,8DAA8D;QAC9D,EAAE;QACF,WAAW,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QACvC,EAAE;QACF,mEAAmE;QACnE,EAAE;QACF,0EAA0E;QAC1E,yEAAyE;QACzE,+DAA+D;QAC/D,EAAE;QACF,+DAA+D;QAC/D,kEAAkE;KACnE,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC;AAED;+DAC+D;AAC/D,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,IAAc,EACd,EAAE,GAAa,SAAS;IAExB,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,eAAe,CAAC,EAAE,CAAC,CAAC;QACpB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,EAAE,CAAC,GAAG,CACJ,uHAAuH,CACxH,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACrD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QAC7D,MAAM,OAAO,GAAG,oDAAoD,IAAI,EAAE,CAAC;QAC3E,IAAI,IAAI,CAAC,IAAI;YAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;;YAClE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAE,eAA4B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAClD,CAAC;QACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,oCAAoC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACtH,IAAI,IAAI,CAAC,IAAI;gBAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;;gBAClE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAExD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACX,EAAE,CAAC,GAAG,CACJ,8HAA8H,CAC/H,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAeD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAA+B,EAC/B,EAAE,GAAa,SAAS;IAExB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IAEvC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,EAAE,CAAC,GAAG,CACJ,cAAc,MAAM,CAAC,QAAQ,CAAC,MAAM,oLAAoL,CACzN,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YAChC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE;QACvD,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;IACH,IAAI,IAAI,EAAE,CAAC;QACT,EAAE,CAAC,GAAG,CACJ,6BAA6B,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,gDAAgD,GAAG,CAC1H,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;AAC/B,CAAC","sourcesContent":["/**\n * `agent-native doctor` — scan an app's source tree for the security-\n * critical code-safety invariants this monorepo already enforces on\n * itself via `scripts/guard-*.mjs` (see\n * `advisor-plans/reports/005-doctor-design.md` for the full design and\n * `advisor-plans/015-doctor-v1-implementation.md` for the implementation\n * plan). v1 ships 7 of those guards, ported to work against a single\n * generated app root instead of this monorepo's multi-template layout —\n * see `../guards/index.ts`.\n *\n * This is a NEW top-level command, deliberately kept separate from the two\n * existing \"doctor\" precedents in this CLI:\n *   - `agent-native upgrade check` (`upgrade.ts`) — dependency-pin health.\n *   - `agent-native recap doctor` (`recap.ts`) — PR Visual Recap config health.\n * Each diagnoses a different domain; none are folded into a shared\n * mega-doctor (see report 005, \"Relationship to upgrade doctor and recap\n * doctor\").\n *\n * `--fix` is reserved, not implemented in v1 — it prints a message and\n * exits 2 rather than silently no-op, so a future implementation doesn't\n * collide with a script already passing the flag.\n */\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport {\n  scanDbToolScoping,\n  scanDrizzlePush,\n  scanEnvCredentials,\n  scanEnvMutation,\n  scanLocalhostFallback,\n  scanUnscopedCredentials,\n  scanUnscopedQueries,\n} from \"../guards/index.js\";\nimport type { GuardResult } from \"../guards/index.js\";\n\nexport type GuardName =\n  | \"no-drizzle-push\"\n  | \"no-unscoped-credentials\"\n  | \"no-unscoped-queries\"\n  | \"no-env-credentials\"\n  | \"db-tool-scoping\"\n  | \"no-env-mutation\"\n  | \"no-localhost-fallback\";\n\nexport const ALL_GUARD_NAMES: GuardName[] = [\n  \"no-drizzle-push\",\n  \"no-unscoped-credentials\",\n  \"no-unscoped-queries\",\n  \"no-env-credentials\",\n  \"db-tool-scoping\",\n  \"no-env-mutation\",\n  \"no-localhost-fallback\",\n];\n\nexport interface DoctorConfig {\n  disabledGuards: string[];\n  dbToolScopingDenylist: Record<string, string>;\n  failOnBuild: boolean;\n}\n\nconst DEFAULT_DOCTOR_CONFIG: DoctorConfig = {\n  disabledGuards: [],\n  dbToolScopingDenylist: {},\n  failOnBuild: false,\n};\n\nexport interface DoctorFinding {\n  guard: string;\n  file: string;\n  line: number;\n  message: string;\n}\n\nexport interface DoctorReport {\n  ok: boolean;\n  findings: DoctorFinding[];\n  guardsRun: string[];\n}\n\n/**\n * Reads the optional `\"doctor\"` key from `<root>/agent-native.json`. All\n * fields are optional with sane empty defaults — an app needs zero config\n * to run `agent-native doctor` with every v1 guard enabled.\n */\nexport function readDoctorConfig(root: string): DoctorConfig {\n  const manifestPath = path.join(root, \"agent-native.json\");\n  if (!fs.existsSync(manifestPath)) {\n    return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };\n  }\n  try {\n    const raw = fs.readFileSync(manifestPath, \"utf-8\");\n    const parsed = JSON.parse(raw) as { doctor?: Record<string, unknown> };\n    const doctor = parsed.doctor ?? {};\n    const disabledGuards = Array.isArray(doctor.disabledGuards)\n      ? doctor.disabledGuards.filter((v): v is string => typeof v === \"string\")\n      : [];\n    const dbToolScopingDenylist =\n      doctor.dbToolScopingDenylist &&\n      typeof doctor.dbToolScopingDenylist === \"object\"\n        ? (Object.fromEntries(\n            Object.entries(\n              doctor.dbToolScopingDenylist as Record<string, unknown>,\n            ).filter(\n              (entry): entry is [string, string] =>\n                typeof entry[1] === \"string\",\n            ),\n          ) as Record<string, string>)\n        : {};\n    const failOnBuild = doctor.failOnBuild === true;\n    return { disabledGuards, dbToolScopingDenylist, failOnBuild };\n  } catch {\n    return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };\n  }\n}\n\nfunction runGuard(\n  name: GuardName,\n  root: string,\n  config: DoctorConfig,\n): GuardResult {\n  switch (name) {\n    case \"no-drizzle-push\":\n      return scanDrizzlePush({ root });\n    case \"no-unscoped-credentials\":\n      return scanUnscopedCredentials({ root });\n    case \"no-unscoped-queries\":\n      return scanUnscopedQueries({ root, extraExemptPaths: [] });\n    case \"no-env-credentials\":\n      return scanEnvCredentials({ root });\n    case \"db-tool-scoping\":\n      return scanDbToolScoping({\n        root,\n        denylist: config.dbToolScopingDenylist,\n      });\n    case \"no-env-mutation\":\n      return scanEnvMutation({ root });\n    case \"no-localhost-fallback\":\n      return scanLocalhostFallback({ root, extraExemptPaths: [] });\n  }\n}\n\nexport interface RunDoctorScanOptions {\n  root: string;\n  /** Restrict to these guard names. When omitted, runs every guard not\n   * listed in `agent-native.json`'s `doctor.disabledGuards`. Unknown names\n   * are silently ignored here — the CLI layer (`runDoctor`) validates\n   * `--only` and reports a usage error before calling this. */\n  only?: string[];\n}\n\n/** Pure scan orchestrator: runs the selected guards against `root` and\n * returns a flat report. No I/O beyond reading `agent-native.json` and the\n * app source tree — no printing, no process.exit. */\nexport function runDoctorScan(options: RunDoctorScanOptions): DoctorReport {\n  const root = options.root;\n  const config = readDoctorConfig(root);\n\n  let names: GuardName[];\n  if (options.only && options.only.length > 0) {\n    const knownOnly = options.only.filter((n): n is GuardName =>\n      (ALL_GUARD_NAMES as string[]).includes(n),\n    );\n    names = knownOnly;\n  } else {\n    names = ALL_GUARD_NAMES.filter((n) => !config.disabledGuards.includes(n));\n  }\n\n  const findings: DoctorFinding[] = [];\n  for (const name of names) {\n    const result = runGuard(name, root, config);\n    for (const f of result.findings) {\n      findings.push({\n        guard: name,\n        file: f.file,\n        line: f.line,\n        message: f.message,\n      });\n    }\n  }\n\n  return { ok: findings.length === 0, findings, guardsRun: names };\n}\n\n/** Pure escalation rule shared by the CLI (`--strict`) and the `build`\n * pre-step (`--strict` / `agent-native.json` `doctor.failOnBuild`). Doctor\n * findings never fail anything on their own — only `strict` or\n * `failOnBuild` turn findings into a hard failure. */\nexport function shouldFailBuild(\n  hasFindings: boolean,\n  opts: { strict?: boolean; failOnBuild?: boolean },\n): boolean {\n  return hasFindings && Boolean(opts.strict || opts.failOnBuild);\n}\n\nexport interface DoctorIo {\n  log: (message: string) => void;\n  err: (message: string) => void;\n}\n\nconst defaultIo: DoctorIo = {\n  log: (message) => console.log(message),\n  err: (message) => console.error(message),\n};\n\nfunction formatDoctorHuman(report: DoctorReport, root: string): string {\n  const lines: string[] = [];\n  lines.push(`agent-native doctor: ${root}`);\n  lines.push(`Guards run: ${report.guardsRun.join(\", \") || \"(none)\"}`);\n  if (report.findings.length === 0) {\n    lines.push(\"Clean — no findings.\");\n  } else {\n    lines.push(`${report.findings.length} finding(s):`);\n    for (const f of report.findings) {\n      lines.push(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);\n    }\n  }\n  return lines.join(\"\\n\");\n}\n\nexport interface DoctorCliOptions {\n  json?: boolean;\n  cwd?: string;\n  only?: string[];\n  strict?: boolean;\n  help?: boolean;\n  fix?: boolean;\n}\n\nexport function parseDoctorArgs(argv: string[]): DoctorCliOptions {\n  const opts: DoctorCliOptions = {};\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i];\n    if (arg === \"--help\" || arg === \"-h\") {\n      opts.help = true;\n    } else if (arg === \"--json\") {\n      opts.json = true;\n    } else if (arg === \"--strict\") {\n      opts.strict = true;\n    } else if (arg === \"--fix\") {\n      opts.fix = true;\n    } else if (arg === \"--cwd\" && argv[i + 1] !== undefined) {\n      opts.cwd = argv[++i];\n    } else if (arg.startsWith(\"--cwd=\")) {\n      opts.cwd = arg.slice(\"--cwd=\".length);\n    } else if (arg === \"--only\" && argv[i + 1] !== undefined) {\n      opts.only = splitGuardList(argv[++i]);\n    } else if (arg.startsWith(\"--only=\")) {\n      opts.only = splitGuardList(arg.slice(\"--only=\".length));\n    }\n  }\n  return opts;\n}\n\nfunction splitGuardList(value: string): string[] {\n  return value\n    .split(\",\")\n    .map((s) => s.trim())\n    .filter((s) => s.length > 0);\n}\n\nexport function printDoctorHelp(io: Pick<DoctorIo, \"log\"> = defaultIo): void {\n  io.log(\n    [\n      \"Usage:\",\n      \"  agent-native doctor                        Scan app source for security-critical guard violations\",\n      \"  agent-native doctor --json                 Machine-readable report: { ok, findings, guardsRun }\",\n      \"  agent-native doctor --only <guard,guard>   Run only the named guard(s)\",\n      \"  agent-native doctor --strict                Escalate findings to a hard failure when used by `agent-native build --strict`\",\n      \"  agent-native doctor --cwd <dir>             Run against a project root other than the current directory\",\n      \"  agent-native doctor --fix                   Not implemented in this version\",\n      \"  agent-native doctor --help                  Show this help\",\n      \"\",\n      `Guards: ${ALL_GUARD_NAMES.join(\", \")}`,\n      \"\",\n      \"Exit codes: 0 clean, 1 findings present, 2 usage/execution error.\",\n      \"\",\n      \"`agent-native build` runs doctor as a warn-only pre-step by default — it\",\n      \"never fails the build unless `agent-native build --strict` is passed or\",\n      'agent-native.json sets { \"doctor\": { \"failOnBuild\": true } }.',\n      \"\",\n      \"For dependency-pin health (framework overrides/patches, stale\",\n      \"@agent-native/* pins), run `agent-native upgrade check` instead.\",\n    ].join(\"\\n\"),\n  );\n}\n\n/** `agent-native doctor` CLI entrypoint. Returns the process exit code —\n * callers are responsible for calling `process.exit(code)`. */\nexport async function runDoctor(\n  argv: string[],\n  io: DoctorIo = defaultIo,\n): Promise<number> {\n  const opts = parseDoctorArgs(argv);\n\n  if (opts.help) {\n    printDoctorHelp(io);\n    return 0;\n  }\n\n  if (opts.fix) {\n    io.err(\n      \"agent-native doctor --fix is not implemented in this version. Fix findings manually and re-run `agent-native doctor`.\",\n    );\n    return 2;\n  }\n\n  const root = path.resolve(opts.cwd ?? process.cwd());\n  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {\n    const message = `--cwd path does not exist or is not a directory: ${root}`;\n    if (opts.json) io.err(JSON.stringify({ ok: false, message }, null, 2));\n    else io.err(message);\n    return 2;\n  }\n\n  if (opts.only) {\n    const unknown = opts.only.filter(\n      (n) => !(ALL_GUARD_NAMES as string[]).includes(n),\n    );\n    if (unknown.length > 0) {\n      const message = `Unknown guard name(s) in --only: ${unknown.join(\", \")}. Known guards: ${ALL_GUARD_NAMES.join(\", \")}`;\n      if (opts.json) io.err(JSON.stringify({ ok: false, message }, null, 2));\n      else io.err(message);\n      return 2;\n    }\n  }\n\n  const report = runDoctorScan({ root, only: opts.only });\n\n  if (opts.json) {\n    const sink = report.ok ? io.log : io.err;\n    sink(JSON.stringify({ ...report, strict: Boolean(opts.strict) }, null, 2));\n  } else {\n    io.log(formatDoctorHuman(report, root));\n    if (!report.ok) {\n      io.err(\"\");\n      io.err(\n        \"agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.\",\n      );\n    }\n  }\n\n  return report.ok ? 0 : 1;\n}\n\nexport interface DoctorBuildHookOptions {\n  cwd: string;\n  /** Set when the caller passed `agent-native build --strict`. */\n  strict?: boolean;\n}\n\nexport interface DoctorBuildHookResult {\n  /** False only when findings are present AND (`strict` was requested OR\n   * `agent-native.json`'s `doctor.failOnBuild` is true). */\n  ok: boolean;\n  report: DoctorReport;\n}\n\n/**\n * `agent-native build`'s doctor pre-step. Always runs every enabled guard\n * and always prints findings (as warnings) to `io.err` — never silent.\n * Never causes the build to fail unless `strict` was passed or\n * `agent-native.json` sets `doctor.failOnBuild: true` (see report 005,\n * \"Where it runs\" — the v1 doctor has zero field mileage against arbitrary\n * app layouts, so shipping fail-by-default would risk breaking a first\n * deploy on a false positive).\n */\nexport async function runDoctorBuildHook(\n  options: DoctorBuildHookOptions,\n  io: DoctorIo = defaultIo,\n): Promise<DoctorBuildHookResult> {\n  const root = path.resolve(options.cwd);\n  const config = readDoctorConfig(root);\n  const report = runDoctorScan({ root });\n\n  if (report.findings.length > 0) {\n    io.err(\n      `\\n[doctor] ${report.findings.length} finding(s) from \\`agent-native doctor\\` — run it directly for details. This does not fail the build unless --strict was passed or agent-native.json's doctor.failOnBuild is true.`,\n    );\n    for (const f of report.findings) {\n      io.err(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);\n    }\n  }\n\n  const fail = shouldFailBuild(report.findings.length > 0, {\n    strict: options.strict,\n    failOnBuild: config.failOnBuild,\n  });\n  if (fail) {\n    io.err(\n      `\\n[doctor] Failing build: ${options.strict ? \"--strict was passed\" : \"agent-native.json's doctor.failOnBuild is true\"}.`,\n    );\n  }\n\n  return { ok: !fail, report };\n}\n"]}

package/dist/cli/index.js

@@ -491,6 +491,25 @@ switch (command) {
         // child exits non-zero, runBuildStep calls process.exit itself; the
         // continuation only runs on success.
         (async () => {
+            // Doctor pre-step: scans app source for the security-critical guard
+            // invariants (see `agent-native doctor --help`). Warn-only by
+            // default — prints findings to stderr and always continues. Only
+            // fails the build when `agent-native build --strict` was passed or
+            // `agent-native.json` sets `{ "doctor": { "failOnBuild": true } }`.
+            try {
+                const { runDoctorBuildHook } = await import("./doctor.js");
+                const hook = await runDoctorBuildHook({
+                    cwd: process.cwd(),
+                    strict: args.includes("--strict"),
+                });
+                if (!hook.ok) {
+                    console.error("\nBuild aborted by `agent-native doctor` (see findings above).");
+                    process.exit(1);
+                }
+            }
+            catch (err) {
+                console.warn(`[doctor] pre-build scan failed to run (continuing): ${err instanceof Error ? err.message : String(err)}`);
+            }
             if (isReactRouterFramework()) {
                 validateReactRouterBuildDependencies();
                 const rr = findReactRouterBin();
@@ -660,6 +679,21 @@ switch (command) {
         });
         break;
     }
+    case "doctor": {
+        // Scan app source for security-critical guard invariants (see
+        // `agent-native doctor --help`). For dependency-pin health, see
+        // `agent-native upgrade check` instead.
+        import("./doctor.js")
+            .then(async (m) => {
+            const code = await m.runDoctor(args);
+            process.exit(code);
+        })
+            .catch((err) => {
+            console.error(err?.message ?? err);
+            process.exit(1);
+        });
+        break;
+    }
     case "code": {
         import("./code.js")
             .then((m) => m.runCode(args))
@@ -838,6 +872,18 @@ switch (command) {
         });
         break;
     }
+    case "package": {
+        import("./package-lifecycle.js")
+            .then(async (m) => {
+            const code = await m.runPackageLifecycle(args);
+            process.exit(code);
+        })
+            .catch((err) => {
+            console.error(err?.message ?? err);
+            process.exit(1);
+        });
+        break;
+    }
     case "audit-agent-web": {
         import("./audit-agent-web.js")
             .then((m) => m.runAuditAgentWeb(args))
@@ -962,6 +1008,10 @@ Usage:
                                 Pass a URL instead of a name for a generic
                                 research-and-integrate blueprint. --list to
                                 browse available blueprints.
+  agent-native package <cmd> <package>
+                                Manifest package lifecycle: inspect | add | eject.
+                                add/eject are dry-run unless --apply; --json emits
+                                a machine-readable compatibility/change report.
   agent-native changelog <cmd>  Author the app's user-facing changelog.
                                 cmds: add "<summary>" [--type added|fixed|...] |
                                 release | list. Pending entries live in