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

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -6,9 +6,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
  * Runtime artifact layout module — resolves the artifact directory shapes
  * (commands, agents, skills) for each supported runtime.
  *
- * grok is intentionally absent: it is in runtime-homes.cjs but not wired
- * here. The TypeError on unknown runtime is the loud-fail signal that a
- * runtime was added to the homes list without a layout entry.
+ * grok is intentionally absent: it is in runtime-homes.cjs but has no runtime
+ * capability descriptor. The TypeError on unknown runtime is the loud-fail
+ * signal that a runtime was added without an artifact layout descriptor.
  *
  * ADR-457 build-at-publish: the hand-written bin/lib/runtime-artifact-layout.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
@@ -19,7 +19,10 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
-const { stageSkillsForProfile, stageAgentsForProfile, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
+const { stageSkillsForProfile, stageAgentsForProfile, stageAgentsForRuntimeWithConverter, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
+const conversionExports = runtimeArtifactConversion;
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 /**
@@ -125,14 +128,6 @@ function findAgentsSourceRoot(runtimeConfigDir) {
     throw new Error(`findAgentsSourceRoot: could not locate agents/ from ${__dirname}`);
 }
 // ---------------------------------------------------------------------------
-// Allowlisted runtimes
-// ---------------------------------------------------------------------------
-const ALLOWED_RUNTIMES = new Set([
-    'claude', 'cursor', 'gemini', 'codex', 'copilot', 'antigravity',
-    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy',
-    'cline', 'kimi', 'opencode', 'kilo',
-]);
-// ---------------------------------------------------------------------------
 // Layout table builders
 // ---------------------------------------------------------------------------
 function commandsKind(destSubpath, prefix, configDir) {
@@ -151,14 +146,42 @@ function agentsKind(destSubpath, prefix, configDir) {
         stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
     };
 }
+/**
+ * Build a converted-agents kind descriptor for runtimes whose agent `.md` files
+ * need runtime-specific frontmatter/body conversion (e.g. Copilot, Cursor, Codex).
+ *
+ * Unlike `agentsKind` (which raw-copies source files), this kind applies
+ * `converterName` from Runtime Artifact Conversion exports to each agent file
+ * during staging, writing flat `${name}.md` files to the staged directory.
+ *
+ * Agent filenames are preserved verbatim (the prefix is already embedded in the
+ * agent stem — e.g. `gsd-planner.md`).
+ *
+ * Mirrors the `convertedCommandsKind` pattern (#785).
+ *
+ * @param destSubpath   destination subpath within configDir (e.g. 'agents')
+ * @param prefix        filename prefix (informational; not applied here)
+ * @param converterName name of converter function in Runtime Artifact Conversion exports
+ * @param configDir     runtime config dir (for .gsd-source marker resolution)
+ */
+function convertedAgentsKind(destSubpath, prefix, converterName, configDir) {
+    return {
+        kind: 'agents',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const converter = conversionExports[converterName];
+            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter);
+        },
+    };
+}
 function kimiAgentsKind(destSubpath, prefix, configDir) {
     return {
         kind: 'kimi-agents',
         destSubpath,
         prefix,
         stage: (resolved) => {
-            const installExports = getInstallExports();
-            const buildKimiAgentArtifacts = installExports['buildKimiAgentArtifacts'];
+            const buildKimiAgentArtifacts = conversionExports['buildKimiAgentArtifacts'];
             const stagedAgents = stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved);
             const subagents = [];
             if (node_fs_1.default.existsSync(stagedAgents)) {
@@ -193,7 +216,7 @@ function kimiAgentsKind(destSubpath, prefix, configDir) {
  *
  * @param destSubpath
  * @param prefix
- * @param converterName  name of converter function in bin/install.js exports
+ * @param converterName  name of converter function in Runtime Artifact Conversion exports
  * @param runtime        canonical runtime ID (gates Hermes/Qwen branding in converter)
  * @param configDir      runtime config dir (for .gsd-source marker resolution)
  * @param nested         if true, nest concrete skills under their ns-* routers (#69)
@@ -208,15 +231,16 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
         destSubpath,
         prefix,
         stage: (resolved) => {
-            const installExports = getInstallExports();
-            const realConverter = installExports[converterName];
+            const realConverter = conversionExports[converterName];
             // Compute cmdNames once per stage call for performance (#3583).
             // Extra trailing args are ignored by converters that don't need them. The
             // isGlobal flag is the 5th positional (NOT the 3rd): the 3rd positional is
             // `runtime` for the claude/kimi/cline converters, so the scope-aware
             // converters (antigravity, copilot) read isGlobal from position 5 to avoid
             // colliding with `runtime` and always taking the global branch.
-            const cmdNames = installExports.readGsdCommandNames();
+            const cmdNames = conversionExports.readGsdCommandNames
+                ? conversionExports.readGsdCommandNames()
+                : [];
             const isGlobal = scope === 'global';
             const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames, isGlobal);
             return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix, nested);
@@ -228,7 +252,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
  * commands directory with per-file conversion (e.g. Cursor 1.6 slash commands).
  *
  * Unlike `commandsKind` (which passes raw source files through), this kind
- * applies `converterName` from bin/install.js exports to each file during
+ * applies `converterName` from Runtime Artifact Conversion exports to each file during
  * staging, writing flat `${prefix}${stem}.md` files to the staged directory.
  *
  * The staged files are then written by `_copyStaged` (commands branch) which
@@ -236,7 +260,7 @@ function skillsKind(destSubpath, prefix, converterName, runtime, configDir, nest
  *
  * @param destSubpath   destination subpath within configDir (e.g. 'commands')
  * @param prefix        filename prefix, e.g. 'gsd-'
- * @param converterName name of converter function in bin/install.js exports
+ * @param converterName name of converter function in Runtime Artifact Conversion exports
  * @param configDir     runtime config dir (for .gsd-source marker resolution)
  */
 function convertedCommandsKind(destSubpath, prefix, converterName, configDir) {
@@ -245,13 +269,11 @@ function convertedCommandsKind(destSubpath, prefix, converterName, configDir) {
         destSubpath,
         prefix,
         stage: (resolved) => {
-            const installExports = getInstallExports();
-            const converter = installExports[converterName];
+            const converter = conversionExports[converterName];
             return stageCommandsForRuntimeFlat(findInstallSourceRoot(configDir), resolved, converter, prefix);
         },
     };
 }
-/** Lazy registry accessor — mirrors pattern from 5b/5c (runtime-homes.cts). */
 function getRegistry() {
     return _require('./capability-registry.cjs');
 }
@@ -269,7 +291,10 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
             }
             return convertedCommandsKind(destSubpath, prefix, converter, configDir);
         case 'agents':
-            return agentsKind(destSubpath, prefix, configDir);
+            if (converter == null) {
+                return agentsKind(destSubpath, prefix, configDir);
+            }
+            return convertedAgentsKind(destSubpath, prefix, converter, configDir);
         case 'skills':
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);
@@ -288,22 +313,21 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
  * instead of a hardcoded switch statement.
  */
 function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
+    return resolveRuntimeArtifactLayoutFromRegistry(getRegistry(), runtime, configDir, scope);
+}
+function resolveRuntimeArtifactLayoutFromRegistry(registry, runtime, configDir, scope = 'global') {
     if (typeof configDir !== 'string' || configDir === '') {
         throw new TypeError('configDir must be a non-empty string');
     }
     if (scope !== 'local' && scope !== 'global') {
         throw new TypeError('scope must be "local" or "global"');
     }
-    if (!ALLOWED_RUNTIMES.has(runtime)) {
-        throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
-    }
-    const desc = getRegistry().runtimes[runtime]?.runtime?.artifactLayout;
+    const desc = registry.runtimes[runtime]?.runtime?.artifactLayout;
     if (!desc) {
-        // Runtime is in ALLOWED_RUNTIMES but has no descriptor — reproduce old default: throw.
         throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
     }
     const entries = desc[scope] ?? [];
     const kinds = entries.map((entry) => dispatchKindEntry(entry, runtime, configDir, scope));
     return { runtime, configDir, scope, kinds };
 }
-module.exports = { resolveRuntimeArtifactLayout, findInstallSourceRoot, getInstallExports };
+module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot, getInstallExports };

package/gsd-core/bin/lib/runtime-config-adapter-registry.cjs

@@ -27,9 +27,8 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { runtimes } = require('./capability-registry.cjs');
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
+/** Valid sandboxTier enum values — mirrors the gen-capability-registry validator vocabulary. */
+const VALID_SANDBOX_TIERS = new Set(['none', 'codex-agent-sandbox']);
 /** The complete set of 16 supported runtimes for config-adapter dispatch. */
 const ALLOWED_CONFIG_RUNTIMES = new Set(Object.entries(runtimes)
     .filter(([, cap]) => cap && cap.runtime && typeof cap.runtime['installSurface'] === 'string')
@@ -63,6 +62,29 @@ function resolveRuntimeConfigIntent(runtime) {
         finishPermissionWriter: permissionWriter == null ? null : permissionWriter,
     };
 }
+function resolveInstallPlanFromRuntimes(runtimeDescriptors, runtime) {
+    const desc = runtimeDescriptors[runtime]?.runtime;
+    if (!desc)
+        throw new TypeError(`Unknown runtime for install plan: ${runtime}`);
+    if (desc['hooksSurface'] == null) {
+        throw new TypeError(`runtime.hooksSurface is required for install plan: ${runtime}`);
+    }
+    const sandboxTier = desc['sandboxTier'];
+    if (typeof sandboxTier !== 'string' || !VALID_SANDBOX_TIERS.has(sandboxTier)) {
+        throw new TypeError(`Runtime '${runtime}' has a missing or invalid sandboxTier descriptor axis: ${JSON.stringify(sandboxTier)}`);
+    }
+    const permissionWriter = desc['permissionWriter'];
+    return {
+        runtime,
+        installSurface: desc['installSurface'],
+        writesSharedSettings: desc['writesSharedSettings'],
+        finishPermissionWriter: permissionWriter == null ? null : permissionWriter,
+        hookEvents: desc['hookEvents'],
+        extendedHookEvents: Array.isArray(desc['extendedHookEvents']) ? [...desc['extendedHookEvents']] : [],
+        hooksSurface: desc['hooksSurface'],
+        sandboxTier,
+    };
+}
 /**
  * Resolve the complete install plan for a given runtime.
  *
@@ -76,20 +98,6 @@ function resolveRuntimeConfigIntent(runtime) {
  * @throws {TypeError} if runtime is not a known supported runtime.
  */
 function resolveInstallPlan(runtime) {
-    const desc = runtimes[runtime]?.runtime;
-    if (!desc)
-        throw new TypeError(`Unknown runtime for install plan: ${runtime}`);
-    const configIntent = resolveRuntimeConfigIntent(runtime);
-    return {
-        runtime,
-        installSurface: configIntent.installSurface,
-        writesSharedSettings: configIntent.writesSharedSettings,
-        finishPermissionWriter: configIntent.finishPermissionWriter,
-        hookEvents: desc['hookEvents'],
-        extendedHookEvents: Array.isArray(desc['extendedHookEvents']) ? desc['extendedHookEvents'] : [],
-        hooksSurface: desc['hooksSurface'] != null
-            ? desc['hooksSurface']
-            : ((runtime === 'opencode' || runtime === 'kilo') ? 'none' : 'settings-json'),
-    };
+    return resolveInstallPlanFromRuntimes(runtimes, runtime);
 }
-module.exports = { resolveRuntimeConfigIntent, resolveInstallPlan, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };
+module.exports = { resolveRuntimeConfigIntent, resolveInstallPlan, resolveInstallPlanFromRuntimes, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };

package/gsd-core/bin/lib/runtime-homes.cjs

@@ -38,6 +38,7 @@ exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
 exports.resolveKimiGlobalDir = resolveKimiGlobalDir;
 exports.getGlobalConfigDir = getGlobalConfigDir;
+exports.resolveSkillsBaseFromDescriptor = resolveSkillsBaseFromDescriptor;
 exports.getGlobalSkillsBase = getGlobalSkillsBase;
 exports.getGlobalSkillDir = getGlobalSkillDir;
 exports.getGlobalSkillDisplayPath = getGlobalSkillDisplayPath;
@@ -54,6 +55,17 @@ function expandTilde(p) {
         return node_path_1.default.join(node_os_1.default.homedir(), p.slice(1));
     return p;
 }
+function resolveDescriptorWithOptions(configHome) {
+    return resolveConfigHomeFromDescriptor(configHome, {
+        env: process.env,
+        home: node_os_1.default.homedir(),
+        existsSync: node_fs_1.default.existsSync,
+    });
+}
+function getRegistry() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require('./capability-registry.cjs');
+}
 /**
  * Resolve a configHome descriptor to an absolute directory path.
  *
@@ -209,15 +221,10 @@ function getGlobalConfigDir(runtime, explicitDir) {
         return env['GROK_AGENTS_HOME'] ? expandTilde(env['GROK_AGENTS_HOME']) : node_path_1.default.join(node_os_1.default.homedir(), '.agents');
     }
     // ── Descriptor-driven: look up in capability-registry ────────────────────
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { runtimes } = require('./capability-registry.cjs');
+    const { runtimes } = getRegistry();
     const runtimeEntry = runtimes[runtime];
     if (runtimeEntry?.runtime?.configHome) {
-        return resolveConfigHomeFromDescriptor(runtimeEntry.runtime.configHome, {
-            env: process.env,
-            home: node_os_1.default.homedir(),
-            existsSync: node_fs_1.default.existsSync,
-        });
+        return resolveDescriptorWithOptions(runtimeEntry.runtime.configHome);
     }
     // ── Default (unknown runtime → Claude fallback) ───────────────────────────
     const env = process.env;
@@ -225,22 +232,21 @@ function getGlobalConfigDir(runtime, explicitDir) {
 }
 /**
  * Return the global skills base directory for the given runtime.
- * Most runtimes: <configDir>/skills
- * Hermes: <configDir>/skills/gsd  (nested category layout — #2841)
- * Cline ≥ v3.48.0: <configDir>/skills  (SKILL.md-based global skills — #782)
+ * Descriptor-backed runtimes derive the base home from configHome.skillsHome
+ * when present, then append the first global skills artifact destSubpath.
  */
