contract-driven-delivery 1.0.0

package/dist/cli/index.js

@@ -0,0 +1,336 @@
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { join as join3 } from "path";
+
+// src/utils/paths.ts
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var PACKAGE_ROOT = join(__dirname, "..", "..");
+var ASSETS_DIR = join(PACKAGE_ROOT, "assets");
+var CLAUDE_HOME = join(homedir(), ".claude");
+var AGENTS_HOME = join(CLAUDE_HOME, "agents");
+var SKILLS_HOME = join(CLAUDE_HOME, "skills");
+var ASSET = {
+  agents: join(ASSETS_DIR, "agents"),
+  skill: join(ASSETS_DIR, "skill"),
+  contracts: join(ASSETS_DIR, "contracts"),
+  specsTemplates: join(ASSETS_DIR, "specs-templates"),
+  testsTemplates: join(ASSETS_DIR, "tests-templates"),
+  ci: join(ASSETS_DIR, "ci"),
+  claudeTemplate: join(ASSETS_DIR, "CLAUDE.template.md"),
+  agentsTemplate: join(ASSETS_DIR, "AGENTS.template.md")
+};
+
+// src/utils/copy.ts
+import {
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  copyFileSync
+} from "fs";
+import { join as join2, dirname as dirname2, relative } from "path";
+
+// src/utils/logger.ts
+var RESET = "\x1B[0m";
+var CYAN = "\x1B[36m";
+var GREEN = "\x1B[32m";
+var YELLOW = "\x1B[33m";
+var RED = "\x1B[31m";
+var DIM = "\x1B[2m";
+var log = {
+  info(msg) {
+    console.log(`${CYAN}\u2139${RESET}  ${msg}`);
+  },
+  ok(msg) {
+    console.log(`${GREEN}\u2713${RESET}  ${msg}`);
+  },
+  warn(msg) {
+    console.log(`${YELLOW}\u26A0${RESET}  ${msg}`);
+  },
+  error(msg) {
+    console.error(`${RED}\u2717${RESET}  ${msg}`);
+  },
+  dim(msg) {
+    console.log(`${DIM}   ${msg}${RESET}`);
+  },
+  blank() {
+    console.log("");
+  }
+};
+
+// src/utils/copy.ts
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true });
+}
+function copyDir(src, dest, opts = {}) {
+  const { overwrite = true, label } = opts;
+  if (!existsSync(src)) {
+    log.warn(`source not found, skipping: ${label ?? src}`);
+    return 0;
+  }
+  ensureDir(dest);
+  let count = 0;
+  function walk(currentSrc, currentDest) {
+    const entries = readdirSync(currentSrc, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = join2(currentSrc, entry.name);
+      const destPath = join2(currentDest, entry.name);
+      if (entry.isDirectory()) {
+        ensureDir(destPath);
+        walk(srcPath, destPath);
+      } else {
+        if (!overwrite && existsSync(destPath)) {
+          const relPath = label ? join2(label, relative(dest, destPath)) : relative(dest, destPath);
+          log.dim(`skip ${relPath}`);
+          continue;
+        }
+        ensureDir(dirname2(destPath));
+        copyFileSync(srcPath, destPath);
+        count += 1;
+      }
+    }
+  }
+  walk(src, dest);
+  return count;
+}
+function copyFile(src, dest, opts = {}) {
+  const { overwrite = true, label } = opts;
+  if (!overwrite && existsSync(dest)) {
+    log.dim(`skip ${label ?? dest}`);
+    return false;
+  }
+  ensureDir(dirname2(dest));
+  copyFileSync(src, dest);
+  return true;
+}
+
+// src/commands/init.ts
+async function init(opts) {
+  if (opts.globalOnly && opts.localOnly) {
+    log.error("--global-only and --local-only are mutually exclusive.");
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  log.blank();
+  log.info("Initialising contract-driven-delivery kit\u2026");
+  log.blank();
+  if (!opts.localOnly) {
+    log.info(`Installing agents \u2192 ${AGENTS_HOME}`);
+    const agentCount = copyDir(ASSET.agents, AGENTS_HOME, { overwrite: true });
+    log.ok(`${agentCount} agent file(s) installed.`);
+    const skillDest = join3(SKILLS_HOME, "contract-driven-delivery");
+    log.info(`Installing skill  \u2192 ${skillDest}`);
+    const skillCount = copyDir(ASSET.skill, skillDest, { overwrite: true });
+    log.ok(`${skillCount} skill file(s) installed.`);
+    log.blank();
+  }
+  if (!opts.globalOnly) {
+    log.info(`Scaffolding project files in ${cwd}`);
+    const contractsCount = copyDir(
+      ASSET.contracts,
+      join3(cwd, "contracts"),
+      { overwrite: opts.force, label: "contracts" }
+    );
+    log.ok(`contracts/ \u2014 ${contractsCount} file(s) written.`);
+    const specsCount = copyDir(
+      ASSET.specsTemplates,
+      join3(cwd, "specs", "templates"),
+      { overwrite: opts.force, label: "specs/templates" }
+    );
+    log.ok(`specs/templates/ \u2014 ${specsCount} file(s) written.`);
+    const testsCount = copyDir(
+      ASSET.testsTemplates,
+      join3(cwd, "tests", "templates"),
+      { overwrite: opts.force, label: "tests/templates" }
+    );
+    log.ok(`tests/templates/ \u2014 ${testsCount} file(s) written.`);
+    const ciCount = copyDir(
+      ASSET.ci,
+      join3(cwd, "ci"),
+      { overwrite: opts.force, label: "ci" }
+    );
+    log.ok(`ci/ \u2014 ${ciCount} file(s) written.`);
+    const claudeWritten = copyFile(
+      ASSET.claudeTemplate,
+      join3(cwd, "CLAUDE.md"),
+      { overwrite: false, label: "CLAUDE.md" }
+    );
+    if (claudeWritten)
+      log.ok("CLAUDE.md created.");
+    const agentsWritten = copyFile(
+      ASSET.agentsTemplate,
+      join3(cwd, "AGENTS.md"),
+      { overwrite: false, label: "AGENTS.md" }
+    );
+    if (agentsWritten)
+      log.ok("AGENTS.md created.");
+    log.blank();
+  }
+  log.ok("Done.");
+  log.blank();
+  log.info("Use the contract-driven-delivery skill in Claude Code to scan this repo.");
+  log.blank();
+}
+
+// src/commands/update.ts
+import { join as join4 } from "path";
+async function update() {
+  log.blank();
+  log.info("Updating ~/.claude agents and skill\u2026");
+  log.blank();
+  log.info(`Updating agents \u2192 ${AGENTS_HOME}`);
+  const agentCount = copyDir(ASSET.agents, AGENTS_HOME, { overwrite: true });
+  log.ok(`${agentCount} agent file(s) updated.`);
+  const skillDest = join4(SKILLS_HOME, "contract-driven-delivery");
+  log.info(`Updating skill  \u2192 ${skillDest}`);
+  const skillCount = copyDir(ASSET.skill, skillDest, { overwrite: true });
+  log.ok(`${skillCount} skill file(s) updated.`);
+  log.blank();
+  log.info("Project files (contracts/, specs/, tests/, ci/) were not changed.");
+  log.ok("Update complete.");
+  log.blank();
+}
+
+// src/commands/new-change.ts
+import { join as join5 } from "path";
+import { existsSync as existsSync2 } from "fs";
+var REQUIRED_TEMPLATES = [
+  "change-request.md",
+  "change-classification.md",
+  "test-plan.md",
+  "ci-gates.md",
+  "tasks.md"
+];
+var OPTIONAL_TEMPLATES = [
+  "current-behavior.md",
+  "proposal.md",
+  "spec.md",
+  "design.md",
+  "contracts.md",
+  "qa-report.md",
+  "regression-report.md",
+  "archive.md"
+];
+var SAFE_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+async function newChange(name, opts) {
+  if (!SAFE_NAME.test(name)) {
+    log.error(`Invalid change name: "${name}". Use letters, numbers, hyphens, or underscores (max 64 chars).`);
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const changeDir = join5(cwd, "specs", "changes", name);
+  if (existsSync2(changeDir)) {
+    log.warn(`Change directory already exists: ${changeDir}`);
+    log.warn("Aborting \u2014 remove or rename the directory to re-scaffold.");
+    return;
+  }
+  log.blank();
+  log.info(`Creating change scaffold: specs/changes/${name}`);
+  ensureDir(changeDir);
+  const templates = opts.all ? [...REQUIRED_TEMPLATES, ...OPTIONAL_TEMPLATES] : [...REQUIRED_TEMPLATES];
+  let written = 0;
+  for (const tmpl of templates) {
+    const src = join5(ASSET.specsTemplates, tmpl);
+    const dest = join5(changeDir, tmpl);
+    if (!existsSync2(src)) {
+      log.warn(`Template not found, skipping: ${tmpl}`);
+      continue;
+    }
+    copyFile(src, dest, { overwrite: false });
+    log.dim(tmpl);
+    written += 1;
+  }
+  log.blank();
+  log.ok(`${written} template(s) created in specs/changes/${name}`);
+  log.blank();
+}
+
+// src/commands/validate.ts
+import { join as join6 } from "path";
+import { existsSync as existsSync3 } from "fs";
+import { execSync } from "child_process";
+var VALIDATORS = [
+  { flag: "contracts", script: "validate_contracts.py", label: "contracts" },
+  { flag: "env", script: "validate_env_contract.py", label: "env contract" },
+  { flag: "ci", script: "validate_ci_gates.py", label: "CI gates" },
+  { flag: "spec", script: "validate_spec_traceability.py", label: "spec traceability" }
+];
+function resolvePython() {
+  for (const cmd of ["python3", "python"]) {
+    try {
+      execSync(`${cmd} --version`, { stdio: "ignore" });
+      return cmd;
+    } catch {
+    }
+  }
+  throw new Error("Python not found. Install Python 3.8+ and ensure it is on PATH.");
+}
+async function validate(opts) {
+  let py;
+  try {
+    py = resolvePython();
+  } catch (e) {
+    log.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  }
+  const scriptsDir = join6(ASSET.skill, "scripts");
+  const runAll = !opts.contracts && !opts.env && !opts.ci && !opts.spec;
+  log.blank();
+  let failed = false;
+  for (const v of VALIDATORS) {
+    if (!runAll && !opts[v.flag])
+      continue;
+    const scriptPath = join6(scriptsDir, v.script);
+    if (!existsSync3(scriptPath)) {
+      log.warn(`${v.label}: script not found, skipping (${v.script})`);
+      log.blank();
+      continue;
+    }
+    log.info(`Validating ${v.label}\u2026`);
+    try {
+      execSync(`${py} "${scriptPath}"`, { stdio: "inherit", cwd: process.cwd() });
+      log.ok(`${v.label} passed.`);
+    } catch {
+      log.error(`${v.label} validation failed.`);
+      failed = true;
+    }
+    log.blank();
+  }
+  if (failed) {
+    log.error("One or more validations failed.");
+    process.exit(1);
+  } else {
+    log.ok("All validations passed.");
+    log.blank();
+  }
+}
+
+// src/cli/index.ts
+var program = new Command();
+program.name("cdd").description("Contract-Driven Delivery Kit CLI").version("1.0.0");
+program.command("init").description(
+  "Install agents/skill into ~/.claude and scaffold project files in cwd"
+).option("--global-only", "Only install into ~/.claude, skip project files", false).option("--local-only", "Only scaffold project files, skip ~/.claude", false).option("--force", "Overwrite existing project files", false).action(
+  (opts) => init({
+    globalOnly: opts.globalOnly,
+    localOnly: opts.localOnly,
+    force: opts.force
+  })
+);
+program.command("update").description("Update ~/.claude agents and skill (does not touch project files)").action(() => update());
+program.command("new <name>").description("Scaffold a new change directory under specs/changes/<name>").option("--all", "Include optional templates in addition to required ones", false).action(
+  (name, opts) => newChange(name, { all: opts.all })
+);
+program.command("validate").description("Run validation scripts (defaults to all)").option("--contracts", "Validate API/data/CSS contracts (use --env separately for env)", false).option("--env", "Validate env contract", false).option("--ci", "Validate CI gate policy", false).option("--spec", "Validate spec traceability", false).action(
+  (opts) => validate({
+    contracts: opts.contracts,
+    env: opts.env,
+    ci: opts.ci,
+    spec: opts.spec
+  })
+);
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "contract-driven-delivery",
+  "version": "1.0.0",
+  "description": "Contract-driven delivery kit CLI — spec-first, test-first AI-assisted delivery for brownfield systems",
+  "keywords": [
+    "contract-driven",
+    "sdd",
+    "tdd",
+    "claude-code",
+    "ai",
+    "specs",
+    "contracts"
+  ],
+  "license": "MIT",
+  "author": "Contract-Driven Delivery Contributors",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "cdd": "bin/cdd.js"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "assets"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "prepublishOnly": "node build.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.0.0"
+  }
+}