create-harness-vibe-coding 0.8.17 → 0.8.19

package/templates/common/Harness/scripts/README.md

@@ -0,0 +1,134 @@
+# Harness Scripts
+
+Agents: use `task-state.mjs` for all task lifecycle operations. Other scripts are purpose-built tools invoked on demand.
+
+## Task Lifecycle (primary)
+
+### `task-state.mjs`
+
+Single entry point for all task capsule operations. Use this for any task CRUD.
+
+```bash
+# Active tasks
+node Harness/scripts/task-state.mjs list [--json]
+node Harness/scripts/task-state.mjs open [--json]
+node Harness/scripts/task-state.mjs validate [--strict] [--json]
+node Harness/scripts/task-state.mjs reconcile [--dry-run|--apply] [--json]
+node Harness/scripts/task-state.mjs set-active <task-id>
+node Harness/scripts/task-state.mjs transition <task-id> --status <s> --phase <p>
+
+# Task creation
+node Harness/scripts/task-state.mjs record <task-id> --create --text "goal" [--status <s>] [--dry-run|--apply]
+node Harness/scripts/task-state.mjs record --title "title" --note "note"  # auto-generates ID
+
+# Archive (moves completed tasks to _archive/YYYY/MM/DD/)
+node Harness/scripts/task-state.mjs archive [--dry-run|--apply] [--keep n] [--task id] [--json]
+
+# History (archived task management)
+node Harness/scripts/task-state.mjs history list [--year YYYY] [--month MM] [--json]
+node Harness/scripts/task-state.mjs history search <keyword> [--json]
+node Harness/scripts/task-state.mjs history load <task-id> [--json]
+node Harness/scripts/task-state.mjs history delete <task-id> [--dry-run|--apply] [--json]
+```
+
+**When to use:**
+- `/wf-task-list` calls `task-state.mjs list`
+- `/wf-task-archive` calls `task-state.mjs archive`
+- `/wf-task-record` calls `task-state.mjs record`
+- Resume: check `task-state.mjs open` for blocked/open tasks
+- Closeout: run `task-state.mjs archive --apply` to clean up verified tasks
+- Debug: run `task-state.mjs validate --strict` to check state integrity
+- Research: run `task-state.mjs history search <keyword>` to find past solutions
+
+### `archive-tasks.mjs`
+
+Compatibility alias for `task-state.mjs archive`. Delegates all flags.
+
+## Validation
+
+### `validate-harness.mjs`
+
+Validates harness structure, task state, file integrity.
+
+```bash
+node Harness/scripts/validate-harness.mjs [--strict] [--json]
+```
+
+**When to use:** pre-commit checks, CI gates, release validation. Strict mode fails on any violation.
+
+## Maintenance
+
+### `wf-remove.mjs`
+
+Safely removes the Harness scaffold from a project.
+
+```bash
+node Harness/scripts/wf-remove.mjs [--dry-run|--apply] [--json]
+```
+
+**When to use:** uninstalling Harness, cleaning up test installs. Always dry-run first.
+
+### `wf-update-check.mjs`
+
+Checks if a newer Harness version is available.
+
+```bash
+node Harness/scripts/wf-update-check.mjs [--json]
+```
+
+**When to use:** `/wf-update` command, periodic drift detection.
+
+### `wf-auto-update-prompt.mjs`
+
+Generates context-aware update prompts for WF-AUTO cycles.
+
+```bash
+node Harness/scripts/wf-auto-update-prompt.mjs
+```
+
+**When to use:** internally by WF-AUTO/WF-AUTO-SPARK cycles. Not invoked directly.
+
+### `scan-clean.mjs`
+
+Scans and cleans stale artifacts, temp files, orphaned references.
+
+```bash
+node Harness/scripts/scan-clean.mjs [--dry-run|--apply] [--json]
+```
+
+**When to use:** before releases, after large refactors, periodic housekeeping.
+
+## Telemetry
+
+### `l2-cache-telemetry.mjs`
+
+Measures prompt-cache hit rates across CLI runtimes (Claude Code, Codex, OpenCode).
+
+```bash
+node Harness/scripts/l2-cache-telemetry.mjs --groups <g1>,<g2> --turns <n> [--json]
+```
+
+**When to use:** benchmarking cache performance, tuning context loading, regression detection.
+
+### `context-budget.mjs`
+
+Estimates context budget usage for a given task or workflow tier.
+
+```bash
+node Harness/scripts/context-budget.mjs [--tier wf-light|wf-standard|wf-full|wf-max]
+```
+
+**When to use:** before large workflows, capacity planning, timeout risk assessment.
+
+## Agent Quick Reference
+
+| Goal | Command |
+|------|---------|
+| List active tasks + graph | `node Harness/scripts/task-state.mjs list` |
+| Find blocked tasks | `node Harness/scripts/task-state.mjs open --json` |
+| Create new task | `node Harness/scripts/task-state.mjs record --title "..." --note "..." --apply` |
+| Archive completed tasks | `node Harness/scripts/task-state.mjs archive --apply` |
+| Search history for "timeout" | `node Harness/scripts/task-state.mjs history search timeout --json` |
+| Load old task full record | `node Harness/scripts/task-state.mjs history load <task-id> --json` |
+| Validate state integrity | `node Harness/scripts/validate-harness.mjs --strict` |
+| Pre-release cleanup | `node Harness/scripts/scan-clean.mjs --dry-run` |

