@nac3/forge-cli 1.20.2 → 1.21.0

package/dist/commands/doctor.d.ts

@@ -1,22 +1,84 @@
 /**
- * `yf doctor` -- environment + project health check. Reports
- * what's installed, what's missing, what's misconfigured.
+ * `yf doctor` -- environment + project health check.
  *
- * v0.2.0-alpha.1 (HITO 0 + HITO 1 closed) -- extended to cover
- * vault availability, voice provider keys, reader parser
- * dependencies, and project root sanity.
+ * THE HONESTY CONTRACT (PND-184, 2026-10-26)
+ * ------------------------------------------
+ * A check may only assert what it verified, and it must say what it
+ * looked at. Every check answers four questions:
+ *
+ *   P1  does it read the source that GOVERNS at runtime -- the file
+ *       the real component reads -- rather than an adjacent or
+ *       inherited field?
+ *   P2  can it go green without having been able to look? (no: that
+ *       is the false-green half of the defect)
+ *   P3  can it go red about something the real component does not
+ *       use? (no: that is the false-red half -- F-01)
+ *   P4  when it cannot look, does it SAY SO, or does it collapse
+ *       "could not verify" into one of the other two?
+ *
+ * Hence `Check.status` is a THIRD state (`ok` | `fail` | `unknown`),
+ * not a boolean, and every check carries `source` (what it read),
+ * plus `expected` / `found` / `conflict` when they add information.
+ *
+ * Why this matters enough to restructure the command: the Urazuke
+ * method documented this same defect twice in its own history -- a
+ * publish check that reported forty failed attempts over thirteen
+ * minutes when the publish had in fact succeeded, because it collapsed
+ * two outcomes into one message; and a guard that claimed a server had
+ * something configured when all it had verified was that a file
+ * existed in a repository. `yf doctor` is the face Forge shows when
+ * something is wrong: it is the last place that can afford a green it
+ * did not earn.
+ *
+ * SIDE EFFECTS: none on the config dir. A diagnostic command must not
+ * change the machine it is diagnosing (PND-188). It does not start the
+ * trial, does not create the vault, does not seed voice-config.json.
+ *
+ * ASCII-only.
  */
 import type { Command } from 'commander';
 export interface DoctorOptions {
     json?: boolean;
+    verbose?: boolean;
 }
-interface Check {
+/** `ok` = verified good. `fail` = verified bad. `unknown` = could NOT
+ *  verify -- a third outcome, never a synonym for either other one. */
+export type CheckStatus = 'ok' | 'fail' | 'unknown';
+export interface Check {
+    /** Stable machine id. Scripts and tests match on this, never on
+     *  `name` -- the label is prose and may be reworded. */
+    id: string;
     name: string;
+    status: CheckStatus;
+    /** Back-compat for existing consumers: true only when status==='ok'.
+     *  An `unknown` is NOT ok -- it is also not a failure, which is why
+     *  the summary counts the three separately. */
     ok: boolean;
+    /** What this check actually looked at: a path, a module specifier,
+     *  a URL, an env var. Mandatory. */
+    source: string;
+    /** What it expected to find there. */
+    expected?: string;
+    /** What it found instead. */
+    found?: string;
     detail: string;
     hint?: string;
+    /** Another source that says something different, named explicitly so
+     *  the user is not sent to reconfigure the one that already works. */
+    conflict?: string;
+}
+export interface DoctorEnv {
+    /** Config dir to inspect. Defaults to configDir(), which honours
+     *  YF_CONFIG_DIR (PND-190: the brain check used to resolve the home
+     *  by hand and read a different directory than the keys layer). */
+    configDir?: string;
+    cwd?: string;
+    fetchImpl?: typeof fetch;
+    nowMs?: () => number;
+    timeoutMs?: number;
 }
 export declare function registerDoctorCommand(program: Command): void;
+export declare function runDoctorChecks(env?: DoctorEnv): Promise<Check[]>;
 /** PND-031 -- 3 HITO 4 doctor probes. Extracted so tests can
  *  exercise them with injected fetch + tmp config dir without
  *  spinning the whole doctor runner. */
@@ -24,9 +86,9 @@ export declare function runHito4DoctorChecks(checks: Check[], opts?: {
     baseUrl?: string;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
+    configDir?: string;
     /** When set, override license.json staleness comparison.
      *  Defaults to `Date.now()`. */
     nowMs?: () => number;
 }): Promise<void>;
-export {};
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,KAAK;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyC5D;AAmWD;;wCAEwC;AACxC,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,GAAE;IACJ,OAAO,CAAC,EAAK,MAAM,CAAC;IACpB,SAAS,CAAC,EAAG,OAAO,KAAK,CAAC;IAC1B,SAAS,CAAC,EAAG,MAAM,CAAC;IACpB;oCACgC;IAChC,KAAK,CAAC,EAAO,MAAM,MAAM,CAAC;CACtB,GACL,OAAO,CAAC,IAAI,CAAC,CAqFf"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;uEACuE;AACvE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD,MAAM,WAAW,KAAK;IACpB;4DACwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB;;mDAE+C;IAC/C,EAAE,EAAE,OAAO,CAAC;IACZ;wCACoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;0EACsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB;;uEAEmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAiBD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2D5D;AAED,wBAAsB,eAAe,CAAC,GAAG,GAAE,SAAc,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CA+B3E;AAonBD;;wCAEwC;AACxC,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,KAAK,EAAE,EACf,IAAI,GAAE;IACJ,OAAO,CAAC,EAAK,MAAM,CAAC;IACpB,SAAS,CAAC,EAAG,OAAO,KAAK,CAAC;IAC1B,SAAS,CAAC,EAAG,MAAM,CAAC;IACpB,SAAS,CAAC,EAAG,MAAM,CAAC;IACpB;oCACgC;IAChC,KAAK,CAAC,EAAO,MAAM,MAAM,CAAC;CACtB,GACL,OAAO,CAAC,IAAI,CAAC,CAsHf"}