@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/runtime-artifact-install-plan.cjs

@@ -10,6 +10,7 @@
 const _require = require;
 const path = _require('node:path');
 const { tryWithinRootLexical } = _require('./security.cjs');
+const { hostBehaviorsFor } = _require('./runtime-name-policy.cjs');
 // #2870: InstallScope is owned by install-scope.cts, not re-declared here.
 // `isGlobalScope` centralizes the `scope === 'global'` boolean projection
 // this module needs at `_computePathPrefix`'s `isGlobal: boolean` boundary
@@ -90,9 +91,11 @@ function createRuntimeArtifactInstallPlan(args) {
     // `undefined` here) — `isGlobalScope` projects it to the boolean
     // `_computePathPrefix`'s existing `isGlobal: boolean` API requires.
     const isGlobal = (0, install_scope_cjs_1.isGlobalScope)(scope);
-    const isOpencode = layout.runtime === 'opencode';
+    const isOpencode = hostBehaviorsFor(layout.runtime).opencodePathPrefix === true;
     const isWindowsHost = (platform ?? process.platform) === 'win32';
-    const pathPrefix = conversionExports._computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir });
+    // #4377: descriptor-derived local dir name, so an opted-in local install
+    // emits a project-relative prefix instead of this checkout's absolute path.
+    const pathPrefix = conversionExports._computePathPrefix({ isGlobal, isOpencode, isWindowsHost, resolvedTarget, homeDir, localDirName: conversionExports._localIncludeDirName(layout.runtime) });
     const attribution = resolveAttribution ? resolveAttribution(layout.runtime) : undefined;
     // #2875 Part 2 (row I1): layout.configDir IS the install root the inline
     // agent loop called `targetDir` — same value, same resolution.

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

@@ -957,4 +957,60 @@ function resolveTriggerSurface(runtime, scopes, opts) {
     }
     return surfaces;
 }
-module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot, resolveTriggerSurface, isNamespacedByDir, composeCommandFilename };
+// ---------------------------------------------------------------------------
+// The advertised "next step" command (#5215, ADR-5057 §5 Phase 12).
+//
+// What the installer tells a user to run is a projection of what the runtime
+// registered: the `new-project` trigger the Trigger Surface resolves for the
+// install scope. It is never a per-runtime literal, so a runtime that registers
+// no such trigger (pi's native extension registers only `/gsd`; windsurf's
+// global layout registers nothing) cannot be told to run one (#4567).
+// ---------------------------------------------------------------------------
+/** The cross-agent default for an id GSD cannot know (ADR-5057 §5 Phase 10 amendment). */
+const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
+/**
+ * How a host invokes a registered trigger. Presentation only — whether the
+ * trigger exists is decided by the registered surface, not by this table. A
+ * runtime absent here is invoked as `/<trigger>`.
+ */
+const TRIGGER_INVOCATION = {
+    codex: (trigger) => `$${trigger}`,
+    cursor: (trigger) => `${trigger} (mention the skill name)`,
+    kimi: (trigger) => `/skill:${trigger}`,
+};
+/**
+ * The command a native-extension runtime registers instead of per-workflow
+ * triggers: the extension file's stem as a slash command (pi's `gsd.js`
+ * registers `/gsd`; pinned by tests/advertised-command-parity.test.cjs against
+ * the extension itself). `null` for a runtime with no native plugin.
+ */
+function nativePluginCommand(runtime) {
+    const descriptor = getTriggerRegistry().runtimes[runtime]?.runtime;
+    const file = descriptor?.hostBehaviors?.nativePlugin?.file;
+    if (typeof file !== 'string' || file.length === 0)
+        return null;
+    const stem = file.replace(/\.[^.]+$/, '');
+    return stem.length > 0 ? `/${stem}` : null;
+}
+/**
+ * The command the installer advertises for starting a project, generated from
+ * the registered trigger surface of `runtime` in `scope`. `unregistered` means
+ * the runtime registers no `new-project` trigger there (`nativeCommand` names
+ * what a native-extension runtime registers instead). An empty or unregistered
+ * id keeps the documented cross-agent default: it names a runtime GSD cannot
+ * know, so no surface exists to project from. Membership is decided up front,
+ * so an error inside the surface resolution is a bug and propagates.
+ */
+function resolveAdvertisedNewProject(runtime, scope) {
+    const known = Boolean(runtime) && Object.prototype.hasOwnProperty.call(getTriggerRegistry().runtimes, runtime);
+    if (!known)
+        return { kind: 'command', command: DEFAULT_NEW_PROJECT_COMMAND };
+    const registered = resolveTriggerSurface(runtime, [scope], { stems: ['new-project'] })[0];
+    if (!registered)
+        return { kind: 'unregistered', nativeCommand: nativePluginCommand(runtime) };
+    const render = Object.prototype.hasOwnProperty.call(TRIGGER_INVOCATION, runtime)
+        ? TRIGGER_INVOCATION[runtime]
+        : (trigger) => `/${trigger}`;
+    return { kind: 'command', command: render(registered.trigger) };
+}
+module.exports = { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry, findInstallSourceRoot, resolveTriggerSurface, resolveAdvertisedNewProject, isNamespacedByDir, composeCommandFilename };

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

