portawhip 0.1.0

package/scripts/load.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// Step 1 proof: one declarative recipe, dispatched to whichever backend
+// already solves that capability type well. This file owns NO install
+// logic and no host list — it only shells out to add-mcp / mise / asm
+// per entry.type, targeting whatever detectHosts() finds on THIS machine.
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import spawnSync from "cross-spawn";
+import { detectHosts } from "./hosts.mjs";
+import { mergeRawEntries } from "../core/registry/registry.mjs";
+import { readActiveSelection, resolveRecipePaths } from "../core/state/bundle-state.mjs";
+
+function run(cmd, args) {
+  console.log(`\n$ ${cmd} ${args.join(" ")}`);
+  const result = spawnSync.sync(cmd, args, { stdio: "inherit" });
+  return result.status === 0;
+}
+
+function slugify(label) {
+  return label.trim().toLowerCase().replace(/\s+/g, "-");
+}
+
+function loadMcp(entry, hosts) {
+  if (hosts.mcpHosts.length === 0) {
+    console.log(`skip ${entry.id}: no MCP-capable agent detected on this machine`);
+    return true;
+  }
+  // add-mcp fails the WHOLE batch if any target lacks transport support for
+  // this entry (e.g. Claude Desktop only takes stdio, not remote/http). It
+  // names the incompatible host in its own error text, so read that instead
+  // of hardcoding a per-host transport capability matrix ourselves.
+  let candidates = [...hosts.mcpHosts];
+  for (let attempt = 0; attempt < candidates.length; attempt += 1) {
+    const args = ["--yes", "add-mcp", entry.source, "-y"];
+    if (entry.scope !== "project") args.push("-g");
+    if (entry.name) args.push("-n", entry.name);
+    // add-mcp can silently upgrade project-scoped entries to global if any
+    // target host requires it (observed: VS Code / Copilot CLI force this).
+    // A relative path only resolves correctly from this repo's own cwd, so
+    // any local file argument must be made absolute regardless of scope.
+    for (const a of entry.args ?? []) {
+      args.push("--args", existsSync(a) ? resolve(a) : a);
+    }
+    for (const host of candidates) args.push("-a", host);
+    console.log(`\n$ npx ${args.join(" ")}`);
+    const result = spawnSync.sync("npx", args, { encoding: "utf8" });
+    const text = (result.stdout || "") + (result.stderr || "");
+    console.log(text);
+    if (result.status === 0) return true;
+
+    const match = text.match(/don't support .*transport:\s*([^\n]+)/i);
+    if (!match) return false; // some other failure — don't loop blindly
+    const excluded = new Set(match[1].split(",").map((s) => slugify(s)));
+    const next = candidates.filter((id) => !excluded.has(id));
+    if (next.length === candidates.length || next.length === 0) return false;
+    console.log(`retrying without incompatible host(s): ${[...excluded].join(", ")}`);
+    candidates = next;
+  }
+  return false;
+}
+
+function loadCli(entry, hosts, scope) {
+  // mise itself is the cross-OS layer here; no per-agent targeting needed.
+  // scope:"project" pins the tool in THIS project's own .mise.toml (created/
+  // updated in the cwd mise is run from) instead of the user's global mise
+  // config — for a bundle role that's only relevant to one project, not
+  // every project on the machine.
+  const args = scope === "project" ? ["use", entry.source] : ["use", "-g", entry.source];
+  return run("mise", args);
+}
+
+function loadSkill(entry, hosts) {
+  if (hosts.skillHosts.length === 0) {
+    console.log(`skip ${entry.id}: no skill-capable agent detected on this machine`);
+    return true;
+  }
+  let ok = true;
+  for (const provider of hosts.skillHosts) {
+    const args = ["--yes", "agent-skill-manager", "install", entry.source];
+    if (entry.path) args.push("--path", entry.path);
+    args.push("-p", provider, "--yes");
+    ok = run("npx", args) && ok;
+  }
+  return ok;
+}
+
+const DISPATCH = { mcp: loadMcp, cli: loadCli, skill: loadSkill };
+
+// Extracted so scripts/bundles.mjs's `select` can install right after
+// recording a bundle choice, without duplicating this dispatch logic.
+// scope only affects type:cli entries (mise -g vs project .mise.toml);
+// mcp/skill handlers ignore the extra argument.
+export function installEntries(entries, hosts, scope = "global") {
+  const results = [];
+  for (const entry of entries) {
+    if (entry.install === false) {
+      console.log(`skip ${entry.id}: route-only entry`);
+      results.push({ id: entry.id, ok: true, skipped: true });
+      continue;
+    }
+    const handler = DISPATCH[entry.type];
+    if (!handler) {
+      console.error(`unknown type "${entry.type}" for ${entry.id}`);
+      results.push({ id: entry.id, ok: false });
+      continue;
+    }
+    const ok = handler(entry, hosts, scope);
+    results.push({ id: entry.id, ok });
+  }
+  return results;
+}
+
+async function main() {
+  // An explicit path argument bypasses the opt-in bundle layer entirely
+  // (existing single-recipe usage, unchanged). Otherwise install whatever
+  // bundles were selected via scripts/bundles.mjs select, composed in front
+  // of this project's own recipe.yaml — defaults to just recipe.yaml when
+  // nothing has been selected (today's exact behavior).
+  const explicitRecipe = process.argv[2];
+  const recipePaths = explicitRecipe
+    ? [explicitRecipe]
+    : resolveRecipePaths(resolve("."), readActiveSelection(resolve(".")));
+  const entries = mergeRawEntries(recipePaths);
+  const hosts = await detectHosts();
+
+  console.log(`detected MCP hosts:   ${hosts.mcpHosts.join(", ") || "(none)"}`);
+  console.log(`detected skill hosts: ${hosts.skillHosts.join(", ") || "(none)"}`);
+
+  const results = installEntries(entries, hosts);
+
+  console.log("\n== load summary ==");
+  for (const r of results) console.log(`${r.ok ? "OK  " : "FAIL"} ${r.id}`);
+  process.exitCode = results.every((r) => r.ok) ? 0 : 1;
+}
+
+import { pathToFileURL } from "node:url";
+
+// Guard main() behind an entry-point check (matches link-hooks/link-connectors/
+// generate) so importing this module never triggers a real install as a side
+// effect of module load.
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();

package/scripts/package-contract.test.mjs

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+test("npm package exposes public npx and MCP entry points", () => {
+  assert.equal(packageJson.private, false);
+  assert.equal(packageJson.publishConfig?.access, "public");
+  assert.equal(packageJson.bin?.portawhip, "scripts/tui.mjs");
+  assert.equal(packageJson.bin?.["portawhip-router"], "core/router/router-cli.mjs");
+  assert.equal(packageJson.bin?.["harness-router"], "server/mcp-server.mjs");
+});
+
+test("npm package declares a supported runtime and a release-safe file allowlist", () => {
+  assert.match(packageJson.engines?.node ?? "", />=20/);
+  assert.ok(packageJson.files?.includes("core/"));
+  assert.ok(packageJson.files?.includes("scripts/"));
+  assert.ok(packageJson.files?.includes("server/"));
+  assert.ok(packageJson.files?.includes("recipe.yaml"));
+  assert.ok(!packageJson.files?.some((entry) => entry.startsWith(".hp-state")));
+});
+
+test("test script uses Node's cross-platform recursive discovery", () => {
+  assert.equal(packageJson.scripts?.test, "node --test");
+});

package/scripts/surface-inventory.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { collectSurfaceInventory } from "../core/surface/surface-inventory.mjs";
+
+const inventory = await collectSurfaceInventory();
+console.log(JSON.stringify(inventory, null, 2));

package/scripts/sync/agents-surface.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import spawnSync from "cross-spawn";
+import { syncSurfaces } from "./sync-surfaces.mjs";
+
+function localAgents(root) {
+  const suffix = process.platform === "win32" ? ".cmd" : "";
+  const candidate = join(root, "node_modules", ".bin", `agents${suffix}`);
+  return existsSync(candidate) ? candidate : "agents";
+}
+
+export function shouldSyncAfterAgents(args) {
+  const [command, subcommand] = args.filter((arg) => !arg.startsWith("-"));
+  if (command === "connect" || command === "disconnect") return true;
+  if (command === "mcp" && ["add", "import", "remove"].includes(subcommand)) return true;
+  return false;
+}
+
+function parseScope(args) {
+  const index = args.indexOf("--scope");
+  if (index === -1) return "project";
+  return args[index + 1] === "project" ? "project" : "global";
+}
+
+async function main() {
+  const root = resolve(".");
+  const args = process.argv.slice(2);
+  const result = spawnSync.sync(localAgents(root), args, { cwd: root, stdio: "inherit" });
+  if (result.status !== 0) {
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  if (!shouldSyncAfterAgents(args)) return;
+
+  console.log("\n== surface auto-sync after agents change ==");
+  const syncResult = await syncSurfaces({ root, scope: parseScope(args) });
+  const ok = syncResult.lanes.every((lane) => lane.ok);
+  for (const lane of syncResult.lanes) {
+    const count = typeof lane.count === "number" ? ` (${lane.count} item(s))` : "";
+    console.log(`${lane.ok ? "OK  " : "FAIL"} ${lane.lane}: ${lane.backend} ${lane.action}${count}`);
+  }
+  process.exitCode = ok ? 0 : 1;
+}
+
+import { pathToFileURL } from "node:url";
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/sync/agents-surface.test.mjs

@@ -0,0 +1,18 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { shouldSyncAfterAgents } from "./agents-surface.mjs";
+
+test("agents-surface: auto-syncs after source-changing agents commands", () => {
+  assert.equal(shouldSyncAfterAgents(["connect", "--llm", "codex"]), true);
+  assert.equal(shouldSyncAfterAgents(["disconnect", "--llm", "codex"]), true);
+  assert.equal(shouldSyncAfterAgents(["mcp", "add", "harness-router"]), true);
+  assert.equal(shouldSyncAfterAgents(["mcp", "import", "--file", "servers.json"]), true);
+  assert.equal(shouldSyncAfterAgents(["mcp", "remove", "harness-router"]), true);
+});
+
+test("agents-surface: read-only agents commands do not trigger full sync", () => {
+  assert.equal(shouldSyncAfterAgents(["status", "--verbose"]), false);
+  assert.equal(shouldSyncAfterAgents(["mcp", "list"]), false);
+  assert.equal(shouldSyncAfterAgents(["mcp", "test", "harness-router"]), false);
+  assert.equal(shouldSyncAfterAgents(["sync", "--check"]), false);
+});

package/scripts/sync/auto-sync.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// Auto-sync worker (Phase S1c, decision D — reconciled) — the background
+// half of "import once, use everywhere".
+//
+// Split of responsibilities (locked with owner 2026-07-10):
+//   IMPORT (discovered -> canonical) is MANUAL: the user runs
+//     `npm run import` and chooses what to canonicalize (auto-enriched there).
+//   FAN-OUT (canonical -> all hosts) is AUTO: this worker, fired
+//     fire-and-forget from the session-start hook, keeps every host in sync
+//     with whatever is already canonical (recipe.yaml + recipes/imported.yaml
+//     + selected bundles).
+//
+// It deliberately does NOT discover-and-import new capabilities on its own —
+// that is what made an earlier auto-import design pour hundreds of entries
+// across every host unbidden. This worker only propagates deliberate,
+// already-canonical entries, so there is no surprise fan-out.
+//
+// Throttled + locked + logged + fully fail-open. Silence (hosts already in
+// sync) is the normal steady state.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import spawnSync from "cross-spawn";
+import { loadConfig } from "../../core/state/config.mjs";
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const STATE_DIR = join(ROOT, ".hp-state");
+const STATE_PATH = join(STATE_DIR, "auto-sync.state.json");
+const LOCK_PATH = join(STATE_DIR, "auto-sync.lock");
+const LOG_PATH = join(STATE_DIR, "auto-sync.log");
+const LOCK_STALE_MS = 15 * 60 * 1000; // a lock older than this is presumed dead
+
+// Pure: has enough time passed since the last run? (throttle)
+export function shouldRun(state, now, throttleMs) {
+  if (!throttleMs || throttleMs <= 0) return true;
+  const last = Number(state?.lastRunAt ?? 0);
+  return now - last >= throttleMs;
+}
+
+// Pure: is an existing lock stale (safe to steal)?
+export function lockIsStale(lockMtimeMs, now, staleMs = LOCK_STALE_MS) {
+  return now - lockMtimeMs >= staleMs;
+}
+
+function readState() {
+  if (!existsSync(STATE_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeState(state) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function log(line) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    appendFileSync(LOG_PATH, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // logging is best-effort; never throw out of the worker
+  }
+}
+
+function acquireLock(now = Date.now()) {
+  mkdirSync(STATE_DIR, { recursive: true });
+  if (existsSync(LOCK_PATH)) {
+    let mtime = 0;
+    try {
+      mtime = Number(readFileSync(LOCK_PATH, "utf8")) || 0;
+    } catch {
+      mtime = 0;
+    }
+    if (!lockIsStale(mtime, now)) return false;
+  }
+  writeFileSync(LOCK_PATH, String(now));
+  return true;
+}
+
+function releaseLock() {
+  try {
+    rmSync(LOCK_PATH, { force: true });
+  } catch {
+    // ignore
+  }
+}
+
+// Fan out canonical -> all hosts via the existing sync-surfaces lane (mise/
+// asm/agents-dotdir). Idempotent; only touches what is already canonical.
+function fanOut() {
+  const r = spawnSync.sync(process.execPath, [join(ROOT, "scripts", "sync-surfaces.mjs"), "sync"], {
+    cwd: ROOT,
+    encoding: "utf8",
+  });
+  return r.status === 0;
+}
+
+export async function runAutoSync({ now = Date.now(), config = null, fanOutImpl = fanOut } = {}) {
+  const cfg = config ?? loadConfig(join(ROOT, "router.config.yaml"));
+  const auto = cfg.autoSync ?? {};
+  if (auto.enabled === false) return { skipped: "disabled" };
+
+  const throttleMs = (Number(auto.throttleMinutes ?? 60) || 0) * 60 * 1000;
+  const state = readState();
+  if (!shouldRun(state, now, throttleMs)) return { skipped: "throttled" };
+  if (!acquireLock(now)) return { skipped: "locked" };
+
+  try {
+    const ok = fanOutImpl();
+    log(`fan-out ${ok ? "ok" : "FAILED"}`);
+    writeState({ ...state, lastRunAt: now, lastResult: ok ? "synced" : "sync-failed" });
+    return { synced: ok };
+  } catch (error) {
+    log(`ERROR ${error.message}`);
+    return { error: error.message };
+  } finally {
+    releaseLock();
+  }
+}
+
+async function main() {
+  const result = await runAutoSync();
+  console.log(`auto-sync: ${JSON.stringify(result)}`);
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main().catch((error) => {
+    log(`FATAL ${error.message}`);
+  });
+}

package/scripts/sync/auto-sync.test.mjs

@@ -0,0 +1,41 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { shouldRun, lockIsStale, runAutoSync } from "./auto-sync.mjs";
+import { loadConfig } from "../../core/state/config.mjs";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+test("shouldRun: throttles until enough time has passed", () => {
+  const throttle = 60 * 60 * 1000;
+  assert.equal(shouldRun({ lastRunAt: 1_000_000 }, 1_000_000 + throttle - 1, throttle), false);
+  assert.equal(shouldRun({ lastRunAt: 1_000_000 }, 1_000_000 + throttle, throttle), true);
+  assert.equal(shouldRun({}, Date.now(), throttle), true);
+  assert.equal(shouldRun({ lastRunAt: Date.now() }, Date.now(), 0), true);
+});
+
+test("lockIsStale: only steals a lock older than the stale window", () => {
+  const now = 10_000_000;
+  const stale = 15 * 60 * 1000;
+  assert.equal(lockIsStale(now - stale + 1, now, stale), false);
+  assert.equal(lockIsStale(now - stale, now, stale), true);
+});
+
+test("runAutoSync: disabled config skips without touching fan-out", async () => {
+  let called = false;
+  const res = await runAutoSync({ config: { autoSync: { enabled: false } }, fanOutImpl: () => (called = true) });
+  assert.deepEqual(res, { skipped: "disabled" });
+  assert.equal(called, false);
+});
+
+// The enabled path acquires a real lock + writes real state under ROOT/
+// .hp-state, so it is verified live (docs/archive/phaseS1c-verify.md) rather than in
+// a unit test that would pollute/contend on that shared state.
+
+test("loadConfig: autoSync defaults on with a 60m throttle; overrides read", () => {
+  assert.deepEqual(loadConfig("does-not-exist.yaml").autoSync, { enabled: true, throttleMinutes: 60 });
+  const dir = mkdtempSync(join(tmpdir(), "autosync-cfg-"));
+  const path = join(dir, "router.config.yaml");
+  writeFileSync(path, "autoSync:\n  enabled: false\n  throttleMinutes: 5\n");
+  assert.deepEqual(loadConfig(path).autoSync, { enabled: false, throttleMinutes: 5 });
+});