@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/hooks/sdd-validate-commit.sh

@@ -1,4 +1,5 @@
-#!/bin/bash
+#!/usr/bin/env bash
+# sdd-hook-version: {{SDD_VERSION}}
 # sdd-validate-commit.sh — PreToolUse hook: enforce Conventional Commits format
 # Blocks git commit commands with non-conforming messages (exit 2).
 # Allows conforming messages and all non-commit commands (exit 0).
@@ -20,8 +21,15 @@ INPUT=$(cat)
 # Extract command from JSON using Node (handles escaping correctly, no jq needed)
 CMD=$(echo "$INPUT" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{process.stdout.write(JSON.parse(d).tool_input?.command||'')}catch{}})" 2>/dev/null)
 
-# Only check git commit commands
-if [[ "$CMD" =~ ^git[[:space:]]+commit ]]; then
+# Only check git commit commands.
+# Delegates to hooks/lib/git-cmd.js isGitSubcommand() — the canonical token-walk
+# classifier that handles env-prefix, -C path, and full-path git invocations.
+# A naive `^git\s+commit` regex misses all three; this guard fixes that (#3129).
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+if GIT_CMD_LIB="$HOOK_DIR/lib/git-cmd.js" node -e "
+  const {isGitSubcommand}=require(process.env.GIT_CMD_LIB);
+  process.exit(isGitSubcommand(process.argv[1],'commit')?0:1);
+" "$CMD" 2>/dev/null; then
   # Extract message from -m flag
   MSG=""
   if [[ "$CMD" =~ -m[[:space:]]+\"([^\"]+)\" ]]; then
@@ -34,11 +42,13 @@ if [[ "$CMD" =~ ^git[[:space:]]+commit ]]; then
     SUBJECT=$(echo "$MSG" | head -1)
     # Validate Conventional Commits format
     if ! [[ "$SUBJECT" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?:[[:space:]].+ ]]; then
-      echo '{"decision": "block", "reason": "Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Subject must be <=72 chars, lowercase, imperative mood, no trailing period."}'
+      # Emit a typed `code` field alongside `reason` (#2974). Tests assert
+      # on the stable code string; the reason is the human-readable copy.
+      echo '{"decision": "block", "code": "CONVENTIONAL_COMMITS_VIOLATION", "reason": "Commit message must follow Conventional Commits: <type>(<scope>): <subject>. Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Subject must be <=72 chars, lowercase, imperative mood, no trailing period."}'
       exit 2
     fi
     if [ ${#SUBJECT} -gt 72 ]; then
-      echo '{"decision": "block", "reason": "Commit subject must be 72 characters or less."}'
+      echo '{"decision": "block", "code": "COMMIT_SUBJECT_TOO_LONG", "reason": "Commit subject must be 72 characters or less."}'
       exit 2
     fi
   fi

package/hooks/sdd-workflow-guard.js

@@ -5,7 +5,7 @@
 // (no active /sdd- skill or Task subagent) and injects an advisory warning.
 //
 // This is a SOFT guard — it advises, not blocks. The edit still proceeds.
-// The warning nudges Claude to use /sdd-quick or /sdd-fast instead of
+// The warning nudges Claude to use /sdd:quick or /sdd:fast instead of
 // making direct edits that bypass state tracking.
 //
 // Enable via config: hooks.workflow_guard: true (default: false)
@@ -80,7 +80,7 @@ process.stdin.on('end', () => {
         hookEventName: "PreToolUse",
         additionalContext: `⚠️ WORKFLOW ADVISORY: You're editing ${path.basename(filePath)} directly without a SDD command. ` +
           'This edit will not be tracked in STATE.md or produce a SUMMARY.md. ' +
-          'Consider using /sdd-fast for trivial fixes or /sdd-quick for larger changes ' +
+          'Consider using /sdd:fast for trivial fixes or /sdd:quick for larger changes ' +
           'to maintain project state tracking. ' +
           'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
       }

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@bhargavvc/sdd-cc",
-  "version": "1.35.0",
+  "version": "1.42.3",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini and Codex by TÂCHES.",
   "bin": {
-    "sdd-cc": "bin/install.js"
+    "sdd-cc": "bin/install.js",
+    "sdd-sdk": "bin/sdd-sdk.js",
+    "sdd-tools": "bin/sdd-sdk.js"
   },
   "files": [
     "bin",
@@ -11,7 +13,14 @@
     "sdd",
     "agents",
     "hooks",
-    "scripts"
+    "scripts",
+    "sdk/src",
+    "sdk/shared",
+    "sdk/prompts",
+    "sdk/dist",
+    "sdk/package.json",
+    "sdk/package-lock.json",
+    "sdk/tsconfig.json"
   ],
   "keywords": [
     "claude",
@@ -38,14 +47,30 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.84",
+    "ws": "^8.20.0"
+  },
   "devDependencies": {
-    "c8": "^11.0.0",
-    "esbuild": "^0.24.0",
-    "vitest": "^4.1.2"
+    "c8": "^11.0.0"
+  },
+  "optionalDependencies": {
+    "fallow": "^2.70.0"
   },
   "scripts": {
     "build:hooks": "node scripts/build-hooks.js",
-    "prepublishOnly": "npm run build:hooks",
+    "build:sdk": "cd sdk && npm ci && npm run build",
+    "check:alias-drift": "cd sdk && npm run check:alias-drift",
+    "check:state-document-fresh": "cd sdk && npm run check:state-document-fresh",
+    "prepublishOnly": "npm run build:hooks && npm run build:sdk",
+    "pretest": "npm run build:sdk && npm run lint:skill-deps",
+    "pretest:coverage": "npm run build:sdk",
+    "lint:descriptions": "node scripts/lint-descriptions.cjs",
+    "lint:skill-deps": "node scripts/lint-skill-deps.cjs",
+    "lint:tests": "node scripts/lint-no-source-grep.cjs",
+    "lint:changeset": "node scripts/changeset/lint.cjs",
+    "changeset": "node scripts/changeset/new.cjs",
+    "changelog:render": "node scripts/changeset/cli.cjs render",
     "test": "node scripts/run-tests.cjs",
     "test:coverage": "c8 --check-coverage --lines 70 --reporter text --include 'sdd/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs"
   },

package/scripts/audit-workflow-script-paths.cjs

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Post-install path audit for workflow-invoked scripts (#2995).
+ *
+ * Walks workflowsDir, extracts every `${SDD_HOME[...]}/<path>.<cjs|js|sh>`
+ * token, and asserts:
+ *   1. the file exists in the repo at that <path> (catches typos)
+ *   2. <path>'s first segment is in installedPrefixes (catches the
+ *      #2994 class: source-vs-deployed-path mismatches)
+ *
+ * Pure function over (workflowsDir, repoRoot, installedPrefixes); no
+ * filesystem mutation. Tests assert on the typed AUDIT_FINDING enum.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const AUDIT_FINDING = Object.freeze({
+  MISSING_FROM_REPO: 'missing_from_repo',
+  NOT_INSTALLED: 'not_installed',
+});
+
+// Match `${SDD_HOME}` or `${SDD_HOME:-...}` followed by a /-rooted path
+// ending in .cjs/.js/.sh. The path is captured verbatim (relative to
+// the install root).
+const REF_RE = /\$\{SDD_HOME(?::-[^}]*)?\}\/([A-Za-z0-9_./-]+\.(?:cjs|js|sh))/g;
+
+function listWorkflowFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(dir, e.name));
+}
+
+function extractReferences(content) {
+  const out = [];
+  let m;
+  // RegExp objects with /g state must be reset per call.
+  const re = new RegExp(REF_RE.source, 'g');
+  while ((m = re.exec(content)) !== null) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+function auditWorkflowScriptPaths({ workflowsDir, repoRoot, installedPrefixes }) {
+  const findings = [];
+  const installedSet = new Set(installedPrefixes);
+  for (const file of listWorkflowFiles(workflowsDir)) {
+    const content = fs.readFileSync(file, 'utf8');
+    const workflow = path.basename(file);
+    for (const ref of extractReferences(content)) {
+      const firstSegment = ref.split('/')[0];
+      // #2996 CR: emit BOTH findings simultaneously when a reference is
+      // both outside an installed prefix AND missing from the repo. The
+      // earlier `continue` short-circuited MISSING_FROM_REPO, so a
+      // developer who moved a missing reference to an installed prefix
+      // would only discover the second issue on a subsequent CI run.
+      if (!installedSet.has(firstSegment)) {
+        findings.push({ workflow, path: ref, kind: AUDIT_FINDING.NOT_INSTALLED });
+      }
+      const sourceFile = path.join(repoRoot, ref);
+      if (!fs.existsSync(sourceFile)) {
+        findings.push({ workflow, path: ref, kind: AUDIT_FINDING.MISSING_FROM_REPO });
+      }
+    }
+  }
+  return { ok: findings.length === 0, findings };
+}
+
+module.exports = { auditWorkflowScriptPaths, AUDIT_FINDING, extractReferences };

package/scripts/build-hooks.js

@@ -12,14 +12,26 @@ const vm = require('vm');
 
 const HOOKS_DIR = path.join(__dirname, '..', 'hooks');
 const DIST_DIR = path.join(HOOKS_DIR, 'dist');
+// Per-process staging directory for atomic writes. Using process.pid in the
+// name eliminates all contention between concurrent builders: each process
+// owns its own staging dir and never races with another builder's cleanup.
+// Lives under hooks/ so it shares a filesystem with DIST_DIR (POSIX
+// rename(2) is only atomic within the same filesystem) but is NOT inside
+// DIST_DIR — so readers that readdirSync(DIST_DIR) (e.g. bin/install.js,
+// install-hooks-copy tests) never observe a transient ".tmp" sibling.
+// The parent pattern hooks/.dist-staging-*/ is gitignored.
+const STAGE_DIR = path.join(HOOKS_DIR, `.dist-staging-${process.pid}`);
 
 // Hooks to copy (pure Node.js, no bundling needed)
 const HOOKS_TO_COPY = [
+  'sdd-check-update-worker.js',
   'sdd-check-update.js',
   'sdd-context-monitor.js',
   'sdd-prompt-guard.js',
   'sdd-read-guard.js',
+  'sdd-read-injection-scanner.js',
   'sdd-statusline.js',
+  'sdd-update-banner.js',
   'sdd-workflow-guard.js',
   // Community hooks (bash, opt-in via .planning/config.json hooks.community)
   'sdd-session-state.sh',
@@ -27,6 +39,61 @@ const HOOKS_TO_COPY = [
   'sdd-phase-boundary.sh'
 ];
 
+// Sync millisecond sleep using Atomics.wait on a throwaway SharedArrayBuffer.
+// Used between Windows rename retries; this script is sync end-to-end so
+// setTimeout would not work. Total worst-case backoff across MAX_ATTEMPTS
+// is bounded (~400ms) — acceptable for a one-shot build script.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Atomic-replace via fs.renameSync, with Windows-only retry and fallback.
+ *
+ * POSIX rename(2) atomically replaces dest even when readers hold open
+ * handles on it. Windows MoveFileEx (which fs.renameSync uses with
+ * MOVEFILE_REPLACE_EXISTING) cannot — it throws EPERM/EBUSY when another
+ * process has the destination open. Concurrent install.js readers and
+ * antivirus scanners are the realistic triggers; both release handles
+ * within milliseconds, so a short backoff resolves the race. After
+ * retries are exhausted, fall back to copy-then-unlink (re-introduces
+ * the truncate-then-write race for this single file but keeps the build
+ * moving rather than crashing). If even copy fails because dest is hard-
+ * locked, log a non-fatal warning and leave the prior dest in place — a
+ * subsequent build invocation will retry from a fresh state.
+ */
+function renameAtomicWithRetry(stagedDest, dest, hook) {
+  if (process.platform !== 'win32') {
+    fs.renameSync(stagedDest, dest);
+    return;
+  }
+  const BACKOFFS_MS = [10, 30, 90, 270];
+  for (let attempt = 0; attempt <= BACKOFFS_MS.length; attempt++) {
+    try {
+      fs.renameSync(stagedDest, dest);
+      return;
+    } catch (e) {
+      const transient = e && (e.code === 'EPERM' || e.code === 'EBUSY');
+      if (!transient) throw e;
+      if (attempt < BACKOFFS_MS.length) {
+        sleepSync(BACKOFFS_MS[attempt]);
+        continue;
+      }
+      // Retries exhausted; fall back to copy-then-unlink.
+      try {
+        fs.copyFileSync(stagedDest, dest);
+        try { fs.unlinkSync(stagedDest); } catch (_) { /* tolerate */ }
+        console.warn(`\x1b[33m! ${hook}: rename failed (${e.code}) after ${BACKOFFS_MS.length} retries; used copy-fallback\x1b[0m`);
+        return;
+      } catch (fallbackErr) {
+        try { fs.unlinkSync(stagedDest); } catch (_) { /* tolerate */ }
+        console.warn(`\x1b[33m! ${hook}: rename + copy fallback both failed (${e.code} → ${fallbackErr.code || fallbackErr.message}); leaving prior dest in place\x1b[0m`);
+        return;
+      }
+    }
+  }
+}
+
 /**
  * Validate JavaScript syntax without executing the file.
  * Catches SyntaxError (duplicate const, missing brackets, etc.)
@@ -47,10 +114,14 @@ function validateSyntax(filePath) {
 }
 
 function build() {
-  // Ensure dist directory exists
+  // Ensure dist and staging directories exist (staging is a sibling of dist
+  // used to make writes atomic — see STAGE_DIR comment above).
   if (!fs.existsSync(DIST_DIR)) {
     fs.mkdirSync(DIST_DIR, { recursive: true });
   }
+  if (!fs.existsSync(STAGE_DIR)) {
+    fs.mkdirSync(STAGE_DIR, { recursive: true });
+  }
 
   let hasErrors = false;
 
@@ -75,13 +146,36 @@ function build() {
     }
 
     console.log(`\x1b[32m✓\x1b[0m Copying ${hook}...`);
-    fs.copyFileSync(src, dest);
-    // Preserve executable bit for shell scripts
+    // Atomic write: copy to a per-process staging file in the per-PID sibling
+    // STAGE_DIR (same filesystem as DIST_DIR so rename(2) is atomic), then
+    // rename into place. Multiple test files invoke this script concurrently
+    // from their before() hooks; fs.copyFileSync truncates then writes the
+    // destination — readers (install.js subprocesses spawned by parallel
+    // install tests) can observe the dest empty or partial mid-write,
+    // producing flaky failures such as bug-2136 part 4 where installed .sh
+    // hooks lacked their "# sdd-hook-version:" header. POSIX rename(2)
+    // makes the swap atomic so readers see either the old file or the new
+    // file. The staging file lives outside DIST_DIR so readdirSync(DIST_DIR)
+    // (in install.js and tests) never observes a transient ".tmp" sibling.
+    // Each process uses its own STAGE_DIR (keyed by PID) so concurrent
+    // builders never race on staging-dir creation or cleanup.
+    const stagedDest = path.join(STAGE_DIR, `${hook}.${Date.now()}`);
+    fs.copyFileSync(src, stagedDest);
+    // Preserve executable bit for shell scripts before rename so the
+    // installed file is executable from the very first observation.
     if (hook.endsWith('.sh')) {
-      try { fs.chmodSync(dest, 0o755); } catch (e) { /* Windows */ }
+      try { fs.chmodSync(stagedDest, 0o755); } catch (e) { /* Windows */ }
     }
+    renameAtomicWithRetry(stagedDest, dest, hook);
   }
 
+  // Best-effort cleanup of this process's own staging dir. Since STAGE_DIR
+  // is per-PID (`.dist-staging-<pid>/`), no other builder touches it — so
+  // rmSync with recursive:true is safe and leaves no race window.
+  try {
+    fs.rmSync(STAGE_DIR, { recursive: true, force: true });
+  } catch (e) { /* tolerate ENOENT if the dir was never created (e.g. all hooks skipped) */ }
+
   if (hasErrors) {
     console.error('\n\x1b[31mBuild failed: fix syntax errors above before publishing.\x1b[0m');
     process.exit(1);

package/scripts/changeset/cli.cjs

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * CLI wrapper for the changeset-fragment workflow (#2975).
+ *
+ * Subcommands:
+ *   render --repo <dir> --version V --date D [--json]   Fold .changeset/*.md
+ *                                                       into CHANGELOG.md;
+ *                                                       delete consumed fragments.
+ *
+ * `--json` emits a structured report on stdout — the only contract tests
+ * assert against. Per CONTRIBUTING.md "Prohibited: Raw Text Matching on
+ * Test Outputs", the human formatter is operator-only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseFragment, FRAGMENT_ERROR } = require('./parse.cjs');
+const { renderChangelog } = require('./render.cjs');
+const { serializeChangelog } = require('./serialize.cjs');
+const { renderGithubReleaseNotes } = require('./github-release-notes.cjs');
+
+function parseArgs(argv) {
+  const opts = {
+    cmd: null,
+    repo: process.cwd(),
+    version: null,
+    date: null,
+    fromRef: null,
+    toRef: null,
+    output: null,
+    repoSlug: 'bhargavvc/sdd-cc',
+    installCommand: 'npx @bhargavvc/sdd-cc@latest',
+    json: false,
+  };
+  if (argv.length === 0) return { ok: true, opts };
+  opts.cmd = argv[0];
+
+  // Pull a value for a value-taking flag, validating that the next token
+  // exists and is not itself another flag (which is the silently-misparsed
+  // case CR called out: e.g. `--repo --json` would consume `--json` as the
+  // repo path).
+  const requireValue = (flag, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      return { ok: false, error: `missing value for ${flag}` };
+    }
+    return { ok: true, value: v };
+  };
+
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') { opts.json = true; continue; }
+    if (
+      a === '--repo' ||
+      a === '--version' ||
+      a === '--date' ||
+      a === '--from' ||
+      a === '--to' ||
+      a === '--output' ||
+      a === '--repo-slug' ||
+      a === '--install-command'
+    ) {
+      const r = requireValue(a, i);
+      if (!r.ok) return { ok: false, error: r.error };
+      if (a === '--repo') opts.repo = r.value;
+      else if (a === '--version') opts.version = r.value;
+      else if (a === '--date') opts.date = r.value;
+      else if (a === '--from') opts.fromRef = r.value;
+      else if (a === '--to') opts.toRef = r.value;
+      else if (a === '--output') opts.output = r.value;
+      else if (a === '--repo-slug') opts.repoSlug = r.value;
+      else if (a === '--install-command') opts.installCommand = r.value;
+      i++;
+      continue;
+    }
+    return { ok: false, error: `unknown argument: ${a}` };
+  }
+  return { ok: true, opts };
+}
+
+function listFragmentFiles(changesetDir) {
+  if (!fs.existsSync(changesetDir)) return [];
+  return fs.readdirSync(changesetDir)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .map((f) => path.join(changesetDir, f));
+}
+
+function splitChangelog(text) {
+  // Split off the top-level "# Changelog" heading + lead matter (everything
+  // before the first "## [version]" block) from the rest. The rest is the
+  // priorChangelog passed into renderChangelog. The "## [Unreleased]" block,
+  // if present, is dropped (the new release replaces it).
+  const lines = text.split(/\r?\n/);
+  const firstReleaseIdx = lines.findIndex((l) => /^##\s+\[/.test(l));
+  if (firstReleaseIdx === -1) {
+    return { lead: text.replace(/\s+$/, ''), prior: '' };
+  }
+  const lead = lines.slice(0, firstReleaseIdx).join('\n').replace(/\s+$/, '');
+  let priorStart = firstReleaseIdx;
+  // Skip the [Unreleased] block if present — it's a placeholder, not a release.
+  if (/^##\s+\[Unreleased\]/i.test(lines[firstReleaseIdx])) {
+    let j = firstReleaseIdx + 1;
+    while (j < lines.length && !/^##\s+\[/.test(lines[j])) j++;
+    priorStart = j;
+  }
+  const prior = lines.slice(priorStart).join('\n').trimStart();
+  return { lead, prior };
+}
+
+function cmdRender(opts) {
+  const repo = path.resolve(opts.repo);
+  const changesetDir = path.join(repo, '.changeset');
+  const changelogPath = path.join(repo, 'CHANGELOG.md');
+  const fragmentFiles = listFragmentFiles(changesetDir);
+
+  const fragments = [];
+  const failures = [];
+  for (const file of fragmentFiles) {
+    const src = fs.readFileSync(file, 'utf8');
+    const r = parseFragment(src);
+    if (r.ok) fragments.push({ ...r.fragment, file });
+    else failures.push({ file: path.relative(repo, file), reason: r.reason, detail: r.detail || null });
+  }
+
+  if (failures.length > 0) {
+    return { exitCode: 1, report: { consumed: 0, failures } };
+  }
+  if (fragments.length === 0) {
+    return { exitCode: 0, report: { consumed: 0, failures: [] } };
+  }
+
+  const priorText = fs.existsSync(changelogPath) ? fs.readFileSync(changelogPath, 'utf8') : '';
+  const { lead, prior } = splitChangelog(priorText);
+
+  const ir = renderChangelog({
+    fragments,
+    version: opts.version,
+    date: opts.date,
+    priorChangelog: prior || null,
+  });
+  const releaseBlock = serializeChangelog(ir);
+  const out = [
+    lead || '# Changelog',
+    '',
+    '## [Unreleased]',
+    '',
+    releaseBlock.replace(/\s+$/, ''),
+    '',
+  ].join('\n');
+
+  fs.writeFileSync(changelogPath, out);
+
+  // Delete consumed fragments. If any unlink fails the changelog is written
+  // but the fragment is still on disk, so a re-run would double-consume it.
+  // Surface the partial-failure as exitCode=1 with structured detail so the
+  // operator can manually clean up before retrying.
+  const deleteFailures = [];
+  for (const f of fragments) {
+    try {
+      fs.unlinkSync(f.file);
+    } catch (e) {
+      deleteFailures.push({
+        file: path.relative(repo, f.file),
+        reason: 'fail_fragment_delete',
+        detail: e.code || e.message,
+      });
+    }
+  }
+
+  return {
+    exitCode: deleteFailures.length > 0 ? 1 : 0,
+    report: {
+      consumed: fragments.length - deleteFailures.length,
+      failures: deleteFailures,
+      release: { version: opts.version, date: opts.date },
+    },
+  };
+}
+
+function cmdGithubReleaseNotes(opts) {
+  const repo = path.resolve(opts.repo);
+  const report = renderGithubReleaseNotes({
+    repo,
+    fromRef: opts.fromRef,
+    toRef: opts.toRef,
+    repoSlug: opts.repoSlug,
+    installCommand: opts.installCommand,
+  });
+
+  if (!report.ok) {
+    return {
+      exitCode: 1,
+      report: {
+        consumed: 0,
+        failures: report.failures,
+        release: { from: opts.fromRef, to: opts.toRef },
+      },
+    };
+  }
+
+  if (opts.output) {
+    fs.writeFileSync(path.resolve(opts.output), report.body);
+  }
+
+  return {
+    exitCode: 0,
+    report: {
+      consumed: report.fragments.length,
+      failures: [],
+      release: { from: opts.fromRef, to: opts.toRef },
+      output: opts.output || null,
+      body: opts.output ? null : report.body,
+    },
+  };
+}
+
+function usage() {
+  return [
+    'usage:',
+    '  changeset/cli.cjs render --repo <dir> --version V --date D [--json]',
+    '  changeset/cli.cjs github-release-notes --repo <dir> --from REF --to REF [--output FILE] [--repo-slug OWNER/REPO] [--install-command CMD] [--json]',
+    '',
+  ].join('\n');
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}\n`);
+    process.stderr.write(usage());
+    process.exit(2);
+  }
+  const { opts } = parsed;
+  if (opts.cmd !== 'render' && opts.cmd !== 'github-release-notes') {
+    process.stderr.write(usage());
+    process.exit(2);
+  }
+  if (opts.cmd === 'render' && (!opts.version || !opts.date)) {
+    process.stderr.write('--version and --date are required for render\n');
+    process.exit(2);
+  }
+  if (opts.cmd === 'github-release-notes' && (!opts.fromRef || !opts.toRef)) {
+    process.stderr.write('--from and --to are required for github-release-notes\n');
+    process.exit(2);
+  }
+
+  const { exitCode, report } = opts.cmd === 'render' ? cmdRender(opts) : cmdGithubReleaseNotes(opts);
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else if (opts.cmd === 'github-release-notes' && report.body) {
+    process.stdout.write(report.body);
+  } else {
+    process.stdout.write(`Consumed: ${report.consumed} fragment(s)\n`);
+    if (report.failures.length > 0) {
+      process.stdout.write(`Failures: ${report.failures.length}\n`);
+      for (const f of report.failures) {
+        process.stdout.write(`  ${f.file}: ${f.reason}${f.detail ? ` (${f.detail})` : ''}\n`);
+      }
+    }
+  }
+  process.exit(exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = { cmdRender, cmdGithubReleaseNotes, parseArgs, splitChangelog, listFragmentFiles, usage };