@opengsd/gsd-core 1.7.0-rc.5 → 1.7.0-rc.6

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -15,6 +15,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = void 0;
 exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
@@ -132,7 +133,15 @@ function resolveRuntimeNameFromCandidates(...candidates) {
  * Aliases are normalized via `canonicalizeRuntimeName` first, so inputs like
  * `codex-cli` resolve to `codex` → `AGENTS.md`. Replaces the prior codex-only
  * override in profile-output.cjs (#3163) which left AGENTS-native runtimes
- * (opencode/kilo/kimi) incorrectly emitting `.claude/CLAUDE.md`. Pure: no I/O.
+ * (opencode/kilo/kimi) incorrectly emitting `.claude/CLAUDE.md`. Pure: no I/O
+ * (the lazy `require` below reads a static generated module, not the disk).
+ *
+ * Descriptor-driven (ADR-1239 / #2096): antigravity's `GEMINI.md` is folded
+ * from a hardcoded `canonical === 'antigravity'` literal into a read of
+ * `runtime.hostBehaviors.projectInstructionFile`. claude/copilot stay
+ * hardcoded (out of scope here) mirroring `getDirName` below, which already
+ * lazy-`require`s `capability-registry.cjs` inside the function body to
+ * avoid a circular dependency at module load.
  */
 function getProjectInstructionFile(runtime) {
     const canonical = canonicalizeRuntimeName(runtime);
@@ -140,17 +149,46 @@ function getProjectInstructionFile(runtime) {
         return '.claude/CLAUDE.md';
     if (canonical === 'copilot')
         return '.github/copilot-instructions.md';
-    if (canonical === 'antigravity')
-        return 'GEMINI.md';
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { runtimes } = require('./capability-registry.cjs');
+    const declared = canonical ? runtimes[canonical]?.runtime?.hostBehaviors?.projectInstructionFile : undefined;
+    if (typeof declared === 'string' && declared.length > 0)
+        return declared;
     // codex, opencode, kilo, kimi, AND unknown/future runtimes all default to
     // root AGENTS.md (the safe cross-agent instruction file).
     return 'AGENTS.md';
 }
+/**
+ * Sentinel returned by {@link getDirName} for a runtime whose
+ * `runtime.configHome.kind === 'none'` (#2103 — a Marketplace/VSIX-distributed
+ * host with NO file-projected config directory at all, e.g. VS Code).
+ *
+ * A plain fallback to `.claude` would be actively wrong here — it would read
+ * as "this runtime installs into .claude", which is false. This sentinel is
+ * a string (not `null`) so `getDirName`'s return type and every existing
+ * template-literal call site (`` `${getDirName(runtime)}` `` in bin/install.js
+ * / runtime-artifact-conversion.cjs / install-engine.cjs) are unaffected —
+ * widening the return type to `string | null` would require auditing every
+ * call site for a null-check, which is out of scope for a runtime that is
+ * never actually dispatched through those installer paths (vscode has no
+ * install surface — see capabilities/vscode/capability.json). The value is
+ * deliberately NOT a plausible dot-dir name (parens are not valid in a
+ * directory-name token GSD would ever generate) so a future caller that
+ * mistakenly interpolates it into a path fails obviously rather than
+ * silently colliding with a real directory.
+ */
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
 /**
  * Map a canonical runtime id to its on-disk local config directory name
  * (e.g. `cursor` -> `.cursor`, `windsurf` -> `.windsurf`). Unknown/empty inputs
  * fall back to `.claude`.
  *
+ * #2103: a runtime whose descriptor declares `configHome.kind === 'none'`
+ * (no file-projected config directory at all) returns
+ * {@link NO_LOCAL_CONFIG_DIR_SENTINEL} instead of falling through to
+ * `.claude` — it has no local config dir, and `.claude` would be a wrong
+ * answer, not just an imprecise one.
+ *
  * Pure runtime-identity projection. Relocated from `bin/install.js` per
  * ADR-1508 (epic #1507, #1510 Phase 1) so the Runtime Artifact Conversion
  * Module's rewrite engine can consume it without importing the installer.
@@ -161,9 +199,12 @@ function getDirName(runtime) {
         return '.claude';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { runtimes } = require('./capability-registry.cjs');
-    const dir = runtimes[runtime]?.runtime?.localConfigDir;
+    const entry = runtimes[runtime]?.runtime;
+    const dir = entry?.localConfigDir;
     if (typeof dir === 'string' && dir.length > 0)
         return dir;
+    if (entry?.configHome?.kind === 'none')
+        return exports.NO_LOCAL_CONFIG_DIR_SENTINEL;
     return '.claude';
 }
 /**
@@ -210,6 +251,12 @@ const RUNTIME_LABELS = {
     codebuddy: 'CodeBuddy',
     cline: 'Cline',
     zcode: 'ZCode',
+    pi: 'pi',
+    // #2103: vscode is a registered (role:runtime) capability for validator +
+    // host-integration coverage, even though it is never CLI-installed (no
+    // --vscode flag — see NON_INSTALLABLE_RUNTIMES in tests/runtime-flags.test.cjs).
+    // A distinct label is still required by the drift guard below.
+    vscode: 'VS Code',
 };
 /**
  * Map a canonical runtime id to its short display label for the
@@ -257,6 +304,12 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
     cline: "'.cline'",
     kimi: "'.config', 'agents'",
     zcode: "'.zcode'",
+    // pi's global config home is ~/.pi/agent (configHome: dot-home-nested,
+    // parent '.pi', name 'agent' — capabilities/pi/capability.json), matching
+    // resolveConfigHomeFromDescriptor's `path.join(home, parent, name)` for the
+    // no-probe dot-home-nested case (src/runtime-homes.cts). Two-segment
+    // path.join args, same shape as opencode/kilo/kimi above.
+    pi: "'.pi', 'agent'",
 };
 /**
  * Return the global config-home path-fragment source snippet for a runtime
@@ -277,9 +330,14 @@ function getGlobalConfigHomeFragment(runtime) {
  * function declaration block (the add-a-host tax ADR-1239 Phase B / #1679 AC2
  * removes).
  */
+// #2094: 'trae' stays here — bin/install.js's agents-converter dispatch
+// (convertClaudeAgentToTraeAgent selection) still reads isTrae directly.
+// Removing it is gated on migrating that runtime-keyed `else if` chain to a
+// cross-runtime agents-dispatch table (out of scope for #2094, which only
+// folds the shared-hooks-install skip).
 const RUNTIME_FLAG_IDS = Object.freeze([
     'opencode', 'kilo', 'codex', 'copilot', 'antigravity', 'cursor',
-    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode',
+    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode', 'pi',
 ]);
 /**
  * Return a frozen map of `is<Runtime>` boolean predicates for the given runtime

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

@@ -34,7 +34,6 @@ exports.safeJsonParse = safeJsonParse;
 exports.validatePhaseNumber = validatePhaseNumber;
 exports.validateFieldName = validateFieldName;
 exports.validatePromptStructure = validatePromptStructure;
-exports.scanEntropyAnomalies = scanEntropyAnomalies;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -443,38 +442,9 @@ function validatePromptStructure(text, fileType) {
     }
     return { valid: violations.length === 0, violations };
 }
-// ─── Layer 4: Paragraph-Level Entropy Anomaly Detection ─────────────────────────────────────────────────────────────────────
-function shannonEntropy(text) {
-    if (!text || text.length === 0)
-        return 0;
-    const freq = {};
-    for (const ch of text) {
-        freq[ch] = (freq[ch] || 0) + 1;
-    }
-    const len = text.length;
-    let entropy = 0;
-    for (const count of Object.values(freq)) {
-        const p = count / len;
-        entropy -= p * Math.log2(p);
-    }
-    return entropy;
-}
-/**
- * Scan text for paragraphs with anomalously high Shannon entropy.
- */
-function scanEntropyAnomalies(text) {
-    if (!text || typeof text !== 'string') {
-        return { clean: true, findings: [] };
-    }
-    const findings = [];
-    const paragraphs = text.split(/\n\n+/);
-    for (const para of paragraphs) {
-        if (para.length <= 50)
-            continue;
-        const entropy = shannonEntropy(para);
-        if (entropy > 5.5) {
-            findings.push(`High-entropy paragraph detected (${entropy.toFixed(2)} bits/char) — possible encoded payload`);
-        }
-    }
-    return { clean: findings.length === 0, findings };
-}
+// NOTE (#2198): scanEntropyAnomalies + shannonEntropy were removed as dead exports.
+// They had zero production callers — the live hooks (gsd-prompt-guard.js,
+// gsd-read-injection-scanner.js) inline their own pattern subsets for hook
+// independence and never called these functions. scanForInjection is retained
+// below: it serves as the CI codebase-scanner engine
+// (tests/prompt-injection-scan.security.test.cjs), not as a live hook.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -38,6 +38,8 @@ exports.projectPersistentPathExportActions = projectPersistentPathExportActions;
 exports.execGit = execGit;
 exports.execNpm = execNpm;
 exports.execTool = execTool;
+exports.resolveGsdToolsPath = resolveGsdToolsPath;
+exports.dispatchGsdCommand = dispatchGsdCommand;
 exports.probeTty = probeTty;
 exports.normalizeContent = normalizeContent;
 exports.retryRenameSync = retryRenameSync;
@@ -122,10 +124,18 @@ function formatManagedHookScriptToken(scriptPath, opts = {}) {
         return null;
     return JSON.stringify(scriptPath.replace(/\\/g, '/'));
 }
-function projectLocalHookPrefix({ runtime = 'claude', dirName }) {
+function projectLocalHookPrefix({ runtime: _runtime = 'claude', dirName, hookPathStyle }) {
     if (!dirName)
         return dirName;
-    return (runtime === 'antigravity')
+    // Descriptor-driven (ADR-1239 / #2096): folded from a hardcoded
+    // `runtime === 'antigravity'` literal into the runtime's declared
+    // `hostBehaviors.hookPathStyle`. Runtimes that always run project hooks
+    // with the project dir as cwd (Antigravity today) declare 'raw' and get
+    // the bare dirName; every other runtime keeps the $CLAUDE_PROJECT_DIR-
+    // anchored prefix. `runtime` itself is now unused here but stays in the
+    // signature for call-site/back-compat parity (kept `_`-prefixed to
+    // satisfy no-unused-vars).
+    return (hookPathStyle === 'raw')
         ? dirName
         : `"$CLAUDE_PROJECT_DIR"/${dirName}`;
 }
@@ -461,6 +471,109 @@ function execTool(program, args, opts = {}) {
     });
     return _spawnResult(result, program);
 }
+/**
+ * Resolve the absolute path to gsd-tools.cjs relative to THIS module.
+ *
+ * This file compiles to gsd-core/bin/lib/shell-command-projection.cjs — a
+ * sibling of gsd-core/bin/gsd-tools.cjs — so the relative walk-up is stable
+ * regardless of install location (global/local/dev-repo layouts all ship
+ * gsd-core/bin/ as a unit).
+ */
+function resolveGsdToolsPath() {
+    return node_path_1.default.resolve(__dirname, '..', 'gsd-tools.cjs');
+}
+/**
+ * Subprocess-shim dispatch to gsd-tools.cjs (ADR-1239 #2102 Stage 2).
+ *
+ * No fully-populated in-process command-routing hub exists anywhere in the
+ * tree — every `createHub()` caller (cjs-command-router-adapter.cts,
+ * phase-command-router.cts, command-routing-hub.cts's own tests) builds a
+ * single-family hub for its own narrow purpose. The ONLY dispatch path that
+ * covers the FULL family/subcommand surface is the gsd-tools.cjs CLI itself.
+ * This mirrors the SUBPROCESS-REUSE precedent already established for the
+ * OpenCode/Kilo hook bridge (see .opencode/plugins/gsd-core.js header:
+ * "Architecture: SUBPROCESS REUSE ... spawns existing hook scripts as child
+ * processes") — the same pattern, applied to command dispatch instead of
+ * hook dispatch.
+ *
+ * Output-flag choice (verified by direct invocation — see #2102 dispatch
+ * notes for the sample invocations): always pass `--raw` (undecorated,
+ * programmatically-consumable stdout on success) and `--json-errors` (a
+ * structured `{ok:false,reason,message}` JSON object on stderr, with a
+ * non-zero exit, instead of a free-text "Error: ..." line). Both are global
+ * flags accepted by every gsd-tools.cjs family/subcommand, so passing them
+ * unconditionally is safe for the full command surface.
+ *
+ * `family` maps 1:1 onto gsd-tools.cjs's first positional argv token;
+ * `subcommand` (when present) onto the second — e.g.
+ * `{family:'phase', subcommand:'add'}` → `gsd-tools.cjs phase add`. An empty
+ * `subcommand` is omitted entirely (some families, e.g. `config-path`, take
+ * no subcommand).
+ *
+ * NEVER throws. Degrades to `{ ok:false, ... }` on:
+ *   - a missing/invalid "family" (validated locally, no subprocess spawned)
+ *   - ENOENT / a missing gsd-tools.cjs (via the injectable `gsdToolsPath`)
+ *   - a wall-clock timeout (`timedOut:true`, mirroring the
+ *     `signal === 'SIGTERM' && error.code === 'ETIMEDOUT'` idiom already used
+ *     by worktree-safety.cts)
+ *   - any other unanticipated throw from the underlying spawn (defensive
+ *     try/catch — execTool itself is spawnSync-based and does not throw).
+ */
+function dispatchGsdCommand({ family, subcommand, args = [], cwd, timeout = 30_000, gsdToolsPath, } = {}) {
+    if (typeof family !== 'string' || family.length === 0) {
+        return {
+            ok: false,
+            stdout: '',
+            stderr: 'dispatchGsdCommand requires a non-empty string "family".',
+            code: null,
+            timedOut: false,
+        };
+    }
+    const resolvedCwd = cwd || process.cwd();
+    const toolsPath = gsdToolsPath || resolveGsdToolsPath();
+    const argv = [
+        toolsPath,
+        family,
+        ...(subcommand ? [subcommand] : []),
+        ...(Array.isArray(args) ? args : []),
+        '--cwd', resolvedCwd,
+        '--raw',
+        '--json-errors',
+    ];
+    let result;
+    try {
+        result = execTool(process.execPath, argv, { cwd: resolvedCwd, timeout });
+    }
+    catch (e) {
+        // Defensive belt-and-suspenders: execTool is spawnSync-based and does not
+        // throw today, but a degraded result here keeps this seam's no-throw
+        // contract true even under an unanticipated future failure mode.
+        return {
+            ok: false,
+            stdout: '',
+            stderr: e instanceof Error ? e.message : String(e),
+            code: null,
+            timedOut: false,
+        };
+    }
+    // Mirrors the established `result.error && (result.error as
+    // NodeJS.ErrnoException).code === ...` idiom (graphify.cts, worktree-safety.cts):
+    // narrow away null via `!== null` FIRST, then cast — asserting `Error | null`
+    // to `NodeJS.ErrnoException | null` directly (paired with optional chaining)
+    // trips a typescript-eslint no-unnecessary-type-assertion false positive for
+    // this exact narrowing shape (all of ErrnoException's extra fields over Error
+    // are optional).
+    const timedOut = result.signal === 'SIGTERM'
+        && result.error !== null
+        && result.error.code === 'ETIMEDOUT';
+    return {
+        ok: result.exitCode === 0 && !timedOut,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        code: result.exitCode,
+        timedOut,
+    };
+}
 function probeTty(opts = {}) {
     const platform = opts.platform ?? process.platform;
     if (platform === 'win32')

package/gsd-core/bin/lib/stale-bake-guard.cjs

@@ -3,9 +3,10 @@
 /**
  * Stale-bake guard for static-frontmatter runtimes (#1688, follow-up to #1650).
  *
- * Runtimes `codex` and `opencode` bake the resolved model ID into each agent's
- * static config at install time (bin/install.js ~5667-5767 for codex,
- * ~10008-10026 for opencode). Their task/spawn_agent interfaces do not accept
+ * Runtimes `codex`, `opencode`, and (since #2093) `kilo` bake the resolved
+ * model ID into each agent's static config at install time (bin/install.js
+ * ~5667-5767 for codex, ~10008-10026 for opencode, and the adjacent kilo
+ * branch added by #2093). Their task/spawn_agent interfaces do not accept
  * an inline `model` parameter, so editing `model_overrides` in
  * `.planning/config.json` or `~/.gsd/defaults.json` has NO effect until the
  * user re-runs `gsd install <runtime>` (or `gsd update`). The failure is
@@ -25,9 +26,17 @@ const os = require('os');
  * Runtimes whose agent config is static frontmatter/TOML baked at install time.
  * MUST stay in sync with the bake paths in bin/install.js. The parity test in
  * tests/stale-bake-guard.test.cjs asserts this matches the runtimes that
- * actually emit a baked model: line id #2256 (opencode) and #49/#2256 (codex).
+ * actually emit a baked model: line id #2256 (opencode), #49/#2256 (codex),
+ * and #2093 (kilo).
  */
-const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'opencode']);
+const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'kilo', 'opencode']);
+
+/** Per-runtime `gsd install` flag, for the remediation hint in the warning. */
+const INSTALL_FLAG_BY_RUNTIME = Object.freeze({
+  codex: '--codex',
+  opencode: '--opencode',
+  kilo: '--kilo',
+});
 
 const _warnedKeys = new Set();
 
