dev-harness-cli 1.0.0

package/cli/lib/state.mjs

@@ -0,0 +1,333 @@
+/**
+ * state — Harness config & state machine.
+ *
+ * Reads/writes harness-config.json, manages phase transitions,
+ * provides dot-notation access for get/set operations.
+ *
+ * Usage:
+ *   import { loadConfig, saveConfig, get, set, transitionPhase } from './state.mjs';
+ *   const cfg = loadConfig('/path/to/project');
+ *   set('/path/to/project', 'gates.enabled', true);
+ *   transitionPhase('/path/to/project', 'build');
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { validateAgainstSchema } from './validate-schema.mjs';
+import { getGitBranch, isGitClean, getLastCommitMessage, hasGitUpstream } from './git.mjs';
+import { CONFIG_SCHEMA_PATH, CONFIG_PATH } from './paths.mjs';
+import { PHASE_ORDER, getPhaseOrder, isValidTransition } from './phases.mjs';
+import { DEFAULT_MAX_RETRIES, COVERAGE_THRESHOLD_DEFAULT } from './constants.mjs';
+
+// Re-export phase logic for backward compatibility (callers import from state.mjs).
+export { PHASE_ORDER, getPhaseOrder, isValidTransition };
+
+// ── Default config ───────────────────────────────────────────────────────────
+
+/**
+ * Canonical default harness-config.json.
+ * @returns {object}
+ */
+export function getDefaultConfig() {
+  return {
+    version: '1.0',
+    stack: null,
+    stackMeta: null,
+    agentTool: null,
+    mode: 'copilot',
+    currentPhase: null,
+    paused: false,
+    features: {
+      remaining: 0,
+      passing: 0,
+      total: 0,
+    },
+    gates: {
+      enabled: false,
+      checks: ['all'],
+      coverage: {
+        enabled: false,
+        threshold: COVERAGE_THRESHOLD_DEFAULT,
+      },
+    },
+    git: {
+      autoCommit: false,
+      autoTag: false,
+      resetOnRetry: false,
+      branch: null,
+      clean: true,
+      hasUpstream: false,
+      lastCommitMessage: null,
+    },
+    phases: {
+      enabled: ['define', 'plan', 'build', 'verify', 'review', 'ship'],
+    },
+    agents: {
+      tone: {
+        planner: 'Analytical and precise. Define clear boundaries.',
+        generator: 'Focused and practical. Build what\'s specified, nothing more.',
+        evaluator: 'Skeptical and thorough. Accept only compelling evidence.',
+        simplifier: 'Relentless about clarity. Delete more than you add.',
+      },
+    },
+    maxRetries: DEFAULT_MAX_RETRIES,
+    retryCount: 0,
+    pipelineIteration: 0,
+    gateHistory: [],
+  };
+}
+
+// ── File I/O ─────────────────────────────────────────────────────────────────
+
+/**
+ * Get the path to harness-config.json for a given project directory.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function getConfigPath(targetDir) {
+  return CONFIG_PATH(targetDir);
+}
+
+/**
+ * Deep-merge a partial config into defaults.
+ * Missing keys get default values; extra keys preserved.
+ * @param {object} defaults
+ * @param {object} partial
+ * @returns {object}
+ */
+function deepMerge(defaults, partial) {
+  const result = { ...defaults };
+  for (const key of Object.keys(partial)) {
+    if (
+      defaults[key] && typeof defaults[key] === 'object' && !Array.isArray(defaults[key]) &&
+      partial[key] && typeof partial[key] === 'object' && !Array.isArray(partial[key])
+    ) {
+      result[key] = deepMerge(defaults[key], partial[key]);
+    } else {
+      result[key] = partial[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Load harness-config.json, merging with defaults.
+ * Returns defaults if file doesn't exist or is invalid.
+ * @param {string} targetDir
+ * @returns {{ config: object, path: string, ok: boolean, error: string|null }}
+ */
+export function loadConfig(targetDir) {
+  const cfgPath = getConfigPath(targetDir);
+  const defaults = getDefaultConfig();
+
+  if (!existsSync(cfgPath)) {
+    return {
+      config: defaults,
+      path: cfgPath,
+      ok: false,
+      error: `Not found: ${cfgPath}. Run: harness-dev init`,
+    };
+  }
+
+  try {
+    const raw = readFileSync(cfgPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    const config = deepMerge(defaults, parsed);
+    // Schema validation — non-blocking: return errors in result so callers
+    // (e.g. status command) can surface them. Library does NOT write to stderr
+    // to keep the error contract clean (stderr reserved for real errors).
+    const schemaResult = validateAgainstSchema(config, CONFIG_SCHEMA_PATH);
+    return { config, path: cfgPath, ok: true, error: null, schemaErrors: schemaResult.ok ? [] : schemaResult.errors };
+  } catch (err) {
+    return {
+      config: defaults,
+      path: cfgPath,
+      ok: false,
+      error: `Invalid config: ${err.message}`,
+    };
+  }
+}
+
+/**
+ * Save config to harness-config.json.
+ * @param {string} targetDir
+ * @param {object} cfg
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function saveConfig(targetDir, cfg) {
+  try {
+    const cfgPath = getConfigPath(targetDir);
+    mkdirSync(dirname(cfgPath), { recursive: true });
+    writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+    return { ok: true, error: null };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+// ── Dot-notation access ──────────────────────────────────────────────────────
+
+/**
+ * Resolve a dot-notation key against an object.
+ * @param {object} obj
+ * @param {string} key — e.g. "gates.enabled"
+ * @returns {any}
+ */
+function resolveKey(obj, key) {
+  const parts = key.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Set a dot-notation key on an object (mutates in-place).
+ * @param {object} obj
+ * @param {string} key
+ * @param {any} value
+ */
+function setKey(obj, key, value) {
+  const parts = key.split('.');
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!(parts[i] in current) || typeof current[parts[i]] !== 'object') {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Get a config value by dot-notation key.
+ * Loads from disk on each call (always fresh).
+ * @param {string} targetDir
+ * @param {string} key — dot-notation key
+ * @returns {{ value: any, ok: boolean, error: string|null }}
+ */
+export function get(targetDir, key) {
+  const { config, ok, error } = loadConfig(targetDir);
+  if (key) {
+    const value = resolveKey(config, key);
+    return { value: value !== undefined ? value : null, ok, error };
+  }
+  return { value: config, ok, error };
+}
+
+/**
+ * Set a config value by dot-notation key and save to disk.
+ * @param {string} targetDir
+ * @param {string} key — dot-notation key
+ * @param {any} value
+ * @returns {{ ok: boolean, error: string|null }}
+ */
+export function set(targetDir, key, value) {
+  const { config } = loadConfig(targetDir);
+  setKey(config, key, value);
+  return saveConfig(targetDir, config);
+}
+
+// ── Phase transitions ────────────────────────────────────────────────────────
+
+/**
+ * Record a gate result in gateHistory.
+ * @param {object} config
+ * @param {string} phase
+ * @param {string} result — "pass" | "fail"
+ */
+function recordGate(config, phase, result) {
+  if (!config.gateHistory) {config.gateHistory = [];}
+  config.gateHistory.push({
+    phase,
+    result,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+/**
+ * Transition to the next phase.
+ *
+ * Steps:
+ * 1. Validate transition
+ * 2. Record old phase gate to history
+ * 3. Update currentPhase
+ * 4. Update git.branch, git.clean, git.lastCommitMessage
+ * 5. Save config
+ *
+ * @param {string} targetDir
+ * @param {string} toPhase
+ * @returns {{ ok: boolean, error: string|null, config: object|null }}
+ */
+export function transitionPhase(targetDir, toPhase) {
+  const { config, ok, error } = loadConfig(targetDir);
+  if (!ok) {
+    return { ok: false, error: error || 'Cannot load config', config: null };
+  }
+
+  const enabled = config.phases?.enabled;
+  if (!isValidTransition(config.currentPhase, toPhase, enabled)) {
+    const order = getPhaseOrder(enabled).join(' → ');
+    return {
+      ok: false,
+      error: `Invalid transition: "${config.currentPhase || 'start'}" → "${toPhase}". Valid order: ${order}`,
+      config: null,
+    };
+  }
+
+  // Record old phase gate if leaving a phase (skip for same-phase re-run)
+  if (config.currentPhase && config.currentPhase !== toPhase) {
+    recordGate(config, config.currentPhase, 'pass');
+  }
+
+  // Retry tracking: increment on same-phase re-run, reset on new phase
+  const isNewPhase = config.currentPhase !== toPhase;
+  if (config.retryCount === undefined) {config.retryCount = 0;}
+  if (isNewPhase) {
+    config.retryCount = 0;
+  } else {
+    config.retryCount = (config.retryCount || 0) + 1;
+  }
+
+  // Update phase
+  config.currentPhase = toPhase;
+
+  // Update git metadata
+  config.git = config.git || {};
+  config.git.branch = getGitBranch(targetDir);
+  config.git.clean = isGitClean(targetDir);
+  config.git.hasUpstream = hasGitUpstream(targetDir);
+  config.git.lastCommitMessage = getLastCommitMessage(targetDir);
+
+  // Clear pause on transition
+  config.paused = false;
+
+  const saveResult = saveConfig(targetDir, config);
+  if (!saveResult.ok) {
+    return { ok: false, error: saveResult.error, config: null };
+  }
+
+  return { ok: true, error: null, config };
+}
+
+/**
+ * Validate config against the JSON schema.
+ * Returns list of missing required fields.
+ * @param {object} cfg
+ * @returns {string[]}
+ */
+export function validateConfig(cfg) {
+  const required = ['version', 'mode', 'currentPhase', 'gates', 'git', 'phases', 'maxRetries'];
+  // Fields where `null` is a valid value (must not report as missing)
+  const nullable = new Set(['currentPhase']);
+  const missing = [];
+  for (const field of required) {
+    if (cfg[field] === undefined || (!nullable.has(field) && cfg[field] === null)) {
+      missing.push(field);
+    }
+  }
+  return missing;
+}

package/cli/lib/templates.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * templates — Stack-aware template engine CLI.
+ *
+ * Processes templates/ files with {{VAR}} substitution using
+ * stack-specific variables from stacks.json.
+ *
+ * Usage:
+ *   node cli/lib/templates.mjs --stack python --target /tmp/out
+ *   node cli/lib/templates.mjs --stack node  --target /tmp/out --override version=0.1.0
+ *   node cli/lib/templates.mjs --stack go    --target /tmp/out --json
+ *
+ * Flags:
+ *   --stack <name>     Required. One of: python, node, go, rust, c, cpp, vhdl, verilog
+ *   --target <dir>     Required. Output directory (created if missing)
+ *   --override k=v     Repeatable. Extra template variables
+ *   --json             Machine-parseable JSON output
+ *   --help             Show this message
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync } from 'node:fs';
+import { resolve, join, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getStackVars, listStacks } from './vars.mjs';
+import { TEMPLATES_DIR, PROJECT_ROOT } from './paths.mjs';
+import { EXECUTABLE_MODE } from './constants.mjs';
+
+const PACKAGE_PATH = resolve(PROJECT_ROOT, 'package.json');
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+export function loadPackageVersion() {
+  try {
+    const raw = readFileSync(PACKAGE_PATH, 'utf-8');
+    return JSON.parse(raw).version || '0.1.0';
+  } catch {
+    return '0.1.0';
+  }
+}
+
+function parseOverrides(args) {
+  const overrides = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--override=')) {
+      // --override=k=v (equals between flag & value)
+      const val = arg.slice('--override='.length);
+      const eqIdx = val.indexOf('=');
+      if (eqIdx !== -1) {
+        overrides[val.slice(0, eqIdx)] = val.slice(eqIdx + 1);
+      }
+    } else if (arg === '--override' && i + 1 < args.length) {
+      // --override key=value or --override key value
+      const key = args[i + 1];
+      const eqIdx = key.indexOf('=');
+      if (eqIdx !== -1) {
+        // --override key=value (one arg with =)
+        overrides[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+        i++;
+      } else if (i + 2 < args.length) {
+        // --override key value (two separate args, no =)
+        overrides[key] = args[i + 2];
+        i += 2;
+      }
+    }
+  }
+  return overrides;
+}
+
+/**
+ * Substitute {{VAR}} placeholders in text with actual values.
+ * Unknown variables are left as-is (optional variables in templates).
+ * @param {string} text
+ * @param {Record<string, string>} vars
+ * @returns {string}
+ */
+export function substitute(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return vars[key] !== undefined ? vars[key] : match;
+  });
+}
+
+/**
+ * Discover template files in the templates directory.
+ * Returns sorted list of absolute paths, excluding dotfiles.
+ * @returns {string[]}
+ */
+export function discoverTemplates() {
+  try {
+    const result = [];
+    const walk = (dir) => {
+      let entries;
+      try {
+        entries = readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const fullPath = join(dir, e.name);
+        if (e.isDirectory() && !e.name.startsWith('.')) {
+          walk(fullPath);
+        } else if (e.isFile() && !e.name.startsWith('.')) {
+          result.push(fullPath);
+        }
+      }
+    };
+    walk(TEMPLATES_DIR);
+    return result.sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Run the template engine.
+ *
+ * @param {object} opts
+ * @param {string} opts.stack — stack name
+ * @param {string} opts.target — output directory
+ * @param {object} [opts.overrides] — extra template variables
+ * @param {boolean} [opts.json] — JSON output mode
+ * @returns {{ files: string[], errors: string[] }}
+ */
+export function generateTemplates(opts) {
+  const { stack, target, overrides = {} } = opts;
+
+  // Load stack variables
+  const stackVars = getStackVars(stack, {
+    harnessVersion: loadPackageVersion(),
+    maxRetries: '3',
+    ...overrides,
+  });
+
+  // Discover templates
+  const templatePaths = discoverTemplates();
+  if (templatePaths.length === 0) {
+    return { files: [], errors: ['No templates found in ' + TEMPLATES_DIR] };
+  }
+
+  // Ensure target directory exists
+  mkdirSync(target, { recursive: true });
+
+  const created = [];
+  const errors = [];
+
+  for (const tmplPath of templatePaths) {
+    const relativePath = tmplPath.startsWith(TEMPLATES_DIR + '/')
+      ? tmplPath.slice(TEMPLATES_DIR.length + 1)
+      : basename(tmplPath);
+    const outPath = join(target, relativePath);
+    const outDir = dirname(outPath);
+
+    try {
+      if (outDir !== target) {
+        mkdirSync(outDir, { recursive: true });
+      }
+      const raw = readFileSync(tmplPath, 'utf-8');
+      const rendered = substitute(raw, stackVars);
+      writeFileSync(outPath, rendered, 'utf-8');
+
+      // Make .sh files executable
+      if (outPath.endsWith('.sh')) {
+        chmodSync(outPath, EXECUTABLE_MODE);
+      }
+
+      created.push(outPath);
+    } catch (err) {
+      errors.push(`${tmplPath}: ${err.message}`);
+    }
+  }
+
+  return { files: created, errors };
+}
+
+// ── CLI entry ────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`Usage: node cli/lib/templates.mjs --stack <name> --target <dir> [options]
+
+Flags:
+  --stack <name>     Required. Project stack (${listStacks().join(', ')})
+  --target <dir>     Required. Output directory
+  --override k=v     Repeatable. Extra variables
+  --json             Machine-parseable output
+  --help             Show this help
+`);
+    return;
+  }
+
+  const json = args.includes('--json');
+  const stackIdx = args.indexOf('--stack');
+  const targetIdx = args.indexOf('--target');
+
+  if (stackIdx === -1 || stackIdx + 1 >= args.length) {
+    const msg = '--stack is required';
+    if (json) {
+      process.stderr.write(JSON.stringify({ command: 'generate-templates', status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    process.exit(2);
+  }
+
+  if (targetIdx === -1 || targetIdx + 1 >= args.length) {
+    const msg = '--target is required';
+    if (json) {
+      process.stderr.write(JSON.stringify({ command: 'generate-templates', status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    process.exit(2);
+  }
+
+  const stack = args[stackIdx + 1];
+  const target = resolve(args[targetIdx + 1]);
+
+  const valid = listStacks();
+  if (!valid.includes(stack)) {
+    const msg = `Unknown stack "${stack}". Valid: ${valid.join(', ')}`;
+    if (json) {
+      process.stderr.write(JSON.stringify({ command: 'generate-templates', status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    process.exit(2);
+  }
+
+  const overrides = parseOverrides(args);
+  const result = generateTemplates({ stack, target, overrides, json });
+
+  if (json) {
+    const successMsg = result.errors.length > 0
+      ? `Generated ${result.files.length} file(s) with ${result.errors.length} error(s)`
+      : `Generated ${result.files.length} file(s) for stack "${stack}"`;
+    process.stdout.write(JSON.stringify({
+      command: 'generate-templates',
+      status: result.errors.length > 0 ? 'partial' : 'ok',
+      message: successMsg,
+      stack,
+      target,
+      filesCreated: result.files.length,
+      files: result.files,
+      errors: result.errors,
+    }) + '\n');
+    return;
+  }
+
+  // Human output
+  for (const f of result.files) {
+    process.stdout.write(`  ✓ ${f}\n`);
+  }
+  for (const e of result.errors) {
+    process.stderr.write(`  ✗ ${e}\n`);
+  }
+  process.stdout.write(`\nCreated ${result.files.length} file(s) for stack "${stack}"\n`);
+}
+
+// Only run as CLI when called directly (not when imported as module)
+if (process.argv[1] && basename(process.argv[1]) === basename(fileURLToPath(import.meta.url))) {
+  main();
+}