@hegemonart/get-design-done 1.28.7 → 1.30.0

package/scripts/build-distribution-bundles.cjs

@@ -0,0 +1,549 @@
+'use strict';
+/**
+ * scripts/build-distribution-bundles.cjs — Phase 28.8 (Plan 28-8-X1).
+ *
+ * Shared-source / multi-channel distribution bundler.
+ *
+ * Per CONTEXT D-06: skills are shared source / per-channel converters at
+ * distribution-build time. This script fans out canonical `skills/` into
+ * three channel-specific bundles under `dist/`:
+ *
+ *   - dist/cursor-marketplace/  (via scripts/lib/install/converters/cursor-marketplace.cjs)
+ *   - dist/codex-plugin/        (via scripts/lib/install/converters/codex-plugin.cjs)
+ *   - dist/agentskills-io/      (passthrough per D-13 lint-only)
+ *
+ * Tier-2 channels are discovered by inspecting `runtimes.cjs` entries with
+ * `kind: 'cursor-marketplace'` or `kind: 'codex-plugin'`. `agentskills-io`
+ * is hardcoded as a passthrough (it's a spec, not a runtime — D-02/D-13).
+ *
+ * Determinism: two consecutive runs produce byte-identical output.
+ * Tier-1 unaffected: only writes under `dist/`.
+ *
+ * --- ADAPTER NOTE (Plan 28-8-X1 implementation): the Wave-B converters
+ * (B1: cursor-marketplace.cjs, C1: codex-plugin.cjs) actually export
+ * `{ buildManifest, convert, CURATED_KEYWORDS }` — NOT the
+ * `{ convertSkill, buildManifest, MANIFEST_PATH }` shape that the plan's
+ * `<interfaces>` block hypothesized. Per the plan's "Adapter divergence
+ * handling" clause, this bundler adapts to the actual converter shape
+ * rather than modifying the converters (which are already shipped and
+ * out of scope per D-05).
+ *
+ * Actual converter contract used here:
+ *   - converter.buildManifest({ packageJson, claudePlugin, claudePluginJson,
+ *                               marketplaceJson, readmeFirstPara })
+ *       → returns a manifest OBJECT (not a string).
+ *       (cursor-marketplace looks for `claudePluginJson`; codex-plugin
+ *        looks for `claudePlugin`. We pass BOTH keys to be compatible
+ *        with either accessor.)
+ *   - converter.convert({ skillsDir, outDir, manifest })
+ *       → writes manifest + copies skills/ tree under outDir. Owns its
+ *        own manifest path (.cursor-plugin/plugin.json or .codex-plugin/
+ *        plugin.json) — the bundler doesn't need to know.
+ *
+ * CLI:
+ *   node scripts/build-distribution-bundles.cjs              # all channels
+ *   node scripts/build-distribution-bundles.cjs --channel cursor-marketplace
+ *   node scripts/build-distribution-bundles.cjs --help
+ *
+ * Exit codes: 0 ok / 1 converter error / 2 missing dependency.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const EXIT_CODES = Object.freeze({
+  OK: 0,
+  CONVERTER_ERROR: 1,
+  MISSING_DEPENDENCY: 2,
+});
+
+// agentskills-io is hardcoded — it is a spec, not a runtime entry
+// (per CONTEXT D-02 / D-13). No converter file, no manifest file.
+const PASSTHROUGH_CHANNEL = Object.freeze({
+  id: 'agentskills-io',
+  kind: 'passthrough',
+  converterPath: null,
+});
+
+// Set of runtime `kind` values that the bundler dispatches to Wave-B
+// converters. Hardcoded to two kinds — adding a third Tier-2 channel in
+// a future phase requires (a) adding the runtime entry with a new kind,
+// (b) shipping a converter at scripts/lib/install/converters/<kind>.cjs,
+// (c) extending this set. The channel-ID discovery itself is data-driven.
+const TIER2_KINDS = Object.freeze(new Set(['cursor-marketplace', 'codex-plugin']));
+
+// ---------------------------------------------------------------
+// Channel discovery
+// ---------------------------------------------------------------
+
+/**
+ * Discover Tier-2 channels from the runtimes registry + add the hardcoded
+ * passthrough channel. Returns Array<{id, kind, converterPath}>.
+ *
+ * `runtimesModule` is dependency-injected so tests can supply a fixture.
+ * Production callers pass `require('./lib/install/runtimes.cjs')`.
+ *
+ * Determinism: runtime list sorted lexicographically by id before iteration.
+ * The hardcoded PASSTHROUGH_CHANNEL is appended last; callers that want a
+ * fully lexicographic ordering should re-sort the returned array.
+ */
+function discoverTier2Channels(runtimesModule) {
+  const channels = [];
+  const runtimes = (runtimesModule && typeof runtimesModule.listRuntimes === 'function')
+    ? runtimesModule.listRuntimes()
+    : [];
+  const sorted = runtimes.slice().sort((a, b) => a.id.localeCompare(b.id));
+  for (const rt of sorted) {
+    if (!TIER2_KINDS.has(rt.kind)) continue;
+    channels.push({
+      id: rt.id,
+      kind: rt.kind,
+      // Converter file lives at scripts/lib/install/converters/<kind>.cjs.
+      // T-28.8-X1-01 (Tampering / require()): `kind` originates in the
+      // version-controlled runtimes.cjs file — an attacker would already
+      // need write access to introduce a malicious value. Acceptable.
+      converterPath: path.join(
+        __dirname,
+        'lib', 'install', 'converters',
+        rt.kind + '.cjs',
+      ),
+    });
+  }
+  channels.push(PASSTHROUGH_CHANNEL);
+  return channels;
+}
+
+// ---------------------------------------------------------------
+// Skill enumeration (canonical source)
+// ---------------------------------------------------------------
+
+/**
+ * Enumerate child directories of `<sourceRoot>/skills/` that contain a
+ * `SKILL.md`. Returns { skillsRoot, skillNames } where skillNames is
+ * sorted lexicographically (determinism).
+ *
+ * Throws Error with code MISSING_SKILLS_ROOT if skills/ is absent.
+ */
+function enumerateSkills(sourceRoot) {
+  const skillsRoot = path.join(sourceRoot, 'skills');
+  if (!fs.existsSync(skillsRoot)) {
+    const err = new Error('Canonical skills/ tree not found at ' + skillsRoot);
+    err.code = 'MISSING_SKILLS_ROOT';
+    throw err;
+  }
+  const names = fs.readdirSync(skillsRoot)
+    .filter((name) => {
+      const skillDir = path.join(skillsRoot, name);
+      try {
+        return fs.statSync(skillDir).isDirectory()
+          && fs.existsSync(path.join(skillDir, 'SKILL.md'));
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+  return { skillsRoot, skillNames: names };
+}
+
+// ---------------------------------------------------------------
+// Filesystem helpers
+// ---------------------------------------------------------------
+
+function ensureCleanDir(dirPath) {
+  if (fs.existsSync(dirPath)) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+  }
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+/**
+ * Deterministic file write: 0o644, no timestamp metadata leaked into content.
+ */
+function writeFile(dest, content) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, content, { mode: 0o644 });
+}
+
+/**
+ * Recursive byte-for-byte copy of `srcDir` into `destDir`. Used by the
+ * passthrough channel. Deterministic: lexicographic readdir + 0o644.
+ *
+ * T-28.8-X1-03 (Tampering / symlinks): only entry.isFile() and
+ * entry.isDirectory() are propagated. Symlinks and other types are
+ * silently skipped — the canonical skills/ tree is expected to be
+ * regular files only.
+ */
+function copyDirRecursive(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else if (entry.isFile()) {
+      const content = fs.readFileSync(srcPath);
+      writeFile(destPath, content);
+    }
+    // Symlinks / other entry types: skip.
+  }
+}
+
+function countFiles(dir) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, entry.name);
+      if (entry.isDirectory()) stack.push(p);
+      else if (entry.isFile()) count++;
+    }
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------
+// Optional ancillary sources (loaded best-effort from repo root)
+// ---------------------------------------------------------------
+
+/**
+ * Best-effort loader for ancillary inputs the converters may consult:
+ *   - .claude-plugin/plugin.json     → claudePlugin / claudePluginJson
+ *   - .claude-plugin/marketplace.json → marketplaceJson
+ *   - README.md (first paragraph)    → readmeFirstPara
+ *
+ * Returns an object with each key present only if the corresponding source
+ * exists and parses cleanly. Never throws — converters are tolerant of
+ * absent optional sources, and tmpdir test fixtures typically omit them.
+ */
+function loadAncillarySources(sourceRoot) {
+  const sources = {};
+  const pluginJsonPath = path.join(sourceRoot, '.claude-plugin', 'plugin.json');
+  if (fs.existsSync(pluginJsonPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+      sources.claudePlugin = parsed;
+      sources.claudePluginJson = parsed;
+    } catch {
+      // Best-effort: malformed plugin.json is the converter's problem,
+      // not the bundler's. Continue without it.
+    }
+  }
+  const marketplaceJsonPath = path.join(sourceRoot, '.claude-plugin', 'marketplace.json');
+  if (fs.existsSync(marketplaceJsonPath)) {
+    try {
+      sources.marketplaceJson = JSON.parse(fs.readFileSync(marketplaceJsonPath, 'utf8'));
+    } catch {
+      // skip
+    }
+  }
+  const readmePath = path.join(sourceRoot, 'README.md');
+  if (fs.existsSync(readmePath)) {
+    try {
+      const raw = fs.readFileSync(readmePath, 'utf8');
+      // First non-empty, non-heading paragraph.
+      const paragraphs = raw.split(/\n\s*\n/);
+      for (const p of paragraphs) {
+        const trimmed = p.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        sources.readmeFirstPara = trimmed.replace(/\s+/g, ' ');
+        break;
+      }
+    } catch {
+      // skip
+    }
+  }
+  return sources;
+}
+
+// ---------------------------------------------------------------
+// Channel build dispatch
+// ---------------------------------------------------------------
+
+/**
+ * Build a single channel into `outRoot/<channelId>/`.
+ * Returns { channel, fileCount }.
+ *
+ * Throws on converter error or missing dependency — caller maps to exit code.
+ *
+ * Errors set `err.code` to one of:
+ *   - 'MISSING_CONVERTER'      → exit 2
+ *   - 'CONVERTER_LOAD_FAILED'  → exit 2 (require() failed — broken module)
+ *   - 'CONVERTER_EXEC_FAILED'  → exit 1 (converter ran and threw)
+ *   - 'MANIFEST_BUILD_FAILED'  → exit 1 (buildManifest threw)
+ *   - 'MISSING_SKILLS_ROOT'    → exit 2 (no skills/ dir to read)
+ */
+function buildChannel(channel, opts) {
+  const { sourceRoot, outRoot, packageJson } = opts || {};
+  if (!channel || typeof channel !== 'object') {
+    throw new Error('buildChannel: channel is required');
+  }
+  if (typeof sourceRoot !== 'string' || sourceRoot.length === 0) {
+    throw new Error('buildChannel: opts.sourceRoot is required');
+  }
+  if (typeof outRoot !== 'string' || outRoot.length === 0) {
+    throw new Error('buildChannel: opts.outRoot is required');
+  }
+
+  const bundleRoot = path.join(outRoot, channel.id);
+  ensureCleanDir(bundleRoot);
+
+  if (channel.kind === 'passthrough') {
+    // agentskills-io: passthrough copy of skills/ (D-13).
+    const skillsSrc = path.join(sourceRoot, 'skills');
+    if (!fs.existsSync(skillsSrc)) {
+      const err = new Error('Canonical skills/ tree not found at ' + skillsSrc);
+      err.code = 'MISSING_SKILLS_ROOT';
+      err.channelId = channel.id;
+      throw err;
+    }
+    copyDirRecursive(skillsSrc, path.join(bundleRoot, 'skills'));
+    return { channel: channel.id, fileCount: countFiles(bundleRoot) };
+  }
+
+  // Tier-2 converter-backed channels (cursor-marketplace, codex-plugin).
+  if (!fs.existsSync(channel.converterPath)) {
+    const err = new Error(
+      'Missing converter for channel "' + channel.id + '": expected at ' + channel.converterPath
+    );
+    err.code = 'MISSING_CONVERTER';
+    err.channelId = channel.id;
+    throw err;
+  }
+
+  let converter;
+  try {
+    converter = require(channel.converterPath);
+  } catch (e) {
+    const err = new Error(
+      'Failed to load converter for channel "' + channel.id + '": ' + e.message
+    );
+    err.code = 'CONVERTER_LOAD_FAILED';
+    err.channelId = channel.id;
+    err.cause = e;
+    throw err;
+  }
+
+  if (typeof converter.buildManifest !== 'function' || typeof converter.convert !== 'function') {
+    const err = new Error(
+      'Converter for channel "' + channel.id + '" missing required exports: ' +
+      'expected { buildManifest, convert }, got ' + Object.keys(converter).join(', ')
+    );
+    err.code = 'CONVERTER_LOAD_FAILED';
+    err.channelId = channel.id;
+    throw err;
+  }
+
+  // Enumerate skills BEFORE invoking convert(). This both validates that
+  // skills/ exists and surfaces a deterministic name list for error
+  // messages — convert() will re-walk the directory itself per its own
+  // semantics, which is fine (idempotent) but we want a stable list for
+  // the CONVERTER_EXEC_FAILED error message.
+  const { skillsRoot, skillNames } = enumerateSkills(sourceRoot);
+
+  // Build manifest via the converter.
+  // Pass BOTH `claudePlugin` and `claudePluginJson` accessor keys so the
+  // adapter works regardless of which key the specific converter consults.
+  const ancillary = loadAncillarySources(sourceRoot);
+  const sources = Object.assign({}, ancillary, { packageJson });
+
+  let manifest;
+  try {
+    manifest = converter.buildManifest(sources);
+  } catch (e) {
+    const err = new Error(
+      'Converter "' + channel.id + '" failed building manifest: ' + e.message
+    );
+    err.code = 'MANIFEST_BUILD_FAILED';
+    err.channelId = channel.id;
+    err.cause = e;
+    throw err;
+  }
+
+  // Invoke convert() — converter writes manifest + copies skills/ under outDir.
+  try {
+    converter.convert({
+      skillsDir: skillsRoot,
+      outDir: bundleRoot,
+      manifest,
+    });
+  } catch (e) {
+    // The converter walked skills/ internally so we don't know which
+    // individual skill triggered the throw — surface the full list to
+    // aid debugging.
+    const skillsHint = skillNames.length > 0
+      ? ' (skills: ' + skillNames.join(', ') + ')'
+      : '';
+    const err = new Error(
+      'Converter "' + channel.id + '" failed during convert()' + skillsHint + ': ' + e.message
+    );
+    err.code = 'CONVERTER_EXEC_FAILED';
+    err.channelId = channel.id;
+    err.skillName = skillNames[0] || null;
+    err.cause = e;
+    throw err;
+  }
+
+  return { channel: channel.id, fileCount: countFiles(bundleRoot) };
+}
+
+/**
+ * Build all (or one filtered) channel(s) into `outRoot`.
+ *
+ * Options:
+ *   sourceRoot      — repo root containing skills/ + ancillary sources
+ *   outRoot         — destination root (e.g., repo/dist)
+ *   runtimesModule  — dependency-injected runtimes registry (test seam)
+ *   packageJson     — parsed package.json object passed to converters
+ *   channelFilter   — optional channel id to scope the build to one channel
+ *
+ * Returns Array<{ channel, fileCount }> in lexicographic channel order.
+ */
+function buildAllChannels(opts) {
+  const { sourceRoot, outRoot, runtimesModule, packageJson, channelFilter } = opts || {};
+  const channels = discoverTier2Channels(runtimesModule);
+  const targets = channelFilter
+    ? channels.filter((c) => c.id === channelFilter)
+    : channels;
+  if (channelFilter && targets.length === 0) {
+    const err = new Error(
+      'Unknown channel: "' + channelFilter + '". Available: ' +
+      channels.map((c) => c.id).join(', ')
+    );
+    err.code = 'UNKNOWN_CHANNEL';
+    throw err;
+  }
+  // Lexicographic order for deterministic stdout + filesystem traversal.
+  targets.sort((a, b) => a.id.localeCompare(b.id));
+  const results = [];
+  for (const channel of targets) {
+    results.push(buildChannel(channel, { sourceRoot, outRoot, packageJson }));
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------
+// CLI entrypoint
+// ---------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { help: false, channel: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      args.help = true;
+    } else if (a === '--channel') {
+      if (i + 1 >= argv.length) {
+        throw new Error('--channel requires a value');
+      }
+      args.channel = argv[++i];
+    } else {
+      throw new Error('Unknown argument: ' + a);
+    }
+  }
+  return args;
+}
+
+function printUsage(out) {
+  out.write([
+    'Usage: node scripts/build-distribution-bundles.cjs [--channel <id>]',
+    '',
+    'Builds Tier-2 distribution bundles from canonical skills/ into dist/.',
+    '',
+    'Options:',
+    '  --channel <id>   Build only the named channel (e.g., cursor-marketplace,',
+    '                   codex-plugin, agentskills-io). Default: all channels.',
+    '  --help, -h       Print this message.',
+    '',
+    'Exit codes:',
+    '  0  success',
+    '  1  converter error (converter ran and threw)',
+    '  2  missing dependency (converter file, runtimes.cjs entry, skills/, or bad arg)',
+    '',
+  ].join('\n'));
+}
+
+function main(argv, ioOpts) {
+  const stdout = (ioOpts && ioOpts.stdout) || process.stdout;
+  const stderr = (ioOpts && ioOpts.stderr) || process.stderr;
+
+  let args;
+  try {
+    args = parseArgs(argv || []);
+  } catch (e) {
+    stderr.write('Error: ' + e.message + '\n');
+    printUsage(stderr);
+    return EXIT_CODES.MISSING_DEPENDENCY;
+  }
+  if (args.help) {
+    printUsage(stdout);
+    return EXIT_CODES.OK;
+  }
+
+  const repoRoot = path.resolve(__dirname, '..');
+  const sourceRoot = repoRoot;
+  const outRoot = path.join(repoRoot, 'dist');
+
+  let runtimesModule;
+  try {
+    runtimesModule = require('./lib/install/runtimes.cjs');
+  } catch (e) {
+    stderr.write('Error: failed to load runtimes.cjs: ' + e.message + '\n');
+    return EXIT_CODES.MISSING_DEPENDENCY;
+  }
+
+  let packageJson;
+  try {
+    packageJson = require(path.join(repoRoot, 'package.json'));
+  } catch (e) {
+    stderr.write('Error: failed to load package.json: ' + e.message + '\n');
+    return EXIT_CODES.MISSING_DEPENDENCY;
+  }
+
+  try {
+    const results = buildAllChannels({
+      sourceRoot,
+      outRoot,
+      runtimesModule,
+      packageJson,
+      channelFilter: args.channel,
+    });
+    for (const r of results) {
+      stdout.write('[bundles] ' + r.channel + ': ' + r.fileCount + ' file(s)\n');
+    }
+    return EXIT_CODES.OK;
+  } catch (e) {
+    stderr.write('Error: ' + e.message + '\n');
+    if (
+      e.code === 'MISSING_CONVERTER' ||
+      e.code === 'MISSING_SKILLS_ROOT' ||
+      e.code === 'UNKNOWN_CHANNEL' ||
+      e.code === 'CONVERTER_LOAD_FAILED'
+    ) {
+      return EXIT_CODES.MISSING_DEPENDENCY;
+    }
+    // CONVERTER_EXEC_FAILED, MANIFEST_BUILD_FAILED, or anything else.
+    return EXIT_CODES.CONVERTER_ERROR;
+  }
+}
+
+module.exports = {
+  buildAllChannels,
+  buildChannel,
+  discoverTier2Channels,
+  enumerateSkills,
+  loadAncillarySources,
+  main,
+  parseArgs,
+  EXIT_CODES,
+  PASSTHROUGH_CHANNEL,
+  TIER2_KINDS,
+};
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/scripts/cli/gdd-events.mjs

