dev-harness-cli 1.0.0

package/cli/lib/args.mjs

@@ -0,0 +1,111 @@
+/**
+ * Minimal argument parser — no external deps.
+ *
+ * Parses: --flag value, --flag=value, --boolean, -h, --, positional args
+ * Supports: --json, --help, --version as named flags
+ */
+
+/**
+ * @param {string[]} argv — typically process.argv
+ * @returns {{
+ *   command: string|null,
+ *   subcommand: string|null,
+ *   flags: Record<string, string|boolean>,
+ *   positionals: string[],
+ *   json: boolean,
+ *   help: boolean,
+ *   version: boolean,
+ * }}
+ */
+export function parseArgs(argv) {
+  const result = {
+    command: null,
+    subcommand: null,
+    flags: {},
+    positionals: [],
+    json: false,
+    help: false,
+    version: false,
+  };
+
+  // skip node binary + script path
+  const tokens = argv.slice(2);
+  let stopParsing = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+
+    // everything after -- is a positional
+    if (stopParsing) {
+      result.positionals.push(token);
+      continue;
+    }
+
+    if (token === '--') {
+      stopParsing = true;
+      continue;
+    }
+
+    // flag tokens
+    if (token.startsWith('--')) {
+      const eqIdx = token.indexOf('=');
+
+      if (eqIdx !== -1) {
+        // --key=value
+        const key = token.slice(2, eqIdx);
+        result.flags[key] = token.slice(eqIdx + 1);
+        // promote well-known flags
+        if (key === 'json') {result.json = true;}
+        if (key === 'help') {result.help = true;}
+        if (key === 'version') {result.version = true;}
+      } else {
+        const key = token.slice(2);
+
+        // promote before value detection so --json alone is boolean
+        if (key === 'json') { result.json = true; continue; }
+        if (key === 'help') { result.help = true; continue; }
+        if (key === 'version') { result.version = true; continue; }
+
+        // peek next token for value
+        if (i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
+          result.flags[key] = tokens[i + 1];
+          i++;
+        } else {
+          // boolean flag (no value)
+          result.flags[key] = true;
+        }
+      }
+      continue;
+    }
+
+    // short flags
+    if (token.startsWith('-') && token.length > 1 && token[1] !== '-') {
+      if (token === '-h') { result.help = true; continue; }
+      result.flags[token.slice(1)] = true;
+      continue;
+    }
+
+    // positional — first one is the command
+    if (!result.command) {
+      result.command = token;
+    } else {
+      result.positionals.push(token);
+    }
+  }
+
+  // The first positional becomes the subcommand (e.g. "phase build" → command=phase, subcommand=build)
+  if (result.positionals.length > 0) {
+    result.subcommand = result.positionals[0];
+    result.positionals = result.positionals.slice(1);
+  }
+
+  return result;
+}
+
+/**
+ * Determine if stdout should be JSON based on args.
+ * Mirrors the implicit promotion logic in parseArgs for external callers.
+ * @param {{ json?: boolean, flags?: Record<string,any> }} args
+ * @returns {boolean}
+ */
+// wantsJson removed — use parseCommandArgs().json from command-helpers.mjs instead.

package/cli/lib/command-helpers.mjs

@@ -0,0 +1,50 @@
+/**
+ * command-helpers — Shared utilities for command handlers.
+ *
+ * Eliminates the repeated `const json = !!(args.json || args.flags?.json)`
+ * and `const targetDir = ...` boilerplate duplicated across all 13 commands,
+ * plus the phaseLabel helper duplicated in 3 files.
+ *
+ * Usage:
+ *   import { parseCommandArgs, phaseLabel } from '../lib/command-helpers.mjs';
+ *   const { json, targetDir, flags } = parseCommandArgs(args);
+ */
+import { resolve } from 'node:path';
+
+/**
+ * Extract common command options from parsed args.
+ * @param {object} args — parsed args from args.mjs parseArgs()
+ * @returns {{
+ *   json: boolean,
+ *   targetDir: string,
+ *   flags: object,
+ *   positionals: string[],
+ *   subcommand: string|null,
+ *   force: boolean,
+ *   gitOps: boolean,
+ * }}
+ */
+export function parseCommandArgs(args) {
+  const json = !!(args.json || args.flags?.json);
+  const rawTarget = args.flags?.target;
+  const targetDir = (typeof rawTarget === 'string') ? resolve(rawTarget) : process.cwd();
+  return {
+    json,
+    targetDir,
+    flags: args.flags || {},
+    positionals: args.positionals || [],
+    subcommand: args.subcommand ?? null,
+    force: !!(args.flags?.force),
+    gitOps: !!(args.flags?.['git-ops'] || args.flags?.gitOps),
+  };
+}
+
+/**
+ * Format a phase name for display (uppercase, or UNKNOWN if null).
+ * Centralized here to avoid 3× duplication across ralph-inner/validate/phase.
+ * @param {string|null} phase
+ * @returns {string}
+ */
+export function phaseLabel(phase) {
+  return phase ? phase.toUpperCase() : 'UNKNOWN';
+}

