@therocketcode/gsd-core 1.4.0

package/scripts/fix-slash-commands.cjs

@@ -0,0 +1,147 @@
+'use strict';
+/**
+ * One-shot script + library: bidirectional GSD slash-command namespace normalizer.
+ *
+ * - Default direction (transformContent): retired /gsd-<cmd> → /gsd:<cmd>
+ *   (keeps monorepo sources, docs, and workflows in the active colon form).
+ * - Reverse direction (transformContentToHyphen): /gsd:<cmd> / gsd:<cmd> → gsd-<cmd>
+ *   (used during skill installation for runtimes that register skills under the
+ *   canonical hyphen form established in #2808).
+ *
+ * Both directions only rewrite known commands from `commands/gsd/*.md` (longest-first
+ * matching + word-boundary safety). Non-commands (gsd-sdk, gsd-tools, etc.) are
+ * intentionally left untouched.
+ *
+ * The transforms are pure and exported for use by the installer and tests.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const COMMANDS_DIR = path.join(__dirname, '..', 'commands', 'gsd');
+const SEARCH_DIRS = [
+  path.join(__dirname, '..', 'gsd-core', 'bin', 'lib'),
+  path.join(__dirname, '..', 'gsd-core', 'workflows'),
+  path.join(__dirname, '..', 'gsd-core', 'references'),
+  path.join(__dirname, '..', 'gsd-core', 'templates'),
+  path.join(__dirname, '..', 'gsd-core', 'contexts'),
+  path.join(__dirname, '..', 'commands', 'gsd'),
+  path.join(__dirname, '..', 'agents'),
+  path.join(__dirname, '..', 'hooks'),
+];
+
+const TOP_LEVEL_FILES = [
+  path.join(__dirname, '..', '.clinerules'),
+];
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.turbo']);
+const EXTENSIONS = new Set(['.md', '.cjs', '.js', '.ts', '.tsx']);
+
+// Test files contain intentional fixture strings (e.g. inputs the sanitizer
+// is expected to strip). Rewriting them changes test semantics.
+function isTestFile(name) {
+  return /\.test\.(c?js|tsx?)$/.test(name);
+}
+
+function buildPattern(cmdNames) {
+  // Empty input would compile `/gsd-()(?=[^a-zA-Z0-9_-]|$)/g`, which the regex
+  // engine still matches at any `/gsd-` token followed by a non-word boundary
+  // (e.g. EOL, whitespace, punctuation) — rewriting it to a stray `/gsd:`.
+  // Short-circuit so the caller can no-op on a missing/empty registry rather
+  // than perform an unintended broad rewrite.
+  if (!Array.isArray(cmdNames) || cmdNames.length === 0) return null;
+  const sorted = [...cmdNames].sort((a, b) => b.length - a.length); // longest first to avoid partial matches
+  return new RegExp(`/gsd-(${sorted.join('|')})(?=[^a-zA-Z0-9_-]|$)`, 'g');
+}
+
+/**
+ * Pure transform: rewrite retired `/gsd-<cmd>` to `/gsd:<cmd>` for the given command names.
+ * Returns the rewritten string. Identifiers not in `cmdNames` (e.g. `/gsd-sdk`,
+ * `/gsd-tools`) are left untouched.
+ */
+function transformContent(src, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return src;
+  return src.replace(pattern, (_, cmd) => `/gsd:${cmd}`);
+}
+
+/**
+ * Build regex for the reverse direction (colon form → hyphen form).
+ * Matches both "gsd:cmd" and "/gsd:cmd" (the leading / is preserved automatically
+ * because it is not part of the match). Uses longest-first ordering plus
+ * bidirectional word-boundary safety (negative lookbehind on the left, lookahead
+ * on the right) so matches only occur at token boundaries.
+ */
+function buildColonPattern(cmdNames) {
+  if (!Array.isArray(cmdNames) || cmdNames.length === 0) return null;
+  const sorted = [...cmdNames].sort((a, b) => b.length - a.length);
+  return new RegExp(`(?<![a-zA-Z0-9_-])gsd:(${sorted.join('|')})(?=[^a-zA-Z0-9_-]|$)`, 'g');
+}
+
+/**
+ * Pure transform (reverse): rewrite `/gsd:<cmd>` / `gsd:<cmd>` to hyphen form
+ * for known GSD commands.
+ *
+ * Non-command identifiers (e.g. gsd-sdk, gsd-tools) are left untouched, matching
+ * the safety contract of the forward transform.
+ */
+function transformContentToHyphen(src, cmdNames) {
+  const pattern = buildColonPattern(cmdNames);
+  if (!pattern) return src;
+  return src.replace(pattern, (_, cmd) => `gsd-${cmd}`);
+}
+
+function readCmdNames() {
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace(/\.md$/, ''));
+}
+
+function processFile(file, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return;
+  let src;
+  try { src = fs.readFileSync(file, 'utf-8'); } catch { return; }
+  const replaced = transformContent(src, cmdNames);
+  if (replaced !== src) {
+    fs.writeFileSync(file, replaced, 'utf-8');
+    const count = (src.match(pattern) || []).length;
+    console.log(`  ${count} replacements: ${path.relative(path.join(__dirname, '..'), file)}`);
+  }
+}
+
+function processDir(dir, cmdNames) {
+  const pattern = buildPattern(cmdNames);
+  if (!pattern) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      processDir(full, cmdNames);
+    } else if (EXTENSIONS.has(path.extname(e.name)) && !isTestFile(e.name)) {
+      processFile(full, cmdNames);
+    }
+  }
+}
+
+if (require.main === module) {
+  const cmdNames = readCmdNames();
+  for (const dir of SEARCH_DIRS) {
+    processDir(dir, cmdNames);
+  }
+  for (const file of TOP_LEVEL_FILES) {
+    processFile(file, cmdNames);
+  }
+  console.log('Done.');
+}
+
+module.exports = {
+  transformContent,
+  transformContentToHyphen,
+  buildPattern,
+  buildColonPattern,
+  readCmdNames,
+  SKIP_DIRS
+};

