@opengsd/gsd-core 1.9.1 → 1.11.0

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

@@ -34,6 +34,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GSD_LOCATION_ENV_KEYS = exports.NON_REGISTRY_CONFIG_HOME_DESCRIPTORS = exports.KIMI_CODE_HOOKS_TOML_DESCRIPTOR = exports.KIMI_HOOKS_TOML_DESCRIPTOR = exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = void 0;
+exports.isRegisteredRuntimeId = isRegisteredRuntimeId;
 exports.resolveConfigHomeFromDescriptor = resolveConfigHomeFromDescriptor;
 exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
 exports.detectAntigravityDirAmbiguity = detectAntigravityDirAmbiguity;
@@ -48,15 +50,36 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
 /**
- * Expand a leading ~ to os.homedir().
+ * Expand a leading ~ to the given home directory (defaults to os.homedir()).
+ * Every call site inside resolveConfigHomeFromDescriptor threads its
+ * resolved `home` local through here so an injected opts.home (used by
+ * hermetic tests) is honored instead of silently falling back to the real
+ * home directory.
  */
-function expandTilde(p) {
+function expandTilde(p, home = node_os_1.default.homedir()) {
     if (!p)
         return p;
     if (p.startsWith('~/') || p === '~')
-        return node_path_1.default.join(node_os_1.default.homedir(), p.slice(1));
+        return node_path_1.default.join(home, p.slice(1));
     return p;
 }
+/**
+ * True when `val` is a usable env-var override: a real string that contains
+ * at least one non-whitespace character. Every env-override consumption site
+ * in resolveConfigHomeFromDescriptor gates on this instead of a bare truthy
+ * check, so `FOO_DIR=''` (empty), `FOO_DIR` unset (`undefined`), and
+ * `FOO_DIR='   '` (whitespace-only — e.g. from a shell templating bug that
+ * leaves a variable substitution blank but quoted) all fall back to the
+ * descriptor default identically. Deliberately does NOT trim: a value that
+ * merely has leading/trailing whitespace around otherwise-real content (or
+ * interior whitespace, e.g. `~/My Agent Dir`) is passed through byte-for-byte
+ * unchanged, exactly as this module already treats every other env-var
+ * override (no site here or elsewhere in this file trims a path value) — so
+ * default behavior for every non-whitespace value is unaffected by this guard.
+ */
+function hasNonBlankOverride(val) {
+    return typeof val === 'string' && val.trim() !== '';
+}
 function resolveDescriptorWithOptions(configHome) {
     return resolveConfigHomeFromDescriptor(configHome, {
         env: process.env,
@@ -68,6 +91,64 @@ function getRegistry() {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return require('./capability-registry.cjs');
 }
+/**
+ * Legacy runtime ids that have a genuine, dedicated resolution branch
+ * elsewhere in this module but no capability-registry descriptor (#3024
+ * review BLOCKER, finding 1).
+ *
+ * `isRegisteredRuntimeId`'s real contract is "does this id resolve to a
+ * real, runtime-specific path?", not "is it a key in the registry map" —
+ * registry membership is only a proxy for that, and the proxy is wrong for
+ * `grok`: `getGlobalConfigDir` has a live hardcoded branch for it (`~/.agents`,
+ * overridable via `GROK_AGENTS_HOME`), predating the capability-registry
+ * descriptor system, and it is documented end-user-facing surface
+ * (pre-fix `gsd-core/workflows/sync-skills.md` listed it explicitly, and
+ * `docs/discussions/grok-build-support-2026-05.md` records the support
+ * decision). Rejecting it here would silently remove working, documented
+ * `--skills-root`/`sync-skills` support for a runtime that never regressed.
+ *
+ * This set is enumerated by hand, not derived, and MUST stay in lockstep
+ * with `getGlobalConfigDir`'s hardcoded branches: as of #3024, `grok` is
+ * the ONLY id in this position (verified by reading the full function body
+ * — every other unregistered id there falls through to the claude
+ * fallback, which is the behavior this validator exists to reject). Do
+ * NOT add an id here just because it "should" work — add it only after
+ * confirming `getGlobalConfigDir` has a real dedicated branch for it, the
+ * 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']);
+/**
+ * True when `runtime` is a real runtime id with a genuine, runtime-specific
+ * resolution path — either a registered id in the capability registry
+ * (`capability-registry.cjs`'s `runtimes` object) or one of the small,
+ * explicitly named `LEGACY_NON_REGISTRY_RUNTIME_IDS` set (currently just
+ * `grok`) that resolves via a dedicated hardcoded branch instead of a
+ * registry descriptor.
+ *
+ * Guarded with an own-property lookup — never a bare index — so a
+ * prototype-chain id (`__proto__`, `constructor`, `prototype`, `toString`,
+ * …) can never resolve to an inherited value and be mistaken for a real
+ * entry. Without this, `getGlobalSkillsBase`/`getGlobalConfigDir`'s bare
+ * `runtimes[runtime]` lookups fall through the prototype chain for those
+ * ids, find no usable descriptor, and silently resolve to claude's
+ * fallback path instead of failing loudly (#3024).
+ *
+ * Single shared validator for every `--skills-root` entry point
+ * (`gsd-tools query skills-root`'s `routeSkillsRoot`, `install.js
+ * --skills-root`) so the two surfaces can never diverge on which runtime
+ * ids they accept.
+ */
+function isRegisteredRuntimeId(runtime) {
+    if (typeof runtime !== 'string')
+        return false;
+    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);
+}
 /**
  * Resolve a configHome descriptor to an absolute directory path.
  *
@@ -86,16 +167,16 @@ function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
             // First env var that is set wins
             for (const varName of configHome.env) {
                 const val = env[varName];
-                if (val)
-                    return expandTilde(val);
+                if (hasNonBlankOverride(val))
+                    return expandTilde(val, home);
             }
             return node_path_1.default.join(home, configHome.name);
         }
         case 'dot-home-nested': {
             // env override
             const nestedEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && nestedEnv0Val) {
-                return expandTilde(nestedEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(nestedEnv0Val)) {
+                return expandTilde(nestedEnv0Val, home);
             }
             const base = node_path_1.default.join(home, configHome.parent);
             if (configHome.probe && configHome.probe.length > 0) {
@@ -127,49 +208,50 @@ function resolveConfigHomeFromDescriptor(configHome, opts = {}) {
         case 'xdg': {
             // env[0]: direct override dir
             const xdgEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && xdgEnv0Val) {
-                return expandTilde(xdgEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(xdgEnv0Val)) {
+                return expandTilde(xdgEnv0Val, home);
             }
             // env[1]: FILE path → dirname
             const xdgEnv1Val = env[configHome.env[1]];
-            if (configHome.env[1] && xdgEnv1Val) {
-                return node_path_1.default.dirname(expandTilde(xdgEnv1Val));
+            if (configHome.env[1] && hasNonBlankOverride(xdgEnv1Val)) {
+                return node_path_1.default.dirname(expandTilde(xdgEnv1Val, home));
             }
             // env[2]: XDG_CONFIG_HOME → subdir
             const xdgEnv2Val = env[configHome.env[2]];
-            if (configHome.env[2] && xdgEnv2Val) {
-                return node_path_1.default.join(expandTilde(xdgEnv2Val), configHome.name);
+            if (configHome.env[2] && hasNonBlankOverride(xdgEnv2Val)) {
+                return node_path_1.default.join(expandTilde(xdgEnv2Val, home), configHome.name);
             }
             return node_path_1.default.join(home, '.config', configHome.name);
         }
         case 'generic-agents-root': {
             // env override
             const garEnv0Val = env[configHome.env[0]];
-            if (configHome.env[0] && garEnv0Val) {
-                return expandTilde(garEnv0Val);
+            if (configHome.env[0] && hasNonBlankOverride(garEnv0Val)) {
+                return expandTilde(garEnv0Val, home);
             }
             // probe each candidate; return first where probeExists subpath exists
             for (const candidate of configHome.probe) {
-                const resolved = expandTildeWithHome(candidate, home);
+                const resolved = expandTilde(candidate, home);
                 if (existsSyncFn(node_path_1.default.join(resolved, configHome.probeExists))) {
                     return resolved;
                 }
             }
             // fallback: first probe candidate
-            return expandTildeWithHome(configHome.probe[0], home);
+            return expandTilde(configHome.probe[0], home);
+        }
+        case 'none': {
+            // #2103: no file-projected config directory exists for this runtime
+            // (e.g. vscode). Previously this kind had no matching case, so the
+            // switch fell through and implicitly returned `undefined` — which
+            // then crashed a downstream `path.join(undefined, ...)` with a
+            // cryptic `TypeError [ERR_INVALID_ARG_TYPE]` far from the real cause.
+            // Throwing here makes the failure mode explicit; callers that need a
+            // nullable result (getGlobalSkillsBase) check `configHome.kind` and
+            // short-circuit BEFORE ever reaching this function.
+            throw new Error(`Runtime "${configHome.name}" has no config-home directory (configHome.kind === "none")`);
         }
     }
 }
-/**
- * Expand ~ using an explicit home directory (for hermetic testing).
- */
-function expandTildeWithHome(p, home) {
-    if (!p)
-        return p;
-    if (p.startsWith('~/') || p === '~')
-        return node_path_1.default.join(home, p.slice(1));
-    return p;
-}
 /**
  * Resolve Antigravity global config dir across 1.x and 2.x layouts.
  *
@@ -257,25 +339,111 @@ function resolveKimiGlobalDir(opts = {}) {
     }, { env, home, existsSync: existsSyncFn });
 }
 /**
- * Resolve the directory holding Kimi CLI's OWN native config.toml (the file
- * Kimi itself reads for providers/models/hooks/etc — see
- * moonshotai.github.io/kimi-cli/en/configuration/data-locations.html and
- * .../reference/kimi-command.html). Default `~/.kimi`, overridden by
- * `KIMI_SHARE_DIR` per Kimi's own upstream env-var (NOT `KIMI_CONFIG_DIR`,
- * which is a GSD-installer write-location override for the unrelated generic
- * Agent-Skills root resolved by resolveKimiGlobalDir above).
+ * Kimi CLI's own native config.toml home. Hoisted out of resolveKimiHooksTomlDir
+ * so it is ENUMERABLE, not merely resolvable.
  *
- * This is deliberately a SEPARATE directory from GSD's kimi configHome
- * (~/.config/agents): Kimi's own docs confirm the Agent-Skills search path is
- * independent of KIMI_SHARE_DIR ("This variable does not affect Agent Skills
- * search paths, which are handled separately"). #2095 Upgrade 1 writes GSD's
- * native [[hooks]] entries into `<this dir>/config.toml`, never into the
- * skills configDir.
+ * #2665 round 3: a config-location var that lives only inside a function body is
+ * invisible to every consumer that needs the SET rather than the path — the test
+ * scrub list and the hermeticity guard both derive from descriptors, and this one
+ * reached neither. `kimi` is the sharp case precisely because it owns TWO config
+ * homes: KIMI_CONFIG_DIR (registry-visible, already covered) and KIMI_SHARE_DIR
+ * (this one), so a derivation keyed only on the registry looks complete and is not.
+ */
+exports.KIMI_HOOKS_TOML_DESCRIPTOR = {
+    kind: 'dot-home',
+    name: '.kimi',
+    env: ['KIMI_SHARE_DIR'],
+};
+/**
+ * Kimi Code's native config.toml home — the `kimi-code` counterpart of the
+ * descriptor above, hoisted for exactly the same reason.
+ *
+ * #2755 landed kimi-code hooks support on `next` while this PR was open, and
+ * declared this descriptor as an inline object literal inside
+ * resolveKimiHooksTomlDir's body — the same resolvable-but-not-enumerable shape
+ * round 3 hoisted KIMI_SHARE_DIR out of. Hoisting it puts `KIMI_CODE_HOME` into
+ * the derived scrub set and the hermeticity guard's watch roots in the SAME
+ * commit, which is the property NON_REGISTRY_CONFIG_HOME_DESCRIPTORS exists to
+ * guarantee. Each product's env var stays scoped to that product (#2755).
+ */
+exports.KIMI_CODE_HOOKS_TOML_DESCRIPTOR = {
+    kind: 'dot-home',
+    name: '.kimi-code',
+    env: ['KIMI_CODE_HOME'],
+};
+/**
+ * Config-home descriptors resolved OUTSIDE the capability registry.
+ *
+ * Anything added here is picked up by every derived consumer in the same commit —
+ * which is the property that makes the derivation structurally incapable of being
+ * narrower than the surface it guards. Adding a hardcoded resolver WITHOUT adding
+ * its descriptor here is the defect this array exists to make hard.
+ */
+exports.NON_REGISTRY_CONFIG_HOME_DESCRIPTORS = [
+    exports.KIMI_HOOKS_TOML_DESCRIPTOR,
+    exports.KIMI_CODE_HOOKS_TOML_DESCRIPTOR,
+];
+/**
+ * GSD's OWN location vars — a second family, not runtime configHomes.
+ *
+ * #2665 round 3: the registry describes where each *third-party runtime* keeps its
+ * config. It says nothing about where GSD keeps its own user-owned state, and that
+ * is a separate env-first surface:
+ *
+ *   GSD_HOME       — `process.env['GSD_HOME'] || os.homedir()`, the root of
+ *                    `$GSD_HOME/.gsd/` (consent.json, defaults.json, capability
+ *                    overlays). Read env-first by capability-loader, capability-consent,
+ *                    capability-state, capability-writer, config-loader, install-profiles
+ *                    and bin/install.js. A WRITE surface.
+ *   GSD_AGENTS_DIR — `if (process.env['GSD_AGENTS_DIR']) return it`, priority 1 in
+ *                    getAgentsDir. Misdirects a READ rather than a write, hence lower
+ *                    severity — but it is env-first and unconditional, so it belongs
+ *                    to the same class.
+ *
+ * Deliberately NOT folded into the descriptor array above: these do not resolve
+ * through resolveConfigHomeFromDescriptor and have no `kind`/`name` shape.
+ */
+exports.GSD_LOCATION_ENV_KEYS = ['GSD_HOME', 'GSD_AGENTS_DIR'];
+/**
+ * Resolve the directory holding the Kimi product's OWN native config.toml —
+ * the file that product itself reads for providers/models/hooks/etc, and the
+ * one GSD writes its `[[hooks]]` block, hooks bundle and CommonJS marker into.
+ *
+ * The two Kimi runtimes share `hooksSurface: "kimi-hooks-toml"` but are
+ * different products with different roots, and this must be selected by
+ * `runtime` (#2755). Before that fix this function was unparameterized and a
+ * `--kimi-code` install wrote its hooks into Kimi CLI's `~/.kimi`, leaving Kimi
+ * Code with none:
+ *
+ *   kimi       → `~/.kimi`,      overridden by `KIMI_SHARE_DIR`
+ *                (moonshotai.github.io/kimi-cli/en/configuration/data-locations.html)
+ *   kimi-code  → `~/.kimi-code`, overridden by `KIMI_CODE_HOME`
+ *                (moonshotai/kimi-code docs/en/configuration/data-locations.md;
+ *                 its hooks doc places `[[hooks]]` in `~/.kimi-code/config.toml`)
+ *
+ * Each product's env var is scoped to that product: `KIMI_SHARE_DIR` is Kimi
+ * CLI's own upstream variable and must NOT redirect kimi-code, nor vice versa.
+ *
+ * An unrecognised `runtime` (and an omitted one) falls back to `~/.kimi`, which
+ * preserves the pre-#2755 behaviour for every existing caller that passes no
+ * runtime — this function is exported, so that default is a contract.
+ *
+ * For BOTH runtimes this is deliberately a SEPARATE directory from the generic
+ * Agent-Skills root resolved by `resolveKimiGlobalDir` (`~/.config/agents`):
+ * both vendors' docs confirm the Agent-Skills search path is independent of the
+ * data-root env var. GSD's native `[[hooks]]` entries go in
+ * `<this dir>/config.toml`, never into the skills configDir.
  */
 function resolveKimiHooksTomlDir(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? node_os_1.default.homedir();
-    return resolveConfigHomeFromDescriptor({ kind: 'dot-home', name: '.kimi', env: ['KIMI_SHARE_DIR'] }, { env, home });
+    // Explicit comparison rather than an object lookup keyed on `runtime`: the
+    // value originates from argv, and an index would resolve inherited keys
+    // (`constructor`, `__proto__`) to something that is not a descriptor.
+    const descriptor = opts.runtime === 'kimi-code'
+        ? exports.KIMI_CODE_HOOKS_TOML_DESCRIPTOR
+        : exports.KIMI_HOOKS_TOML_DESCRIPTOR;
+    return resolveConfigHomeFromDescriptor(descriptor, { env, home });
 }
 /**
  * Return the global config base directory for the given runtime.
@@ -317,6 +485,17 @@ function resolveSkillsBaseFromDescriptor(configHome, opts = {}, skillsDestSubpat
 function getGlobalSkillsBase(runtime) {
     const runtimeEntry = getRegistry().runtimes[runtime];
     const descriptor = runtimeEntry?.runtime;
+    // #2103: a runtime with `configHome.kind === 'none'` (e.g. vscode —
+    // Marketplace/VSIX extension, installSurface:'none') has no file-projected
+    // config directory at all, and therefore no skills root. Short-circuit to
+    // null BEFORE falling through to getGlobalConfigDir below, which would
+    // otherwise throw resolving a 'none' configHome (see
+    // resolveConfigHomeFromDescriptor's 'none' case). null is the correct
+    // answer here, not a crash — the `=== null` guard at every call site
+    // (bin/install.js --skills-root, gsd-tools routeSkillsRoot) already
+    // handles it as "this runtime does not use a skills directory".
+    if (descriptor?.configHome?.kind === 'none')
+        return null;
     const globalSkillsKind = descriptor?.artifactLayout?.global?.find((entry) => entry.kind === 'skills');
     // ADR-1239 upgrade 3 (#2088): honor a skills-kind `home` override (e.g. Codex
     // → $HOME/.agents/skills, independent of $CODEX_HOME) so the reported skills