+function resolveSkillsBaseFromDescriptor(configHome, opts = {}, skillsDestSubpath = 'skills') {
+    const baseDescriptor = configHome.skillsHome ?? configHome;
+    const base = resolveConfigHomeFromDescriptor(baseDescriptor, opts);
+    return node_path_1.default.join(base, skillsDestSubpath);
+}
 function getGlobalSkillsBase(runtime) {
-    if (runtime === 'hermes') {
-        const configDir = getGlobalConfigDir(runtime);
-        return node_path_1.default.join(configDir, 'skills', 'gsd');
+    const runtimeEntry = getRegistry().runtimes[runtime];
+    const descriptor = runtimeEntry?.runtime;
+    const globalSkillsKind = descriptor?.artifactLayout?.global?.find((entry) => entry.kind === 'skills');
+    if (descriptor?.configHome && globalSkillsKind?.destSubpath) {
+        return resolveSkillsBaseFromDescriptor(descriptor.configHome, { env: process.env, home: node_os_1.default.homedir(), existsSync: node_fs_1.default.existsSync }, globalSkillsKind.destSubpath);
     }
-    // Kilo Code discovers global skills from ~/.kilo/skills/ (HOME-relative),
-    // independent of the XDG-based config dir (~/.config/kilo) used for commands.
-    // See: https://kilo.ai/docs/customize/skills
-    // "Global skills are located in the `.kilo` directory within your Home
-    //  directory: ~/.kilo/skills/"
-    if (runtime === 'kilo')
-        return node_path_1.default.join(node_os_1.default.homedir(), '.kilo', 'skills');
     const configDir = getGlobalConfigDir(runtime);
     return node_path_1.default.join(configDir, 'skills');
 }

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

@@ -42,9 +42,10 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
         args,
         subcommands: ['load', 'complete-phase', ...command_aliases_cjs_1.STATE_SUBCOMMANDS.filter((s) => s !== 'load')],
         defaultSubcommand: 'load',
-        unsupported: {
-            'add-roadmap-evolution': 'state add-roadmap-evolution is SDK-only. Use: gsd-tools query state.add-roadmap-evolution ...',
-        },
+        // No SDK-only state subcommands remain: add-roadmap-evolution was the last
+        // holdout after the SDK retirement (ADR-0174) and is now implemented in CJS
+        // (handler below). See #1140.
+        unsupported: {},
         error,
         cwd,
         raw,
@@ -113,6 +114,17 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text', 'text-file']);
                 state.cmdStateAddBlocker(cwd, { text: strArg(a, 'text'), text_file: strArg(a, 'text-file') }, raw);
             },
