dev-harness-cli 1.0.0

package/cli/lib/help.mjs

@@ -0,0 +1,246 @@
+/**
+ * Help text builder — centralized to keep all formatting in one place.
+ */
+
+const USAGE = `Usage: harness-dev <command> [options]
+
+Pipeline commands:
+  init                  Scaffold full harness in current directory
+  phase <name>          Invoke a phase (define|plan|build|verify|simplify|review|ship)
+  validate              Run gate checks for current phase
+  validate --feature X --task Y   Validate a single task (feature-iterate phases)
+
+State commands:
+  status                Show current phase + gate state + detected stack
+  config list            List all config parameters with descriptions
+  config get [key]      Get config value (omit key for all)
+  config set <key> <val> Set config value (e.g. config set gates.enabled true)
+  pause                 Pause autopilot execution
+  resume                Resume autopilot execution
+  learn <message>       Append a lesson to progress.md
+
+Agent workflow commands:
+  contract propose      Write/update sprint-contract.md
+  contract review       Evaluator reviews contract, sets status
+  contract status       Show current contract state
+  contract escalate     Human adjudication when agents can't agree
+
+Git workflow commands:
+  worktree create <name> Create isolated worktree for a feature
+  worktree list          List active worktrees
+  worktree prune         Remove orphaned worktrees
+  worktree remove <name> Clean up worktree (optionally merge branch)
+  rollback list          Show available checkpoints
+  rollback to <tag>      Restore state to a checkpoint
+  rollback branch <tag>  Branch off a good iteration
+  checkpoint create <label> Force a manual checkpoint tag
+  detect-tool           Detect which agent tools are configured
+
+Mode:
+  set-mode <mode>       Switch mode (copilot|autopilot)
+
+Other:
+  help                  Alias for --help
+
+Global flags:
+  --json      Machine-parseable JSON output
+  --help, -h  Show this help message
+  --version   Show version
+
+Exit codes:
+  0  Success
+  1  Validation failure (gate check failed)
+  2  Usage error (bad arguments)
+  3  Internal error`;
+
+const VERSION = '0.2.0';
+
+// Help text for JSON output
+function buildJsonHelp() {
+  return {
+    help: true,
+    version: VERSION,
+    usage: 'harness-dev <command> [options]',
+    commands: {
+      init: 'Scaffold full harness in current directory',
+      status: 'Show current phase + gate state + detected stack',
+      phase: 'Invoke a phase (define|plan|build|verify|simplify|review|ship)',
+      validate: 'Run gate checks for current phase (--feature --task for per-task check)',
+      'set-mode': 'Switch mode (copilot|autopilot)',
+      config: 'Get/set config values',
+      pause: 'Pause autopilot execution',
+      resume: 'Resume autopilot execution',
+      learn: 'Append a lesson to progress.md',
+      contract: 'Sprint Contract workflow (propose/review/status/escalate)',
+      worktree: 'Git worktree management (create/list/prune/remove)',
+      rollback: 'Checkpoint recovery (list/to/branch)',
+      checkpoint: 'Manual checkpoint tagging (create)',
+      'detect-tool': 'Detect which agent coding tools are configured in the project',
+      help: 'Alias for --help',
+    },
+    flags: {
+      json: 'Machine-parseable JSON output',
+      help: 'Show this help message',
+      version: 'Show version',
+    },
+    exitCodes: {
+      0: 'Success',
+      1: 'Validation failure (gate check failed)',
+      2: 'Usage error (bad arguments)',
+      3: 'Internal error',
+    },
+  };
+}
+
+/**
+ * @param {boolean} json
+ * @returns {string}
+ */
+export function helpText(json = false) {
+  if (json) {
+    return JSON.stringify(buildJsonHelp());
+  }
+  return USAGE;
+}
+
+/**
+ * @param {boolean} json
+ * @returns {string}
+ */
+export function versionText(json = false) {
+  if (json) {
+    return JSON.stringify({ version: VERSION });
+  }
+  return `harness-dev v${VERSION}`;
+}
+
+// Per-command help text (for `harness-dev <command> --help`).
+const COMMAND_HELP = {
+  init: `Usage: harness-dev init [--stack <name>] [--target <dir>] [--force] [--no-git] [--json]
+
+Scaffold a full harness in the target directory:
+  - Detects stack (or use --stack)
+  - Generates AGENTS.md, harness-config.json, init.sh, progress.md,
+    sprint-contract.md, feature_list.json, docs/, ci/, evaluator-rubric.md
+  - Initializes git repo + initial commit (unless --no-git)
+
+Flags:
+  --stack <name>    Override stack detection (node|python|go|rust|java|...)
+  --target <dir>    Target directory (default: cwd)
+  --force           Overwrite existing harness files
+  --no-git          Skip git init
+  --json            JSON output`,
+
+  status: `Usage: harness-dev status [--target <dir>] [--json]
+
+Show current phase, gate state, detected stack, recent lessons, and next action.
+
+Flags:
+  --target <dir>    Project directory (default: cwd)
+  --json            JSON output`,
+
+  phase: `Usage: harness-dev phase <name> [--target <dir>] [--git-ops] [--json]
+
+Invoke a phase. Valid phases: define, plan, build, verify, simplify, review, ship.
+
+Flags:
+  --target <dir>    Project directory (default: cwd)
+  --git-ops         Execute git reset --hard + clean on retry (fresh context)
+  --json            JSON output`,
+
+  validate: `Usage: harness-dev validate [--phase <name>] [--feature <id> --task <id>] [--target <dir>] [--json]
+
+Run gate checks for the current (or specified) phase.
+
+Flags:
+  --phase <name>    Override current phase
+  --feature <id>    Validate a single feature (feature-iterate phases)
+  --task <id>       Validate a single task within a feature
+  --target <dir>    Project directory (default: cwd)
+  --json            JSON output`,
+
+  'set-mode': `Usage: harness-dev set-mode <copilot|autopilot> [--target <dir>] [--json]
+
+Switch execution mode. Autopilot requires DEFINE phase or later.`,
+
+  config: `Usage: harness-dev config list [--target <dir>] [--json]
+       harness-dev config get [key] [--target <dir>] [--json]
+       harness-dev config set <key> <value> [--target <dir>] [--json]
+
+List all parameters with descriptions, or get/set values via dot-notation.
+Use 'config list' to see all configurable parameters, their current values,
+types, allowed options, and descriptions.
+
+Examples:
+  harness-dev config list
+  harness-dev config list --json
+  harness-dev config get gates.enabled
+  harness-dev config set gates.enabled true
+  harness-dev config set mode autopilot
+  harness-dev config set maxRetries 5`,
+
+  pause: `Usage: harness-dev pause [--target <dir>] [--json]
+
+Pause autopilot execution. Autopilot stops after the current phase gate.`,
+
+  resume: `Usage: harness-dev resume [--target <dir>] [--json]
+
+Resume autopilot execution.`,
+
+  learn: `Usage: harness-dev learn "<message>" [--target <dir>] [--json]
+
+Append a lesson to the Lessons section of progress.md.`,
+
+  contract: `Usage: harness-dev contract <subcommand> [options] [--target <dir>] [--json]
+
+Subcommands:
+  propose --scope "..." [--exclusions "..."] [--criteria "..."]   Generator proposes
+  review --decision <agreed|needs-revision> [--notes "..."]       Evaluator reviews
+  status                                                            Show contract state
+  escalate [--reason "..."]                                         Human adjudication`,
+
+  worktree: `Usage: harness-dev worktree <subcommand> [options] [--target <dir>] [--json]
+
+Subcommands:
+  create <name>   Create isolated worktree for a feature
+  list            List active worktrees
+  prune           Remove orphaned worktrees
+  remove <name>   Clean up worktree (optionally merge branch)`,
+
+  rollback: `Usage: harness-dev rollback <subcommand> [checkpoint] [--target <dir>] [--json]
+
+Subcommands:
+  list            Show available checkpoints
+  to <tag>        Restore state to a checkpoint
+  branch <tag>    Branch off a good iteration`,
+
+  checkpoint: `Usage: harness-dev checkpoint create <label> [--force] [--target <dir>] [--json]
+
+Create a manual checkpoint tag (manual/<label>). Requires clean working tree
+unless --force is given.`,
+
+  'detect-tool': `Usage: harness-dev detect-tool [--target <dir>] [--json]
+
+Scan the project for agent-tool files (CLAUDE.md, .cursorrules, AGENTS.md, etc.)
+and report which coding agents are available. Recommends a tool based on config
+and detected files.`,
+
+  help: `Usage: harness-dev help
+
+Show the global help message. Alias for --help.`,
+};
+
+/**
+ * Get per-command help text.
+ * @param {string} command
+ * @param {boolean} json
+ * @returns {string|null} — null if no per-command help exists
+ */
+export function commandHelpText(command, json = false) {
+  const text = COMMAND_HELP[command];
+  if (!text) { return null; }
+  if (json) {
+    return JSON.stringify({ command, help: text });
+  }
+  return text;
+}

