@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/hooks/sdd-validate-commit.sh

@@ -0,0 +1,57 @@
+#!/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).
+# Uses Node.js for JSON parsing (always available in SDD projects, no jq dependency).
+#
+# OPT-IN: This hook is a no-op unless config.json has hooks.community: true.
+# Enable with: "hooks": { "community": true } in .planning/config.json
+
+# Check opt-in config — exit silently if not enabled
+if [ -f .planning/config.json ]; then
+  ENABLED=$(node -e "try{const c=require('./.planning/config.json');process.stdout.write(c.hooks?.community===true?'1':'0')}catch{process.stdout.write('0')}" 2>/dev/null)
+  if [ "$ENABLED" != "1" ]; then exit 0; fi
+else
+  exit 0
+fi
+
+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.
+# 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
+    MSG="${BASH_REMATCH[1]}"
+  elif [[ "$CMD" =~ -m[[:space:]]+\'([^\']+)\' ]]; then
+    MSG="${BASH_REMATCH[1]}"
+  fi
+
+  if [ -n "$MSG" ]; then
+    SUBJECT=$(echo "$MSG" | head -1)
+    # Validate Conventional Commits format
+    if ! [[ "$SUBJECT" =~ ^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\(.+\))?:[[:space:]].+ ]]; then
+      # 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", "code": "COMMIT_SUBJECT_TOO_LONG", "reason": "Commit subject must be 72 characters or less."}'
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

package/hooks/sdd-workflow-guard.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// sdd-hook-version: {{SDD_VERSION}}
+// SDD Workflow Guard — PreToolUse hook
+// Detects when Claude attempts file edits outside a SDD workflow context
+// (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
+// making direct edits that bypass state tracking.
+//
+// Enable via config: hooks.workflow_guard: true (default: false)
+// Only triggers on Write/Edit tool calls to non-.planning/ files.
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 3000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name;
+
+    // Only guard Write and Edit tool calls
+    if (toolName !== 'Write' && toolName !== 'Edit') {
+      process.exit(0);
+    }
+
+    // Check if we're inside a SDD workflow (Task subagent or /sdd- skill)
+    // Subagents have a session_id that differs from the parent
+    // and typically have a description field set by the orchestrator
+    if (data.tool_input?.is_subagent || data.session_type === 'task') {
+      process.exit(0);
+    }
+
+    // Check the file being edited
+    const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
+
+    // Allow edits to .planning/ files (SDD state management)
+    if (filePath.includes('.planning/') || filePath.includes('.planning\\')) {
+      process.exit(0);
+    }
+
+    // Allow edits to common config/docs files that don't need SDD tracking
+    const allowedPatterns = [
+      /\.gitignore$/,
+      /\.env/,
+      /CLAUDE\.md$/,
+      /AGENTS\.md$/,
+      /GEMINI\.md$/,
+      /settings\.json$/,
+    ];
+    if (allowedPatterns.some(p => p.test(filePath))) {
+      process.exit(0);
+    }
+
+    // Check if workflow guard is enabled
+    const cwd = data.cwd || process.cwd();
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (fs.existsSync(configPath)) {
+      try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (!config.hooks?.workflow_guard) {
+          process.exit(0); // Guard disabled (default)
+        }
+      } catch (e) {
+        process.exit(0);
+      }
+    } else {
+      process.exit(0); // No SDD project — don't guard
+    }
+
+    // If we get here: SDD project, guard enabled, file edit outside .planning/,
+    // not in a subagent context. Inject advisory warning.
+    const output = {
+      hookSpecificOutput: {
+        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 ' +
+          'to maintain project state tracking. ' +
+          'If this is intentional (e.g., user explicitly asked for a direct edit), proceed normally.'
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    // Silent fail — never block tool execution
+    process.exit(0);
+  }
+});

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "@bhargavvc/sdd-cc",
-  "version": "1.30.1",
+  "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",
     "commands",
     "sdd",
     "agents",
-    "hooks/dist",
-    "scripts"
+    "hooks",
+    "scripts",
+    "sdk/src",
+    "sdk/shared",
+    "sdk/prompts",
+    "sdk/dist",
+    "sdk/package.json",
+    "sdk/package-lock.json",
+    "sdk/tsconfig.json"
   ],
   "keywords": [
     "claude",
@@ -36,16 +45,32 @@
     "url": "https://github.com/bhargavvc/sdd-cc/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "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,16 +12,88 @@ 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-workflow-guard.js'
+  'sdd-update-banner.js',
+  'sdd-workflow-guard.js',
+  // Community hooks (bash, opt-in via .planning/config.json hooks.community)
+  'sdd-session-state.sh',
+  'sdd-validate-commit.sh',
+  '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.)
@@ -42,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;
 
@@ -59,18 +135,47 @@ function build() {
       continue;
     }
 
-    // Validate syntax before copying
-    const syntaxError = validateSyntax(src);
-    if (syntaxError) {
-      console.error(`\x1b[31m✗ ${hook}: SyntaxError — ${syntaxError}\x1b[0m`);
-      hasErrors = true;
-      continue;
+    // Validate JS syntax before copying (.sh files skip — not Node.js)
+    if (hook.endsWith('.js')) {
+      const syntaxError = validateSyntax(src);
+      if (syntaxError) {
+        console.error(`\x1b[31m✗ ${hook}: SyntaxError — ${syntaxError}\x1b[0m`);
+        hasErrors = true;
+        continue;
+      }
     }
 
     console.log(`\x1b[32m✓\x1b[0m Copying ${hook}...`);
-    fs.copyFileSync(src, dest);
+    // 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(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);