@opengsd/gsd-core 1.4.4 → 1.5.0-rc.2

package/gsd-core/bin/lib/capability-state.cjs

@@ -0,0 +1,336 @@
+"use strict";
+/**
+ * Capability State Resolver — ADR-857 phase 4b
+ *
+ * Unified capability-state resolver that composes the three toggle systems
+ * (install profile, runtime surface, config activation) into one per-capability
+ * view. ADDITIVE — install/surface/workflows are untouched; this resolver is
+ * consumed by nothing yet (phase-6 wiring is out of scope).
+ *
+ * Exports (three things, mirroring loop-resolver):
+ *   resolveCapabilityState({ registry, installedSkills, surfacedSkills, config, cwd })
+ *     → { capabilities: CapabilityStateEntry[] }
+ *   cmdCapabilityState(cwd, runtimeConfigDir, raw, options) — I/O entry point
+ *
+ * resolveCapabilityState is DETERMINISTIC given (registry, installedSkills,
+ * surfacedSkills, config) and — when `cwd` is provided — the project config
+ * files at `cwd` (.planning/config.json etc). Pass `cwd: undefined` for a
+ * pure, config-only resolution with no filesystem I/O.
+ * cmdCapabilityState is the I/O handler.
+ *
+ * Dependencies (leaf modules only — no core.cjs circular risk):
+ *   - node:path (used by _resolveActivationValue via loop-resolver)
+ *   - ./core.cjs               (output, error)
+ *   - ./loop-resolver.cjs      (_resolveActivationValue — reuse the export)
+ *   - ./install-profiles.cjs   (readActiveProfile, loadSkillsManifest, resolveProfile)
+ *   - ./surface.cjs            (resolveSurface)
+ *   - ./config-loader.cjs      (loadConfig)
+ *   - ./runtime-homes.cjs      (getGlobalConfigDir — for runtimeConfigDir auto-detection)
+ *   - capability-registry.cjs  (loaded at call time)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+const { output: coreOutput, error: coreError } = core;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const loopResolverMod = require("./loop-resolver.cjs");
+const { _resolveActivationValue } = loopResolverMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+const { loadConfig } = configLoaderMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installProfilesMod = require("./install-profiles.cjs");
+const { readActiveProfile, loadSkillsManifest, resolveProfile } = installProfilesMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const surfaceMod = require("./surface.cjs");
+const { resolveSurface } = surfaceMod;
+// ─── Prototype-pollution guard (inline literal, CodeQL barrier) ───────────────
+function _isSafePropKey(key) {
+    // Inline literal guards — CodeQL barrier pattern
+    if (typeof key !== 'string')
+        return false;
+    if (key === '__proto__')
+        return false;
+    if (key === 'constructor')
+        return false;
+    if (key === 'prototype')
+        return false;
+    return true;
+}
+// ─── Pure resolver ─────────────────────────────────────────────────────────────
+/**
+ * Deterministic resolver: for each capability in the registry, produce the
+ * three-dimension state view:
+ *   1. installed  — does the install profile cover this capability?
+ *   2. surfaced   — does the runtime surface enable this capability?
+ *   3. hooks      — per-hook activation derived from config `when` keys.
+ *
+ * Determinism contract: given the same (registry, installedSkills,
+ * surfacedSkills, config) and — when `cwd` is set — the same project config
+ * files at `cwd`, the output is identical across calls. Pass `cwd: undefined`
+ * for a pure, config-only resolution with no filesystem I/O.
+ *
+ * Never throws for malformed registry/hook entries — skips/defaults defensively.
+ * An empty or missing capabilities object → { capabilities: [] }.
+ *
+ * @param input.registry         The capability-registry.cjs module export.
+ * @param input.installedSkills  Set<string> | '*' — from resolveProfile().skills.
+ * @param input.surfacedSkills   Set<string> — from resolveSurface().skills.
+ * @param input.config           Record from loadConfig(cwd).
+ * @param input.cwd              Optional; when provided, enables raw .planning/config.json
+ *                               fallback reads (levels 2+3 of _resolveActivationValue
+ *                               precedence). Omit for a pure in-memory resolution.
+ */
+function resolveCapabilityState(input) {
+    const { registry, installedSkills, surfacedSkills, config, cwd } = input;
+    // Guard: registry missing capabilities
+    if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+        return { capabilities: [] };
+    }
+    const capabilitiesRaw = registry['capabilities'];
+    if (!capabilitiesRaw || typeof capabilitiesRaw !== 'object' || Array.isArray(capabilitiesRaw)) {
+        return { capabilities: [] };
+    }
+    const capabilitiesMap = capabilitiesRaw;
+    const results = [];
+    for (const capId of Object.keys(capabilitiesMap)) {
+        // Prototype-pollution guard on capability id
+        if (!_isSafePropKey(capId))
+            continue;
+        const cap = capabilitiesMap[capId];
+        if (!cap || typeof cap !== 'object' || Array.isArray(cap))
+            continue;
+        const capObj = cap;
+        // Extract tier
+        const tier = typeof capObj['tier'] === 'string' ? capObj['tier'] : 'unknown';
+        // Extract skills array
+        const skillsRaw = capObj['skills'];
+        const skills = Array.isArray(skillsRaw)
+            ? skillsRaw.filter((s) => typeof s === 'string')
+            : [];
+        // ── installed ──────────────────────────────────────────────────────────────
+        // Empty-skills cap → vacuously installed (no skills to be absent).
+        // installedSkills === '*' → installed = true for every cap.
+        let installed;
+        if (installedSkills === '*') {
+            installed = true;
+        }
+        else if (skills.length === 0) {
+            installed = true; // vacuous: no skills required
+        }
+        else {
+            installed = skills.every((s) => installedSkills.has(s));
+        }
+        // ── surfaced ───────────────────────────────────────────────────────────────
+        // Empty-skills cap → vacuously surfaced.
+        let surfaced;
+        if (skills.length === 0) {
+            surfaced = true; // vacuous
+        }
+        else {
+            surfaced = skills.every((s) => surfacedSkills.has(s));
+        }
+        // ── hooks ──────────────────────────────────────────────────────────────────
+        // Collect from steps, gates, contributions. Each may have a `when` key.
+        // Activation semantics (mirrors loop-resolver.isActive exactly):
+        //   - No `when` field present (undefined/null) → unconditional, active=true
+        //   - Non-empty string `when` → resolve via _resolveActivationValue
+        //   - Present-but-empty-string or non-string `when` → malformed, active=false
+        // The original `when` value is carried through to the output for visibility.
+        const hooks = [];
+        function processHooks(arr, kind) {
+            for (const hookRaw of arr) {
+                if (!hookRaw || typeof hookRaw !== 'object' || Array.isArray(hookRaw))
+                    continue;
+                const h = hookRaw;
+                const point = typeof h['point'] === 'string' ? h['point'] : '';
+                // Carry the raw `when` value through for visibility
+                const whenRaw = h['when'];
+                let active;
+                if (whenRaw === undefined || whenRaw === null) {
+                    // No `when` field → unconditional, always active
+                    active = true;
+                }
+                else if (typeof whenRaw === 'string' && whenRaw.length > 0) {
+                    // Non-empty string `when` → resolve via _resolveActivationValue
+                    active = _resolveActivationValue(whenRaw, config, cwd, registry);
+                }
+                else {
+                    // Present-but-empty-string or non-string `when` → malformed, inactive
+                    // (mirrors loop-resolver.isActive: `typeof when !== 'string' || when.length === 0` → false)
+                    active = false;
+                }
+                hooks.push({ point, kind, when: whenRaw, active });
+            }
+        }
+        const stepsRaw = capObj['steps'];
+        const gatesRaw = capObj['gates'];
+        const contributionsRaw = capObj['contributions'];
+        processHooks(Array.isArray(stepsRaw) ? stepsRaw : [], 'step');
+        processHooks(Array.isArray(gatesRaw) ? gatesRaw : [], 'gate');
+        processHooks(Array.isArray(contributionsRaw) ? contributionsRaw : [], 'contribution');
+        results.push({ id: capId, tier, skills, installed, surfaced, hooks });
+    }
+    // Deterministic sort by id for stable output across calls
+    results.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return { capabilities: results };
+}
+// ─── I/O command handler ───────────────────────────────────────────────────────
+/**
+ * Derive the commands/gsd path from __dirname (which resolves to
+ * gsd-core/bin/lib/ at runtime). The source tree is:
+ *   <repo>/gsd-core/bin/lib/capability-state.cjs
+ *   <repo>/commands/gsd/*.md
+ * So we walk up three levels: lib/ → bin/ → gsd-core/ → <repo>/, then
+ * into commands/gsd/.
+ */
+function _resolveCommandsGsdDir() {
+    // __dirname = gsd-core/bin/lib/
+    const repoRoot = node_path_1.default.resolve(__dirname, '..', '..', '..');
+    return node_path_1.default.join(repoRoot, 'commands', 'gsd');
+}
+/**
+ * Command entry point: resolve install profile, surface, and config; compute
+ * capability state; emit the envelope via core.output.
+ *
+ * Envelope: { runtimeConfigDir, warnings?: string[], capabilities: CapabilityStateEntry[] }
+ *
+ * runtimeConfigDir resolution (when not provided or empty):
+ *   Uses the canonical getGlobalConfigDir from runtime-homes.cjs to detect the
+ *   active runtime's config dir — the same resolver used by install.js. This
+ *   correctly handles all supported runtimes (claude, codex, cursor, gemini,
+ *   opencode, grok, etc.) and their env-var overrides. Defaults to claude
+ *   (falls back to ~/.claude) if the resolver throws.
+ *
+ * Failure surfacing: genuine resolution failures (manifest/profile/surface
+ * errors) are reported in the `warnings` array in the envelope. The output
+ * remains useful — degraded to the best available state — but the caller can
+ * detect that the state is not fully resolved.
+ *
+ *   Legitimate "no marker → default full profile" is NOT a warning.
+ *   A thrown error during profile/surface resolution IS a warning.
+ *
+ * @param cwd              Project root directory
+ * @param runtimeConfigDir Runtime config directory (e.g. ~/.claude). May be
+ *                         empty/undefined — falls back to auto-detection.
+ *                         Providing a value without a next token (e.g. the flag
+ *                         is last in argv with no following value) should be
+ *                         caught by the caller before invoking this function.
+ * @param raw              Whether to emit raw JSON (core.output raw mode)
+ * @param _options         Reserved for future use
+ */
+function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
+    const warnings = [];
+    // Resolve runtimeConfigDir using the canonical runtime-homes resolver.
+    // When not provided, getGlobalConfigDir(runtime) is called with 'claude'
+    // as the default runtime — the same fallback as install.js. The canonical
+    // resolver handles all env-var overrides (CLAUDE_CONFIG_DIR, CODEX_HOME,
+    // CURSOR_CONFIG_DIR, GROK_AGENTS_HOME, etc.) correctly and without
+    // fabricating env vars that don't exist upstream.
+    let resolvedConfigDir = runtimeConfigDir || '';
+    if (!resolvedConfigDir) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const runtimeHomes = require('./runtime-homes.cjs');
+            // Delegate runtime detection entirely to getGlobalConfigDir: calling it
+            // with 'claude' causes it to check CLAUDE_CONFIG_DIR first, falling back
+            // to ~/.claude. The canonical resolver already encodes the correct env-var
+            // precedence for each runtime — we do not re-implement that logic here.
+            // For non-claude runtimes, the caller should pass --config-dir explicitly
+            // (or set the runtime-specific env var, which getGlobalConfigDir honors).
+            resolvedConfigDir = runtimeHomes.getGlobalConfigDir('claude');
+        }
+        catch {
+            // Defensive fallback: use ~/.claude if the canonical resolver throws.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const os = require('node:os');
+            resolvedConfigDir = node_path_1.default.join(os.homedir(), '.claude');
+        }
+    }
+    // ── Load registry (ADR-857 phase 4c) ────────────────────────────────────────
+    // Load BEFORE resolveProfile and resolveSurface so both calls receive the
+    // registry and capability-contributed skills are reflected in installed/surfaced.
+    // No-op today (UI capability is tier:full → only adds to 'full', which returns
+    // '*' regardless) but cutover-ready for future tier:core/standard capabilities.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    // ── Resolve installed skills (from install profile) ──────────────────────────
+    // Distinguish "no profile marker → default full" (legitimate) from a thrown
+    // error (surface as a warning and degrade gracefully — do NOT silently report
+    // installedSkills='*' as if the install profile were truly unlimited).
+    let installedSkills;
+    try {
+        const commandsGsdDir = _resolveCommandsGsdDir();
+        const manifest = loadSkillsManifest(commandsGsdDir);
+        const profileName = readActiveProfile(resolvedConfigDir) ?? 'full';
+        const resolvedInstall = resolveProfile({
+            modes: profileName.split(',').map((s) => s.trim()),
+            manifest,
+            registry,
+        });
+        installedSkills = resolvedInstall.skills;
+    }
+    catch (err) {
+        // Genuine resolution failure — surface it so the caller is not misled.
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`profile-resolution failed: ${msg}`);
+        coreError(`capability state: profile resolution failed: ${msg}`);
+        // Degrade to empty set (not '*') so installed=false is reported accurately.
+        installedSkills = new Set();
+    }
+    // ── Resolve surfaced skills (from runtime surface) ────────────────────────────
+    let surfacedSkills;
+    try {
+        const commandsGsdDir = _resolveCommandsGsdDir();
+        const manifest = loadSkillsManifest(commandsGsdDir);
+        const surfaceResult = resolveSurface(resolvedConfigDir, manifest, undefined, registry);
+        // resolveSurface returns { name, skills: Set<string>, agents: Set<string> }
+        // (always a concrete Set — full profile is materialized)
+        surfacedSkills = surfaceResult.skills instanceof Set
+            ? surfaceResult.skills
+            : new Set();
+    }
+    catch (err) {
+        // Genuine surface resolution failure — surface it so the caller is not misled.
+        const msg = err instanceof Error ? err.message : String(err);
+        warnings.push(`surface-resolution failed: ${msg}`);
+        coreError(`capability state: surface resolution failed: ${msg}`);
+        surfacedSkills = new Set();
+    }
+    // ── Load config ───────────────────────────────────────────────────────────────
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        config = {};
+    }
+    // ── Resolve state ────────────────────────────────────────────────────────────
+    const result = resolveCapabilityState({
+        registry,
+        installedSkills,
+        surfacedSkills,
+        config,
+        cwd,
+    });
+    // Build envelope — include warnings array only when non-empty so the nominal
+    // path keeps the output clean and callers can check `warnings` for degraded state.
+    const envelope = {
+        runtimeConfigDir: resolvedConfigDir,
+        capabilities: result.capabilities,
+    };
+    if (warnings.length > 0) {
+        envelope.warnings = warnings;
+    }
+    coreOutput(envelope, raw);
+}
+module.exports = {
+    resolveCapabilityState,
+    cmdCapabilityState,
+    // Exported for tests
+    _resolveCommandsGsdDir,
+    _isSafePropKey,
+};