package/cli/lib/modes.mjs

@@ -0,0 +1,92 @@
+/**
+ * modes — Copilot/Autopilot mode configuration and behavior.
+ *
+ * Shared utilities for determining mode, reading copilot config,
+ * and handling interactive prompts.
+ *
+ * Usage:
+ *   import { getMode, shouldAutoPrompt, shouldConfirmGates, promptYesNo } from './modes.mjs';
+ */
+import { loadConfig, set } from './state.mjs';
+import * as readline from 'node:readline';
+
+/**
+ * Get the current mode for a project.
+ * @param {string} targetDir
+ * @returns {'copilot'|'autopilot'}
+ */
+export function getMode(targetDir) {
+  const { config } = loadConfig(targetDir);
+  return (config.mode === 'autopilot') ? 'autopilot' : 'copilot';
+}
+
+/**
+ * Check if copilot should auto-prompt after gate passes.
+ * @param {string} targetDir
+ * @returns {boolean}
+ */
+export function shouldAutoPrompt(targetDir) {
+  const { config } = loadConfig(targetDir);
+  if (config.mode !== 'copilot') {return false;}
+  return config.copilot?.autoPrompt !== false; // default true
+}
+
+/**
+ * Check if copilot should confirm before advancing gates.
+ * @param {string} targetDir
+ * @returns {boolean}
+ */
+export function shouldConfirmGates(targetDir) {
+  const { config } = loadConfig(targetDir);
+  if (config.mode !== 'copilot') {return false;}
+  return config.copilot?.confirmGates !== false; // default true
+}
+
+/**
+ * Prompt the user with a yes/no question. Returns true for y/yes.
+ * In non-interactive contexts (stdin not a TTY), returns null (no answer).
+ * @param {string} question — question text to display
+ * @returns {Promise<boolean|null>} true=y, false=n, null=no answer
+ */
+export function promptYesNo(question) {
+  // Use readline for interactive prompt
+  return new Promise((resolve) => {
+    try {
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+      rl.question(`${question} (y/n) `, (answer) => {
+        rl.close();
+        const trimmed = answer.trim().toLowerCase();
+        if (trimmed === 'y' || trimmed === 'yes') {
+          resolve(true);
+        } else if (trimmed === 'n' || trimmed === 'no') {
+          resolve(false);
+        } else {
+          // Invalid input — treat as no
+          resolve(false);
+        }
+      });
+    } catch {
+      // Not interactive or readline unavailable
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * Ensure copilot config block exists in project config.
+ * @param {string} targetDir
+ * @param {object} [overrides]
+ */
+export function ensureCopilotConfig(targetDir, overrides = {}) {
+  const { config } = loadConfig(targetDir);
+  if (!config.copilot) {
+    config.copilot = { autoPrompt: true, confirmGates: true };
+  }
+  // Apply overrides
+  if (overrides.autoPrompt !== undefined) {config.copilot.autoPrompt = overrides.autoPrompt;}
+  if (overrides.confirmGates !== undefined) {config.copilot.confirmGates = overrides.confirmGates;}
+  set(targetDir, 'copilot', config.copilot);
+}

package/cli/lib/output.mjs

@@ -0,0 +1,49 @@
+/**
+ * output — Centralized CLI output helpers.
+ *
+ * Standardizes the JSON output contract { command, status, message, ... }
+ * and human-mode text emission so every command emits output the same way.
+ *
+ * Usage:
+ *   import { emitJson, emitHuman, emitError } from '../lib/output.mjs';
+ *   emitJson({ command: 'status', status: 'ok', message: '...', ...extras });
+ *   emitHuman('✓ Done\n');
+ */
+
+/**
+ * Write a JSON object to stdout followed by a newline.
+ * @param {object} obj
+ */
+export function emitJson(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n');
+}
+
+/**
+ * Write human-readable text to stdout.
+ * @param {string} text
+ */
+export function emitHuman(text) {
+  process.stdout.write(text);
+}
+
+/**
+ * Write human-readable error text to stderr.
+ * @param {string} text
+ */
+export function emitHumanError(text) {
+  process.stderr.write(text);
+}
+
+/**
+ * Emit a standard command result in JSON or human form.
+ *
+ * @param {object} opts
+ * @param {string} opts.command — command name
+ * @param {boolean} opts.json — JSON mode
+ * @param {boolean} opts.ok — success flag
+ * @param {string} opts.message — status message
+ * @param {string} [opts.okText] — human success text (defaults to message)
+ * @param {string} [opts.errText] — human error text (defaults to message)
+ * @param {object} [opts.extras] — additional JSON fields
+ */
+// emitResult and emitFatalError removed — commands use emitJson/emitHuman directly.

package/cli/lib/paths.mjs

@@ -0,0 +1,75 @@
+/**
+ * paths — Centralized path resolution for the CLI.
+ *
+ * Single source of truth for the lib directory location and all
+ * project-relative file paths (config, feature list, contract, progress,
+ * schemas, templates). Eliminates 4× duplicated __dirname boilerplate and
+ * scattered resolve(targetDir, '...') calls.
+ *
+ * Usage:
+ *   import { LIB_DIR, TEMPLATES_DIR, SCHEMA_DIR, CONFIG_PATH, FEATURE_LIST_PATH } from './paths.mjs';
+ */
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Directory containing cli/lib/ (this module's directory). */
+export const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** Project root (parent of cli/). */
+export const PROJECT_ROOT = resolve(LIB_DIR, '..', '..');
+
+/** Templates directory (project_root/templates). */
+export const TEMPLATES_DIR = resolve(PROJECT_ROOT, 'templates');
+
+/** Adapters directory (project_root/adapters) — tool-specific integration files. */
+export const ADAPTERS_DIR = resolve(PROJECT_ROOT, 'adapters');
+
+/** JSON schemas directory (project_root/schema). */
+export const SCHEMA_DIR = resolve(PROJECT_ROOT, 'schema');
+
+/** harness-config.json schema path. */
+export const CONFIG_SCHEMA_PATH = resolve(SCHEMA_DIR, 'harness-config.schema.json');
+
+/** feature_list.json schema path. */
+export const FEATURE_LIST_SCHEMA_PATH = resolve(SCHEMA_DIR, 'feature-list.schema.json');
+
+/** stacks.json metadata path (cli/lib/schemas/stacks.json). */
+export const STACKS_SCHEMA_PATH = resolve(LIB_DIR, 'schemas', 'stacks.json');
+
+// ── Project-relative paths (target project, not this CLI) ────────────────────
+
+/**
+ * Path to a project's harness-config.json.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function CONFIG_PATH(targetDir) {
+  return resolve(targetDir, 'harness-config.json');
+}
+
+/**
+ * Path to a project's feature_list.json.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function FEATURE_LIST_PATH(targetDir) {
+  return resolve(targetDir, 'feature_list.json');
+}
+
+/**
+ * Path to a project's sprint-contract.md.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function CONTRACT_PATH(targetDir) {
+  return resolve(targetDir, 'sprint-contract.md');
+}
+
+/**
+ * Path to a project's progress.md.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function PROGRESS_PATH(targetDir) {
+  return resolve(targetDir, 'progress.md');
+}

package/cli/lib/phases.mjs

@@ -0,0 +1,58 @@
+/**
+ * phases — Phase pipeline definitions and pure transition logic.
+ *
+ * Extracted from state.mjs to separate the phase state machine (pure logic,
+ * no I/O) from config file I/O. state.mjs re-exports these for backward
+ * compatibility.
+ *
+ * Usage:
+ *   import { PHASE_ORDER, getPhaseOrder, isValidTransition } from './phases.mjs';
+ */
+
+/** Canonical phase pipeline order. */
+export const PHASE_ORDER = [
+  'init',
+  'define',
+  'plan',
+  'build',
+  'verify',
+  'simplify',
+  'review',
+  'ship',
+];
+
+/**
+ * Get the ordered list of enabled phases.
+ * Filters out SIMPLIFY unless explicitly enabled.
+ * @param {string[]} [enabled]
+ * @returns {string[]}
+ */
+export function getPhaseOrder(enabled) {
+  if (enabled === undefined || enabled === null) {
+    // Default: all phases except simplify
+    return PHASE_ORDER.filter(p => p !== 'simplify');
+  }
+  if (Array.isArray(enabled)) {
+    return PHASE_ORDER.filter(p => enabled.includes(p));
+  }
+  // Fallback: default
+  return PHASE_ORDER.filter(p => p !== 'simplify');
+}
+
+/**
+ * Check if a phase transition is valid.
+ * @param {string|null} fromPhase — current phase (null = start)
+ * @param {string} toPhase — target phase
+ * @param {string[]} [enabled]
+ * @returns {boolean}
+ */
+export function isValidTransition(fromPhase, toPhase, enabled) {
+  const order = getPhaseOrder(enabled);
+  if (!order.includes(toPhase)) {return false;}
+  if (fromPhase === null) {return order[0] === toPhase;}
+  // Re-running the same phase is always valid
+  if (fromPhase === toPhase) {return true;}
+  const fromIdx = order.indexOf(fromPhase);
+  const toIdx = order.indexOf(toPhase);
+  return toIdx === fromIdx + 1;
+}

package/cli/lib/platform.mjs

@@ -0,0 +1,78 @@
+/**
+ * platform — Cross-platform detection and execution helpers.
+ *
+ * Usage:
+ *   import { getPlatform, isWindows, crossExec } from './platform.mjs';
+ */
+import { execSync } from 'node:child_process';
+
+/**
+ * Detect the current platform.
+ * @returns {'linux'|'darwin'|'win32'}
+ */
+export function getPlatform() {
+  return process.platform;
+}
+
+/**
+ * Check if running on Windows.
+ * @returns {boolean}
+ */
+export function isWindows() {
+  return process.platform === 'win32';
+}
+
+/**
+ * Check if running on macOS.
+ * @returns {boolean}
+ */
+export function isMacOS() {
+  return process.platform === 'darwin';
+}
+
+/**
+ * Shell-quote a string for the current platform.
+ * On Windows, uses double quotes. On Unix, wraps in single quotes (or double if shell chars present).
+ * @param {string} str
+ * @returns {string}
+ */
+export function shellQuote(str) {
+  if (isWindows()) {
+    // Windows CMD: double quotes, doubled for literal
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  // Unix: single quotes, escaped for any single quotes in the string
+  if (str.includes("'")) {
+    return `"${str.replace(/"/g, '\\"')}"`;
+  }
+  return `'${str}'`;
+}
+
+/**
+ * Execute a command using the platform-appropriate shell.
+ * On Windows, uses 'cmd /c'. On Unix, uses 'sh -c'.
+ * @param {string} cmd
+ * @param {object} [options]
+ * @returns {{ stdout: string, stderr: string, exitCode: number }}
+ */
+export function crossExec(cmd, options = {}) {
+  const shell = isWindows() ? 'cmd' : 'sh';
+  const shellFlag = isWindows() ? '/c' : '-c';
+  try {
+    // execSync with encoding:'utf-8' returns the stdout string directly
+    // (not an object with .stdout/.stderr).
+    const stdout = execSync(`${shell} ${shellFlag} ${shellQuote(cmd)}`, {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: options.timeout || 60000,
+      ...options,
+    });
+    return { stdout: stdout || '', stderr: '', exitCode: 0 };
+  } catch (err) {
+    return {
+      stdout: typeof err.stdout === 'string' ? err.stdout : (err.stdout?.toString() || ''),
+      stderr: typeof err.stderr === 'string' ? err.stderr : (err.stderr?.toString() || err.message),
+      exitCode: err.status || 1,
+    };
+  }
+}