package/cli/lib/config-registry.mjs

@@ -0,0 +1,329 @@
+/**
+ * config-registry — Metadata for all configurable harness parameters.
+ *
+ * Single source of truth for parameter descriptions, types, allowed values,
+ * and defaults. Used by:
+ *   - `harness-dev config list` — interactive parameter listing
+ *   - docs/CONFIGURATION.md — generated documentation
+ *   - config command — validation of set values
+ *
+ * Each entry: { key, group, label, type, description, default, options?, editable }
+ *   - editable: false for runtime state (currentPhase, retryCount, etc.)
+ *
+ * Usage:
+ *   import { CONFIG_PARAMS, getParamMeta, EDITABLE_PARAMS } from './config-registry.mjs';
+ */
+export const CONFIG_PARAMS = [
+  // ── Execution Mode ────────────────────────────────────────────────────────
+  {
+    key: 'mode',
+    group: 'Execution',
+    label: 'Mode',
+    type: 'enum',
+    description: 'Execution mode. copilot = human runs each phase manually. autopilot = harness auto-advances through phases after each gate passes.',
+    default: 'copilot',
+    options: ['copilot', 'autopilot'],
+    editable: true,
+  },
+  {
+    key: 'paused',
+    group: 'Execution',
+    label: 'Paused',
+    type: 'boolean',
+    description: 'Autopilot pause state. When true, autopilot stops after current phase gate. Set by pause/resume commands.',
+    default: false,
+    editable: true,
+  },
+  {
+    key: 'maxRetries',
+    group: 'Execution',
+    label: 'Max Retries',
+    type: 'integer',
+    description: 'Maximum retry attempts per phase before escalating to human. Each retry gets fresh context (git reset if --git-ops enabled).',
+    default: 3,
+    editable: true,
+  },
+
+  // ── Stack ──────────────────────────────────────────────────────────────────
+  {
+    key: 'stack',
+    group: 'Stack',
+    label: 'Stack',
+    type: 'string',
+    description: 'Project programming stack. 31 built-in stacks (python, node, go, rust, etc.) or any custom name (fill stackMeta).',
+    default: null,
+    editable: true,
+  },
+  {
+    key: 'stackMeta',
+    group: 'Stack',
+    label: 'Stack Metadata',
+    type: 'object',
+    description: 'Custom stack metadata (overrides built-in stacks.json). Fill during DEFINE for unknown stacks. Keys: label, testCmd, lintCmd, typeCheckCmd, buildCmd, installCmd, coverageCmd, versionFile, configFile, extensions, detectFiles.',
+    default: null,
+    editable: true,
+  },
+
+  // ── Agent Tool ─────────────────────────────────────────────────────────────
+  {
+    key: 'agentTool',
+    group: 'Agent Tool',
+    label: 'Agent Tool',
+    type: 'enum',
+    description: 'Which agentic coding tool the project uses. Determines tool-specific file generated (CLAUDE.md, .cursorrules, etc.). null = unspecified.',
+    default: null,
+    options: [null, 'generic', 'claude-code', 'codex', 'cursor', 'windsurf', 'gemini', 'copilot', 'cline', 'roo', 'kilo-code', 'aider', 'continue', 'opencode', 'amazon-q', 'antigravity', 'openclaw', 'pi', 'hermes'],
+    editable: true,
+  },
+
+  // ── Gates ──────────────────────────────────────────────────────────────────
+  {
+    key: 'gates.enabled',
+    group: 'Gates',
+    label: 'Gates Enabled',
+    type: 'boolean',
+    description: 'Master switch for phase gate validation. When false, validate reports gates disabled. Enable to enforce lint/test/coverage checks.',
+    default: false,
+    editable: true,
+  },
+  {
+    key: 'gates.checks',
+    group: 'Gates',
+    label: 'Gate Checks',
+    type: 'array',
+    description: 'Which checks to run. ["all"] runs every check for the phase. Or specify individual: git-repo, config-exists, git-clean, lint, tests, coverage, contract-agreed, etc.',
+    default: ['all'],
+    editable: true,
+  },
+  {
+    key: 'gates.coverage.enabled',
+    group: 'Gates',
+    label: 'Coverage Gate',
+    type: 'boolean',
+    description: 'Enable coverage threshold check in BUILD/VERIFY phases.',
+    default: false,
+    editable: true,
+  },
+  {
+    key: 'gates.coverage.threshold',
+    group: 'Gates',
+    label: 'Coverage Threshold',
+    type: 'integer',
+    description: 'Minimum coverage percentage (0-100) to pass coverage gate.',
+    default: 80,
+    editable: true,
+  },
+
+  // ── Git ────────────────────────────────────────────────────────────────────
+  {
+    key: 'git.autoCommit',
+    group: 'Git',
+    label: 'Auto-Commit',
+    type: 'boolean',
+    description: 'Automatically commit after each successful phase iteration. Recommended for autopilot.',
+    default: false,
+    editable: true,
+  },
+  {
+    key: 'git.autoTag',
+    group: 'Git',
+    label: 'Auto-Tag',
+    type: 'boolean',
+    description: 'Create git tag when pipeline completes. Tags named pipeline-<date>-<timestamp>.',
+    default: false,
+    editable: true,
+  },
+  {
+    key: 'git.resetOnRetry',
+    group: 'Git',
+    label: 'Reset on Retry',
+    type: 'boolean',
+    description: 'Reset git working tree on retry (fresh context). Also via --git-ops flag on phase command.',
+    default: false,
+    editable: true,
+  },
+
+  // ── Phases ─────────────────────────────────────────────────────────────────
+  {
+    key: 'phases.enabled',
+    group: 'Phases',
+    label: 'Enabled Phases',
+    type: 'array',
+    description: 'Phases in pipeline. Default excludes simplify. Add "simplify" to enable. Order: define, plan, build, verify, [simplify], review, ship.',
+    default: ['define', 'plan', 'build', 'verify', 'review', 'ship'],
+    editable: true,
+  },
+
+  // ── Agent Tones ────────────────────────────────────────────────────────────
+  {
+    key: 'agents.tone.planner',
+    group: 'Agent Tones',
+    label: 'Planner Tone',
+    type: 'string',
+    description: 'Personality/instructions for the Planner agent persona.',
+    default: 'Analytical and precise. Define clear boundaries.',
+    editable: true,
+  },
+  {
+    key: 'agents.tone.generator',
+    group: 'Agent Tones',
+    label: 'Generator Tone',
+    type: 'string',
+    description: 'Personality/instructions for the Generator agent persona.',
+    default: 'Focused and practical. Build what\'s specified, nothing more.',
+    editable: true,
+  },
+  {
+    key: 'agents.tone.evaluator',
+    group: 'Agent Tones',
+    label: 'Evaluator Tone',
+    type: 'string',
+    description: 'Personality/instructions for the Evaluator agent persona.',
+    default: 'Skeptical and thorough. Accept only compelling evidence.',
+    editable: true,
+  },
+  {
+    key: 'agents.tone.simplifier',
+    group: 'Agent Tones',
+    label: 'Simplifier Tone',
+    type: 'string',
+    description: 'Personality/instructions for the Simplifier agent persona.',
+    default: 'Relentless about clarity. Delete more than you add.',
+    editable: true,
+  },
+
+  // ── Runtime State (read-only — managed by harness) ─────────────────────────
+  {
+    key: 'currentPhase',
+    group: 'Runtime State',
+    label: 'Current Phase',
+    type: 'string',
+    description: 'Current pipeline phase. Managed by harness-dev phase — do not edit.',
+    default: null,
+    editable: false,
+  },
+  {
+    key: 'retryCount',
+    group: 'Runtime State',
+    label: 'Retry Count',
+    type: 'integer',
+    description: 'Retry count for active phase. Reset on transition. Managed by harness.',
+    default: 0,
+    editable: false,
+  },
+  {
+    key: 'pipelineIteration',
+    group: 'Runtime State',
+    label: 'Pipeline Iteration',
+    type: 'integer',
+    description: 'Full pipeline completion count. Incremented on SHIP. Managed by harness.',
+    default: 0,
+    editable: false,
+  },
+  {
+    key: 'gateHistory',
+    group: 'Runtime State',
+    label: 'Gate History',
+    type: 'array',
+    description: 'Record of gate pass/fail results. Managed by harness.',
+    default: [],
+    editable: false,
+  },
+  {
+    key: 'features.remaining',
+    group: 'Runtime State',
+    label: 'Features Remaining',
+    type: 'integer',
+    description: 'Incomplete feature count. Managed by harness.',
+    default: 0,
+    editable: false,
+  },
+  {
+    key: 'features.passing',
+    group: 'Runtime State',
+    label: 'Features Passing',
+    type: 'integer',
+    description: 'Completed feature count. Managed by harness.',
+    default: 0,
+    editable: false,
+  },
+  {
+    key: 'features.total',
+    group: 'Runtime State',
+    label: 'Features Total',
+    type: 'integer',
+    description: 'Total feature count. Managed by harness.',
+    default: 0,
+    editable: false,
+  },
+  {
+    key: 'git.branch',
+    group: 'Runtime State',
+    label: 'Git Branch',
+    type: 'string',
+    description: 'Current git branch. Auto-detected — do not edit.',
+    default: null,
+    editable: false,
+  },
+  {
+    key: 'git.clean',
+    group: 'Runtime State',
+    label: 'Git Clean',
+    type: 'boolean',
+    description: 'Working tree clean state. Auto-detected — do not edit.',
+    default: true,
+    editable: false,
+  },
+  {
+    key: 'git.hasUpstream',
+    group: 'Runtime State',
+    label: 'Has Upstream',
+    type: 'boolean',
+    description: 'Branch upstream tracking. Auto-detected — do not edit.',
+    default: false,
+    editable: false,
+  },
+  {
+    key: 'git.lastCommitMessage',
+    group: 'Runtime State',
+    label: 'Last Commit',
+    type: 'string',
+    description: 'Last git commit message. Auto-detected — do not edit.',
+    default: null,
+    editable: false,
+  },
+];
+
+/**
+ * Get metadata for a specific parameter key.
+ * @param {string} key
+ * @returns {object|null}
+ */
+export function getParamMeta(key) {
+  return CONFIG_PARAMS.find(p => p.key === key) || null;
+}
+
+/**
+ * Get all parameters in a specific group.
+ * @param {string} group
+ * @returns {object[]}
+ */
+export function getParamsByGroup(group) {
+  return CONFIG_PARAMS.filter(p => p.group === group);
+}
+
+/**
+ * Get unique group names (preserving order).
+ * @returns {string[]}
+ */
+export function getGroups() {
+  const seen = new Set();
+  const groups = [];
+  for (const p of CONFIG_PARAMS) {
+    if (!seen.has(p.group)) {
+      seen.add(p.group);
+      groups.push(p.group);
+    }
+  }
+  return groups;
+}