package/gsd-core/bin/lib/check-command-router.cjs

@@ -16,6 +16,10 @@ const node_child_process_1 = require("node:child_process");
 const core = require("./core.cjs");
 const { output, error, ERROR_REASON } = core;
 const decisions_cjs_1 = require("./decisions.cjs");
+const ui_safety_gate_cjs_1 = require("./ui-safety-gate.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapModule = require("./roadmap.cjs");
+const { getRoadmapPhaseWithFallback } = roadmapModule;
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function normalizePhrase(text) {
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -320,8 +324,130 @@ function cmdDecisionCoverageVerify(projectDir, args, raw) {
         message: buildVerifyMessage(notHonored),
     }, raw, undefined);
 }
+// ─── ui-plan-gate ─────────────────────────────────────────────────────────────
+/**
+ * ui-plan-gate: given a phase number, checks whether the phase has frontend
+ * indicators and whether a *-UI-SPEC.md already exists in the phase directory.
+ *
+ * Returns JSON: { frontend: boolean, hasUiSpec: boolean, block: boolean }
+ *   block = frontend && !hasUiSpec (gate fires when UI work is detected but no spec exists)
+ *
+ * Invocable as: gsd_run check ui-plan-gate <phase>
+ *
+ * Uses checkUiPresence from ui-safety-gate.cjs — does NOT reimplement frontend detection.
+ * Uses getRoadmapPhaseInternal + findPhaseInternal from core.cjs for phase data.
+ */
+function findUiSpecInDir(phaseDir) {
+    if (!phaseDir || !node_fs_1.default.existsSync(phaseDir))
+        return '';
+    try {
+        const files = node_fs_1.default.readdirSync(phaseDir);
+        const found = files.find((f) => /-UI-SPEC\.md$/.test(f));
+        return found ? node_path_1.default.join(phaseDir, found) : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pure logic for ui-plan-gate — exposed for direct behavioral testing.
+ *
+ * Given a projectDir and phase number:
+ *   (a) Reads the phase section from ROADMAP.md via getRoadmapPhaseWithFallback —
+ *       same two-pass lookup (current milestone → full roadmap) as `roadmap.get-phase`
+ *       (cmdRoadmapGetPhase). Cross-milestone / older frontend phases resolve correctly.
+ *       If ROADMAP.md is missing, phaseSection is '' (ROADMAP.md not present = project
+ *       has no roadmap = cannot be frontend). If the phase truly can't be found after
+ *       both passes, phaseSection is '' and phaseLookupFailed is set so callers can
+ *       surface the miss — we do NOT silently degrade to frontend:false if the roadmap
+ *       exists but the phase header is absent.
+ *   (b) Runs checkUiPresence (frontend detection) — no reimplementation.
+ *   (c) Resolves the phase directory via core.findPhaseInternal; checks for *-UI-SPEC.md.
+ *
+ * Returns: { frontend, hasUiSpec, block, uiSpecPath, phaseLookupFailed }
+ *   block = frontend && !hasUiSpec
+ *   phaseLookupFailed = ROADMAP.md present but phase header not found (surfaced for
+ *                       onError:halt gates so a missing phase doesn't silently bypass)
+ */
+function computeUiPlanGate(projectDir, phase) {
+    // (a) Read the phase section text using the same two-pass lookup as roadmap.get-phase.
+    // getRoadmapPhaseWithFallback: current-milestone first, then stripShippedMilestones
+    // fallback — mirrors cmdRoadmapGetPhase exactly.
+    let phaseSection = '';
+    let phaseLookupFailed;
+    try {
+        const section = getRoadmapPhaseWithFallback(projectDir, phase);
+        if (section === null) {
+            // Distinguish: ROADMAP.md missing (no-roadmap project) vs phase not found in ROADMAP.
+            // core.planningDir(cwd) resolves the .planning/ root for workstream-aware paths.
+            const planDir = typeof core['planningDir'] === 'function'
+                ? core['planningDir'](projectDir)
+                : node_path_1.default.join(projectDir, '.planning');
+            const roadmapPath = node_path_1.default.join(planDir, 'ROADMAP.md');
+            if (node_fs_1.default.existsSync(roadmapPath)) {
+                // ROADMAP.md exists but phase was not found → surface the miss
+                phaseLookupFailed = true;
+            }
+            // phaseSection stays ''
+        }
+        else {
+            phaseSection = section;
+        }
+    }
+    catch { /* roadmap read failure → treat as empty (non-frontend) */ }
+    // (b) Run checkUiPresence (frontend detection) — reuse existing helper; no reimplementation
+    const presenceResult = (0, ui_safety_gate_cjs_1.checkUiPresence)(phaseSection);
+    const frontend = presenceResult.hasUI;
+    // (c) Resolve phase directory via findPhaseInternal and check for *-UI-SPEC.md
+    const coreModule = core;
+    let phaseDir = '';
+    try {
+        const findPhase = coreModule['findPhaseInternal'];
+        if (typeof findPhase === 'function') {
+            const result = findPhase(projectDir, phase);
+            if (result && typeof result === 'object') {
+                // findPhaseInternal returns { directory: '<relative-posix-path>', ... }
+                // directory is relative to cwd — resolve it to absolute.
+                const relDir = typeof result['directory'] === 'string' ? result['directory'] : '';
+                if (relDir) {
+                    phaseDir = node_path_1.default.resolve(projectDir, relDir);
+                }
+            }
+            else if (typeof result === 'string') {
+                phaseDir = result;
+            }
+        }
+    }
+    catch { /* phase dir lookup failure → hasUiSpec=false */ }
+    const uiSpecPath = findUiSpecInDir(phaseDir);
+    const hasUiSpec = uiSpecPath !== '';
+    // block = frontend phase with no UI-SPEC
+    const block = frontend && !hasUiSpec;
+    const result = {
+        frontend, hasUiSpec, block, uiSpecPath: hasUiSpec ? uiSpecPath : null,
+    };
+    if (phaseLookupFailed)
+        result.phaseLookupFailed = true;
+    return result;
+}
+function cmdUiPlanGate(projectDir, args, raw) {
+    // args[0] = 'check', args[1] = 'ui-plan-gate', args[2] = phase
+    const phase = args[2] || '';
+    if (!phase) {
+        error('ui-plan-gate requires a phase argument: check ui-plan-gate <phase>', ERROR_REASON.SDK_MISSING_ARG);
+        return;
+    }
+    output(computeUiPlanGate(projectDir, phase), raw, undefined);
+}
 function routeCheckCommand({ args, cwd, raw }) {
-    const subcommand = args[1];
+    // Normalize dots to hyphens in the subcommand so both forms are accepted.
+    // This makes `check.query = "ui.plan-gate"` (dotted form in capability.json gates)
+    // directly runnable as `gsd_run check ui.plan-gate` — the dot is normalized to
+    // `ui-plan-gate` before routing. The generic gate-dispatch in §5.6 reads
+    // `check.query` from the active gate hook and runs `gsd_run check ${hook.check.query}`,
+    // so the declared query must be dispatchable exactly as declared.
+    const rawSubcommand = args[1];
+    const subcommand = typeof rawSubcommand === 'string' ? rawSubcommand.replace(/\./g, '-') : rawSubcommand;
     if (subcommand === 'auto-mode') {
         cmdAutoMode(cwd, raw);
         return;
@@ -334,10 +460,15 @@ function routeCheckCommand({ args, cwd, raw }) {
         cmdDecisionCoverageVerify(cwd, args, raw);
         return;
     }
-    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    if (subcommand === 'ui-plan-gate') {
+        cmdUiPlanGate(cwd, args, raw);
+        return;
+    }
+    error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify, ui-plan-gate', ERROR_REASON.SDK_UNKNOWN_COMMAND);
 }
 module.exports = {
     routeCheckCommand,
     decisionMentioned,
     extractPlanDesignatedSections,
+    computeUiPlanGate,
 };

package/gsd-core/bin/lib/cli-exit.cjs

@@ -1,4 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ioModule = require("./io.cjs");
+const { getJsonErrorMode, ERROR_REASON } = ioModule;
 /**
  * Error carrying a process exit code. CLI logic throws this instead of calling
  * process.exit() (banned by n/no-process-exit); runMain() translates it into
@@ -20,7 +27,8 @@ class ExitError extends Error {
  * process.on('exit') cleanup still fires). main may be sync or async:
  *   number return -> process.exitCode = it
  *   thrown ExitError -> process.exitCode = err.code (+ stderr err.message if hasUserMessage && code!=0)
- *   other throw -> stderr stack + process.exitCode = 1
+ *   other throw -> when json-error mode is active, emits structured { ok:false, reason, message }
+ *                  to stderr; otherwise writes raw stack trace. exit code = 1 in either case.
  */
 function runMain(main) {
     Promise.resolve()
@@ -34,8 +42,19 @@ function runMain(main) {
             process.exitCode = err.code;
             return;
         }
-        const e = err;
-        process.stderr.write(`${e && e.stack ? e.stack : String(err)}\n`);
+        if (getJsonErrorMode()) {
+            const e = err;
+            const payload = JSON.stringify({
+                ok: false,
+                reason: ERROR_REASON.SDK_FAIL_FAST,
+                message: (e && e.message) ? e.message : String(err),
+            }) + '\n';
+            node_fs_1.default.writeSync(2, payload);
+        }
+        else {
+            const e = err;
+            process.stderr.write(`${e && e.stack ? e.stack : String(err)}\n`);
+        }
         process.exitCode = 1;
     });
 }