dev-harness-cli 1.0.0

package/cli/lib/tool-registry.mjs

@@ -0,0 +1,218 @@
+/**
+ * tool-registry — Central registry of all supported agentic coding tools.
+ *
+ * Maps each tool to:
+ *   - file: the tool-specific file to generate (or null if tool reads AGENTS.md natively)
+ *   - header: optional prefix prepended to AGENTS.md content when generating tool file
+ *   - detectionFiles: files whose presence indicates this tool is in use
+ *   - label: human-readable name
+ *   - notes: short description
+ *   - special: true for tools with full adapter directories (e.g. Hermes)
+ *
+ * AGENTS.md is the canonical source. Tool-specific files (CLAUDE.md, .cursorrules,
+ * etc.) are generated by copying AGENTS.md content + optional header — no separate
+ * templates needed. This keeps content DRY: one source, many filenames.
+ *
+ * Usage:
+ *   import { TOOL_REGISTRY, KNOWN_TOOLS, getToolFile, getToolDetectionFiles } from './tool-registry.mjs';
+ */
+
+/**
+ * @typedef {Object} ToolEntry
+ * @property {string} label - Human-readable tool name
+ * @property {string|null} file - Tool-specific filename to generate (null = AGENTS.md only)
+ * @property {string|null} header - Optional header prepended to AGENTS.md content
+ * @property {string[]} detectionFiles - Files whose presence indicates this tool
+ * @property {string} notes - Short description
+ * @property {boolean} [special] - True if tool has a full adapter directory
+ */
+
+/** @type {Record<string, ToolEntry>} */
+export const TOOL_REGISTRY = {
+  // ── AGENTS.md-native tools (no extra file needed) ────────────────────────
+  'generic': {
+    label: 'Generic',
+    file: null,
+    header: null,
+    detectionFiles: [],
+    notes: 'Default — AGENTS.md only. Works with any tool that reads AGENTS.md.',
+  },
+  'codex': {
+    label: 'Codex CLI',
+    file: null,
+    header: null,
+    detectionFiles: [],
+    notes: 'OpenAI Codex CLI reads AGENTS.md from project root natively.',
+  },
+  'opencode': {
+    label: 'OpenCode',
+    file: null,
+    header: null,
+    detectionFiles: [],
+    notes: 'OpenCode reads AGENTS.md natively.',
+  },
+  'continue': {
+    label: 'Continue',
+    file: null,
+    header: null,
+    detectionFiles: ['.continue/config.json', 'continue.json'],
+    notes: 'Continue reads AGENTS.md from project root.',
+  },
+  'aider': {
+    label: 'Aider',
+    file: null,
+    header: null,
+    detectionFiles: ['.aider.conf.yml', '.aider.conf.yaml', '.aider.conf.json'],
+    notes: 'Aider auto-discovers AGENTS.md (or via --read CONVENTIONS.md).',
+  },
+
+  // ── Tools with a specific rules file (generated from AGENTS.md content) ──
+  'claude-code': {
+    label: 'Claude Code',
+    file: 'CLAUDE.md',
+    header: '> Read by Claude Code automatically. Mirrors AGENTS.md.\n',
+    detectionFiles: ['CLAUDE.md'],
+    notes: 'Claude Code reads CLAUDE.md on startup (falls back to AGENTS.md).',
+  },
+  'cursor': {
+    label: 'Cursor',
+    file: '.cursorrules',
+    header: '# Cursor rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.cursorrules', '.cursor/rules'],
+    notes: 'Cursor reads .cursorrules as system context.',
+  },
+  'windsurf': {
+    label: 'Windsurf',
+    file: '.windsurfrules',
+    header: '# Windsurf rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.windsurfrules'],
+    notes: 'Windsurf (Codeium) reads .windsurfrules.',
+  },
+  'gemini': {
+    label: 'Gemini CLI',
+    file: 'GEMINI.md',
+    header: '> Read by Gemini CLI. Mirrors AGENTS.md.\n',
+    detectionFiles: ['GEMINI.md'],
+    notes: 'Google Gemini CLI reads GEMINI.md.',
+  },
+  'copilot': {
+    label: 'GitHub Copilot',
+    file: '.github/copilot-instructions.md',
+    header: '# GitHub Copilot instructions — mirrors AGENTS.md\n',
+    detectionFiles: ['.github/copilot-instructions.md'],
+    notes: 'GitHub Copilot reads .github/copilot-instructions.md.',
+  },
+  'cline': {
+    label: 'Cline',
+    file: '.clinerules',
+    header: '# Cline rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.clinerules'],
+    notes: 'Cline (VS Code extension) reads .clinerules.',
+  },
+  'roo': {
+    label: 'Roo Code',
+    file: '.roorules',
+    header: '# Roo Code rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.roorules'],
+    notes: 'Roo Code reads .roorules.',
+  },
+  'kilo-code': {
+    label: 'Kilo Code',
+    file: '.kilocoderules',
+    header: '# Kilo Code rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.kilocoderules'],
+    notes: 'Kilo Code reads .kilocoderules.',
+  },
+  'amazon-q': {
+    label: 'Amazon Q Developer',
+    file: '.amazonq/rules.md',
+    header: '# Amazon Q Developer rules — mirrors AGENTS.md\n',
+    detectionFiles: ['.amazonq/rules.md', '.amazonq/rules'],
+    notes: 'Amazon Q Developer reads .amazonq/rules.',
+  },
+
+  // ── Tools assumed to read AGENTS.md (format not yet confirmed) ───────────
+  'antigravity': {
+    label: 'Antigravity 2',
+    file: null,
+    header: null,
+    detectionFiles: ['.antigravity'],
+    notes: 'Antigravity 2 (IDE/CLI/SDK) — assumed to read AGENTS.md. Adjust if needed.',
+  },
+  'openclaw': {
+    label: 'OpenClaw',
+    file: null,
+    header: null,
+    detectionFiles: ['.openclaw'],
+    notes: 'OpenClaw — assumed to read AGENTS.md. Adjust if needed.',
+  },
+  'pi': {
+    label: 'Pi',
+    file: null,
+    header: null,
+    detectionFiles: ['.pi'],
+    notes: 'Pi — assumed to read AGENTS.md. Adjust if needed.',
+  },
+
+  // ── Special: full adapter directory ──────────────────────────────────────
+  'hermes': {
+    label: 'Hermes',
+    file: null,
+    header: null,
+    detectionFiles: ['adapters/hermes/SKILL.md', 'hermes/skill/dev-harness/SKILL.md'],
+    special: true,
+    notes: 'Hermes uses SKILL.md manifest with wrapper scripts in adapters/hermes/.',
+  },
+};
+
+/** All known tool names (keys of TOOL_REGISTRY). */
+export const KNOWN_TOOLS = Object.keys(TOOL_REGISTRY);
+
+/** Tools that read AGENTS.md natively (no tool-specific file). */
+export const AGENTS_MD_TOOLS = Object.entries(TOOL_REGISTRY)
+  .filter(([, t]) => t.file === null && !t.special)
+  .map(([name]) => name);
+
+/**
+ * Get the tool-specific file info for a tool, or null.
+ * @param {string} toolName
+ * @returns {ToolEntry|null}
+ */
+export function getToolEntry(toolName) {
+  return TOOL_REGISTRY[toolName] || null;
+}
+
+/**
+ * Get the filename to generate for a tool, or null (AGENTS.md only).
+ * @param {string} toolName
+ * @returns {string|null}
+ */
+export function getToolFile(toolName) {
+  const entry = TOOL_REGISTRY[toolName];
+  return entry ? entry.file : null;
+}
+
+/**
+ * Get detection files for a tool.
+ * @param {string} toolName
+ * @returns {string[]}
+ */
+export function getToolDetectionFiles(toolName) {
+  const entry = TOOL_REGISTRY[toolName];
+  return entry ? entry.detectionFiles : [];
+}
+
+/**
+ * Get all detection signatures across all tools (for detect-tool scan).
+ * Returns array of { tool, file } pairs.
+ * @returns {Array<{tool: string, file: string}>}
+ */
+export function getAllDetectionSignatures() {
+  const sigs = [];
+  for (const [tool, entry] of Object.entries(TOOL_REGISTRY)) {
+    for (const file of entry.detectionFiles) {
+      sigs.push({ tool, file });
+    }
+  }
+  return sigs;
+}

