@opengsd/gsd-core 1.4.2 → 1.5.0-rc.1

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

@@ -0,0 +1,116 @@
+'use strict';
+/**
+ * Intel command router — CLI subcommand dispatcher for `gsd-tools intel`.
+ *
+ * ADR-959 (phase 4d-impl-4): intel command family cutover — last first-party
+ * command cutover in the initial capability rollout.
+ * Extracted from the hardcoded `case 'intel':` arm in gsd-tools.cjs.
+ * Behaviour is preserved byte-for-behaviour from the prior inline case;
+ * the dispatch path now flows: default → dispatchCapabilityCommand →
+ * require(intel-command-router.cjs) → routeIntelCommand.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to the existing
+ * host routers. No new handler/arg convention; the capability registry
+ * discovers this router by name.
+ *
+ * Arg indexing (preserved exactly from the original case):
+ *   args[0] = 'intel'       (family — matched by dispatchCapabilityCommand)
+ *   args[1] = subcommand    (query | status | diff | snapshot | patch-meta |
+ *                            validate | extract-exports | update | api-surface)
+ *   args[2] = term (query) | filePath (patch-meta | extract-exports)
+ *
+ * Notable: the `status` subcommand applies a `timeAgo` transform on
+ * `status.files[*].updated_at` in non-raw mode — preserved exactly.
+ *
+ * Test seams: pass `_intel` to inject a mock intel module; pass `_core` to
+ * inject a mock core module (captures `output` calls and provides a
+ * deterministic `timeAgo` without writing to real stdout).  The `_`-prefix
+ * follows the repo's established seam convention (see audit-command-router.cts
+ * for the `_core` seam pattern).  Production callers omit both.
+ *
+ * Note on `error(); return` pairs: in production `error()` calls
+ * `process.exit(1)` so the `return` is an equivalent no-op halt. The pairs
+ * are kept for lint/control-flow clarity; they do NOT change behaviour.
+ *
+ * Lazy require: intel.cjs is required INSIDE the route function so it is
+ * only loaded when an intel command is actually dispatched (preserves
+ * equivalence with the old inline case arm which required it at the top of
+ * the case block).
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const core = require("./core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+const { ERROR_REASON } = io;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeIntelCommand({ args, cwd, raw, error, _intel, _core }) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const intel = _intel ?? require('./intel.cjs');
+    const c = _core ?? core;
+    const subcommand = args[1];
+    if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) {
+            error('Usage: gsd-tools intel query <term>', ERROR_REASON.USAGE);
+            return;
+        }
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelQuery(term, planningDir), raw);
+    }
+    else if (subcommand === 'status') {
+        const planningDir = path.join(cwd, '.planning');
+        const status = intel.intelStatus(planningDir);
+        if (!raw && status.files) {
+            for (const file of Object.values(status.files)) {
+                if (file.updated_at) {
+                    file.updated_at = c.timeAgo(new Date(file.updated_at));
+                }
+            }
+        }
+        c.output(status, raw);
+    }
+    else if (subcommand === 'diff') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelDiff(planningDir), raw);
+    }
+    else if (subcommand === 'snapshot') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelSnapshot(planningDir), raw);
+    }
+    else if (subcommand === 'patch-meta') {
+        const filePath = args[2];
+        if (!filePath) {
+            error('Usage: gsd-tools intel patch-meta <file-path>', ERROR_REASON.USAGE);
+            return;
+        }
+        c.output(intel.intelPatchMeta(path.resolve(cwd, filePath)), raw);
+    }
+    else if (subcommand === 'validate') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelValidate(planningDir), raw);
+    }
+    else if (subcommand === 'extract-exports') {
+        const filePath = args[2];
+        if (!filePath) {
+            error('Usage: gsd-tools intel extract-exports <file-path>', ERROR_REASON.USAGE);
+            return;
+        }
+        c.output(intel.intelExtractExports(path.resolve(cwd, filePath)), raw);
+    }
+    else if (subcommand === 'update') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelUpdate(planningDir), raw);
+    }
+    else if (subcommand === 'api-surface') {
+        const planningDir = path.join(cwd, '.planning');
+        c.output(intel.intelApiSurface(planningDir), raw);
+    }
+    else {
+        error('Unknown intel subcommand. Available: query, status, update, diff, snapshot, patch-meta, validate, extract-exports, api-surface', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}
+module.exports = {
+    routeIntelCommand,
+};

package/gsd-core/bin/lib/io.cjs

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * CLI I/O primitives — output(), error(), ERROR_REASON, JSON-error mode,
+ * and the temp-file helpers that output() depends on.
+ *
+ * Extracted from core.cts (ADR-857 rollout phase 1 / issue #859).
+ * The hand-written bodies are preserved byte-for-behaviour; only the module
+ * boundary moved. core.cts re-exports every symbol here under its own
+ * `export =` object so existing consumers are unaffected.
+ *
+ * New imports should pull I/O primitives from io.cjs directly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Temp-file helpers (needed by output()) ──────────────────────────────────
+/**
+ * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
+ * Created on first use. Keeps GSD temp files isolated from the system
+ * temp directory so reap scans only GSD files (#1975).
+ */
+const GSD_TEMP_DIR = node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd');
+function ensureGsdTempDir() {
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(GSD_TEMP_DIR);
+}
+/**
+ * Remove stale gsd-* temp files/dirs older than maxAgeMs (default: 5 minutes).
+ * Runs opportunistically before each new temp file write to prevent unbounded accumulation.
+ * @param prefix - filename prefix to match (e.g., 'gsd-')
+ * @param opts
+ * @param opts.maxAgeMs - max age in ms before removal (default: 5 min)
+ * @param opts.dirsOnly - if true, only remove directories (default: false)
+ */
+function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnly = false } = {}) {
+    try {
+        ensureGsdTempDir();
+        const now = Date.now();
+        const entries = node_fs_1.default.readdirSync(GSD_TEMP_DIR);
+        for (const entry of entries) {
+            if (!entry.startsWith(prefix))
+                continue;
+            const fullPath = node_path_1.default.join(GSD_TEMP_DIR, entry);
+            try {
+                const stat = node_fs_1.default.statSync(fullPath);
+                if (now - stat.mtimeMs > maxAgeMs) {
+                    if (stat.isDirectory()) {
+                        node_fs_1.default.rmSync(fullPath, { recursive: true, force: true });
+                    }
+                    else if (!dirsOnly) {
+                        node_fs_1.default.unlinkSync(fullPath);
+                    }
+                }
+            }
+            catch {
+                // File may have been removed between readdir and stat — ignore
+            }
+        }
+    }
+    catch {
+        // Non-critical — don't let cleanup failures break output
+    }
+}
+// ─── Output helpers ───────────────────────────────────────────────────────────
+function output(result, raw, rawValue) {
+    let data;
+    if (raw && rawValue !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        data = String(rawValue);
+    }
+    else {
+        const json = JSON.stringify(result, null, 2);
+        // Large payloads exceed Claude Code's Bash tool buffer (~50KB).
+        // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
+        if (json.length > 50000) {
+            reapStaleTempFiles();
+            ensureGsdTempDir();
+            const tmpPath = node_path_1.default.join(GSD_TEMP_DIR, `gsd-${Date.now()}.json`);
+            (0, shell_command_projection_cjs_1.platformWriteSync)(tmpPath, json);
+            data = '@file:' + tmpPath;
+        }
+        else {
+            data = json;
+        }
+    }
+    // process.stdout.write() is async when stdout is a pipe — process.exit()
+    // can tear down the process before the reader consumes the buffer.
+    // fs.writeSync(1, ...) blocks until the kernel accepts the bytes, and
+    // skipping process.exit() lets the event loop drain naturally.
+    node_fs_1.default.writeSync(1, data);
+}
+/**
+ * Frozen enum of typed reason codes used by error() for structured errors.
+ * Each subcommand contributes its own codes; the enum exists so tests can
+ * assert against typed values instead of grepping stderr (#2974).
+ *
+ * Adding a new code:
+ *   - Pick a snake_case lowercase value (the JSON wire form)
+ *   - Group by subsystem prefix (CONFIG_*, SDK_*, etc)
+ *   - Pass it to error(msg, ERROR_REASON.NEW_CODE) at the call site
+ */
+const ERROR_REASON = Object.freeze({
+    // config-get / config-set
+    CONFIG_KEY_NOT_FOUND: 'config_key_not_found',
+    CONFIG_NO_FILE: 'config_no_file',
+    CONFIG_PARSE_FAILED: 'config_parse_failed',
+    CONFIG_INVALID_KEY: 'config_invalid_key',
+    // SDK / gsd-tools dispatch
+    SDK_FAIL_FAST: 'sdk_fail_fast',
+    SDK_UNKNOWN_COMMAND: 'sdk_unknown_command',
+    SDK_MISSING_ARG: 'sdk_missing_arg',
+    // workflow / phase
+    PHASE_NOT_FOUND: 'phase_not_found',
+    SUMMARY_NO_PLANNING: 'summary_no_planning',
+    // graphify
+    GRAPHIFY_NO_GRAPH: 'graphify_no_graph',
+    GRAPHIFY_INVALID_QUERY: 'graphify_invalid_query',
+    // hooks
+    HOOKS_OPT_OUT: 'hooks_opt_out',
+    // security-scan
+    SECURITY_SCAN_FAILED: 'security_scan_failed',
+    // generic
+    USAGE: 'usage',
+    UNKNOWN: 'unknown',
+});
+/**
+ * Process-level flag: when true, error() emits structured JSON to stderr
+ * instead of plain "Error: <message>" text. Set by gsd-tools.cjs when the
+ * CLI is invoked with `--json-errors`. Tests opt in to typed-IR error
+ * assertions by passing that flag and parsing the JSON.
+ *
+ * Default off so existing callers and human operators keep their plain-text
+ * diagnostics. The structured form is opt-in for tooling and tests (#2974).
+ */
+let _jsonErrorMode = false;
+function setJsonErrorMode(v) { _jsonErrorMode = !!v; }
+function getJsonErrorMode() { return _jsonErrorMode; }
+/**
+ * Emit an error and exit. When the second argument is provided it must be
+ * a value from ERROR_REASON; tests can assert on `result.reason`. When the
+ * process is in JSON-error mode, stderr receives `{ ok: false, reason,
+ * message }` so callers can parse it; otherwise stderr keeps the plain
+ * text form for human operators.
+ */
+function error(message, reason = ERROR_REASON.UNKNOWN) {
+    if (_jsonErrorMode) {
+        const payload = JSON.stringify({ ok: false, reason, message }) + '\n';
+        node_fs_1.default.writeSync(2, payload);
+    }
+    else {
+        node_fs_1.default.writeSync(2, 'Error: ' + message + '\n');
+    }
+    process.exit(1);
+}
+module.exports = {
+    GSD_TEMP_DIR,
+    ensureGsdTempDir,
+    reapStaleTempFiles,
+    output,
+    ERROR_REASON,
+    setJsonErrorMode,
+    getJsonErrorMode,
+    error,
+};

