@lumi-ai-lab/harness-data 0.0.1

package/README.md

@@ -0,0 +1,9 @@
+# Harness Data npm installer
+
+```bash
+npx @lumi-ai-lab/harness-data install
+npx @lumi-ai-lab/harness-data doctor --dir ~/harness-data
+npx @lumi-ai-lab/harness-data update --dir ~/harness-data
+```
+
+This package is only the installer and updater. The full Harness Data workspace is cloned and maintained outside the npm package.

package/bin/harness-data.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lumi-ai-lab/harness-data",
+  "version": "0.0.1",
+  "description": "Installer and updater for Harness Data",
+  "type": "module",
+  "bin": {
+    "harness-data": "bin/harness-data.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/src/cli.js

@@ -0,0 +1,44 @@
+import { installCommand } from "./commands/install.js";
+import { updateCommand } from "./commands/update.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { versionCommand } from "./commands/version.js";
+
+const commands = new Set(["install", "update", "doctor", "version"]);
+
+function parse(argv) {
+  const args = argv.slice(2);
+  const unknown = Boolean(args[0] && !commands.has(args[0]));
+  const command = commands.has(args[0]) ? args.shift() : "help";
+  const options = { _: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      options._.push(arg);
+      continue;
+    }
+    const [rawKey, inline] = arg.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (["yes", "skipWikisCheck", "check", "json"].includes(key)) {
+      options[key] = inline === undefined ? true : inline !== "false";
+    } else {
+      options[key] = inline ?? args[++i];
+    }
+  }
+  return { command, options, unknown };
+}
+
+export async function main(argv) {
+  const { command, options, unknown } = parse(argv);
+  if (command === "install") return installCommand(options);
+  if (command === "update") return updateCommand(options);
+  if (command === "doctor") return doctorCommand(options);
+  if (command === "version") return versionCommand(options);
+  console.log(`Usage: harness-data <install|update|doctor|version> [options]
+
+Commands:
+  install  Clone/reuse a Harness Data workspace and complete setup
+  update   Check and apply installer, repository, CLI, and wikis updates
+  doctor   Diagnose workspace CLI, config, auth, index, and Agent hooks
+  version  Print installer, repository, wikis, and manifest versions`);
+  if (unknown) process.exitCode = 1;
+}

package/src/commands/doctor.js