package/cli/lib/validate-schema.mjs

@@ -0,0 +1,131 @@
+/**
+ * validate-schema — Lightweight JSON-schema validator (no external deps).
+ *
+ * Supports the subset of JSON Schema draft-07 used by this project's schemas:
+ *   - type (string, number, integer, boolean, array, object, null)
+ *   - type as union array (e.g. ["string", "null"])
+ *   - required (array of property names)
+ *   - enum (array of allowed values)
+ *   - properties (nested object schema)
+ *   - items (schema for array elements)
+ *   - minimum (number)
+ *
+ * Intentionally minimal — not a general-purpose validator. Schemas live in
+ * /schema at the project root and are loaded by absolute path.
+ *
+ * Usage:
+ *   import { validateAgainstSchema } from './validate-schema.mjs';
+ *   const result = validateAgainstSchema(obj, '/path/to/schema.json');
+ *   if (!result.ok) console.error(result.errors);
+ */
+import { readFileSync } from 'node:fs';
+
+// Cache loaded schemas by path to avoid re-reading on every load.
+const schemaCache = new Map();
+
+/**
+ * Load a JSON schema from disk (cached).
+ * @param {string} schemaPath — absolute path to the .schema.json file
+ * @returns {object|null}
+ */
+function loadSchema(schemaPath) {
+  if (schemaCache.has(schemaPath)) {
+    return schemaCache.get(schemaPath);
+  }
+  try {
+    const raw = readFileSync(schemaPath, 'utf-8');
+    const schema = JSON.parse(raw);
+    schemaCache.set(schemaPath, schema);
+    return schema;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check a value against a single type string.
+ * @param {*} value
+ * @param {string} type
+ * @returns {boolean}
+ */
+function matchesType(value, type) {
+  switch (type) {
+    case 'string':  return typeof value === 'string';
+    case 'number':  return typeof value === 'number' && !Number.isNaN(value);
+    case 'integer': return typeof value === 'number' && Number.isInteger(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'array':   return Array.isArray(value);
+    case 'object':  return typeof value === 'object' && value !== null && !Array.isArray(value);
+    case 'null':    return value === null;
+    default:        return true; // unknown types pass (forward-compat)
+  }
+}
+
+/**
+ * Validate a value against a schema node, collecting errors.
+ * @param {*} value
+ * @param {object} schema
+ * @param {string} path — dotted path for error messages (e.g. "root.gates.enabled")
+ * @param {string[]} errors — accumulator
+ */
+function validateNode(value, schema, path, errors) {
+  // type
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const ok = types.some((t) => matchesType(value, t));
+    if (!ok) {
+      errors.push(`${path}: expected type ${types.join('|')}, got ${Array.isArray(value) ? 'array' : typeof value}`);
+      return; // no point checking further on a type mismatch
+    }
+  }
+
+  // enum
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path}: value "${value}" not in enum [${schema.enum.join(', ')}]`);
+  }
+
+  // minimum
+  if (schema.minimum !== undefined && typeof value === 'number' && value < schema.minimum) {
+    errors.push(`${path}: value ${value} below minimum ${schema.minimum}`);
+  }
+
+  // object properties + required
+  if (matchesType(value, 'object') && schema.properties) {
+    if (schema.required) {
+      for (const req of schema.required) {
+        if (!(req in value)) {
+          errors.push(`${path}: missing required property "${req}"`);
+        }
+      }
+    }
+    for (const [key, subSchema] of Object.entries(schema.properties)) {
+      if (key in value) {
+        validateNode(value[key], subSchema, `${path}.${key}`, errors);
+      }
+    }
+  }
+
+  // array items
+  if (matchesType(value, 'array') && schema.items) {
+    for (let i = 0; i < value.length; i++) {
+      validateNode(value[i], schema.items, `${path}[${i}]`, errors);
+    }
+  }
+}
+
+/**
+ * Validate an object against a JSON schema loaded from disk.
+ * @param {object} obj — the value to validate
+ * @param {string} schemaPath — absolute path to the schema file
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateAgainstSchema(obj, schemaPath) {
+  const schema = loadSchema(schemaPath);
+  if (!schema) {
+    // Schema missing/unreadable — fail open (don't block on missing schema).
+    return { ok: true, errors: [] };
+  }
+  const errors = [];
+  validateNode(obj, schema, 'config', errors);
+  return { ok: errors.length === 0, errors };
+}

package/cli/lib/vars.mjs

@@ -0,0 +1,114 @@
+/**
+ * vars — Stack-aware variable loader.
+ *
+ * Loads stack metadata from stacks.json and returns a flat variable map
+ * suitable for {{VAR}} substitution in templates.
+ *
+ * Usage:
+ *   import { getStackVars } from './vars.mjs';
+ *   const vars = getStackVars('python');
+ *   // → { stack: 'python', testCmd: 'python3 -m pytest', ... }
+ */
+
+import { readFileSync } from 'node:fs';
+import { STACKS_SCHEMA_PATH } from './paths.mjs';
+import { loadConfig } from './state.mjs';
+
+const STACKS_PATH = STACKS_SCHEMA_PATH;
+
+/** @type {Record<string, object>|null} */
+let _stacksCache = null;
+
+/**
+ * Load and cache the stacks schema.
+ * @returns {Record<string, object>}
+ */
+function loadStacks() {
+  if (_stacksCache) {return _stacksCache;}
+  const raw = readFileSync(STACKS_PATH, 'utf-8');
+  _stacksCache = JSON.parse(raw);
+  return _stacksCache;
+}
+
+/**
+ * Fields in stacks.json that carry through as template variables.
+ * Ordered for deterministic output.
+ */
+const VAR_FIELDS = [
+  'label',
+  'testCmd',
+  'lintCmd',
+  'typeCheckCmd',
+  'buildCmd',
+  'installCmd',
+  'versionFile',
+  'configFile',
+];
+
+/**
+ * Get template variables for a given stack.
+ *
+ * @param {string} stackName — stack name (built-in or custom)
+ * @param {object} [overrides] — optional extra variables to merge in (e.g. agent-provided settings)
+ * @param {string} [targetDir] — optional project dir (enables config.stackMeta override)
+ * @returns {Record<string, string>}
+ */
+export function getStackVars(stackName, overrides = {}, targetDir) {
+  const meta = getEffectiveStackMeta(stackName, targetDir);
+
+  const vars = {
+    stack: stackName,
+    stackLabel: meta.label || stackName,
+  };
+
+  for (const field of VAR_FIELDS) {
+    vars[field] = (meta[field] || '').toString();
+  }
+
+  // Merge overrides (overwrites any computed vars)
+  Object.assign(vars, overrides);
+
+  return vars;
+}
+
+/**
+ * Get effective stack metadata: config.stackMeta overrides built-in stacks.json.
+ * Priority: config.stackMeta > built-in stacks.json[stackName] > generic fallback.
+ * @param {string} stackName
+ * @param {string} [targetDir] — project dir to read config from
+ * @returns {object}
+ */
+export function getEffectiveStackMeta(stackName, targetDir) {
+  const stacks = loadStacks();
+  const builtIn = stacks[stackName] || stacks.generic || {};
+
+  // If targetDir given, check config.stackMeta for user/agent overrides
+  if (targetDir) {
+    try {
+      const { config, ok } = loadConfig(targetDir);
+      if (ok && config.stackMeta && typeof config.stackMeta === 'object') {
+        return { ...builtIn, ...config.stackMeta };
+      }
+    } catch {
+      // config unreadable — use built-in
+    }
+  }
+
+  return builtIn;
+}
+
+/**
+ * List all available stack names.
+ * @returns {string[]}
+ */
+export function listStacks() {
+  const stacks = loadStacks();
+  return Object.keys(stacks).sort();
+}
+
+/**
+ * Reset internal cache (for testing).
+ */
+export function _resetCache() {
+  _stacksCache = null;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "dev-harness-cli",
+  "version": "1.0.0",
+  "description": "Agent-agnostic software development harness CLI — scaffold, phase orchestration, gate validation for any coding agent",
+  "type": "module",
+  "bin": {
+    "harness-dev": "./cli/harness-dev.mjs"
+  },
+  "files": [
+    "cli/",
+    "templates/",
+    "schema/",
+    "adapters/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "Bakr Bagaber",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bakr-bagaber/dev-harness"
+  },
+  "homepage": "https://github.com/bakr-bagaber/dev-harness#readme",
+  "bugs": {
+    "url": "https://github.com/bakr-bagaber/dev-harness/issues"
+  },
+  "keywords": [
+    "harness",
+    "developer-tools",
+    "ai-agents",
+    "phase-pipeline",
+    "gate-validation",
+    "scaffold",
+    "cli"
+  ],
+  "scripts": {
+    "check": "node --check cli/harness-dev.mjs && echo 'Syntax OK'",
+    "postinstall": "node -e \"try{process.stdout.write('harness-dev installed. Run: npx harness-dev --help\\n')}catch(e){}\""
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/harness-config.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Harness Config",
+  "description": "Schema for harness-config.json — project state, phase tracking, and agent configuration",
+  "type": "object",
+  "required": ["version", "mode", "currentPhase", "gates", "git", "phases", "maxRetries"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version (not CLI version)",
+      "default": "1.0"
+    },
+    "stack": {
+      "type": ["string", "null"],
+      "description": "Detected or explicitly set project stack"
+    },
+    "stackMeta": {
+      "type": ["object", "null"],
+      "description": "User/agent-supplied stack metadata (overrides built-in stacks.json). Filled during DEFINE phase for custom/unknown stacks.",
+      "properties": {
+        "label": { "type": "string" },
+        "testCmd": { "type": "string" },
+        "lintCmd": { "type": "string" },
+        "typeCheckCmd": { "type": "string" },
+        "buildCmd": { "type": "string" },
+        "installCmd": { "type": "string" },
+        "coverageCmd": { "type": "string" },
+        "versionFile": { "type": "string" },
+        "configFile": { "type": "string" },
+        "extensions": { "type": "array", "items": { "type": "string" } },
+        "detectFiles": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "agentTool": {
+      "type": ["string", "null"],
+      "enum": [null, "generic", "claude-code", "codex", "cursor", "windsurf", "gemini", "copilot", "cline", "roo", "kilo-code", "aider", "continue", "opencode", "amazon-q", "antigravity", "openclaw", "pi", "hermes"],
+      "default": null,
+      "description": "Which agentic coding tool the project uses (null = unspecified, tools auto-detect via AGENTS.md)"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["copilot", "autopilot"],
+      "default": "copilot",
+      "description": "Execution mode"
+    },
+    "currentPhase": {
+      "type": ["string", "null"],
+      "enum": [null, "init", "define", "plan", "build", "verify", "simplify", "review", "ship"],
+      "default": null,
+      "description": "Current pipeline phase"
+    },
+    "paused": {
+      "type": "boolean",
+      "default": false,
+      "description": "Autopilot paused state"
+    },
+    "features": {
+      "type": "object",
+      "properties": {
+        "remaining": { "type": "integer", "minimum": 0, "default": 0 },
+        "passing": { "type": "integer", "minimum": 0, "default": 0 },
+        "total": { "type": "integer", "minimum": 0, "default": 0 }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "checks": { "type": "array", "items": { "type": "string" }, "default": ["all"] }
+      }
+    },
+    "git": {
+      "type": "object",
+      "properties": {
+        "autoCommit": { "type": "boolean", "default": false },
+        "autoTag": { "type": "boolean", "default": false },
+        "resetOnRetry": { "type": "boolean", "default": false },
+        "branch": { "type": ["string", "null"], "default": null },
+        "clean": { "type": "boolean", "default": true },
+        "hasUpstream": { "type": "boolean", "default": false },
+        "lastCommitMessage": { "type": ["string", "null"], "default": null }
+      }
+    },
+    "phases": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["define", "plan", "build", "verify", "review", "ship"]
+        }
+      }
+    },
+    "agents": {
+      "type": "object",
+      "properties": {
+        "tone": {
+          "type": "object",
+          "properties": {
+            "planner": { "type": "string", "default": "Analytical and precise. Define clear boundaries." },
+            "generator": { "type": "string", "default": "Focused and practical. Build what's specified, nothing more." },
+            "evaluator": { "type": "string", "default": "Skeptical and thorough. Accept only compelling evidence." },
+            "simplifier": { "type": "string", "default": "Relentless about clarity. Delete more than you add." }
+          }
+        }
+      }
+    },
+    "maxRetries": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 3
+    },
+    "gateHistory": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "phase": { "type": "string" },
+          "result": { "type": "string", "enum": ["pass", "fail"] },
+          "timestamp": { "type": "string" }
+        }
+      },
+      "default": []
+    }
+  }
+}