package/gsd-core/bin/lib/loop-host-contract.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * loop-host-contract.cjs — generated by scripts/gen-loop-host-contract.cjs
+ * DO NOT EDIT BY HAND. Run: node scripts/gen-loop-host-contract.cjs --write
+ * ADR-894 §3 — Loop Host Contract, generated from workflow markers.
+ * 12 points: discuss:pre/post, plan:pre/post, execute:pre/wave:pre/wave:post/post,
+ * verify:pre/post, ship:pre/post. Per-step agentRoles and coreArtifacts.
+ */
+
+const LOOP_HOST_CONTRACT = [
+  {
+    "step": "discuss",
+    "points": [
+      "discuss:pre",
+      "discuss:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "CONTEXT.md"
+      ],
+      "consumes": []
+    }
+  },
+  {
+    "step": "plan",
+    "points": [
+      "plan:pre",
+      "plan:post"
+    ],
+    "agentRoles": [
+      "researcher",
+      "planner",
+      "checker"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "PLAN.md"
+      ],
+      "consumes": [
+        "CONTEXT.md"
+      ]
+    }
+  },
+  {
+    "step": "execute",
+    "points": [
+      "execute:pre",
+      "execute:wave:pre",
+      "execute:wave:post",
+      "execute:post"
+    ],
+    "agentRoles": [
+      "executor",
+      "verifier"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "SUMMARY.md"
+      ],
+      "consumes": [
+        "PLAN.md"
+      ]
+    }
+  },
+  {
+    "step": "verify",
+    "points": [
+      "verify:pre",
+      "verify:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [
+        "UAT.md"
+      ],
+      "consumes": [
+        "SUMMARY.md"
+      ]
+    }
+  },
+  {
+    "step": "ship",
+    "points": [
+      "ship:pre",
+      "ship:post"
+    ],
+    "agentRoles": [
+      "orchestrator"
+    ],
+    "coreArtifacts": {
+      "produces": [],
+      "consumes": [
+        "UAT.md"
+      ]
+    }
+  }
+];
+
+module.exports = { LOOP_HOST_CONTRACT };