sdd-forge 0.1.0-alpha.622 → 0.1.0-alpha.692

package/README.md

@@ -129,12 +129,12 @@ See the [configuration reference](docs/configuration.md) for details.
 <!-- {{data("cli.docs.chapters", {header: "", labels: "Chapter|Summary", ignoreError: true})}} -->
 | Chapter | Summary |
 | --- | --- |
-| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter introduces sdd-forge — a CLI tool for automated documentation generation and Spec-Driven Development (SD… |
-| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | sdd-forge is implemented in JavaScript using Node.js (>=18.0.0) with the ES Modules system, and is distributed as a z… |
-| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | This chapter describes the source layout of sdd-forge across three major directory groups: src/docs (documentation ge… |
-| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | The CLI provides over 30 commands organized in a three-level dispatch hierarchy: the top-level sdd-forge entry point … |
-| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge reads a single JSON configuration file placed inside your project's .sdd-forge/ directory and exposes a bro… |
-| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | This chapter describes the internal architecture of sdd-forge, a layered CLI tool in which top-level dispatchers rout… |
+| [Tool Overview and Architecture](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/overview.md) | This chapter provides a concise introduction to sdd-forge — a CLI tool that generates structured technical documentat… |
+| [Technology Stack and Operations](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/stack_and_ops.md) | This chapter covers the technology stack and operational procedures for sdd-forge, a Node.js CLI tool built with ES M… |
+| [Project Structure](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/project_structure.md) | This chapter describes the source tree of sdd-forge, which is organized into five major directories: src/docs (docume… |
+| [CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/cli_commands.md) | sdd-forge exposes over 35 commands organized across three namespace groups — docs, flow, and check — plus four standa… |
+| [Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/configuration.md) | sdd-forge reads a single JSON configuration file per project, through which users can control documentation output la… |
+| [Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/internal_design.md) | sdd-forge is a Node.js CLI tool organized into three primary source layers — src/docs/ for documentation pipeline com… |
 <!-- {{/data}} -->
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.622",
+  "version": "0.1.0-alpha.692",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",

package/src/check/commands/config.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * src/check/commands/config.js
+ *
+ * sdd-forge check config — config.json validation report.
+ *
+ * Runs three checks in order:
+ *   1. File existence and JSON parse
+ *   2. Schema validation (required fields, type constraints)
+ *   3. Preset existence (type values must match known presets)
+ */
+
+import fs from "fs";
+import { runIfDirect } from "../../lib/entrypoint.js";
+import { repoRoot, parseArgs } from "../../lib/cli.js";
+import { sddConfigPath } from "../../lib/config.js";
+import { validateConfig } from "../../lib/types.js";
+import { PRESETS } from "../../lib/presets.js";
+import { EXIT_ERROR } from "../../lib/exit-codes.js";
+
+const MAX_SCHEMA_ERRORS = 50;
+
+function printHelp() {
+  console.log(
+    [
+      "Usage: sdd-forge check config [options]",
+      "",
+      "Validate .sdd-forge/config.json for required fields, preset existence,",
+      "and schema consistency.",
+      "",
+      "Options:",
+      "  --format <text|json>  Output format (default: text)",
+      "  -h, --help            Show this help",
+    ].join("\n")
+  );
+}
+
+/**
+ * Run all config checks and return check results.
+ * Stops early if file or schema check fails.
+ *
+ * @param {string} root - repo root
+ * @returns {{ name: string, result: "pass"|"fail", errors: string[] }[]}
+ */
+function runChecks(root) {
+  const configPath = sddConfigPath(root);
+  const checks = [];
+
+  // Check 1: file existence + JSON parse
+  if (!fs.existsSync(configPath)) {
+    checks.push({ name: "file", result: "fail", errors: [`config.json not found: ${configPath}`] });
+    return checks;
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch (err) {
+    checks.push({ name: "file", result: "fail", errors: [`Failed to parse config.json: ${err.message}`] });
+    return checks;
+  }
+  checks.push({ name: "file", result: "pass", errors: [] });
+
+  // Check 2: schema validation
+  try {
+    validateConfig(raw);
+    checks.push({ name: "schema", result: "pass", errors: [] });
+  } catch (err) {
+    const errors = err.message
+      .replace(/^Config validation failed:\n/, "")
+      .split(/\n\s*-\s*/)
+      .map((e) => e.trim())
+      .filter(Boolean)
+      .slice(0, MAX_SCHEMA_ERRORS);
+    checks.push({ name: "schema", result: "fail", errors });
+    return checks;
+  }
+
+  // Check 3: preset existence
+  const types = Array.isArray(raw.type) ? raw.type : [raw.type];
+  const validKeys = new Set(PRESETS.map((p) => p.key));
+  const unknownPresets = types.filter((t) => !validKeys.has(t));
+
+  if (unknownPresets.length > 0) {
+    checks.push({
+      name: "presets",
+      result: "fail",
+      errors: unknownPresets.map((t) => `Preset not found: ${t}`),
+    });
+  } else {
+    checks.push({ name: "presets", result: "pass", errors: [] });
+  }
+
+  return checks;
+}
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2), {
+    options: ["--format"],
+    defaults: { format: "text" },
+  });
+
+  if (cli.help) {
+    printHelp();
+    return;
+  }
+
+  const format = cli.format || "text";
+  if (!["text", "json"].includes(format)) {
+    process.stderr.write(`sdd-forge check config: unknown format '${format}'. Use text or json.\n`);
+    process.exit(EXIT_ERROR);
+  }
+
+  const root = repoRoot();
+  const checks = runChecks(root);
+  const ok = checks.every((c) => c.result === "pass");
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ ok, checks }, null, 2) + "\n");
+    if (!ok) process.exit(EXIT_ERROR);
+    return;
+  }
+
+  // text format
+  if (ok) {
+    process.stdout.write("config is valid\n");
+  } else {
+    for (const check of checks) {
+      if (check.result === "fail") {
+        for (const err of check.errors) {
+          process.stderr.write(`  - ${err}\n`);
+        }
+      }
+    }
+    process.exit(EXIT_ERROR);
+  }
+}
+
+export { main };
+runIfDirect(import.meta.url, main);