@@ -0,0 +1,93 @@
+import fs from "node:fs";
+import path from "node:path";
+import { run } from "../lib/exec.js";
+import { findWorkspaceDir } from "../lib/paths.js";
+import { currentCommit, submoduleCommit } from "../lib/git.js";
+import { validateCasConfigDir } from "../lib/config.js";
+
+function existsExecutable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function agentOk(workspace, name) {
+  const target = path.join(workspace, `.${name}`);
+  const source = path.join(workspace, ".agents", name);
+  if (!fs.existsSync(target) || !fs.existsSync(source)) return false;
+  try {
+    return fs.realpathSync(target) === fs.realpathSync(source);
+  } catch {
+    return false;
+  }
+}
+
+async function tokenCheck(workspace, binary, env) {
+  const file = path.join(workspace, "bin", binary);
+  if (!existsExecutable(file)) return false;
+  const result = await run(file, ["config", "check-token"], { cwd: workspace, env, allowFailure: true });
+  return result.code === 0;
+}
+
+function configPathsValid(workspace) {
+  const file = path.join(workspace, "config", "qdm-cli-paths.env");
+  if (!fs.existsSync(file)) return false;
+  const content = fs.readFileSync(file, "utf8");
+  const matches = [...content.matchAll(/="([^"]+)"/g)].map((match) => match[1]);
+  return matches.length >= 3 && matches.every((entry) => fs.existsSync(entry));
+}
+
+function casCredentialsValid(dir) {
+  try {
+    validateCasConfigDir(dir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function collectDoctor(workspace, options = {}) {
+  const casConfigDir = options.casConfigDir || path.join(workspace, ".qdm-auth", "cas");
+  const env = { QDM_CAS_CONFIG_DIR: casConfigDir };
+  const checks = [];
+  const add = (name, ok, detail = "") => checks.push({ name, ok, detail });
+
+  add("workspace", fs.existsSync(path.join(workspace, "bootstrap", "cli-manifest.json")), workspace);
+  add("wikis submodule", fs.existsSync(path.join(workspace, "wikis", ".git")) || fs.existsSync(path.join(workspace, ".git", "modules", "wikis")));
+  for (const binary of ["data-harness-cli", "qdm-cmr-cli", "qdm-indicators-cli", "cas-cli"]) {
+    add(`bin/${binary}`, existsExecutable(path.join(workspace, "bin", binary)));
+  }
+  add("config/harness-config.yaml", fs.existsSync(path.join(workspace, "config", "harness-config.yaml")));
+  add("config/qdm-cli-paths.env", fs.existsSync(path.join(workspace, "config", "qdm-cli-paths.env")));
+  add("config CLI paths", configPathsValid(workspace));
+  add("CAS credentials", casCredentialsValid(casConfigDir), casConfigDir);
+  add("CMR token", await tokenCheck(workspace, "qdm-cmr-cli", env));
+  add("Indicators token", await tokenCheck(workspace, "qdm-indicators-cli", env));
+  add("wikis index", fs.existsSync(path.join(workspace, ".harness", "index", "wikis-index.json")) || fs.existsSync(path.join(workspace, ".harness", "index", "wikis-runtime-index.json")));
+  add("Agent hook", agentOk(workspace, "claude") || agentOk(workspace, "codex"));
+
+  return {
+    workspace,
+    mainCommit: await currentCommit(workspace),
+    wikisCommit: await submoduleCommit(workspace),
+    checks
+  };
+}
+
+export async function doctorCommand(options = {}) {
+  const workspace = findWorkspaceDir(options.dir);
+  const report = await collectDoctor(workspace, options);
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Harness Data doctor: ${report.workspace}`);
+    for (const check of report.checks) {
+      console.log(`${check.ok ? "PASS" : "FAIL"} ${check.name}${check.detail ? ` (${check.detail})` : ""}`);
+    }
+  }
+  if (report.checks.some((check) => !check.ok)) process.exitCode = 1;
+  return report;
+}

package/src/commands/install.js

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import path from "node:path";
+import { commandExists, run } from "../lib/exec.js";
+import { writeLocalConfig, validateCasConfigDir, linkAgents } from "../lib/config.js";
+import { confirm, chooseAgent } from "../lib/prompt.js";
+import { defaultWorkspaceDir, looksLikeWorkspace, resolveWorkspaceDir, writeState } from "../lib/paths.js";
+import { isGitRepo, currentCommit, submoduleCommit } from "../lib/git.js";
+import { installToolsFromManifest, manifestDigest, readManifest } from "../lib/manifest.js";
+import { platformKey } from "../lib/platform.js";
+import { collectDoctor } from "./doctor.js";
+import { checkUpdates } from "./update.js";
+import { packageVersion } from "../lib/package.js";
+
+const defaultRepo = "https://github.com/lumi-ai-lab/harness-data.git";
+
+async function requireCommands(commands) {
+  for (const command of commands) {
+    if (!(await commandExists(command))) throw new Error(`missing required command: ${command}`);
+  }
+}
+
+async function prepareWorkspace(options) {
+  const target = resolveWorkspaceDir(options.dir || (looksLikeWorkspace(process.cwd()) ? process.cwd() : defaultWorkspaceDir()));
+  const repo = options.repo || defaultRepo;
+  const branch = options.branch || "master";
+  if (!fs.existsSync(target)) {
+    if (!(await confirm(`Clone ${repo} to ${target}?`, { yes: options.yes }))) throw new Error("install cancelled");
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    await run("git", ["clone", "--recurse-submodules", "--branch", branch, repo, target], { stdio: "inherit" });
+    return target;
+  }
+  if (!(await isGitRepo(target)) || !looksLikeWorkspace(target)) {
+    throw new Error(`${target} exists but is not a valid harness-data workspace; pass --dir or move the directory`);
+  }
+  if (!(await confirm(`Reuse existing workspace ${target}?`, { yes: options.yes }))) throw new Error("install cancelled");
+  return target;
+}
+
+async function configureAuth(workspace, options) {
+  const casConfigDir = path.resolve(options.casConfigDir || path.join(workspace, ".qdm-auth", "cas"));
+  fs.mkdirSync(casConfigDir, { recursive: true, mode: 0o700 });
+  const env = { QDM_CAS_CONFIG_DIR: casConfigDir };
+  if (options.casConfigDir) {
+    validateCasConfigDir(casConfigDir);
+  } else if (options.yes) {
+    throw new Error("non-interactive install requires --cas-config-dir with existing CAS credentials");
+  } else {
+    await run(path.join(workspace, "bin", "cas-cli"), ["config", "set-credentials"], { cwd: workspace, env, stdio: "inherit" });
+    validateCasConfigDir(casConfigDir);
+  }
+  await run("sh", ["-c", `"${path.join(workspace, "bin", "qdm-cmr-cli")}" config set-token "$("${path.join(workspace, "bin", "cas-cli")}" token --app cmr)"`], {
+    cwd: workspace,
+    env,
+    stdio: "inherit"
+  });
+  await run("sh", ["-c", `"${path.join(workspace, "bin", "qdm-indicators-cli")}" config set-token "$("${path.join(workspace, "bin", "cas-cli")}" token --app indicators)"`], {
+    cwd: workspace,
+    env,
+    stdio: "inherit"
+  });
+  await run(path.join(workspace, "bin", "qdm-cmr-cli"), ["config", "check-token"], { cwd: workspace, env, stdio: "inherit" });
+  await run(path.join(workspace, "bin", "qdm-indicators-cli"), ["config", "check-token"], { cwd: workspace, env, stdio: "inherit" });
+  return casConfigDir;
+}
+
+async function buildAndCheck(workspace, options) {
+  const cli = path.join(workspace, "bin", "data-harness-cli");
+  await run(cli, ["wikis", "build-index"], { cwd: workspace, stdio: "inherit" });
+  await run(cli, ["context", "--question", "会员复购为什么下降？", "--json"], { cwd: workspace, stdio: "inherit" });
+  let runFullCheck = !options.skipWikisCheck;
+  if (!options.yes && !options.skipWikisCheck) {
+    runFullCheck = await confirm("Run wikis check-all?", { defaultNo: false });
+  }
+  if (runFullCheck) {
+    const result = await run(cli, ["wikis", "check-all"], { cwd: workspace, stdio: "inherit", allowFailure: true });
+    if (result.code !== 0) console.warn("warning: wikis check-all reported issues");
+  } else {
+    console.warn("warning: wikis check-all skipped");
+  }
+}
+
+export async function installCommand(options = {}) {
+  platformKey();
+  await requireCommands(["git", "curl", "tar", "unzip"]);
+  const workspace = await prepareWorkspace(options);
+  const manifestPath = path.resolve(options.manifest || path.join(workspace, "bootstrap", "cli-manifest.json"));
+  if (!(await confirm("Download or refresh CLI binaries?", { yes: options.yes }))) throw new Error("install cancelled");
+  const manifest = await installToolsFromManifest(workspace, manifestPath);
+  const configExists = fs.existsSync(path.join(workspace, "config", "harness-config.yaml")) ||
+    fs.existsSync(path.join(workspace, "config", "qdm-cli-paths.env"));
+  const overwrite = configExists && !options.yes ? await confirm("Overwrite existing local config files?", { defaultNo: true }) : !configExists;
+  if (configExists && !overwrite) {
+    console.log("Reusing existing local config files");
+  } else {
+    writeLocalConfig(workspace, { overwrite: true });
+  }
+  const casConfigDir = await configureAuth(workspace, options);
+  await buildAndCheck(workspace, options);
+  const agent = await chooseAgent(options);
+  linkAgents(workspace, agent);
+  const doctor = await collectDoctor(workspace, { ...options, casConfigDir });
+  for (const check of doctor.checks) console.log(`${check.ok ? "PASS" : "FAIL"} ${check.name}`);
+  if (doctor.checks.some((check) => !check.ok)) throw new Error("doctor failed; install is incomplete");
+  const updates = await checkUpdates(workspace);
+  if (updates.hasUpdates) {
+    console.log(`Updates available. Next step: npx @lumi-ai-lab/harness-data update --dir "${workspace}"`);
+  }
+  writeState(workspace, {
+    mainCommit: await currentCommit(workspace),
+    wikisCommit: await submoduleCommit(workspace),
+    manifestSha256: manifestDigest(manifest),
+    lastCheckAt: new Date().toISOString(),
+    packageVersion: packageVersion()
+  });
+  console.log(`Harness Data installed: ${workspace}`);
+}

package/src/commands/update.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+import { confirm } from "../lib/prompt.js";
+import { findWorkspaceDir, readUserState, writeState } from "../lib/paths.js";
+import { run } from "../lib/exec.js";
+import { installToolsFromManifest, manifestDigest, readManifest } from "../lib/manifest.js";
+import { behindCount, currentCommit, dirtyPaths, submoduleCommit, submodulePointerChanged, submoduleRemoteBehind } from "../lib/git.js";
+import { packageVersion } from "../lib/package.js";
+import { collectDoctor } from "./doctor.js";
+
+async function npmLatest() {
+  try {
+    const response = await fetch("https://registry.npmjs.org/@lumi-ai-lab%2Fharness-data/latest", { signal: AbortSignal.timeout(5000) });
+    if (!response.ok) return "";
+    const data = await response.json();
+    return data.version || "";
+  } catch {
+    return "";
+  }
+}
+
+async function remoteManifest(workspace) {
+  const upstream = (await run("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], { cwd: workspace, allowFailure: true })).stdout.trim();
+  if (!upstream) return null;
+  const result = await run("git", ["show", `${upstream}:bootstrap/cli-manifest.json`], { cwd: workspace, allowFailure: true });
+  if (result.code !== 0 || !result.stdout.trim()) return null;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function versionChanged(current, latest) {
+  return latest && latest !== current;
+}
+
+export async function checkUpdates(workspace) {
+  const manifestPath = path.join(workspace, "bootstrap", "cli-manifest.json");
+  const currentInstaller = packageVersion();
+  const latestInstaller = await npmLatest();
+  const mainBehind = await behindCount(workspace);
+  const wikisBehind = await submoduleRemoteBehind(workspace);
+  const manifest = fs.existsSync(manifestPath) ? readManifest(manifestPath) : { tools: [] };
+  const digest = manifestDigest(manifest);
+  const remote = await remoteManifest(workspace);
+  const remoteDigest = remote ? manifestDigest(remote) : "";
+  const state = readUserState();
+  const updates = {
+    installer: { current: currentInstaller, latest: latestInstaller, update: versionChanged(currentInstaller, latestInstaller) },
+    mainRepo: { behind: mainBehind, update: mainBehind > 0 },
+    wikis: { remoteBehind: wikisBehind, pointerChanged: await submodulePointerChanged(workspace), update: wikisBehind > 0 },
+    cli: {
+      digest,
+      remoteDigest,
+      previousDigest: state.manifestSha256 || "",
+      update: Boolean((state.manifestSha256 && state.manifestSha256 !== digest) || (remoteDigest && remoteDigest !== digest)),
+      tools: manifest.tools || [],
+      remoteTools: remote?.tools || []
+    }
+  };
+  updates.wikis.update = updates.wikis.update || updates.wikis.pointerChanged;
+  updates.hasUpdates = updates.installer.update || updates.mainRepo.update || updates.wikis.update || updates.cli.update;
+  return updates;
+}
+
+function printUpdateSummary(updates) {
+  console.log("Update summary:");
+  console.log(`installer: ${updates.installer.current}${updates.installer.latest ? ` -> ${updates.installer.latest}` : " (latest unavailable)"}`);
+  console.log(`main repo: ${updates.mainRepo.behind} commits behind`);
+  console.log(`wikis: ${updates.wikis.remoteBehind} commits behind remote${updates.wikis.pointerChanged ? ", submodule pointer changed" : ""}`);
+  console.log(`CLI manifest: ${updates.cli.update ? "changed" : "unchanged or first check"}`);
+  const remoteByName = new Map(updates.cli.remoteTools.map((tool) => [tool.name, tool]));
+  for (const tool of updates.cli.tools) {
+    const remote = remoteByName.get(tool.name);
+    const target = remote && remote.version !== tool.version ? ` -> ${remote.version}` : "";
+    console.log(`  ${tool.name} ${tool.version}${target}`);
+  }
+}
+
+export async function updateCommand(options = {}) {
+  const workspace = findWorkspaceDir(options.dir);
+  if (!fs.existsSync(workspace)) throw new Error(`workspace does not exist: ${workspace}`);
+  const mainDirty = await dirtyPaths(workspace);
+  const wikisDirty = fs.existsSync(path.join(workspace, "wikis")) ? await dirtyPaths(path.join(workspace, "wikis")) : [];
+  if (mainDirty.length || wikisDirty.length) {
+    console.error("Dirty worktree detected; update will not overwrite local changes.");
+    for (const line of mainDirty) console.error(`main: ${line}`);
+    for (const line of wikisDirty) console.error(`wikis: ${line}`);
+    process.exitCode = 1;
+    return;
+  }
+  const updates = await checkUpdates(workspace);
+  printUpdateSummary(updates);
+  if (options.check) {
+    writeState(workspace, {
+      mainCommit: await currentCommit(workspace),
+      wikisCommit: await submoduleCommit(workspace),
+      manifestSha256: updates.cli.digest,
+      packageVersion: packageVersion(),
+      lastCheckAt: new Date().toISOString()
+    });
+    return updates;
+  }
+  if (!updates.hasUpdates) {
+    console.log("No repository or wikis updates detected.");
+    writeState(workspace, {
+      mainCommit: await currentCommit(workspace),
+      wikisCommit: await submoduleCommit(workspace),
+      manifestSha256: updates.cli.digest,
+      packageVersion: packageVersion(),
+      lastCheckAt: new Date().toISOString()
+    });
+    return updates;
+  }
+  if (!(await confirm(`Apply updates to ${workspace}?`, { yes: options.yes, defaultNo: true }))) throw new Error("update cancelled");
+  if (updates.mainRepo.update) {
+    await run("git", ["pull", "--ff-only"], { cwd: workspace, stdio: "inherit" });
+  }
+  if (updates.wikis.update || updates.mainRepo.update) {
+    if (!(await confirm("Update wikis submodule? This can change Agent behavior.", { yes: options.yes, defaultNo: true }))) {
+      console.warn("warning: wikis update skipped");
+    } else {
+      await run("git", ["submodule", "update", "--init", "--recursive", "--remote", "wikis"], { cwd: workspace, stdio: "inherit" });
+    }
+  }
+  await installToolsFromManifest(workspace, path.join(workspace, "bootstrap", "cli-manifest.json"));
+  await run(path.join(workspace, "bin", "data-harness-cli"), ["wikis", "build-index"], { cwd: workspace, stdio: "inherit" });
+  const doctor = await collectDoctor(workspace, options);
+  for (const check of doctor.checks) console.log(`${check.ok ? "PASS" : "FAIL"} ${check.name}`);
+  if (doctor.checks.some((check) => !check.ok)) throw new Error("doctor failed after update");
+  writeState(workspace, {
+    mainCommit: await currentCommit(workspace),
+    wikisCommit: await submoduleCommit(workspace),
+    manifestSha256: updates.cli.digest,
+    packageVersion: packageVersion(),
+    lastCheckAt: new Date().toISOString()
+  });
+  console.log(`Harness Data updated: ${workspace}`);
+}

package/src/commands/version.js

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findWorkspaceDir } from "../lib/paths.js";
+import { currentCommit, submoduleCommit } from "../lib/git.js";
+import { readManifest } from "../lib/manifest.js";
+import { packageVersion } from "../lib/package.js";
+
+export async function versionCommand(options = {}) {
+  const workspace = findWorkspaceDir(options.dir);
+  const manifestPath = path.join(workspace, "bootstrap", "cli-manifest.json");
+  const result = {
+    installer: packageVersion(),
+    workspace,
+    mainCommit: fs.existsSync(workspace) ? await currentCommit(workspace) : "",
+    wikisCommit: fs.existsSync(workspace) ? await submoduleCommit(workspace) : "",
+    tools: []
+  };
+  if (fs.existsSync(manifestPath)) {
+    result.tools = (readManifest(manifestPath).tools || []).map((tool) => ({
+      name: tool.name,
+      binary: tool.binary,
+      version: tool.version
+    }));
+  }
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`installer ${result.installer}`);
+    console.log(`workspace ${result.workspace}`);
+    if (result.mainCommit) console.log(`main ${result.mainCommit}`);
+    if (result.wikisCommit) console.log(`wikis ${result.wikisCommit}`);
+    for (const tool of result.tools) console.log(`${tool.name} ${tool.version}`);
+  }
+  return result;
+}

package/src/lib/config.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function writeLocalConfig(workspace, options = {}) {
+  const configDir = path.join(workspace, "config");
+  fs.mkdirSync(configDir, { recursive: true });
+  const harness = path.join(configDir, "harness-config.yaml");
+  const env = path.join(configDir, "qdm-cli-paths.env");
+  if ((fs.existsSync(harness) || fs.existsSync(env)) && !options.overwrite) {
+    throw new Error("local config already exists; rerun interactively and confirm overwrite or remove the files");
+  }
+  const bin = (name) => path.join(workspace, "bin", name).replaceAll("\\", "/");
+  fs.writeFileSync(harness, `paths:\n  spec: wikis/spec\n  playbooks: wikis/playbooks\n  templates: wikis/templates\n\ncli:\n  qdm_cmr_cli: ${bin("qdm-cmr-cli")}\n  qdm_indicators_cli: ${bin("qdm-indicators-cli")}\n  qdm_cas_cli: ${bin("cas-cli")}\n`);
+  fs.writeFileSync(env, `export QDM_CMR_CLI="${bin("qdm-cmr-cli")}"\nexport QDM_INDICATORS_CLI="${bin("qdm-indicators-cli")}"\nexport QDM_CAS_CLI="${bin("cas-cli")}"\n`);
+}
+
+export function validateCasConfigDir(dir) {
+  const file = path.join(dir, "config.json");
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`CAS config is missing or invalid: ${file}`);
+  }
+  if (!config?.cas?.username || !config?.cas?.password) {
+    throw new Error(`CAS config must contain non-empty cas.username and cas.password: ${file}`);
+  }
+}
+
+export function linkAgents(workspace, agent) {
+  const pairs = [];
+  if (agent === "claude" || agent === "both") pairs.push([".agents/claude", ".claude"]);
+  if (agent === "codex" || agent === "both") pairs.push([".agents/codex", ".codex"]);
+  for (const [sourceRel, targetRel] of pairs) {
+    const source = path.join(workspace, sourceRel);
+    const target = path.join(workspace, targetRel);
+    if (!fs.existsSync(source)) throw new Error(`agent template missing: ${sourceRel}`);
+    if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+    fs.symlinkSync(source, target, "junction");
+  }
+}

package/src/lib/exec.js

@@ -0,0 +1,34 @@
+import { spawn } from "node:child_process";
+
+export function run(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: { ...process.env, ...(options.env || {}) },
+      shell: options.shell || false,
+      stdio: options.stdio || "pipe"
+    });
+    let stdout = "";
+    let stderr = "";
+    if (child.stdout) child.stdout.on("data", (chunk) => (stdout += chunk));
+    if (child.stderr) child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const result = { code, stdout, stderr };
+      if (code === 0 || options.allowFailure) {
+        resolve(result);
+        return;
+      }
+      const detail = stderr.trim() || stdout.trim();
+      reject(new Error(`${command} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`));
+    });
+  });
+}
+
+export async function commandExists(command) {
+  const result = await run(process.platform === "win32" ? "where" : "command", process.platform === "win32" ? [command] : ["-v", command], {
+    shell: process.platform !== "win32",
+    allowFailure: true
+  });
+  return result.code === 0;
+}

package/src/lib/git.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import path from "node:path";
+import { run } from "./exec.js";
+
+export async function isGitRepo(dir) {
+  if (!fs.existsSync(path.join(dir, ".git"))) return false;
+  const result = await run("git", ["rev-parse", "--is-inside-work-tree"], { cwd: dir, allowFailure: true });
+  return result.code === 0 && result.stdout.trim() === "true";
+}
+
+export async function currentCommit(dir) {
+  const result = await run("git", ["rev-parse", "HEAD"], { cwd: dir, allowFailure: true });
+  return result.code === 0 ? result.stdout.trim() : "";
+}
+
+export async function dirtyPaths(dir) {
+  const result = await run("git", ["status", "--porcelain"], { cwd: dir, allowFailure: true });
+  if (result.code !== 0) return ["<git status failed>"];
+  return result.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+export async function isDirty(dir) {
+  return (await dirtyPaths(dir)).length > 0;
+}
+
+export async function currentBranch(dir) {
+  const result = await run("git", ["branch", "--show-current"], { cwd: dir, allowFailure: true });
+  return result.stdout.trim();
+}
+
+export async function remoteTracking(dir) {
+  const result = await run("git", ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], { cwd: dir, allowFailure: true });
+  return result.code === 0 ? result.stdout.trim() : "";
+}
+
+export async function behindCount(dir) {
+  const upstream = await remoteTracking(dir);
+  if (!upstream) return 0;
+  await run("git", ["fetch", "--quiet"], { cwd: dir, allowFailure: true });
+  const result = await run("git", ["rev-list", "--count", `HEAD..${upstream}`], { cwd: dir, allowFailure: true });
+  return Number(result.stdout.trim() || "0");
+}
+
+export async function submoduleCommit(dir, name = "wikis") {
+  const result = await run("git", ["-C", name, "rev-parse", "HEAD"], { cwd: dir, allowFailure: true });
+  return result.code === 0 ? result.stdout.trim() : "";
+}
+
+export async function submoduleRemoteBehind(dir, name = "wikis") {
+  const subdir = path.join(dir, name);
+  if (!fs.existsSync(subdir)) return 0;
+  await run("git", ["fetch", "--quiet"], { cwd: subdir, allowFailure: true });
+  const upstream = await remoteTracking(subdir);
+  if (!upstream) return 0;
+  const result = await run("git", ["rev-list", "--count", `HEAD..${upstream}`], { cwd: subdir, allowFailure: true });
+  return Number(result.stdout.trim() || "0");
+}
+
+async function gitlink(dir, rev, name) {
+  const result = await run("git", ["ls-tree", rev, name], { cwd: dir, allowFailure: true });
+  return result.stdout.trim().split(/\s+/)[2] || "";
+}
+
+export async function submodulePointerChanged(dir, name = "wikis") {
+  const upstream = await remoteTracking(dir);
+  if (!upstream) return false;
+  const current = await gitlink(dir, "HEAD", name);
+  const remote = await gitlink(dir, upstream, name);
+  return Boolean(current && remote && current !== remote);
+}

package/src/lib/manifest.js

@@ -0,0 +1,80 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import https from "node:https";
+import path from "node:path";
+import { run } from "./exec.js";
+import { platformKey } from "./platform.js";
+
+export function readManifest(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function manifestDigest(manifest) {
+  return crypto.createHash("sha256").update(JSON.stringify(manifest)).digest("hex");
+}
+
+function download(url, file) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if ([301, 302, 307, 308].includes(response.statusCode) && response.headers.location) {
+        download(response.headers.location, file).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`download failed ${response.statusCode}: ${url}`));
+        return;
+      }
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      const out = fs.createWriteStream(file);
+      response.pipe(out);
+      out.on("finish", () => out.close(resolve));
+      out.on("error", reject);
+    });
+    request.on("error", reject);
+  });
+}
+
+async function expectedSha256(asset) {
+  if (asset.sha256) return asset.sha256;
+  try {
+    const tmp = path.join(fs.mkdtempSync(path.join(process.cwd(), ".bootstrap-cache-sha-")), "asset.sha256");
+    await download(`${asset.url}.sha256`, tmp);
+    return fs.readFileSync(tmp, "utf8").trim().split(/\s+/)[0];
+  } catch {
+    return "";
+  }
+}
+
+function fileSha256(file) {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+export async function installToolsFromManifest(workspace, manifestPath) {
+  const manifest = readManifest(manifestPath);
+  const key = platformKey();
+  const cacheDir = path.join(workspace, ".bootstrap-cache");
+  const binDir = path.join(workspace, "bin");
+  fs.mkdirSync(cacheDir, { recursive: true });
+  fs.mkdirSync(binDir, { recursive: true });
+
+  for (const tool of manifest.tools || []) {
+    const asset = tool.platforms?.[key];
+    if (!asset?.url) throw new Error(`manifest missing ${tool.name} asset for ${key}`);
+    const archive = path.join(cacheDir, path.basename(new URL(asset.url).pathname));
+    console.log(`Downloading ${tool.name} ${tool.version} (${key})`);
+    await download(asset.url, archive);
+    const sha = await expectedSha256(asset);
+    if (sha && fileSha256(archive) !== sha) throw new Error(`${tool.name} sha256 mismatch`);
+    if (!sha) console.warn(`warning: ${tool.name} has no sha256; continuing without checksum`);
+    if (archive.endsWith(".zip")) {
+      await run("unzip", ["-o", archive, "-d", binDir], { stdio: "inherit" });
+    } else {
+      await run("tar", ["-xzf", archive, "-C", binDir], { stdio: "inherit" });
+    }
+    const binary = path.join(binDir, tool.binary);
+    if (!fs.existsSync(binary)) throw new Error(`${tool.binary} was not extracted to bin/`);
+    fs.chmodSync(binary, 0o755);
+  }
+  return manifest;
+}

package/src/lib/package.js

@@ -0,0 +1,9 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageVersion() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "..", "package.json"), "utf8"));
+  return pkg.version;
+}

package/src/lib/paths.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const appDir = path.join("lumi-ai-lab", "harness-data");
+const stateDir = path.join("lumi-ai-lab", "harness-data-installer");
+
+export function expandHome(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+export function defaultWorkspaceDir() {
+  if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Application Support", appDir);
+  if (process.platform === "win32") return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), appDir);
+  return path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share"), appDir);
+}
+
+export function userStatePath() {
+  if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Application Support", stateDir, "state.json");
+  if (process.platform === "win32") return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), stateDir, "state.json");
+  return path.join(process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), stateDir, "state.json");
+}
+
+export function readUserState() {
+  try {
+    return JSON.parse(fs.readFileSync(userStatePath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeState(workspace, patch) {
+  const file = userStatePath();
+  const state = {
+    ...readUserState(),
+    lastInstallDir: workspace,
+    updatedAt: new Date().toISOString(),
+    ...patch
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  const local = path.join(workspace, ".harness", "installer-state.json");
+  fs.mkdirSync(path.dirname(local), { recursive: true });
+  fs.writeFileSync(local, `${JSON.stringify(state, null, 2)}\n`);
+  return state;
+}
+
+export function resolveWorkspaceDir(value) {
+  return path.resolve(expandHome(value || defaultWorkspaceDir()));
+}
+
+export function findWorkspaceDir(explicitDir) {
+  if (explicitDir) return resolveWorkspaceDir(explicitDir);
+  if (looksLikeWorkspace(process.cwd())) return process.cwd();
+  const state = readUserState();
+  if (state.lastInstallDir) return path.resolve(state.lastInstallDir);
+  return defaultWorkspaceDir();
+}
+
+export function looksLikeWorkspace(dir) {
+  return fs.existsSync(path.join(dir, "bootstrap", "cli-manifest.json")) &&
+    fs.existsSync(path.join(dir, ".agents")) &&
+    fs.existsSync(path.join(dir, "wikis"));
+}

package/src/lib/platform.js

@@ -0,0 +1,9 @@
+export function platformKey() {
+  const os = process.platform === "darwin" ? "darwin" : process.platform === "linux" ? "linux" : process.platform === "win32" ? "windows" : process.platform;
+  const arch = process.arch === "x64" ? "amd64" : process.arch;
+  const key = `${os}-${arch}`;
+  if (!["darwin-arm64", "darwin-amd64", "linux-arm64", "linux-amd64"].includes(key)) {
+    throw new Error(`unsupported platform: ${key}`);
+  }
+  return key;
+}

package/src/lib/prompt.js

@@ -0,0 +1,29 @@
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export async function confirm(message, options = {}) {
+  if (options.yes) return true;
+  const suffix = options.defaultNo ? " [y/N] " : " [Y/n] ";
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question(message + suffix)).trim().toLowerCase();
+    if (!answer) return !options.defaultNo;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export async function chooseAgent(options = {}) {
+  if (options.agent) return options.agent;
+  if (options.yes) throw new Error("non-interactive install requires --agent claude|codex|both");
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question("Choose Agent: claude, codex, both [codex] ")).trim().toLowerCase();
+    const value = answer || "codex";
+    if (!["claude", "codex", "both"].includes(value)) throw new Error("agent must be claude, codex, or both");
+    return value;
+  } finally {
+    rl.close();
+  }
+}