@@ -55,7 +64,7 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
   const signal = detectStaleBake({ runtime, configMtimeMs, agentMtimeMs });
   if (!signal) return '';
   const configDate = new Date(configMtimeMs).toISOString();
-  const installFlag = runtime === 'opencode' ? '--opencode' : '--codex';
+  const installFlag = INSTALL_FLAG_BY_RUNTIME[runtime] || `--${runtime}`;
   return [
     `gsd: model config in ${configPath} changed since agents were last baked (${configDate}).`,
     `     Static-frontmatter runtime '${runtime}' ignores the new model_overrides`,
@@ -79,13 +88,24 @@ function resolveRuntimeFromConfig(config) {
 
 /**
  * Resolve the install root for a runtime's agent files, honoring the same env
- * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR). Returns the
- * absolute directory or `null` for unsupported runtimes.
+ * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR, KILO_CONFIG_DIR).
+ * Returns the absolute directory or `null` for unsupported runtimes.
  */
 function resolveAgentDir(runtime, { env = process.env, homedir = os.homedir } = {}) {
   if (runtime === 'opencode') {
     const base = (env.OPENCODE_CONFIG_DIR && String(env.OPENCODE_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'opencode');
-    return path.join(base, 'agent');
+    // #2093 fix: the installer writes agents to `<base>/agents` (plural — see
+    // bin/install.js's universal `agentsDest = path.join(targetDir, 'agents')`,
+    // verified against a live `--opencode --global` install). The prior
+    // singular `agent` never matched the real install output, so this guard's
+    // `findOldestAgentMtime` always hit ENOENT and warnIfStaleBake was a
+    // silent no-op for opencode in production — discovered while wiring the
+    // parallel kilo entry below (same bake mechanism, #2093).
+    return path.join(base, 'agents');
+  }
+  if (runtime === 'kilo') {
+    const base = (env.KILO_CONFIG_DIR && String(env.KILO_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'kilo');
+    return path.join(base, 'agents');
   }
   if (runtime === 'codex') {
     const base = (env.CODEX_HOME && String(env.CODEX_HOME).trim()) || path.join(homedir(), '.codex');
@@ -148,7 +168,7 @@ function findOldestAgentMtime(runtime, { env = process.env, homedir = os.homedir
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith('gsd-')) continue;
-    const isAgentFile = (runtime === 'opencode' && entry.name.endsWith('.md'))
+    const isAgentFile = ((runtime === 'opencode' || runtime === 'kilo') && entry.name.endsWith('.md'))
       || (runtime === 'codex' && (entry.name.endsWith('.toml') || entry.name.endsWith('.md')));
     if (!isAgentFile) continue;
     try {

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

@@ -472,10 +472,14 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
     // Normalize: allow legacy string context for backward-compat with internal callers
     const kindName = (typeof kind === 'string') ? kind : kind.kind;
     const kindPrefix = (typeof kind === 'object' && kind !== null) ? kind.prefix : 'gsd-';
-    // #1575: copilot agents are renamed .md -> .agent.md at copy time, mirroring
-    // the inline agent loop in bin/install.js (line ~9118). Other runtimes keep
-    // the staged filename verbatim.
-    const isCopilotAgents = runtime === 'copilot' && kindName === 'agents';
+    // #1575 / #2103: agent files are renamed .md -> <agentFileExtension> at copy
+    // time when the runtime's descriptor declares hostBehaviors.agentFileExtension
+    // (e.g. copilot's '.agent.md'), mirroring install-engine.cts's staged-copy
+    // loop (`_copyStaged`) — ONE descriptor read shared by both surfaces instead
+    // of a duplicated hardcoded `runtime === 'copilot'` literal. Other runtimes
+    // (no agentFileExtension declared) keep the staged filename verbatim.
+    const _agentExt = runtime ? runtimeArtifactConversion.agentFileExtensionFor(runtime) : undefined;
+    const isRenamedAgents = !!_agentExt && kindName === 'agents';
     if (kindName === 'skills') {
         // Skills kind: work with directories, not files.
         // Each staged entry is a directory named ${prefix}${stem}.
@@ -510,8 +514,8 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
         const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
         const stagedDestNames = new Set();
         for (const file of stagedFiles) {
-            const destName = isCopilotAgents
-                ? file.replace(/\.md$/, '.agent.md')
+            const destName = isRenamedAgents
+                ? file.replace(/\.md$/, _agentExt)
                 : (kindName === 'agents' || namespacedByDir)
                     ? file
                     : `${kindPrefix}${file.slice(0, -3)}.md`;