package/scripts/gen-inventory-manifest.cjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generates docs/INVENTORY-MANIFEST.json — a structural skeleton of every
+ * shipped surface derived entirely from the filesystem. Commit this file;
+ * CI re-runs the script and diffs. A non-empty diff means a surface shipped
+ * without an INVENTORY.md row.
+ *
+ * Usage:
+ *   node scripts/gen-inventory-manifest.cjs              # print to stdout
+ *   node scripts/gen-inventory-manifest.cjs --write      # write docs/INVENTORY-MANIFEST.json
+ *   node scripts/gen-inventory-manifest.cjs --check      # exit 1 if committed manifest is stale
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const MANIFEST_PATH = path.join(ROOT, 'docs', 'INVENTORY-MANIFEST.json');
+
+const FAMILIES = [
+  {
+    name: 'agents',
+    dir: path.join(ROOT, 'agents'),
+    filter: (f) => /^gsd-.*\.md$/.test(f),
+    toName: (f) => f.replace(/\.md$/, ''),
+  },
+  {
+    name: 'commands',
+    dir: path.join(ROOT, 'commands', 'gsd'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => '/gsd-' + f.replace(/\.md$/, ''),
+  },
+  {
+    name: 'workflows',
+    dir: path.join(ROOT, 'gsd-core', 'workflows'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => f,
+  },
+  {
+    name: 'references',
+    dir: path.join(ROOT, 'gsd-core', 'references'),
+    filter: (f) => f.endsWith('.md'),
+    toName: (f) => f,
+  },
+  {
+    name: 'cli_modules',
+    dir: path.join(ROOT, 'gsd-core', 'bin', 'lib'),
+    filter: (f) => f.endsWith('.cjs'),
+    toName: (f) => f,
+  },
+  {
+    name: 'hooks',
+    dir: path.join(ROOT, 'hooks'),
+    filter: (f) => /\.(js|sh)$/.test(f),
+    toName: (f) => f,
+  },
+];
+
+function buildManifest() {
+  const manifest = { generated: new Date().toISOString().slice(0, 10), families: {} };
+  for (const { name, dir, filter, toName } of FAMILIES) {
+    manifest.families[name] = fs
+      .readdirSync(dir)
+      .filter((f) => fs.statSync(path.join(dir, f)).isFile() && filter(f))
+      .map(toName)
+      .sort();
+  }
+  return manifest;
+}
+
+function main() {
+  const [, , flag] = process.argv;
+
+  if (flag === '--check') {
+    const committed = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+    const live = buildManifest();
+    // Strip the generated date for comparison
+    delete committed.generated;
+    delete live.generated;
+    const committedStr = JSON.stringify(committed, null, 2);
+    const liveStr = JSON.stringify(live, null, 2);
+    if (committedStr !== liveStr) {
+      process.stderr.write(
+        'docs/INVENTORY-MANIFEST.json is stale. Run:\n' +
+        '  node scripts/gen-inventory-manifest.cjs --write\n' +
+        'then add a matching row in docs/INVENTORY.md for each new entry.\n\n',
+      );
+      // Show diff-friendly output
+      for (const family of Object.keys(live.families)) {
+        const liveSet = new Set(live.families[family]);
+        const committedSet = new Set((committed.families || {})[family] || []);
+        for (const name of liveSet) {
+          if (!committedSet.has(name)) process.stderr.write('  + ' + family + '/' + name + '\n');
+        }
+        for (const name of committedSet) {
+          if (!liveSet.has(name)) process.stderr.write('  - ' + family + '/' + name + '\n');
+        }
+      }
+      throw new ExitError(1);
+    }
+    process.stdout.write('docs/INVENTORY-MANIFEST.json is up to date.\n');
+  } else if (flag === '--write') {
+    const manifest = buildManifest();
+    fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
+    process.stdout.write('Wrote ' + MANIFEST_PATH + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(buildManifest(), null, 2) + '\n');
+  }
+}
+
+runMain(main);

package/scripts/gen-research-agents.cjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * gen-research-agents.cjs — profile-driven drift guard for the 7 researcher agents.
+ *
+ * Usage:
+ *   node scripts/gen-research-agents.cjs           # same as --check
+ *   node scripts/gen-research-agents.cjs --check   # assert every agent matches its profile
+ *   node scripts/gen-research-agents.cjs --write   # regenerate frontmatter from profiles
+ *
+ * --check assertions per agent:
+ *   (a) frontmatter name/description/color/tools exactly match the profile
+ *   (b) every requiredInclude string is present in the body
+ *   (c) every requiredSeamCall string is present in the body
+ *   (d) every outputContract marker string is present in the body
+ *
+ * --write regenerates ONLY the opening `---\n...\n---` frontmatter block from the
+ * profile, leaving the body byte-identical. After --write, --check must pass and
+ * `git diff` must be empty (profiles were derived from current state).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { PROFILES } = require('./research-profiles.cjs');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const AGENTS_DIR = path.join(ROOT, 'agents');
+
+// ─── Frontmatter serialization ────────────────────────────────────────────────
+
+/**
+ * Build the frontmatter block for a profile.
+ *
+ * The agent files have two patterns for commented hooks:
+ *   - Agents with Write in tools (file-writers): include the commented hooks block
+ *   - The advisor-researcher (Read-only tools, no Write): no commented hooks
+ *
+ * We read the CURRENT commented-hooks block from the agent file and preserve it
+ * byte-for-byte; only name/description/tools/color are regenerated.
+ */
+function buildFrontmatter(profile, existingFrontmatter) {
+  // Extract the commented hooks section from the existing frontmatter, if any.
+  // The hooks block starts at `# hooks:` and runs to (but not including) the
+  // closing `---`. In the committed files there is NO blank line between
+  // `color:` and `# hooks:`, so we append it directly after the color line's `\n`.
+  const hooksMatch = existingFrontmatter.match(/(# hooks:[\s\S]*?)(?=\n---)/);
+  // hooksSuffix: if present, the block followed by a newline so `---` is on its own line;
+  // if absent, empty string (the closing `---` follows directly after color's `\n`).
+  const hooksSuffix = hooksMatch ? hooksMatch[1] + '\n' : '';
+
+  return (
+    '---\n' +
+    'name: ' + profile.name + '\n' +
+    'description: ' + profile.description + '\n' +
+    'tools: ' + profile.tools + '\n' +
+    'color: ' + profile.color + '\n' +
+    hooksSuffix +
+    '---'
+  );
+}
+
+// ─── Parse agent file ─────────────────────────────────────────────────────────
+
+/**
+ * Parse a .md file and return { frontmatterRaw, body, frontmatterFields }.
+ *
+ * frontmatterRaw: the raw text between the first and second `---` delimiters (exclusive)
+ * body: everything after the closing `---\n`
+ * frontmatterFields: { name, description, color, tools }
+ */
+function parseAgentFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // The frontmatter is between the first `---` line and the next `---` line.
+  const lines = raw.split('\n');
+  let start = -1;
+  let end = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '---') {
+      if (start === -1) {
+        start = i;
+      } else {
+        end = i;
+        break;
+      }
+    }
+  }
+
+  if (start === -1 || end === -1) {
+    throw new Error('No valid frontmatter delimiters found in ' + filePath);
+  }
+
+  const frontmatterLines = lines.slice(start + 1, end);
+  const frontmatterRaw = frontmatterLines.join('\n');
+  // body includes the closing `---` line and everything after
+  const fullFrontmatter = lines.slice(start, end + 1).join('\n');
+  const body = lines.slice(end + 1).join('\n');
+
+  const fields = {};
+  // Parse simple key: value pairs (not nested YAML, no multi-line values here)
+  for (const line of frontmatterLines) {
+    // Skip comment lines
+    if (line.trimStart().startsWith('#')) continue;
+    const m = line.match(/^(\w+):\s*(.*)/);
+    if (m) {
+      fields[m[1]] = m[2].trim();
+    }
+  }
+
+  return { raw, frontmatterRaw, fullFrontmatter, body, fields };
+}
+
+// ─── Check ────────────────────────────────────────────────────────────────────
+
+/**
+ * Check one profile against its agent file.
+ * Returns an array of failure strings (empty = pass).
+ */
+function checkAgent(profile) {
+  // Validate required array fields — return a clear failure rather than throwing TypeError.
+  for (const field of ['requiredIncludes', 'requiredSeamCalls', 'outputContract']) {
+    if (!Array.isArray(profile[field])) {
+      return ['profile ' + profile.name + ': missing required array field ' + field];
+    }
+  }
+
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const failures = [];
+
+  if (!fs.existsSync(agentPath)) {
+    return ['agent file not found: ' + agentPath];
+  }
+
+  const { fields } = parseAgentFile(agentPath);
+  const fullContent = fs.readFileSync(agentPath, 'utf8');
+
+  // (a) frontmatter fields
+  if (fields.name !== profile.name) {
+    failures.push(
+      'name mismatch: got "' + fields.name + '", want "' + profile.name + '"',
+    );
+  }
+  if (fields.description !== profile.description) {
+    failures.push(
+      'description mismatch:\n  got:  "' + fields.description + '"\n  want: "' + profile.description + '"',
+    );
+  }
+  if (fields.color !== profile.color) {
+    failures.push(
+      'color mismatch: got "' + fields.color + '", want "' + profile.color + '"',
+    );
+  }
+  if (fields.tools !== profile.tools) {
+    failures.push(
+      'tools mismatch:\n  got:  "' + fields.tools + '"\n  want: "' + profile.tools + '"',
+    );
+  }
+
+  // (b) requiredIncludes
+  for (const include of profile.requiredIncludes) {
+    if (!fullContent.includes(include)) {
+      failures.push('missing required include: ' + include);
+    }
+  }
+
+  // (c) requiredSeamCalls
+  for (const seam of profile.requiredSeamCalls) {
+    if (!fullContent.includes(seam)) {
+      failures.push('missing required seam call: ' + seam);
+    }
+  }
+
+  // (d) outputContract
+  for (const marker of profile.outputContract) {
+    if (!fullContent.includes(marker)) {
+      failures.push('missing output contract marker: ' + marker);
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Run --check for all profiles. Prints pass/fail per agent.
+ * Returns true if all pass, false otherwise.
+ */
+function runCheck() {
+  let allPassed = true;
+
+  for (const profile of PROFILES) {
+    const failures = checkAgent(profile);
+    if (failures.length === 0) {
+      process.stdout.write('  PASS  ' + profile.name + '\n');
+    } else {
+      process.stdout.write('  FAIL  ' + profile.name + '\n');
+      for (const f of failures) {
+        process.stdout.write('        ' + f.replace(/\n/g, '\n        ') + '\n');
+      }
+      allPassed = false;
+    }
+  }
+
+  return allPassed;
+}
+
+// ─── Write ────────────────────────────────────────────────────────────────────
+
+/**
+ * Regenerate the frontmatter block of one agent file from its profile.
+ * The body (everything after the closing ---) is preserved byte-for-byte.
+ */
+function writeAgent(profile) {
+  const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+  const { fullFrontmatter, body } = parseAgentFile(agentPath);
+
+  const newFrontmatter = buildFrontmatter(profile, fullFrontmatter);
+  const newContent = newFrontmatter + '\n' + body;
+
+  fs.writeFileSync(agentPath, newContent, 'utf8');
+}
+
+function runWrite() {
+  for (const profile of PROFILES) {
+    const agentPath = path.join(AGENTS_DIR, profile.name + '.md');
+    if (!fs.existsSync(agentPath)) {
+      throw new ExitError(1, 'ERROR: agent file not found: ' + agentPath);
+    }
+    writeAgent(profile);
+    process.stdout.write('  wrote  ' + profile.name + '.md\n');
+  }
+  process.stdout.write('\nRun --check to verify:\n');
+  process.stdout.write('  node scripts/gen-research-agents.cjs --check\n');
+}
+
+// ─── Exports (for tests) ──────────────────────────────────────────────────────
+
+module.exports = { PROFILES, checkAgent, runCheck, parseAgentFile };
+
+// ─── CLI entry point ──────────────────────────────────────────────────────────
+
+function main() {
+  const flag = process.argv[2] || '--check';
+
+  if (flag === '--write') {
+    process.stdout.write('Writing frontmatter from profiles...\n');
+    runWrite();
+    process.stdout.write('\nVerifying...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nERROR: --check failed after --write. Fix serialization.\n');
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll agents match their profiles.\n');
+  } else if (flag === '--check') {
+    process.stdout.write('Checking research agent profiles...\n');
+    const ok = runCheck();
+    if (!ok) {
+      process.stderr.write('\nSome agents do not match their profiles.\n');
+      process.stdout.write(
+        '\nTo regenerate frontmatter from profiles:\n' +
+        '  node scripts/gen-research-agents.cjs --write\n',
+      );
+      throw new ExitError(1);
+    }
+    process.stdout.write('\nAll 7 agents match their profiles.\n');
+  } else {
+    throw new ExitError(1, 'Unknown flag: ' + flag + '\nUsage: node scripts/gen-research-agents.cjs [--check|--write]');
+  }
+}
+
+if (require.main === module) {
+  runMain(main);
+}

package/scripts/generate-package-identity.cjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Single source for GSD's published-package coordinates (issue #498).
+ *
+ * `deriveIdentity(pkg)` is the pure core: it turns a parsed package.json into
+ * the coordinate record every consumer needs. The generated runtime module
+ * `gsd-core/bin/lib/package-identity.cjs` bakes those values at build
+ * time, because the installed tree carries only a synthetic
+ * `{"type":"commonjs"}` package.json (no `.name`) — so a runtime
+ * `require('package.json').name` resolves to `undefined` (the #378 bug this
+ * seam retires). Baking from package.json reconciles #378 (renames survive)
+ * with #2992 (the value is never an LLM runtime choice).
+ */
+
+/**
+ * Parse `owner/name` out of a package.json `repository.url`, stripping the
+ * `git+` prefix and `.git` suffix npm conventionally adds.
+ */
+function parseRepoSlug(repository) {
+  const url = typeof repository === 'string' ? repository : (repository && repository.url) || '';
+  const m = url.replace(/^git\+/, '').replace(/\.git$/, '').match(/github\.com[/:]([^/]+\/[^/]+)$/);
+  return m ? m[1] : '';
+}
+
+/**
+ * Pure: turn an npm package name into a filesystem-safe slug for cache filenames.
+ * Strips a leading `@`, replaces `/` with `-`, then collapses any run of
+ * characters that are NOT `[a-z0-9]` to a single `-`, and trims leading/trailing `-`.
+ */
+function slugifyPackageName(name) {
+  if (!name) return '';
+  return name
+    .replace(/^@/, '')
+    .replace(/\//g, '-')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Pure: package.json object -> the package identity coordinates.
+ */
+function deriveIdentity(pkg = {}) {
+  const packageName = pkg.name || '';
+  const binName = pkg.bin ? Object.keys(pkg.bin)[0] || '' : '';
+  const repoSlug = parseRepoSlug(pkg.repository);
+  const repoUrl = repoSlug ? `https://github.com/${repoSlug}` : '';
+  const changelogRawUrl = repoSlug
+    ? `https://raw.githubusercontent.com/${repoSlug}/main/CHANGELOG.md`
+    : '';
+  const cacheSlug = slugifyPackageName(packageName);
+  const updateCacheFileName = cacheSlug ? `gsd-update-check-${cacheSlug}.json` : 'gsd-update-check.json';
+  return { packageName, binName, repoSlug, repoUrl, changelogRawUrl, cacheSlug, updateCacheFileName };
+}
+
+/**
+ * Pure: format the `npx` fallback install command. Shape matches the literal
+ * the update workflow embeds: `npx -y --package=<pkg>@latest -- <bin>
+ * [--<runtime>] --<scope>`. The runtime flag is omitted when not supplied.
+ *
+ * This function is the canonical source — `render()` serializes it verbatim
+ * into the generated module, so the runtime copy can never drift from it.
+ */
+function formatManualInstall({ packageName, binName, scope, runtime } = {}) {
+  const runtimeFlag = runtime ? ` --${runtime}` : '';
+  return `npx -y --package=${packageName}@latest -- ${binName}${runtimeFlag} --${scope}`;
+}
+
+const GENERATED_HEADER =
+  '// @generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.\n' +
+  '// Single source for GSD package coordinates (issue #498). Regenerate with:\n' +
+  '//   node scripts/generate-package-identity.cjs\n';
+
+/**
+ * Render the generated runtime module text for a derived identity. Values are
+ * baked as literals; `formatManualInstall` is embedded by `.toString()` so the
+ * runtime command builder is byte-identical to the tested source above.
+ */
+function render(identity) {
+  const { packageName, binName, repoSlug, repoUrl, changelogRawUrl, cacheSlug, updateCacheFileName } = identity;
+  const j = (v) => JSON.stringify(v);
+  return (
+    GENERATED_HEADER +
+    "'use strict';\n\n" +
+    `const packageName = ${j(packageName)};\n` +
+    `const binName = ${j(binName)};\n` +
+    `const repoSlug = ${j(repoSlug)};\n` +
+    `const repoUrl = ${j(repoUrl)};\n` +
+    `const changelogRawUrl = ${j(changelogRawUrl)};\n` +
+    `const cacheSlug = ${j(cacheSlug)};\n` +
+    `const updateCacheFileName = ${j(updateCacheFileName)};\n\n` +
+    `${formatManualInstall.toString()}\n\n` +
+    'function manualInstallCommand(opts = {}) {\n' +
+    '  return formatManualInstall({ packageName, binName, scope: opts.scope, runtime: opts.runtime });\n' +
+    '}\n\n' +
+    'module.exports = Object.freeze({\n' +
+    '  packageName,\n' +
+    '  // PACKAGE_NAME: back-compat alias for #516-era consumers. Baked here, so it\n' +
+    "  // survives the installed tree's synthetic package.json (fixes the #378 undefined).\n" +
+    '  PACKAGE_NAME: packageName,\n' +
+    '  binName,\n' +
+    '  repoSlug,\n' +
+    '  repoUrl,\n' +
+    '  changelogRawUrl,\n' +
+    '  cacheSlug,\n' +
+    '  updateCacheFileName,\n' +
+    '  manualInstallCommand,\n' +
+    '});\n'
+  );
+}
+
+function main() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const pkg = require(path.join(__dirname, '..', 'package.json'));
+  const out = path.join(__dirname, '..', 'gsd-core', 'bin', 'lib', 'package-identity.cjs');
+  fs.writeFileSync(out, render(deriveIdentity(pkg)));
+  process.stdout.write(`wrote ${path.relative(path.join(__dirname, '..'), out)}\n`);
+}
+
+if (require.main === module) main();
+
+module.exports = { deriveIdentity, parseRepoSlug, slugifyPackageName, formatManualInstall, render, main };