golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix(#2116): use resolvable paths in surface.md require + correct package name

Browse Source 
Four require() examples in commands/gsd/surface.md used bare
'gsd-core/...' specifiers that Node cannot resolve (wrong package
name + runtime-mirror layout off module path). Now derives the path
from runtimeConfigDir. Also fixes reinstall hint from
'npm i -g gsd-core' to 'npm i -g @opengsd/gsd-core'.
This commit is contained in:
Tom Boucher
2026-07-12 01:06:39 -04:00
parent 7252807194
commit 64c4a105f6
19 changed files with 74 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/2116-surface-bare-require.md Normal file
View File

@@ -0,0 +1,5 @@
---
type: Documentation
pr: 0
---
**Fixed unresolvable bare `require('gsd-core/...')` in `gsd-surface` command doc** — the four `require()` examples now derive the engine path from `runtimeConfigDir` (resolvable at runtime), and the reinstall hint corrects `npm i -g gsd-core` to `npm i -g @opengsd/gsd-core`. (#2116)

12
commands/gsd/surface.md
View File

@@ -37,9 +37,9 @@ Parse the first token of $ARGUMENTS:
## list / status
Load the capability registry and call `listSurface(runtimeConfigDir, manifest, CLUSTERS, registry)` from
`gsd-core/bin/lib/surface.cjs`. The registry is loaded via:
the engine module at `${runtimeConfigDir}/gsd-core/bin/lib/surface.cjs`. The registry is loaded via:
```js
const registry = require('gsd-core/bin/lib/capability-registry.cjs');
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
```
Display:
@@ -71,7 +71,7 @@ Install profile: standard (from .gsd-profile)
3. `writeSurface(runtimeConfigDir, surfaceState)`.
4. Resolve and re-apply:
```js
const registry = require('gsd-core/bin/lib/capability-registry.cjs');
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
```
@@ -89,7 +89,7 @@ Valid cluster names: `core_loop`, `audit_review`, `milestone`, `research_ideate`
3. Add cluster to `surfaceState.disabledClusters` (deduplicate).
4. `writeSurface` → resolve layout → `applySurface`:
```js
const registry = require('gsd-core/bin/lib/capability-registry.cjs');
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
```
@@ -103,7 +103,7 @@ Valid cluster names: `core_loop`, `audit_review`, `milestone`, `research_ideate`
2. Remove cluster from `surfaceState.disabledClusters`.
3. `writeSurface` → resolve layout → `applySurface`:
```js
const registry = require('gsd-core/bin/lib/capability-registry.cjs');
const registry = require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs');
const layout = resolveRuntimeArtifactLayout(runtime, runtimeConfigDir, scope);
applySurface(runtimeConfigDir, layout, manifest, CLUSTERS, registry);
```
@@ -151,7 +151,7 @@ All paths can be overridden by reading the `CLAUDE_CONFIG_DIR` env var if set.
- Unknown cluster name → list valid cluster names, exit without writing.
- Unknown profile name → list known profiles (`core`, `standard`, `full`), exit.
- Missing `surface.cjs` → prompt: "Run `npm i -g gsd-core` to reinstall GSD."
- Missing `surface.cjs` → prompt: "Run `npm i -g @opengsd/gsd-core` to reinstall GSD."
<execution_context>
Surface state file: `~/.claude/.gsd-surface.json`

2
tests/fixtures/golden-install-parity/antigravity.json vendored
View File

@@ -413,7 +413,7 @@
"skills/gsd-spec-phase/SKILL.md": "6b35d59f65e2e607",
"skills/gsd-spike/SKILL.md": "63b5093cbc7978ca",
"skills/gsd-stats/SKILL.md": "1cef40c0a0e7b19b",
"skills/gsd-surface/SKILL.md": "963aa5a09d8e3695",
"skills/gsd-surface/SKILL.md": "19e018ebe4c89857",
"skills/gsd-thread/SKILL.md": "4d91aab9f5ed4ca7",
"skills/gsd-ui-phase/SKILL.md": "b2412418ebf0dfb8",
"skills/gsd-ui-review/SKILL.md": "e49734488684fd9a",

4
tests/fixtures/golden-install-parity/augment.json vendored
View File

@@ -95,7 +95,7 @@
"commands/gsd-spec-phase.md": "8bb332566911dfd9",
"commands/gsd-spike.md": "a99190d9496c6ac0",
"commands/gsd-stats.md": "58b4d86a5390e243",
"commands/gsd-surface.md": "acab871ec856e353",
"commands/gsd-surface.md": "12078dca898a6c16",
"commands/gsd-thread.md": "51be0cdeb925ab28",
"commands/gsd-ui-phase.md": "75d4be44797ccef7",
"commands/gsd-ui-review.md": "9191082973068dbf",
@@ -449,7 +449,7 @@
"skills/gsd-ns-manage/skills/settings/SKILL.md": "8751c29421208a00",
"skills/gsd-ns-manage/skills/ship/SKILL.md": "7498424e965545e1",
"skills/gsd-ns-manage/skills/stats/SKILL.md": "0bce39e8f3b64f5e",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "0644bd7dbeeb0a73",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "ca10834ce41967c9",
"skills/gsd-ns-manage/skills/thread/SKILL.md": "fbe591e8162f8b1c",
"skills/gsd-ns-manage/skills/undo/SKILL.md": "5ffc86a2c67aa9df",
"skills/gsd-ns-manage/skills/update/SKILL.md": "c8165b8085ba106a",

2
tests/fixtures/golden-install-parity/claude-local.json vendored
View File

@@ -94,7 +94,7 @@
"commands/gsd-spec-phase.md": "383b4928c4df4bf1",
"commands/gsd-spike.md": "98d789db7ca53873",
"commands/gsd-stats.md": "a9c0e3f338bd61a5",
"commands/gsd-surface.md": "998bf327c3f4a001",
"commands/gsd-surface.md": "20bbba15eac52024",
"commands/gsd-thread.md": "1b78c7b75b53ad4e",
"commands/gsd-ui-phase.md": "67a759b3973f961f",
"commands/gsd-ui-review.md": "9b4ecf2d40bdc476",

2
tests/fixtures/golden-install-parity/claude.json vendored
View File

@@ -411,7 +411,7 @@
"skills/gsd-spec-phase/SKILL.md": "7e4dfa2070b7d9d1",
"skills/gsd-spike/SKILL.md": "04d5f50d8d4a1c1a",
"skills/gsd-stats/SKILL.md": "5403a46852241fa8",
"skills/gsd-surface/SKILL.md": "970f30acc073a7b9",
"skills/gsd-surface/SKILL.md": "4b9c977a74a975ed",
"skills/gsd-thread/SKILL.md": "a76c70c368f82dee",
"skills/gsd-ui-phase/SKILL.md": "7c9404102a9b9d74",
"skills/gsd-ui-review/SKILL.md": "ef8f643abff1486b",

2
tests/fixtures/golden-install-parity/cline.json vendored
View File

@@ -353,7 +353,7 @@
"skills/gsd-ns-manage/skills/settings/SKILL.md": "67eff2d16e17403c",
"skills/gsd-ns-manage/skills/ship/SKILL.md": "4ad9695934e069ee",
"skills/gsd-ns-manage/skills/stats/SKILL.md": "25898070fb2a4b20",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "6d6ed15c90424f3f",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "a89b3bde1d2b620a",
"skills/gsd-ns-manage/skills/thread/SKILL.md": "67b5a0451b58c50c",
"skills/gsd-ns-manage/skills/undo/SKILL.md": "88407c6379617c7b",
"skills/gsd-ns-manage/skills/update/SKILL.md": "2666ab7786b69017",

4
tests/fixtures/golden-install-parity/codebuddy.json vendored
View File

@@ -95,7 +95,7 @@
"commands/gsd-spec-phase.md": "145f2ab750344022",
"commands/gsd-spike.md": "54c094f40b601688",
"commands/gsd-stats.md": "60f7077e7949d2ad",
"commands/gsd-surface.md": "29688da5df785b58",
"commands/gsd-surface.md": "84d89b840d00b7f0",
"commands/gsd-thread.md": "07da4f657b3efcc1",
"commands/gsd-ui-phase.md": "3b90f3d1c8fa531d",
"commands/gsd-ui-review.md": "4e5fb1e77def9b64",
@@ -483,7 +483,7 @@
"skills/gsd-spec-phase/SKILL.md": "96a095cd634129d8",
"skills/gsd-spike/SKILL.md": "d4af42b801139876",
"skills/gsd-stats/SKILL.md": "7d1fbadcae5f0b67",
"skills/gsd-surface/SKILL.md": "5008f49701e7deea",
"skills/gsd-surface/SKILL.md": "1b840c8ddd76b9c7",
"skills/gsd-thread/SKILL.md": "18ddd2aa60997949",
"skills/gsd-ui-phase/SKILL.md": "132ccf2ddc9e24e0",
"skills/gsd-ui-review/SKILL.md": "7e8cf0bcee9859cd",

2
tests/fixtures/golden-install-parity/codex.json vendored
View File

@@ -59,7 +59,7 @@
".agents/skills/gsd-spec-phase/SKILL.md": "56a5cbd606db9cba",
".agents/skills/gsd-spike/SKILL.md": "77209fef7a04c11a",
".agents/skills/gsd-stats/SKILL.md": "566024444ef71f44",
".agents/skills/gsd-surface/SKILL.md": "492cda98187a969b",
".agents/skills/gsd-surface/SKILL.md": "e8b9d3c291a5c18c",
".agents/skills/gsd-thread/SKILL.md": "85326c97c83a02d1",
".agents/skills/gsd-ui-phase/SKILL.md": "a0c8fbcbe5e3c2b9",
".agents/skills/gsd-ui-review/SKILL.md": "081a3292a2d357f5",

2
tests/fixtures/golden-install-parity/copilot.json vendored
View File

@@ -386,7 +386,7 @@
"skills/gsd-spec-phase/SKILL.md": "e402110c96d1f44f",
"skills/gsd-spike/SKILL.md": "de84271bdba0ef67",
"skills/gsd-stats/SKILL.md": "e0beaf89d27c8058",
"skills/gsd-surface/SKILL.md": "2f2647c7bd664605",
"skills/gsd-surface/SKILL.md": "c6ae441eb5e2e84a",
"skills/gsd-thread/SKILL.md": "8db4d6ebcf0a8898",
"skills/gsd-ui-phase/SKILL.md": "317081b3be7c536f",
"skills/gsd-ui-review/SKILL.md": "dc07bbe9094b6dbe",

4
tests/fixtures/golden-install-parity/cursor.json vendored
View File

@@ -95,7 +95,7 @@
"commands/gsd-spec-phase.md": "7c95987dcd7aa3fb",
"commands/gsd-spike.md": "8102cc426fa1f1b3",
"commands/gsd-stats.md": "eb39e4c4ec8eccea",
"commands/gsd-surface.md": "1fb3de1651eb182a",
"commands/gsd-surface.md": "96a66a3607b253b4",
"commands/gsd-thread.md": "fc5975fdb73eb045",
"commands/gsd-ui-phase.md": "b91b691e1eb007c2",
"commands/gsd-ui-review.md": "2f9842e07e7df4df",
@@ -461,7 +461,7 @@
"skills/gsd-spec-phase/SKILL.md": "5c48117fbb7aa595",
"skills/gsd-spike/SKILL.md": "3850674027d81c2a",
"skills/gsd-stats/SKILL.md": "ebbd0d39b5cee9a9",
"skills/gsd-surface/SKILL.md": "805deb95c48af938",
"skills/gsd-surface/SKILL.md": "9b869434321867c3",
"skills/gsd-thread/SKILL.md": "621cde6272262eef",
"skills/gsd-ui-phase/SKILL.md": "505ad61ef61c9e9c",
"skills/gsd-ui-review/SKILL.md": "dc79fe0ad42f4948",

2
tests/fixtures/golden-install-parity/hermes.json vendored
View File

@@ -379,7 +379,7 @@
"skills/gsd/gsd-ns-manage/skills/settings/SKILL.md": "db053a82acb85969",
"skills/gsd/gsd-ns-manage/skills/ship/SKILL.md": "3f7e7023802a185d",
"skills/gsd/gsd-ns-manage/skills/stats/SKILL.md": "847f1a79382e05a3",
"skills/gsd/gsd-ns-manage/skills/surface/SKILL.md": "f63005360828e726",
"skills/gsd/gsd-ns-manage/skills/surface/SKILL.md": "232dc849db8ec365",
"skills/gsd/gsd-ns-manage/skills/thread/SKILL.md": "12e14ca63fe5a982",
"skills/gsd/gsd-ns-manage/skills/undo/SKILL.md": "cb410bf1813a2d1e",
"skills/gsd/gsd-ns-manage/skills/update/SKILL.md": "433a236998c305b0",

4
tests/fixtures/golden-install-parity/kilo.json vendored
View File

@@ -95,7 +95,7 @@
"command/gsd-spec-phase.md": "8f8e3e109ebb7011",
"command/gsd-spike.md": "fdcb1ae289790818",
"command/gsd-stats.md": "b54c0d533cff9710",
"command/gsd-surface.md": "3290127fe8241ced",
"command/gsd-surface.md": "e2e7898a020a954b",
"command/gsd-thread.md": "9c6a1900b3c57be6",
"command/gsd-ui-phase.md": "efeba2d2381173e3",
"command/gsd-ui-review.md": "35a12e93cddf266c",
@@ -457,7 +457,7 @@
"skills/gsd-spec-phase/SKILL.md": "749dee6f739b9b44",
"skills/gsd-spike/SKILL.md": "0938ac1386ca4a58",
"skills/gsd-stats/SKILL.md": "25898070fb2a4b20",
"skills/gsd-surface/SKILL.md": "1bfb5b380f42a02b",
"skills/gsd-surface/SKILL.md": "0672169f8292ed7d",
"skills/gsd-thread/SKILL.md": "d5917840279459f1",
"skills/gsd-ui-phase/SKILL.md": "c35f175ccc747d56",
"skills/gsd-ui-review/SKILL.md": "48267dc071481a89",

2
tests/fixtures/golden-install-parity/kimi.json vendored
View File

@@ -448,7 +448,7 @@
"skills/gsd-spec-phase/SKILL.md": "23ff63ddf425c1c2",
"skills/gsd-spike/SKILL.md": "aa740909d20a82f2",
"skills/gsd-stats/SKILL.md": "a7e478f76e0b6db1",
"skills/gsd-surface/SKILL.md": "2f72da87138503aa",
"skills/gsd-surface/SKILL.md": "f0356c0fef0b1d4c",
"skills/gsd-thread/SKILL.md": "fb52a782c6e83e03",
"skills/gsd-ui-phase/SKILL.md": "1d7ed00d7970ed51",
"skills/gsd-ui-review/SKILL.md": "39b36951bafe1495",

4
tests/fixtures/golden-install-parity/opencode.json vendored
View File

@@ -95,7 +95,7 @@
"command/gsd-spec-phase.md": "b92bca076ca2c5c6",
"command/gsd-spike.md": "1b2fa4b468e831dc",
"command/gsd-stats.md": "51af934859f87623",
"command/gsd-surface.md": "26a5f0aab82c1c4a",
"command/gsd-surface.md": "e559ca6733ce288f",
"command/gsd-thread.md": "ae3b000bee0ee1e0",
"command/gsd-ui-phase.md": "21c9c043d813dc0a",
"command/gsd-ui-review.md": "ef36603b519e8fe8",
@@ -485,7 +485,7 @@
"skills/gsd-spec-phase/SKILL.md": "332028ed34b85b1f",
"skills/gsd-spike/SKILL.md": "9303cd74a8bf0741",
"skills/gsd-stats/SKILL.md": "2af976632e239069",
"skills/gsd-surface/SKILL.md": "ea512089d0e1d057",
"skills/gsd-surface/SKILL.md": "a0cec79a0bbf9c97",
"skills/gsd-thread/SKILL.md": "9ff9979a8213dbf8",
"skills/gsd-ui-phase/SKILL.md": "5eee1bdd13640252",
"skills/gsd-ui-review/SKILL.md": "c99d6725326bfbc4",

2
tests/fixtures/golden-install-parity/qwen.json vendored
View File

@@ -378,7 +378,7 @@
"skills/gsd-ns-manage/skills/settings/SKILL.md": "6d9fbddb0b00fd46",
"skills/gsd-ns-manage/skills/ship/SKILL.md": "bd6cb3b46d57123f",
"skills/gsd-ns-manage/skills/stats/SKILL.md": "5403a46852241fa8",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "0b3fe299b6544de7",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "ef08f90f89ca373c",
"skills/gsd-ns-manage/skills/thread/SKILL.md": "a76c70c368f82dee",
"skills/gsd-ns-manage/skills/undo/SKILL.md": "0ad1218f55c94e4b",
"skills/gsd-ns-manage/skills/update/SKILL.md": "530b4206d729b56d",

2
tests/fixtures/golden-install-parity/trae.json vendored
View File

@@ -350,7 +350,7 @@
"skills/gsd-ns-manage/skills/settings/SKILL.md": "e3590bb5e3d0fdf2",
"skills/gsd-ns-manage/skills/ship/SKILL.md": "456609cf127b36dc",
"skills/gsd-ns-manage/skills/stats/SKILL.md": "f5f5f1fbfe65cee8",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "025a48d0b1129e47",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "2c92a300547a5a97",
"skills/gsd-ns-manage/skills/thread/SKILL.md": "48894eaf985265b3",
"skills/gsd-ns-manage/skills/undo/SKILL.md": "0deb95bc44edf37c",
"skills/gsd-ns-manage/skills/update/SKILL.md": "ffcd813ad256769b",

4
tests/fixtures/golden-install-parity/zcode.json vendored
View File

@@ -95,7 +95,7 @@
"commands/gsd-spec-phase.md": "c0e592ef19cc6721",
"commands/gsd-spike.md": "5c85bade6e6b804f",
"commands/gsd-stats.md": "bea8a4f0e6f2ddf3",
"commands/gsd-surface.md": "b1ab5c2127dbf856",
"commands/gsd-surface.md": "0317dc3b56ffcce6",
"commands/gsd-thread.md": "56036040a95fc60b",
"commands/gsd-ui-phase.md": "b48b780198ec7a2e",
"commands/gsd-ui-review.md": "2ed61b5729f6e492",
@@ -421,7 +421,7 @@
"skills/gsd-ns-manage/skills/settings/SKILL.md": "8fcd8b04bb607ca7",
"skills/gsd-ns-manage/skills/ship/SKILL.md": "eb23c16b4893b035",
"skills/gsd-ns-manage/skills/stats/SKILL.md": "af60a0fed275a90b",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "9bc5790f601615cf",
"skills/gsd-ns-manage/skills/surface/SKILL.md": "cf3c08a3fe963be7",
"skills/gsd-ns-manage/skills/thread/SKILL.md": "59e0ea339e45a105",
"skills/gsd-ns-manage/skills/undo/SKILL.md": "22d4462c987b7b66",
"skills/gsd-ns-manage/skills/update/SKILL.md": "01ca0efbdb8f6efa",

41
tests/surface-md-paths.regression.test.cjs Normal file
View File

@@ -0,0 +1,41 @@
/**
* Regression test for #2116 — commands/gsd/surface.md had unresolvable bare
* `require('gsd-core/...')` specifiers and a wrong-package reinstall hint
* (`npm i -g gsd-core` instead of `@opengsd/gsd-core`).
*
* This test asserts the doc uses resolvable paths (derived from runtimeConfigDir)
* and the correct scoped package name in the reinstall hint.
*/
'use strict';
const { describe, test } = require('node:test');
const assert = require('node:assert/strict');
const fs = require('fs');
const path = require('path');
const SURFACE_MD = path.join(__dirname, '..', 'commands', 'gsd', 'surface.md');
describe('#2116 regression: surface.md resolvable require + correct package', () => {
const content = fs.readFileSync(SURFACE_MD, 'utf-8');
test('no bare require("gsd-core/...") specifiers', () => {
assert.ok(
!content.match(/require\s*\(\s*['"]gsd-core\//),
'surface.md should not use bare require(\'gsd-core/...\') — use runtimeConfigDir-derived path (#2116)'
);
});
test('reinstall hint uses scoped package name', () => {
assert.ok(
content.includes('@opengsd/gsd-core'),
'surface.md reinstall hint should reference @opengsd/gsd-core, not bare gsd-core (#2116)'
);
});
test('require examples use runtimeConfigDir-derived paths', () => {
assert.ok(
content.includes("require(runtimeConfigDir + '/gsd-core/bin/lib/capability-registry.cjs')"),
'surface.md require examples should derive the path from runtimeConfigDir (#2116)'
);
});
});