@@ -49,6 +49,7 @@ exports.getGlobalSkillDisplayPath = getGlobalSkillDisplayPath;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 /**
  * Expand a leading ~ to the given home directory (defaults to os.homedir()).
  * Every call site inside resolveConfigHomeFromDescriptor threads its
@@ -117,7 +118,7 @@ function getRegistry() {
  * way `grok`'s is confirmed above. Do not "clean this up" by removing it;
  * that is exactly the regression this constant guards against.
  */
-exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = new Set(['grok']);
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = runtime_name_policy_cjs_1.LEGACY_NON_REGISTRY_RUNTIME_IDS;
 /**
  * True when `runtime` is a real runtime id with a genuine, runtime-specific
  * resolution path — either a registered id in the capability registry
@@ -145,9 +146,7 @@ function isRegisteredRuntimeId(runtime) {
     const trimmed = runtime.trim();
     if (!trimmed)
         return false;
-    if (Object.prototype.hasOwnProperty.call(getRegistry().runtimes, trimmed))
-        return true;
-    return exports.LEGACY_NON_REGISTRY_RUNTIME_IDS.has(trimmed);
+    return (0, runtime_name_policy_cjs_1.isKnownRuntimeId)(trimmed);
 }
 /**
  * Resolve a configHome descriptor to an absolute directory path.
@@ -455,12 +454,19 @@ function resolveKimiHooksTomlDir(opts = {}) {
  *   the behaviour of bin/install.js getGlobalDir(runtime, explicitDir).
  */
 function getGlobalConfigDir(runtime, explicitDir) {
+    // A retired or unknown runtime id must never resolve — checked before
+    // `explicitDir` so an explicit directory cannot mask the fact that the runtime
+    // itself is gone (retired) or was never registered (#5169). An absent id
+    // (`''`) is the generic "no runtime" path and still reaches the default.
+    (0, runtime_name_policy_cjs_1.assertKnownRuntime)(runtime);
     if (explicitDir)
         return expandTilde(explicitDir);
-    // ── Grok: not in the registry — hardcoded branch ─────────────────────────
-    if (runtime === 'grok') {
+    // ── Legacy non-registry runtimes (grok): table-driven, not registry-backed ─
+    if (Object.prototype.hasOwnProperty.call(runtime_name_policy_cjs_1.LEGACY_NON_REGISTRY_RUNTIME_HOMES, runtime)) {
+        const legacy = runtime_name_policy_cjs_1.LEGACY_NON_REGISTRY_RUNTIME_HOMES[runtime];
         const env = process.env;
-        return env['GROK_AGENTS_HOME'] ? expandTilde(env['GROK_AGENTS_HOME']) : node_path_1.default.join(node_os_1.default.homedir(), '.agents');
+        const override = env[legacy.env];
+        return override ? expandTilde(override) : node_path_1.default.join(node_os_1.default.homedir(), ...legacy.dir);
     }
     // ── Descriptor-driven: look up in capability-registry ────────────────────
     const { runtimes } = getRegistry();
@@ -483,6 +489,7 @@ function resolveSkillsBaseFromDescriptor(configHome, opts = {}, skillsDestSubpat
     return node_path_1.default.join(base, skillsDestSubpath);
 }
 function getGlobalSkillsBase(runtime) {
+    (0, runtime_name_policy_cjs_1.assertKnownRuntime)(runtime);
     const runtimeEntry = getRegistry().runtimes[runtime];
     const descriptor = runtimeEntry?.runtime;
     // #2103: a runtime with `configHome.kind === 'none'` (e.g. vscode —