package/src/check/commands/freshness.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * src/check/commands/freshness.js
+ *
+ * sdd-forge check freshness — compare docs/ and source modification timestamps.
+ *
+ * Determines whether `sdd-forge build` is needed by comparing the newest mtime
+ * of files under SDD_SOURCE_ROOT with the newest mtime of files under docs/.
+ *
+ * Results:
+ *   fresh       — docs/ is up to date (exit 0)
+ *   stale       — source is newer than docs/ (exit 1)
+ *   never-built — docs/ does not exist (exit 1)
+ */
+
+import fs from "fs";
+import path from "path";
+import { runIfDirect } from "../../lib/entrypoint.js";
+import { repoRoot, sourceRoot, parseArgs } from "../../lib/cli.js";
+import { EXIT_ERROR } from "../../lib/exit-codes.js";
+
+const FILE_LIMIT = 10_000;
+
+function printHelp() {
+  console.log(
+    [
+      "Usage: sdd-forge check freshness [options]",
+      "",
+      "Compare docs/ and source modification timestamps to determine if",
+      "sdd-forge build is needed.",
+      "",
+      "Results:",
+      "  fresh       docs/ is up to date",
+      "  stale       source is newer than docs/ — run sdd-forge build",
+      "  never-built docs/ does not exist — run sdd-forge build",
+      "",
+      "Exit codes:",
+      "  0  fresh",
+      "  1  stale or never-built",
+      "",
+      "Options:",
+      "  --format <text|json>  Output format (default: text)",
+      "  -h, --help            Show this help",
+    ].join("\n")
+  );
+}
+
+/**
+ * Recursively walk a directory and collect file paths, up to `limit` entries.
+ *
+ * @param {string} dir
+ * @param {number} limit
+ * @returns {Promise<{ files: string[], truncated: boolean }>}
+ */
+async function walkFiles(dir, limit) {
+  const files = [];
+  let truncated = false;
+
+  async function walk(current) {
+    if (truncated) return;
+    let entries;
+    try {
+      entries = await fs.promises.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (truncated) return;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        files.push(full);
+        if (files.length >= limit) {
+          truncated = true;
+          return;
+        }
+      }
+    }
+  }
+
+  await walk(dir);
+  return { files, truncated };
+}
+
+/**
+ * Find the newest mtime (ms) among files in a directory.
+ *
+ * @param {string} dir
+ * @param {number} limit
+ * @returns {Promise<{ newestMs: number|null, truncated: boolean }>}
+ */
+async function newestMtime(dir, limit) {
+  const { files, truncated } = await walkFiles(dir, limit);
+  let newestMs = null;
+  for (const f of files) {
+    try {
+      const ms = (await fs.promises.stat(f)).mtimeMs;
+      if (newestMs === null || ms > newestMs) newestMs = ms;
+    } catch {
+      // skip unreadable files
+    }
+  }
+  return { newestMs, truncated };
+}
+
+/**
+ * Run the freshness check.
+ *
+ * @param {string} workRoot - repo root (docs/ lives here)
+ * @param {string} srcRoot  - source root
+ * @returns {Promise<{ result: "fresh"|"stale"|"never-built", srcNewest: string|null, docsNewest: string|null }>}
+ */
+async function checkFreshness(workRoot, srcRoot) {
+  const docsDir = path.join(workRoot, "docs");
+
+  try {
+    await fs.promises.access(docsDir);
+  } catch {
+    return { result: "never-built", srcNewest: null, docsNewest: null };
+  }
+
+  const [srcResult, docsResult] = await Promise.all([
+    newestMtime(srcRoot, FILE_LIMIT),
+    newestMtime(docsDir, FILE_LIMIT),
+  ]);
+
+  const { newestMs: srcMs, truncated: srcTruncated } = srcResult;
+  const { newestMs: docsMs, truncated: docsTruncated } = docsResult;
+
+  if (srcTruncated) {
+    process.stderr.write(
+      `sdd-forge check freshness: warning — source file limit (${FILE_LIMIT}) reached, result may be approximate\n`
+    );
+  }
+  if (docsTruncated) {
+    process.stderr.write(
+      `sdd-forge check freshness: warning — docs file limit (${FILE_LIMIT}) reached, result may be approximate\n`
+    );
+  }
+
+  const srcNewest = srcMs !== null ? new Date(srcMs).toISOString() : null;
+  const docsNewest = docsMs !== null ? new Date(docsMs).toISOString() : null;
+
+  // If source has no files, treat as fresh (nothing to build from)
+  if (srcMs === null) {
+    return { result: "fresh", srcNewest, docsNewest };
+  }
+
+  // If docs has no files but dir exists, treat as stale
+  if (docsMs === null) {
+    return { result: "stale", srcNewest, docsNewest };
+  }
+
+  const result = srcMs > docsMs ? "stale" : "fresh";
+  return { result, srcNewest, docsNewest };
+}
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2), {
+    options: ["--format"],
+    defaults: { format: "text" },
+  });
+
+  if (cli.help) {
+    printHelp();
+    return;
+  }
+
+  const format = cli.format;
+  if (!["text", "json"].includes(format)) {
+    process.stderr.write(`sdd-forge check freshness: unknown format '${format}'. Use text or json.\n`);
+    process.exit(EXIT_ERROR);
+  }
+
+  const workRoot = repoRoot();
+  const srcRoot = sourceRoot();
+  const { result, srcNewest, docsNewest } = await checkFreshness(workRoot, srcRoot);
+
+  const ok = result === "fresh";
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify({ ok, result, srcNewest, docsNewest }, null, 2) + "\n");
+    if (!ok) process.exit(EXIT_ERROR);
+    return;
+  }
+
+  // text format
+  switch (result) {
+    case "fresh":
+      process.stdout.write("fresh — docs/ is up to date\n");
+      break;
+    case "stale":
+      process.stdout.write("stale — source is newer than docs/, run: sdd-forge build\n");
+      process.exit(EXIT_ERROR);
+      break;
+    case "never-built":
+      process.stdout.write("never-built — docs/ does not exist, run: sdd-forge build\n");
+      process.exit(EXIT_ERROR);
+      break;
+  }
+}
+
+export { main, checkFreshness };
+runIfDirect(import.meta.url, main);