@@ -50,6 +50,7 @@ function usage() {
       '  gdd-events cat [--path=<p>]',
       '  gdd-events list-types',
       '  gdd-events serve [--port=<n>] [--token=<t>] [--tail=<file>]',
+      '  gdd-events --type <typename> [--path=<p>]   (Plan 29-03 ergonomic alias for `grep type=<typename>`)',
       '',
       'Filter language (grep): type=<s>  payload.<dotted.path>=<s>  !type=<s>',
       '',
@@ -59,11 +60,22 @@ function usage() {
 
 function parseArgs(args) {
   const out = { _: [], flags: {} };
-  for (const a of args) {
+  // Flags that take a value via the space-separated form `--flag <value>`.
+  // Without this set, `--type capability_gap` would be parsed as
+  // { flags: { type: true } } and the value would land in positional args.
+  const VALUE_FLAGS = new Set(['type', 'path', 'port', 'token', 'tail']);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
     if (a.startsWith('--')) {
       const eq = a.indexOf('=');
       if (eq === -1) {
-        out.flags[a.slice(2)] = true;
+        const name = a.slice(2);
+        if (VALUE_FLAGS.has(name) && i + 1 < args.length && !args[i + 1].startsWith('--')) {
+          out.flags[name] = args[i + 1];
+          i += 1;
+        } else {
+          out.flags[name] = true;
+        }
       } else {
         out.flags[a.slice(2, eq)] = a.slice(eq + 1);
       }
@@ -242,6 +254,27 @@ async function cmdServe(parsed) {
 
 async function main() {
   const parsed = parseArgs(argv.slice(2));
+
+  // Plan 29-03: `--type <typename>` (and `--type=<typename>`) is an ergonomic
+  // alias for `grep type=<typename>`. Desugar BEFORE shifting the subcommand
+  // so the flag can be used without a subcommand prefix:
+  //   gdd-events --type capability_gap --path=…
+  // Equivalent to:
+  //   gdd-events grep type=capability_gap --path=…
+  if (typeof parsed.flags.type === 'string' && parsed.flags.type.length > 0) {
+    const typeValue = parsed.flags.type;
+    delete parsed.flags.type;
+    // Inject the filter term and force the grep code path. Preserve any
+    // additional positional terms the user already supplied.
+    parsed._ = [`type=${typeValue}`, ...parsed._];
+    try {
+      return await cmdGrep(parsed);
+    } catch (err) {
+      stderr.write(`gdd-events: ${err && err.message ? err.message : String(err)}\n`);
+      return 1;
+    }
+  }
+
   const sub = parsed._.shift();
   try {
     switch (sub) {