@deftai/directive-core 0.90.0 → 0.92.0

package/dist/scm/main.d.ts

@@ -3,6 +3,11 @@ export interface MainOptions {
     readonly whichFn?: Parameters<typeof import("./binary.js").resolveBinary>[0];
     /** Subprocess seam threaded through the `--rest` path for test isolation. */
     readonly runGhApiFn?: GhRestSeams["runGhApiFn"];
+    /**
+     * Skip the #2275 readiness probe (tests that inject REST seams / binary mocks).
+     * Production CLI always probes.
+     */
+    readonly skipReadiness?: boolean;
 }
 /**
  * CLI entry point. Returns the underlying binary's exit code (or 2 on arg error).

package/dist/scm/main.js

@@ -3,7 +3,26 @@ import { extractFlag } from "./argv.js";
 import { buildCommand } from "./build-command.js";
 import { REST_OPT_IN_VERBS } from "./constants.js";
 import { ScmStubError } from "./errors.js";
+import { requireScmReady } from "./readiness.js";
 import { runRestList, runRestView } from "./rest-dispatch.js";
+/**
+ * #2275 fail-loud gate after argv validation, before network/binary work.
+ */
+function guardScmReady(options) {
+    if (options.skipReadiness)
+        return null;
+    try {
+        requireScmReady({ whichFn: options.whichFn });
+        return null;
+    }
+    catch (err) {
+        if (err instanceof ScmStubError) {
+            process.stderr.write(`error: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+}
 /**
  * CLI entry point. Returns the underlying binary's exit code (or 2 on arg error).
  * Mirrors `scripts/scm.py::main`.
@@ -29,6 +48,10 @@ export function main(argv, options = {}) {
                 "REST migration.\n");
             return 2;
         }
+        // Argv-valid REST path: still fail loud when SCM is unusable (#2275).
+        const blocked = guardScmReady(options);
+        if (blocked !== null)
+            return blocked;
         const seams = {
             whichFn: options.whichFn,
             runGhApiFn: options.runGhApiFn,
@@ -43,7 +66,11 @@ export function main(argv, options = {}) {
         return result.exitCode;
     }
     try {
+        // Build/validate argv first so unknown namespace errors surface before readiness.
         const cmd = buildCommand(namespace, verb, extra, { whichFn: options.whichFn });
+        const blocked = guardScmReady(options);
+        if (blocked !== null)
+            return blocked;
         const binary = cmd[0];
         if (binary === undefined) {
             throw new ScmStubError("internal error: empty command argv");

package/dist/scm/readiness-cli.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI entry for `scm:status` / `scm-readiness` (#2275).
+ *
+ * Reports SCM binary + auth readiness in the current execution env.
+ * Exit 0 when ready; exit 1 when not ready (loud diagnostic); exit 2 on bad flags.
+ */
+import { probeScmReadiness, type ScmProbeDepth } from "./readiness.js";
+export interface ScmReadinessCliArgs {
+    readonly json?: boolean;
+    readonly deep?: boolean;
+    readonly depth?: ScmProbeDepth;
+    readonly help?: boolean;
+}
+export declare function parseScmReadinessArgs(argv: readonly string[]): {
+    args: ScmReadinessCliArgs;
+    error: string | null;
+};
+export declare function scmReadinessMain(args: ScmReadinessCliArgs, options?: {
+    writeOut?: (s: string) => void;
+    writeErr?: (s: string) => void;
+    probe?: typeof probeScmReadiness;
+}): number;
+export declare function mainEntry(argv?: string[]): number;
+//# sourceMappingURL=readiness-cli.d.ts.map

package/dist/scm/readiness-cli.js

@@ -0,0 +1,85 @@
+/**
+ * CLI entry for `scm:status` / `scm-readiness` (#2275).
+ *
+ * Reports SCM binary + auth readiness in the current execution env.
+ * Exit 0 when ready; exit 1 when not ready (loud diagnostic); exit 2 on bad flags.
+ */
+import { fileURLToPath } from "node:url";
+import { clearScmReadyCache, formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "./readiness.js";
+export function parseScmReadinessArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            out.json = true;
+        }
+        else if (arg === "--deep") {
+            out.deep = true;
+            out.depth = "deep";
+        }
+        else if (arg === "--shallow") {
+            out.depth = "shallow";
+        }
+        else if (arg === "--depth") {
+            const value = argv[++i];
+            if (value !== "shallow" && value !== "deep") {
+                return {
+                    args: out,
+                    error: `--depth expects shallow|deep, got ${JSON.stringify(value ?? "")}`,
+                };
+            }
+            out.depth = value;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            out.help = true;
+        }
+        else if (arg.startsWith("-")) {
+            return { args: out, error: `unknown flag ${JSON.stringify(arg)}` };
+        }
+        else {
+            return { args: out, error: `unexpected argument ${JSON.stringify(arg)}` };
+        }
+    }
+    return { args: out, error: null };
+}
+const USAGE = "usage: deft scm:status [--json] [--deep|--shallow|--depth shallow|deep]\n" +
+    "  Report SCM (gh/ghx) availability + auth state in this execution env (#2275).\n" +
+    "  Exit 0 ready / 1 not ready / 2 config error.\n";
+export function scmReadinessMain(args, options = {}) {
+    const writeOut = options.writeOut ?? ((s) => process.stdout.write(s));
+    const writeErr = options.writeErr ?? ((s) => process.stderr.write(s));
+    if (args.help) {
+        writeOut(USAGE);
+        return 0;
+    }
+    const depth = args.depth ?? (args.deep ? "deep" : "shallow");
+    // Explicit probe always re-evaluates (credentials may have changed since
+    // session:start). Clears the process-scoped requireScmReady cache too.
+    clearScmReadyCache();
+    const probe = options.probe ?? probeScmReadiness;
+    const report = probe({ depth });
+    if (args.json) {
+        writeOut(`${JSON.stringify(scmReadinessToDict(report), null, 2)}\n`);
+    }
+    else {
+        for (const line of formatScmReadinessLines(report)) {
+            writeOut(`${line}\n`);
+        }
+        if (!report.ready && report.remediation) {
+            writeErr(`${report.remediation}\n`);
+        }
+    }
+    return report.ready ? 0 : 1;
+}
+export function mainEntry(argv = process.argv.slice(2)) {
+    const { args, error } = parseScmReadinessArgs(argv);
+    if (error) {
+        process.stderr.write(`error: ${error}\n${USAGE}`);
+        return 2;
+    }
+    return scmReadinessMain(args);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(mainEntry());
+}
+//# sourceMappingURL=readiness-cli.js.map

package/dist/scm/readiness.d.ts

@@ -0,0 +1,104 @@
+/**
+ * SCM tooling + auth readiness probe for mismatched / headless envs (#2275).
+ *
+ * Framework-local gates (session:start, verify:*, xbrief:preflight, doctor,
+ * scope:*) run without GitHub credentials. SCM-dependent gates (triage:queue,
+ * issue:ingest, pr:*, reconcile:issues, cache:fetch-all, scm:*) need `gh`/`ghx`
+ * on PATH and either host credential store auth or an injected token
+ * (`GH_TOKEN` / `GITHUB_TOKEN` / `GH_ENTERPRISE_TOKEN`).
+ *
+ * This module:
+ *   1. Detects binary + auth state in the *current* execution env (not the
+ *      install host).
+ *   2. Emits a clear one-line diagnostic for session-start and CLI surfaces.
+ *   3. Lists which SCM-dependent gates are skipped when readiness is false.
+ *   4. Supplies fail-loud error text so SCM verbs never fail opaquely.
+ *
+ * Hot-path rule (#2991): the default "shallow" probe is local-only (PATH +
+ * env token presence + optional short `gh auth status`). Deep API validation
+ * is opt-in via `deep: true` (session:start --with-network).
+ */
+import { findInjectedToken, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
+import { type RuntimeCapabilityReport } from "../intake/platform-capabilities.js";
+import { type WhichFn } from "./binary.js";
+import { BINARY_PREFERENCE } from "./constants.js";
+import { ScmStubError } from "./errors.js";
+/** Named SCM-dependent surfaces that need gh/ghx + auth (#2275). */
+export declare const SCM_DEPENDENT_GATES: readonly ["triage:queue", "triage:welcome (network hydrate)", "issue:ingest", "reconcile:issues", "pr:*", "cache:fetch-all", "scm:*", "github-auth-modes (deep)", "umbrella:current-shape"];
+export type ScmBinaryName = (typeof BINARY_PREFERENCE)[number];
+export type ScmAuthState = "authenticated" | "unauthenticated" | "missing-token" | "binary-absent" | "unknown";
+export type ScmProbeDepth = "shallow" | "deep";
+export interface ScmReadinessReport {
+    /** True when a binary is on PATH and auth is usable for SCM gates. */
+    readonly ready: boolean;
+    /** Preferred binary name when present (`ghx` > `gh`). */
+    readonly binary: ScmBinaryName | null;
+    /** Absolute path from PATH lookup, when known. */
+    readonly binaryPath: string | null;
+    /** Auth usability classification. */
+    readonly authState: ScmAuthState;
+    /** Inferred or explicit github_auth_mode label (never a secret). */
+    readonly githubAuthMode: string;
+    /** Runtime mode from the #1557a probe. */
+    readonly runtimeMode: string;
+    /** Whether an injected token env var is present (value never reported). */
+    readonly injectedTokenPresent: boolean;
+    /** Probe depth used for this report. */
+    readonly depth: ScmProbeDepth;
+    /** One-line human diagnostic (no secrets). */
+    readonly detail: string;
+    /** Multi-line remediation when not ready; null when ready. */
+    readonly remediation: string | null;
+    /** Named SCM-dependent gates skipped when not ready (empty when ready). */
+    readonly skippedGates: readonly string[];
+    /** Login from deep validation when available. */
+    readonly login: string | null;
+    /** failure_kind from deep validation when applicable. */
+    readonly failureKind: string | null;
+}
+export interface ProbeScmReadinessOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly whichFn?: WhichFn;
+    /** `shallow` (default) = PATH + token + optional auth status; `deep` = full auth validation. */
+    readonly depth?: ScmProbeDepth;
+    readonly runtimeReport?: RuntimeCapabilityReport;
+    readonly githubAuthMode?: string | null;
+    readonly repo?: string;
+    readonly runGh?: GhRunner;
+    /** When false, skip even `gh auth status` on the shallow path (tests / pure PATH). */
+    readonly checkAuthStatus?: boolean;
+}
+/**
+ * Probe SCM binary + auth readiness in the current execution environment.
+ *
+ * Never throws. Never echoes token values. Suitable for session:start.
+ */
+export declare function probeScmReadiness(options?: ProbeScmReadinessOptions): ScmReadinessReport;
+/** JSON-friendly snake_case dict for session:start --json / CLI. */
+export declare function scmReadinessToDict(report: ScmReadinessReport): Record<string, unknown>;
+/**
+ * Format human lines for session:start (and similar orientation surfaces).
+ * First line is always the one-line status; when not ready, adds skipped gates
+ * and a short remediation pointer.
+ */
+export declare function formatScmReadinessLines(report: ScmReadinessReport): string[];
+/**
+ * Fail-loud error for SCM-dependent entry points when readiness is false.
+ * Includes named reason + skipped-gate list so agents never see an opaque failure.
+ */
+export declare function scmNotReadyError(report?: ScmReadinessReport): ScmStubError;
+/**
+ * Assert SCM binary presence for call sites that only need PATH resolution.
+ * Throws ScmStubError with #2275 diagnostic (not the bare "neither ghx nor gh" text alone).
+ */
+export declare function assertScmBinaryPresent(whichFn?: WhichFn): ScmBinaryName;
+export declare function requireScmReady(options?: ProbeScmReadinessOptions & {
+    force?: boolean;
+}): ScmReadinessReport;
+/**
+ * Clear the process-scoped readiness cache.
+ * Used by tests and by long-running processes after credential injection.
+ */
+export declare function clearScmReadyCache(): void;
+export { findInjectedToken, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN };
+//# sourceMappingURL=readiness.d.ts.map