package/src/check/commands/scan.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * src/check/commands/scan.js
+ *
+ * sdd-forge check scan — scan coverage report.
+ *
+ * Shows DataSource coverage: scan.include matched files vs DataSource-analyzed files.
+ * Reports uncovered files grouped by extension (actionable summary) followed by the file list.
+ */
+
+import fs from "fs";
+import path from "path";
+import { runIfDirect } from "../../lib/entrypoint.js";
+import { repoRoot, sourceRoot, parseArgs } from "../../lib/cli.js";
+import { loadConfig, sddOutputDir } from "../../lib/config.js";
+import { globToRegex } from "../../docs/lib/scanner.js";
+import { pushSection, DIVIDER } from "../../lib/formatter.js";
+import { EXIT_ERROR } from "../../lib/exit-codes.js";
+
+const DEFAULT_MAX_FILES = 10;
+
+// Meta keys to skip when reading analysis categories
+const META_KEYS = new Set(["analyzedAt", "enrichedAt"]);
+
+function printHelp() {
+  console.log([
+    "Usage: sdd-forge check scan [options]",
+    "",
+    "Show scan coverage report for the current project.",
+    "",
+    "Options:",
+    "  --format <text|json|md>  Output format (default: text)",
+    "  --list                   Show all uncovered files (default: up to 10)",
+    "  -h, --help               Show this help",
+  ].join("\n"));
+}
+
+/**
+ * Group files by extension, sorted by count descending then extension alphabetically.
+ *
+ * @param {string[]} files - relative file paths
+ * @returns {{ ext: string, count: number }[]}
+ */
+function groupByExtension(files) {
+  const counts = new Map();
+  for (const f of files) {
+    const ext = path.extname(f);
+    counts.set(ext, (counts.get(ext) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .sort(([extA, countA], [extB, countB]) => countB - countA || extA.localeCompare(extB))
+    .map(([ext, count]) => ({ ext, count }));
+}
+
+/**
+ * Walk baseDir recursively, collecting files matched by includeMatchers.
+ * Skips .git, node_modules, vendor, .sdd-forge directories.
+ * Applies excludeMatchers to relative paths.
+ *
+ * @param {string} baseDir
+ * @param {RegExp[]} includeMatchers
+ * @param {RegExp[]} excludeMatchers
+ * @returns {string[]} relative paths
+ */
+function walkIncludedFiles(baseDir, includeMatchers, excludeMatchers) {
+  const results = [];
+
+  function walk(dir, relPrefix) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "vendor" || entry.name === ".sdd-forge") continue;
+        const nextRel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        walk(path.join(dir, entry.name), nextRel);
+      } else if (entry.isFile()) {
+        const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (excludeMatchers.some((m) => m.test(relPath))) continue;
+        if (includeMatchers.some((m) => m.test(relPath))) results.push(relPath);
+      }
+    }
+  }
+
+  walk(baseDir, "");
+  return results.sort();
+}
+
+/**
+ * Compute DataSource coverage from config and analysis.json.
+ *
+ * @param {string} root - work root
+ * @param {string} src - source root
+ * @param {Object} cfg - sdd config
+ * @returns {{ dataSourceCoverage: { total, analyzed, uncovered } }}
+ */
+function computeCoverage(root, src, cfg) {
+  const outputPath = path.join(sddOutputDir(root), "analysis.json");
+  if (!fs.existsSync(outputPath)) {
+    throw new Error(`analysis.json not found: ${outputPath}\nRun 'sdd-forge docs scan' first.`);
+  }
+
+  let analysis;
+  try {
+    analysis = JSON.parse(fs.readFileSync(outputPath, "utf8"));
+  } catch (err) {
+    throw new Error(`Failed to parse analysis.json: ${err.message}`);
+  }
+
+  // Resolve scan patterns
+  const include = cfg.scan?.include || [];
+  const exclude = cfg.scan?.exclude || [];
+  const excludeMatchers = exclude.map((p) => globToRegex(p));
+  const includeMatchers = include.map((p) => globToRegex(p));
+
+  // scan.include matched files
+  const includedFiles = walkIncludedFiles(src, includeMatchers, excludeMatchers);
+
+  // Files analyzed by any DataSource (from analysis.json entries)
+  const analyzedFiles = new Set();
+  for (const key of Object.keys(analysis)) {
+    if (META_KEYS.has(key)) continue;
+    const cat = analysis[key];
+    if (!cat || !Array.isArray(cat.entries)) continue;
+    for (const entry of cat.entries) {
+      if (entry?.file) analyzedFiles.add(entry.file);
+    }
+  }
+
+  const uncovered = includedFiles.filter((f) => !analyzedFiles.has(f));
+
+  return {
+    dataSourceCoverage: {
+      total: includedFiles.length,
+      analyzed: analyzedFiles.size,
+      uncovered,
+    },
+  };
+}
+
+/**
+ * Format as plain text.
+ */
+function formatText(data, showAll) {
+  const { dataSourceCoverage: ds } = data;
+  const lines = [];
+  const dsPct = ds.total === 0 ? 0 : Math.round((ds.analyzed / ds.total) * 100);
+
+  lines.push(`  DataSource: ${ds.analyzed} / ${ds.total} files (${dsPct}%)`);
+
+  if (ds.uncovered.length > 0) {
+    const extGroups = groupByExtension(ds.uncovered);
+
+    pushSection(lines, "Uncovered by extension");
+    for (const { ext, count } of extGroups) {
+      const label = ext || "(no extension)";
+      lines.push(`    ${label.padEnd(12)} ${count} files`);
+    }
+
+    pushSection(lines, "Uncovered files");
+    const display = showAll ? ds.uncovered : ds.uncovered.slice(0, DEFAULT_MAX_FILES);
+    for (const f of display) lines.push(`      - ${f}`);
+    if (!showAll && ds.uncovered.length > DEFAULT_MAX_FILES) {
+      lines.push(`      ... and ${ds.uncovered.length - DEFAULT_MAX_FILES} more (use --list to show all)`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format as Markdown.
+ */
+function formatMarkdown(data, showAll) {
+  const { dataSourceCoverage: ds } = data;
+  const dsPct = ds.total === 0 ? 0 : Math.round((ds.analyzed / ds.total) * 100);
+
+  const lines = [];
+  lines.push("# Scan Coverage Report");
+  lines.push("");
+  lines.push("## DataSource Coverage");
+  lines.push("");
+  lines.push(`**${ds.analyzed} / ${ds.total} files (${dsPct}%)**`);
+
+  if (ds.uncovered.length > 0) {
+    const extGroups = groupByExtension(ds.uncovered);
+
+    lines.push("");
+    lines.push("### Uncovered by extension");
+    lines.push("");
+    for (const { ext, count } of extGroups) {
+      const label = ext || "(no extension)";
+      lines.push(`- \`${label}\`  ${count} files`);
+    }
+
+    lines.push("");
+    lines.push("### Uncovered files");
+    lines.push("");
+    const display = showAll ? ds.uncovered : ds.uncovered.slice(0, DEFAULT_MAX_FILES);
+    for (const f of display) lines.push(`- \`${f}\``);
+    if (!showAll && ds.uncovered.length > DEFAULT_MAX_FILES) {
+      lines.push(`- _...and ${ds.uncovered.length - DEFAULT_MAX_FILES} more (use --list to show all)_`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+async function main() {
+  const cli = parseArgs(process.argv.slice(2), {
+    flags: ["--list"],
+    options: ["--format"],
+    defaults: { list: false, format: "text" },
+  });
+
+  if (cli.help) {
+    printHelp();
+    return;
+  }
+
+  const format = cli.format || "text";
+  if (!["text", "json", "md"].includes(format)) {
+    process.stderr.write(`sdd-forge check scan: unknown format '${format}'. Use text, json, or md.\n`);
+    process.exit(EXIT_ERROR);
+  }
+
+  const root = repoRoot();
+  const src = sourceRoot();
+
+  let cfg;
+  try {
+    cfg = loadConfig(root);
+  } catch (err) {
+    process.stderr.write(`sdd-forge check scan: failed to load config: ${err.message}\n`);
+    process.exit(EXIT_ERROR);
+  }
+
+  let data;
+  try {
+    data = computeCoverage(root, src, cfg);
+  } catch (err) {
+    process.stderr.write(`sdd-forge check scan: ${err.message}\n`);
+    process.exit(EXIT_ERROR);
+  }
+
+  const showAll = cli.list;
+
+  if (format === "json") {
+    const { dataSourceCoverage: ds } = data;
+    const dsPct = ds.total === 0 ? 0 : Math.round((ds.analyzed / ds.total) * 100);
+    const out = {
+      dataSourceCoverage: {
+        total: ds.total,
+        analyzed: ds.analyzed,
+        percent: dsPct,
+        uncovered: showAll ? ds.uncovered : ds.uncovered.slice(0, DEFAULT_MAX_FILES),
+        uncoveredTotal: ds.uncovered.length,
+        uncoveredByExtension: groupByExtension(ds.uncovered),
+      },
+    };
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+  } else if (format === "md") {
+    process.stdout.write(formatMarkdown(data, showAll) + "\n");
+  } else {
+    process.stdout.write(formatText(data, showAll) + "\n");
+  }
+}
+
+export { main, groupByExtension, computeCoverage, formatText };
+runIfDirect(import.meta.url, main);

package/src/check.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * src/check.js
+ *
+ * Check dispatcher. Routes check subcommands to scripts under check/commands/.
+ */
+
+import path from "path";
+import { PKG_DIR } from "./lib/cli.js";
+import { EXIT_ERROR } from "./lib/exit-codes.js";
+
+/** Subcommand → script mapping */
+const SCRIPTS = {
+  config: "check/commands/config.js",
+  freshness: "check/commands/freshness.js",
+  scan: "check/commands/scan.js",
+};
+
+const args = process.argv.slice(2);
+const subCmd = args[0];
+const rest = args.slice(1);
+
+if (!subCmd || subCmd === "-h" || subCmd === "--help") {
+  console.error("Usage: sdd-forge check <command>\n");
+  console.error("Available commands:");
+  for (const c of Object.keys(SCRIPTS)) console.error(`  ${c}`);
+  console.error("\nRun: sdd-forge check <command> --help");
+  process.exit(subCmd ? 0 : 1);
+}
+
+const scriptRelPath = SCRIPTS[subCmd];
+if (!scriptRelPath) {
+  console.error(`sdd-forge check: unknown command '${subCmd}'`);
+  console.error("Run: sdd-forge check --help");
+  process.exit(EXIT_ERROR);
+}
+
+const scriptPath = path.join(PKG_DIR, scriptRelPath);
+process.argv = [process.argv[0], scriptPath, ...rest];
+
+await import(scriptPath);