package/templates/common/Harness/scripts/a2a-terminal.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+
+const MAX_LIMIT = 2000;
+
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  const flags = {};
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (!arg.startsWith('--')) continue;
+    const key = arg.slice(2);
+    const value = rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[++i] : 'true';
+    flags[key] = value;
+  }
+  return { command, flags };
+}
+
+function validId(id) {
+  return typeof id === 'string' && /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
+function readJson(filePath, fallback = null) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readJsonl(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    return fs.readFileSync(filePath, 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function appendJsonl(filePath, row) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(row)}\n`, 'utf8');
+}
+
+function allSessionDirs(projectRoot) {
+  const tasksRoot = path.join(projectRoot, 'Harness', 'tasks');
+  let tasks = [];
+  try { tasks = fs.readdirSync(tasksRoot, { withFileTypes: true }); } catch { return []; }
+  const out = [];
+  for (const task of tasks) {
+    if (!task.isDirectory() || task.name.startsWith('_')) continue;
+    const sessionsRoot = path.join(tasksRoot, task.name, 'sessions');
+    let sessions = [];
+    try { sessions = fs.readdirSync(sessionsRoot, { withFileTypes: true }); } catch { continue; }
+    for (const session of sessions) {
+      if (session.isDirectory()) out.push({ taskId: task.name, sessionId: session.name, dir: path.join(sessionsRoot, session.name) });
+    }
+  }
+  return out;
+}
+
+function findSession(projectRoot, sessionId) {
+  if (!validId(sessionId)) return null;
+  return allSessionDirs(projectRoot).find((session) => session.sessionId === sessionId) || null;
+}
+
+function globToRegex(pattern) {
+  const escaped = String(pattern || '**/*')
+    .replace(/\\/g, '/')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '::DOUBLE_STAR::')
+    .replace(/\*/g, '[^/]*')
+    .replace(/::DOUBLE_STAR::/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function print(data) {
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+
+function listSessions(projectRoot) {
+  return allSessionDirs(projectRoot)
+    .map(({ dir }) => readJson(path.join(dir, 'STATE.json')))
+    .filter(Boolean)
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
+}
+
+function readRange(projectRoot, flags) {
+  const found = findSession(projectRoot, flags.session);
+  if (!found) return { sessionId: flags.session, entries: [] };
+  let entries = readJsonl(path.join(found.dir, 'terminal.jsonl'));
+  const from = Number(flags.from);
+  const to = Number(flags.to);
+  const tail = Number(flags.tail);
+  if (Number.isFinite(from)) entries = entries.filter((entry) => entry.seq >= from);
+  if (Number.isFinite(to)) entries = entries.filter((entry) => entry.seq <= to);
+  if (Number.isFinite(tail) && tail > 0) entries = entries.slice(-Math.min(tail, MAX_LIMIT));
+  else entries = entries.slice(0, MAX_LIMIT);
+  return { taskId: found.taskId, sessionId: found.sessionId, entries };
+}
+
+function globEvents(projectRoot, flags) {
+  const regex = globToRegex(flags.pattern || flags.glob || '**/*');
+  const limit = Math.min(Math.max(Number(flags.limit) || 200, 1), MAX_LIMIT);
+  const sinceMs = flags.since ? new Date(flags.since).getTime() : null;
+  const rows = [];
+  for (const session of allSessionDirs(projectRoot)) {
+    for (const filename of ['events.jsonl', 'terminal.jsonl', 'input-requests.jsonl']) {
+      const rel = `Harness/tasks/${session.taskId}/sessions/${session.sessionId}/${filename}`;
+      if (!regex.test(rel)) continue;
+      for (const row of readJsonl(path.join(session.dir, filename))) {
+        const tsMs = row.ts ? new Date(row.ts).getTime() : 0;
+        if (sinceMs && tsMs < sinceMs) continue;
+        rows.push({ source: rel, ...row });
+      }
+    }
+  }
+  return rows.sort((a, b) => String(a.ts || '').localeCompare(String(b.ts || ''))).slice(-limit);
+}
+
+function postInput(urlText, token, sessionId, text) {
+  return new Promise((resolve, reject) => {
+    const base = new URL(urlText);
+    const body = JSON.stringify({ data: text });
+    const req = http.request({
+      hostname: base.hostname,
+      port: base.port,
+      path: `/api/sessions/${encodeURIComponent(sessionId)}/input`,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        Authorization: `Bearer ${token}`,
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => {
+        try { resolve({ status: res.statusCode, body: JSON.parse(data) }); }
+        catch { resolve({ status: res.statusCode, body: data }); }
+      });
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+async function sendInput(projectRoot, flags) {
+  const sessionId = flags.session;
+  const text = flags.text || '';
+  const url = flags.url || process.env.WF_UI_URL;
+  const token = flags.token || process.env.WF_UI_TOKEN;
+  if (url && token) return postInput(url, token, sessionId, text);
+
+  const found = findSession(projectRoot, sessionId);
+  if (!found) throw new Error(`Session not found: ${sessionId}`);
+  const state = readJson(path.join(found.dir, 'STATE.json'));
+  if (!state?.attachMode) throw new Error('Input rejected: session is in watch mode. Enable attach mode first.');
+  const row = {
+    ts: new Date().toISOString(),
+    type: 'terminal.input.requested',
+    taskId: found.taskId,
+    sessionId,
+    data: text,
+  };
+  appendJsonl(path.join(found.dir, 'input-requests.jsonl'), row);
+  return { queued: true, ...row };
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  const projectRoot = path.resolve(flags.project || process.cwd());
+  if (command === 'list-sessions') return print(listSessions(projectRoot));
+  if (command === 'read-range') return print(readRange(projectRoot, flags));
+  if (command === 'tail') return print(readRange(projectRoot, { ...flags, tail: flags.lines || flags.tail || 100 }));
+  if (command === 'glob-events') return print(globEvents(projectRoot, flags));
+  if (command === 'send-input') return print(await sendInput(projectRoot, flags));
+  throw new Error('Usage: a2a-terminal.mjs list-sessions|read-range|tail|glob-events|send-input [--project .]');
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(1);
+});

package/templates/common/Harness/scripts/context-budget.mjs

@@ -20,7 +20,7 @@ const routes = [
   },
   {
     id: 'wf-router-prefix',
-    maxBytes: 42000,
+    maxBytes: 43000,
     paths: [
       'CLAUDE.md',
       'Harness/MEMORY.md',

package/templates/common/Harness/scripts/sync-host-global.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+
+function readFlagValue(flagName) {
+  const idx = args.indexOf(flagName);
+  if (idx === -1) return null;
+  const value = args[idx + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+const ROOT = path.resolve(process.env.WF_ROOT || readFlagValue('--root') || path.resolve(__dirname, '..', '..'));
+const VERSION_FILE = path.join(ROOT, 'Harness', '.harness-version');
+const APPLY = args.includes('--apply');
+const JSON_OUT = args.includes('--json');
+const DRY_RUN = args.includes('--dry-run') || (!APPLY && !args.includes('--apply'));
+
+const HARNESS_MARKERS = [
+  /\bcreate-harness-vibe-coding\b/i,
+  /\bproject harness\b/i,
+  /\bHarness\/(?:specs|WF|MEMORY|tasks|scripts|subagents|dispatch|context-loading|lifecycle|SETUP)\b/,
+  /\bWF-(?:MAX|AUTO|KERNEL|STATE)\b/,
+  /^harness:\s*(?:wf-agent|wf-framework|create-harness-vibe-coding)\b/im,
+];
+
+function normalizePath(value) {
+  return String(value || '').replace(/\\/g, '/');
+}
+
+function sha256(content) {
+  return 'sha256-' + createHash('sha256').update(content).digest('hex');
+}
+
+function readNormalized(filePath) {
+  return fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+}
+
+function sha256File(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return sha256(readNormalized(filePath));
+}
+
+function containsPath(parent, child) {
+  const resolvedParent = path.resolve(parent);
+  const resolvedChild = path.resolve(child);
+  const rel = path.relative(resolvedParent, resolvedChild);
+  return rel === '' || (rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function resolveUnder(base, rel) {
+  if (!rel || typeof rel !== 'string' || path.isAbsolute(rel)) return null;
+  const parts = normalizePath(rel).split('/').filter(Boolean);
+  if (parts.some(part => part === '..')) return null;
+  const resolved = path.resolve(base, ...parts);
+  return containsPath(base, resolved) ? resolved : null;
+}
+
+function sourceDestForHostFile(host, file) {
+  const normalized = normalizePath(file);
+  if (host === 'claude') {
+    if (normalized === 'settings.json') return '.claude/settings.json';
+    if (/^(commands|skills|agents|rules)\//.test(normalized)) return `.claude/${normalized}`;
+  }
+  if (host === 'codex') {
+    if (normalized === 'config.toml') return '.codex/config.toml';
+    if (normalized === 'hooks.json') return '.codex/hooks.json';
+    if (normalized.startsWith('skills/')) return `.agents/${normalized}`;
+  }
+  if (host === 'opencode') {
+    if (normalized === 'opencode.json') return 'opencode.json';
+    if (/^(commands|agents|plugins)\//.test(normalized)) return `.opencode/${normalized}`;
+  }
+  return null;
+}
+
+function hasHarnessMarker(filePath) {
+  try {
+    const body = fs.readFileSync(filePath, 'utf8');
+    return HARNESS_MARKERS.some(marker => marker.test(body));
+  } catch {
+    return false;
+  }
+}
+
+function readVersion() {
+  if (!fs.existsSync(VERSION_FILE)) {
+    throw new Error(`Harness/.harness-version not found under ${ROOT}`);
+  }
+  return JSON.parse(fs.readFileSync(VERSION_FILE, 'utf8'));
+}
+
+function hostTargets(version) {
+  const hostGlobal = version?.hostGlobal;
+  if (!hostGlobal || hostGlobal.copyMode !== 'copy' || !hostGlobal.targets || typeof hostGlobal.targets !== 'object') {
+    return null;
+  }
+  return hostGlobal.targets;
+}
+
+function summarize(plan) {
+  return {
+    created: plan.created.length,
+    updated: plan.updated.length,
+    conflict: plan.conflict.length,
+    skipped: plan.skipped.length,
+    errors: plan.errors.length,
+  };
+}
+
+function createPlan(version) {
+  const targets = hostTargets(version);
+  const plan = {
+    root: normalizePath(ROOT),
+    installScope: version?.installScope || 'project',
+    created: [],
+    updated: [],
+    conflict: [],
+    skipped: [],
+    errors: [],
+  };
+
+  if (version?.installScope !== 'global') {
+    plan.skipped.push({ reason: 'not a global install' });
+    return plan;
+  }
+  if (!targets) {
+    plan.errors.push({ reason: 'Harness/.harness-version missing hostGlobal copy targets' });
+    return plan;
+  }
+
+  for (const [host, target] of Object.entries(targets)) {
+    const hostRoot = target && typeof target.root === 'string'
+      ? path.resolve(target.root)
+      : null;
+    const files = Array.isArray(target?.files) ? target.files : [];
+    if (!hostRoot) {
+      plan.errors.push({ host, reason: 'missing host root' });
+      continue;
+    }
+    for (const file of files) {
+      const sourceDest = sourceDestForHostFile(host, file);
+      const sourcePath = sourceDest ? resolveUnder(ROOT, sourceDest) : null;
+      const targetPath = resolveUnder(hostRoot, file);
+      if (!sourceDest || !sourcePath) {
+        plan.errors.push({ host, file, reason: 'unknown host-global source mapping' });
+        continue;
+      }
+      if (!targetPath) {
+        plan.errors.push({ host, file, source: sourceDest, reason: 'invalid host-global target path' });
+        continue;
+      }
+      if (!fs.existsSync(sourcePath)) {
+        plan.errors.push({ host, file, source: sourceDest, reason: 'missing runtime source file' });
+        continue;
+      }
+      if (fs.existsSync(targetPath)) {
+        const stat = fs.lstatSync(targetPath);
+        if (stat.isSymbolicLink()) {
+          plan.errors.push({ host, file, source: sourceDest, reason: 'target is symlink' });
+          continue;
+        }
+        if (!stat.isFile()) {
+          plan.errors.push({ host, file, source: sourceDest, reason: 'target is not a regular file' });
+          continue;
+        }
+      }
+
+      const sourceHash = sha256File(sourcePath);
+      const targetHash = sha256File(targetPath);
+      const entry = { host, file, source: sourceDest, targetRoot: normalizePath(hostRoot), sourceHash, targetHash };
+      if (!targetHash) {
+        plan.created.push({ ...entry, reason: 'missing host-global copy' });
+      } else if (targetHash === sourceHash) {
+        plan.skipped.push({ ...entry, reason: 'already current' });
+      } else if (hasHarnessMarker(targetPath)) {
+        plan.updated.push({ ...entry, reason: 'stale Harness-marked host-global copy' });
+      } else {
+        plan.conflict.push({ ...entry, reason: 'existing host-global file lacks Harness ownership marker' });
+      }
+    }
+  }
+
+  return plan;
+}
+
+function applyPlan(plan) {
+  const written = [];
+  for (const entry of [...plan.created, ...plan.updated]) {
+    const sourcePath = resolveUnder(ROOT, entry.source);
+    const targetPath = resolveUnder(entry.targetRoot, entry.file);
+    if (!sourcePath || !targetPath) {
+      plan.errors.push({ ...entry, reason: 'path resolution failed during apply' });
+      continue;
+    }
+    if (fs.existsSync(targetPath) && fs.lstatSync(targetPath).isSymbolicLink()) {
+      plan.errors.push({ ...entry, reason: 'target became symlink during apply' });
+      continue;
+    }
+    const content = readNormalized(sourcePath);
+    if (sha256(content) !== entry.sourceHash) {
+      plan.errors.push({ ...entry, reason: 'runtime source changed during apply' });
+      continue;
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, content, 'utf8');
+    written.push({ host: entry.host, file: entry.file, source: entry.source });
+  }
+  return written;
+}
+
+function printResult(result) {
+  if (JSON_OUT) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.status === 'not-global') {
+    console.log('Host-global sync skipped: installScope is not global.');
+    return;
+  }
+  console.log(`Host-global sync ${result.status}: ${result.summary.created} created, ${result.summary.updated} updated, ${result.summary.conflict} conflict, ${result.summary.errors} error.`);
+  if (result.plan?.conflict?.length) {
+    for (const entry of result.plan.conflict) {
+      console.log(`  conflict ${entry.host}:${entry.file} (${entry.reason})`);
+    }
+  }
+  if (result.plan?.errors?.length) {
+    for (const entry of result.plan.errors) {
+      console.log(`  error ${entry.host || 'host'}:${entry.file || ''} ${entry.reason}`);
+    }
+  }
+}
+
+function main() {
+  let version;
+  try {
+    version = readVersion();
+  } catch (err) {
+    const result = { status: 'error', root: normalizePath(ROOT), message: err.message };
+    printResult(result);
+    process.exitCode = 1;
+    return;
+  }
+
+  const plan = createPlan(version);
+  const summary = summarize(plan);
+  let written = [];
+  if (APPLY && summary.conflict === 0 && summary.errors === 0) {
+    written = applyPlan(plan);
+  }
+  const afterErrors = plan.errors.length;
+  const status = version?.installScope !== 'global'
+    ? 'not-global'
+    : afterErrors > 0
+      ? 'error'
+      : summary.conflict > 0
+        ? 'conflict'
+        : summary.created + summary.updated > 0
+          ? (APPLY ? 'synced' : 'needs-sync')
+          : 'ok';
+  const result = {
+    status,
+    dryRun: DRY_RUN,
+    applied: APPLY && status === 'synced',
+    root: normalizePath(ROOT),
+    summary: summarize(plan),
+    written,
+    plan,
+  };
+  printResult(result);
+  if (!['ok', 'synced', 'not-global'].includes(status)) process.exitCode = 1;
+}
+
+main();