package/cli/lib/constants.mjs

@@ -0,0 +1,30 @@
+/**
+ * constants — Centralized magic numbers and strings.
+ *
+ * Single source of truth for tunable values scattered across modules.
+ * Keeping them here makes intent clear and changes auditable.
+ *
+ * Usage:
+ *   import { GATE_TIMEOUT, COVERAGE_TIMEOUT, MAX_NEGOTIATION_ROUNDS } from './constants.mjs';
+ */
+
+/** Default max retries per phase before escalating to human. */
+export const DEFAULT_MAX_RETRIES = 3;
+
+/** Timeout (ms) for standard git/shell commands. */
+export const COMMAND_TIMEOUT = 30000;
+
+/** Timeout (ms) for coverage checks (longer — coverage runs the full test suite). */
+export const COVERAGE_TIMEOUT = 120000;
+
+/** Default coverage threshold percentage. */
+export const COVERAGE_THRESHOLD_DEFAULT = 80;
+
+/** Max sprint-contract negotiation rounds before auto-escalation. */
+export const MAX_NEGOTIATION_ROUNDS = 5;
+
+/** Directory scan depth for stack detection. */
+export const STACK_SCAN_DEPTH = 2;
+
+/** File mode for executable scripts (init.sh). */
+export const EXECUTABLE_MODE = 0o755;