+            'add-roadmap-evolution': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'action', 'after', 'note', 'note-file'], ['urgent']);
+                state.cmdStateAddRoadmapEvolution(cwd, {
+                    phase: strArg(a, 'phase'),
+                    action: strArg(a, 'action'),
+                    after: strArg(a, 'after'),
+                    note: strArg(a, 'note'),
+                    note_file: strArg(a, 'note-file'),
+                    urgent: a['urgent'] === true,
+                }, raw);
+            },
             'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text']), 'text'), raw),
             'record-session': () => {
                 const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['stopped-at', 'resume-file']);

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

@@ -31,26 +31,71 @@ function existingProgressExceedsDerived(existingProgress, derivedProgress, key)
     const derived = toFiniteNumber(derivedProgress[key]);
     return existing !== null && derived !== null && existing > derived;
 }
+/**
+ * Return true if a pipe-table row's first cell is a separator cell (`---`
+ * variants) rather than a field name.  Prevents the separator row
+ * `| --- | --- |` from being treated as a field named "---".
+ */
+function isTableSeparatorRow(firstCell) {
+    // A separator cell contains only dashes, colons (alignment hints), and whitespace.
+    return /^[\s\-:]+$/.test(firstCell.trim());
+}
+/**
+ * Build a regex that matches a pipe-table row `| FieldName | value |` for the
+ * given (already-escaped) field name.  The match is case-insensitive and
+ * tolerates variable amounts of whitespace around the cell contents.
+ *
+ * Capture group 1: leading pipe + whitespace before the field cell
+ * Capture group 2: the field name cell text (trimmed)
+ * Capture group 3: whitespace between field cell and separator pipe
+ * Capture group 4: the value cell text (trimmed)
+ * Capture group 5: trailing whitespace + closing pipe(s)
+ *
+ * We use a single-line match (`m` flag so ^ anchors work on each line) to
+ * avoid cross-row replacement.
+ */
+function tableRowPattern(escapedFieldName) {
+    return new RegExp(`^(\\|[ \\t]*)(${escapedFieldName})([ \\t]*\\|[ \\t]*)([^|\\n]*?)([ \\t]*\\|[ \\t]*)$`, 'im');
+}
 function stateExtractField(content, fieldName) {
     const escaped = escapeRegex(fieldName);
+    // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
     const boldMatch = content.match(boldPattern);
     if (boldMatch)
         return boldMatch[1].trim();
+    // Plain line-start format: FieldName: value
     const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
     const plainMatch = content.match(plainPattern);
-    return plainMatch ? plainMatch[1].trim() : null;
+    if (plainMatch)
+        return plainMatch[1].trim();
+    // Pipe-table format: | FieldName | value |
+    // (Separator rows such as `| --- | --- |` are excluded.)
+    const tableMatch = content.match(tableRowPattern(escaped));
+    if (tableMatch && !isTableSeparatorRow(tableMatch[2]))
+        return tableMatch[4].trim();
+    return null;
 }
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = escapeRegex(fieldName);
+    // Bold inline format: **FieldName:** value
     const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
     if (boldPattern.test(content)) {
         return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
     }
+    // Plain line-start format: FieldName: value
     const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
     if (plainPattern.test(content)) {
         return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
     }
+    // Pipe-table format: | FieldName | value |
+    // Preserve the surrounding pipe/whitespace structure; only swap the value cell.
+    const tblPat = tableRowPattern(escaped);
+    const tblMatch = content.match(tblPat);
+    if (tblMatch && !isTableSeparatorRow(tblMatch[2])) {
+        // Reconstruct the row, preserving the original surrounding whitespace/pipes.
+        return content.replace(tblPat, (_m, leadPipe, fieldCell, midPipe, _oldVal, trailPipe) => `${leadPipe}${fieldCell}${midPipe}${newValue}${trailPipe}`);
+    }
     return null;
 }
 function stateReplaceFieldWithFallback(content, primary, fallback, value) {