coding-agent-harness 1.0.0

package/scripts/harness.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import {
+  addCapability,
+  buildStatus,
+  doctorUserSkill,
+  installUserSkill,
+  renderDashboard,
+  normalizeLocale,
+  writeDashboardFolder,
+  writeInitFiles,
+} from "./lib/harness-core.mjs";
+
+const args = process.argv.slice(2);
+const command = args.shift() || "help";
+
+function takeFlag(name, fallback = false) {
+  const index = args.indexOf(name);
+  if (index < 0) return fallback;
+  args.splice(index, 1);
+  return true;
+}
+
+function takeOption(name, fallback = "") {
+  const index = args.indexOf(name);
+  if (index < 0) return fallback;
+  const value = args[index + 1] || fallback;
+  args.splice(index, 2);
+  return value;
+}
+
+async function resolveInitLocale(requestedLocale) {
+  if (requestedLocale) return normalizeLocale(requestedLocale);
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return "en-US";
+
+  const prompt = [
+    "Select harness language / 选择初始化语言:",
+    "  1. 中文 (zh-CN)",
+    "  2. English (en-US)",
+    "Language [1/2, default 2]: ",
+  ].join("\n");
+  const reader = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await reader.question(prompt)).trim().toLowerCase();
+    if (["1", "zh", "zh-cn", "cn", "中文"].includes(answer)) return "zh-CN";
+    if (["2", "en", "en-us", "english", "英文", ""].includes(answer)) return "en-US";
+    console.error(`Unknown language selection: ${answer}. Falling back to en-US.`);
+    return "en-US";
+  } finally {
+    reader.close();
+  }
+}
+
+async function confirmUserInstall({ yes = false, dryRun = false, agent = "codex" } = {}) {
+  if (yes || dryRun) return true;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  const reader = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = (await reader.question(`Install Coding Agent Harness into user skill directory for ${agent}? [y/N] `)).trim().toLowerCase();
+    return ["y", "yes"].includes(answer);
+  } finally {
+    reader.close();
+  }
+}
+
+function targetArg() {
+  return args[args.length - 1] && !args[args.length - 1].startsWith("-") ? args[args.length - 1] : ".";
+}
+
+function printHelp() {
+  console.log(`Coding Agent Harness
+
+Usage:
+  harness check [--profile source-package|private-harness|target-project] [target]
+  harness status [--json] [--strict] [target]
+  harness dashboard [--out file.html] [--out-dir folder] [target]
+  harness init [--dry-run] [--locale zh-CN|en-US] [--capabilities core,dashboard] [target]
+  harness add-capability <name> [--dry-run] [--locale zh-CN|en-US] [target]
+  harness install-user [--agent codex|claude|gemini|openclaw|agents|all] [--home dir] [--dry-run] [--force] [--yes]
+  harness doctor-user [--agent codex|claude|gemini|openclaw|agents|all] [--home dir]
+
+If init runs in an interactive terminal and --locale is omitted, it asks for a
+language. Non-interactive init defaults to en-US.
+`);
+}
+
+function exitWithReport(report) {
+  for (const warning of report.warnings || []) console.log(`Warning: ${warning}`);
+  for (const failure of report.failures || []) console.error(`Failure: ${failure}`);
+  process.exit((report.failures || []).length > 0 ? 1 : 0);
+}
+
+if (command === "help" || command === "--help" || command === "-h") {
+  printHelp();
+} else if (command === "check") {
+  const profile = takeOption("--profile", "target-project");
+  const strict = takeFlag("--strict");
+  const target = targetArg();
+  const failures = [];
+  const warnings = [];
+
+  if (profile === "source-package") {
+    for (const required of ["package.json", "scripts/harness.mjs", "scripts/check-harness.mjs", "templates/planning/task_plan.md"]) {
+      if (!fs.existsSync(path.resolve(target, required))) failures.push(`missing source package file: ${required}`);
+    }
+  }
+
+  const status = buildStatus(target, { skipLegacyCheck: profile === "source-package", strictLegacy: strict, strict });
+  failures.push(...status.checkState.details.failures);
+  warnings.push(...status.checkState.details.warnings);
+
+  if (!["source-package", "private-harness", "target-project"].includes(profile)) failures.push(`unknown profile: ${profile}`);
+  if (failures.length === 0) console.log(`Harness check passed (${profile}): ${path.resolve(target)}`);
+  exitWithReport({ failures: [...new Set(failures)], warnings: [...new Set(warnings)] });
+} else if (command === "status") {
+  const json = takeFlag("--json");
+  const strict = takeFlag("--strict");
+  const status = buildStatus(targetArg(), { strictLegacy: strict, strict });
+  if (json) {
+    console.log(JSON.stringify(status, null, 2));
+  } else {
+    console.log(`${status.project.name}: ${status.checkState.status} (${status.checkState.failures} failures, ${status.checkState.warnings} warnings)`);
+    console.log(`mode: ${status.mode}`);
+    console.log(`capabilities: ${status.capabilities.map((capability) => `${capability.name}:${capability.state}`).join(", ")}`);
+    console.log(`tasks: ${status.tasks.length}`);
+  }
+  process.exit(status.checkState.status === "fail" ? 1 : 0);
+} else if (command === "dashboard") {
+  const out = takeOption("--out", "harness-dashboard.html");
+  const outDir = takeOption("--out-dir", "");
+  if (outDir) {
+    console.log(writeDashboardFolder(outDir, targetArg()));
+  } else {
+    const status = buildStatus(targetArg());
+    const html = renderDashboard(status);
+    fs.mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    fs.writeFileSync(path.resolve(out), html);
+    console.log(path.resolve(out));
+  }
+  process.exit(0);
+} else if (command === "init") {
+  const dryRun = takeFlag("--dry-run");
+  const locale = await resolveInitLocale(takeOption("--locale", ""));
+  const capabilities = takeOption("--capabilities", "core").split(",").map((item) => item.trim()).filter(Boolean);
+  try {
+    const result = writeInitFiles(targetArg(), capabilities, { dryRun, locale });
+    console.log(JSON.stringify({ dryRun, locale: result.locale, capabilities: result.capabilities, changes: result.changes, report: result.report }, null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+} else if (command === "add-capability") {
+  const dryRun = takeFlag("--dry-run");
+  const locale = normalizeLocale(takeOption("--locale", ""));
+  const capability = args.shift();
+  if (!capability) {
+    console.error("Missing capability name");
+    process.exit(2);
+  }
+  try {
+    const result = addCapability(targetArg(), capability, { dryRun, locale });
+    console.log(JSON.stringify({ dryRun, registry: result.registry, changes: result.changes, report: result.report }, null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+} else if (command === "install-user") {
+  const dryRun = takeFlag("--dry-run");
+  const force = takeFlag("--force");
+  const yes = takeFlag("--yes") || takeFlag("-y");
+  takeFlag("--global");
+  const agent = takeOption("--agent", "codex");
+  const home = takeOption("--home", "");
+  if (!(await confirmUserInstall({ yes, dryRun, agent }))) {
+    console.error("Refusing to write user skill files without confirmation. Re-run with --yes or --dry-run.");
+    process.exit(2);
+  }
+  try {
+    console.log(JSON.stringify(installUserSkill({ agent, home, dryRun, force }), null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+} else if (command === "doctor-user") {
+  const agent = takeOption("--agent", "codex");
+  const home = takeOption("--home", "");
+  try {
+    const report = doctorUserSkill({ agent, home });
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(report.status === "pass" ? 0 : 1);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+} else {
+  printHelp();
+  process.exit(2);
+}

package/scripts/lib/dashboard-writer.mjs

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../..");
+const dashboardTemplateRoot = path.join(repoRoot, "templates/dashboard");
+const dashboardMarker = ".harness-dashboard";
+
+export function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function copyDashboardAssets(outDir, options = {}) {
+  copyDirectory(dashboardTemplateRootForLocale(options.locale), outDir);
+}
+
+export function writeDashboardDirectory(outDir, bundle, options = {}) {
+  const target = path.resolve(outDir);
+  assertSafeDashboardTarget(target, options);
+  if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+  copyDashboardAssets(target, options);
+  fs.writeFileSync(path.join(target, dashboardMarker), "generated dashboard directory\n");
+  writeJsonFile(path.join(target, "data/status.json"), bundle.status);
+  writeJsonFile(path.join(target, "data/tables.json"), bundle.tables);
+  writeJsonFile(path.join(target, "data/documents.json"), bundle.documents);
+  writeJsonFile(path.join(target, "data/graph.json"), bundle.graph);
+  writeJsonFile(path.join(target, "data/adoption.json"), bundle.adoption);
+  fs.writeFileSync(
+    path.join(target, "assets/dashboard-data.js"),
+    `window.__HARNESS_DASHBOARD__ = ${JSON.stringify(bundle, null, 2)};\n`,
+  );
+  fs.writeFileSync(
+    path.join(target, "README.md"),
+    [
+      "# Harness Dashboard",
+      "",
+      "This is a read-only static snapshot generated by `harness dashboard --out-dir`.",
+      "Open `index.html` directly in a browser. No target project files are read at browser runtime.",
+      "",
+    ].join("\n"),
+  );
+  return target;
+}
+
+function assertSafeDashboardTarget(target, options) {
+  const localizedDashboardTemplateRoot = dashboardTemplateRootForLocale(options.locale);
+  const protectedRoots = [
+    path.parse(target).root,
+    process.env.HOME,
+    options.repoRoot,
+    options.projectRoot,
+    options.docsRoot,
+    dashboardTemplateRoot,
+    localizedDashboardTemplateRoot,
+  ].filter(Boolean).map((item) => path.resolve(item));
+  if (protectedRoots.includes(target)) {
+    throw new Error(`Refusing unsafe dashboard output directory: ${target}`);
+  }
+  for (const root of [options.docsRoot, dashboardTemplateRoot, localizedDashboardTemplateRoot].filter(Boolean).map((item) => path.resolve(item))) {
+    if (isPathInside(target, root)) {
+      throw new Error(`Refusing dashboard output inside protected directory: ${target}`);
+    }
+  }
+  if (fs.existsSync(target)) {
+    const entries = fs.readdirSync(target);
+    const hasMarker = fs.existsSync(path.join(target, dashboardMarker));
+    if (entries.length > 0 && !hasMarker) {
+      throw new Error(`Refusing to overwrite non-dashboard directory: ${target}`);
+    }
+  }
+}
+
+function dashboardTemplateRootForLocale(locale = "en-US") {
+  const localized = locale === "zh-CN" ? path.join(repoRoot, "templates-zh-CN/dashboard") : dashboardTemplateRoot;
+  return fs.existsSync(localized) ? localized : dashboardTemplateRoot;
+}
+
+function isPathInside(candidate, parent) {
+  const relative = path.relative(parent, candidate);
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function copyDirectory(from, to) {
+  if (!fs.existsSync(from)) throw new Error(`Missing dashboard template directory: ${from}`);
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const source = path.join(from, entry.name);
+    const destination = path.join(to, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(source, destination);
+    } else {
+      fs.copyFileSync(source, destination);
+    }
+  }
+}