portawhip 0.1.0

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

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildBackendArgs, runBackend } from "../../core/surface/config-sync-backends.mjs";
+import { collectSyncConfig, parseArgs } from "./sync-config.mjs";
+
+test("sync-config: ai-config-sync preview builds a dry-run plan command", () => {
+  assert.deepEqual(
+    buildBackendArgs("ai-config-sync", "preview", {
+      from: "claude",
+      to: "codex",
+      scope: "project",
+      include: "instructions,skills",
+      exclude: "mcp",
+    }),
+    [
+      "sync",
+      "--dry-run",
+      "--plan-json",
+      "--from",
+      "claude",
+      "--to",
+      "codex",
+      "--scope",
+      "project",
+      "--include",
+      "instructions,skills",
+      "--exclude",
+      "mcp",
+    ],
+  );
+});
+
+test("sync-config: apply is guarded by an explicit flag", () => {
+  assert.throws(() => parseArgs(["node", "sync-config.mjs", "apply"]), /explicit --apply/);
+  assert.throws(() => parseArgs(["node", "sync-config.mjs", "apply", "--apply"]), /requires --include/);
+  assert.equal(parseArgs(["node", "sync-config.mjs", "apply", "--apply", "--include", "mcp:notion"]).allowApply, true);
+});
+
+test("sync-config: apply blocks broad all-skills writes", () => {
+  assert.throws(
+    () => parseArgs(["node", "sync-config.mjs", "apply", "--apply", "--include", "skills"]),
+    /all skills is blocked/,
+  );
+  assert.equal(
+    parseArgs(["node", "sync-config.mjs", "apply", "--apply", "--include", "skills:pdf"]).include,
+    "skills:pdf",
+  );
+});
+
+test("sync-config: profiles fill safe defaults", () => {
+  const args = parseArgs(["node", "sync-config.mjs", "preview", "--profile", "ai-project-instructions"]);
+  assert.equal(args.backends[0], "ai-config-sync");
+  assert.equal(args.scope, "project");
+  assert.equal(args.include, "instructions");
+});
+
+test("sync-config: agent-skill-manager is probe-only", () => {
+  assert.deepEqual(buildBackendArgs("asm", "status"), ["config", "show"]);
+  assert.throws(() => buildBackendArgs("asm", "preview"), /does not support preview/);
+});
+
+test("sync-config: .agents preview maps to sync --check", () => {
+  assert.deepEqual(buildBackendArgs(".agents", "preview"), ["sync", "--check"]);
+});
+
+test("sync-config: .agents preview planned changes are not install failures", () => {
+  const runner = () => ({
+    status: 1,
+    stdout: "\u001b[36m[info]\u001b[39m Would update 1 item(s):\n  -> .agents/agents.json\n",
+    stderr: "",
+  });
+  const row = runBackend("agents-dotdir", "preview", {}, runner);
+  assert.equal(row.ok, true);
+  assert.equal(row.status, "changed");
+  assert.equal(row.installHint, null);
+  assert.match(row.summary, /planned changes/);
+});
+
+test("sync-config: collect marks probe-only unsupported actions without failing all", () => {
+  const result = collectSyncConfig({
+    action: "preview",
+    backends: ["agent-skill-manager"],
+    options: {},
+  });
+  assert.equal(result.status, "success");
+  assert.equal(result.rows[0].ok, true);
+  assert.equal(result.rows[0].status, "unsupported");
+  assert.match(result.rows[0].summary, /does not support preview/);
+});
+
+test("sync-config: collect reports backend output in stable shape", () => {
+  const calls = [];
+  const runner = (cmd, args) => {
+    calls.push([cmd, args]);
+    return { status: 0, stdout: "{\"ok\":true}\n", stderr: "" };
+  };
+  const row = runBackend("ai-config-sync", "status", {}, runner);
+  assert.equal(row.status, "success");
+  assert.equal(row.backend, "ai-config-sync");
+  assert.match(row.command[0].replace(/\\/g, "/"), /(node_modules\/\.bin\/ai-config-sync|ai-config-sync)(\.cmd)?$/);
+  assert.deepEqual(row.command.slice(1), ["status", "--json"]);
+
+  const result = collectSyncConfig({
+    action: "status",
+    backends: ["agent-skill-manager"],
+    options: {},
+    runner,
+  });
+  assert.equal(result.rows.length, 1);
+  assert.equal(result.rows[0].backend, "agent-skill-manager");
+  assert.match(calls[0][0].replace(/\\/g, "/"), /(node_modules\/\.bin\/ai-config-sync|ai-config-sync)(\.cmd)?$/);
+  assert.deepEqual(calls[0][1], ["status", "--json"]);
+  assert.match(calls[1][0].replace(/\\/g, "/"), /agent-skill-manager(\.cmd)?$/);
+  assert.deepEqual(calls[1][1], ["config", "show"]);
+});
+
+test("sync-config: pinned local backend wins even when npx fallback is allowed", () => {
+  const calls = [];
+  const runner = (cmd, args) => {
+    calls.push([cmd, args]);
+    return { status: 0, stdout: "{\"ok\":true}\n", stderr: "" };
+  };
+  const args = parseArgs(["node", "sync-config.mjs", "status", "--allow-npx"]);
+  assert.equal(args.allowNpx, true);
+  runBackend("ai-config-sync", "status", { allowNpx: true }, runner);
+  assert.match(calls[0][0].replace(/\\/g, "/"), /(node_modules\/\.bin\/ai-config-sync|ai-config-sync)(\.cmd)?$/);
+  assert.deepEqual(calls[0][1], ["status", "--json"]);
+});
+
+test("sync-config: backend ledger inner errors make the wrapper fail", () => {
+  const runner = () => ({
+    status: 0,
+    stdout: '{"summary":{"applied":0,"error":1}}\nextra human output\n',
+    stderr: "",
+  });
+  const row = runBackend("ai-config-sync", "apply", { include: "instructions" }, runner);
+  assert.equal(row.ok, false);
+  assert.equal(row.status, "error");
+  assert.match(row.summary, /inner error/);
+  assert.deepEqual(row.parsedSummary, { applied: 0, error: 1 });
+});

package/scripts/sync/sync-surfaces.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import spawnSync from "cross-spawn";
+import { activeSelectionPathFor, readActiveSelection, resolveRecipePaths } from "../../core/state/bundle-state.mjs";
+import { mergeRawEntries } from "../../core/registry/registry.mjs";
+import { detectHosts } from "../hosts.mjs";
+import { installEntries } from "../load.mjs";
+import { collectSurfaceLinks, presentHostSet } from "../link/link-surfaces.mjs";
+
+const VALID_COMMANDS = new Set(["sync", "check", "watch"]);
+const INSTALL_TYPES = new Set(["cli", "skill"]);
+
+function localBin(root, name) {
+  const suffix = process.platform === "win32" ? ".cmd" : "";
+  const candidate = join(root, "node_modules", ".bin", `${name}${suffix}`);
+  return existsSync(candidate) ? candidate : name;
+}
+
+export function parseArgs(argv) {
+  const args = {
+    command: argv[2] ?? "sync",
+    scope: "project",
+    intervalMs: 1200,
+    once: false,
+    json: false,
+  };
+
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scope") {
+      args.scope = argv[i + 1];
+      i += 1;
+    } else if (arg === "--interval") {
+      args.intervalMs = Number(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--once") {
+      args.once = true;
+    } else if (arg === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  if (!VALID_COMMANDS.has(args.command)) {
+    throw new Error("usage: sync-surfaces.mjs <sync|check|watch> [--scope project|global] [--interval ms] [--once] [--json]");
+  }
+  if (!["project", "global"].includes(args.scope)) throw new Error(`invalid scope "${args.scope}"`);
+  if (!Number.isFinite(args.intervalMs) || args.intervalMs <= 0) throw new Error("invalid --interval");
+  return args;
+}
+
+export function installableEntries(entries) {
+  return entries.filter((entry) => entry.install !== false && INSTALL_TYPES.has(entry.type));
+}
+
+function recipeEntries(root) {
+  const recipePaths = resolveRecipePaths(root, readActiveSelection(root));
+  return {
+    recipePaths,
+    entries: mergeRawEntries(recipePaths),
+  };
+}
+
+function run(command, args, { cwd }) {
+  const result = spawnSync.sync(command, args, { cwd, stdio: "inherit" });
+  return result.status === 0;
+}
+
+export async function syncSurfaces({ root = resolve("."), scope = "project", check = false, runner = run, hosts = null } = {}) {
+  const absoluteRoot = resolve(root);
+  const { recipePaths, entries } = recipeEntries(absoluteRoot);
+  const installEntriesForSync = installableEntries(entries);
+  const result = {
+    root: absoluteRoot,
+    mode: check ? "check" : "sync",
+    recipePaths,
+    lanes: [],
+  };
+
+  const agentsArgs = ["sync", "--verbose"];
+  if (check) agentsArgs.push("--check");
+  const mcpOk = runner(localBin(absoluteRoot, "agents"), agentsArgs, { cwd: absoluteRoot });
+  result.lanes.push({
+    lane: "mcp",
+    backend: "agents",
+    ok: mcpOk,
+    action: check ? "check" : "sync",
+  });
+
+  if (check) {
+    result.lanes.push({
+      lane: "cli+skills",
+      backend: "mise+agent-skill-manager",
+      ok: true,
+      action: "planned",
+      count: installEntriesForSync.length,
+    });
+    const surfacePlan = collectSurfaceLinks({ command: "status", scope, root: absoluteRoot, presentHosts: await presentHostSet() });
+    result.lanes.push(surfaceLane(surfacePlan, "planned"));
+    return result;
+  }
+
+  const detectedHosts = hosts ?? (await detectHosts());
+  const installResults = installEntries(installEntriesForSync, detectedHosts, scope);
+  result.lanes.push({
+    lane: "cli+skills",
+    backend: "mise+agent-skill-manager",
+    ok: installResults.every((item) => item.ok),
+    action: "sync",
+    count: installResults.length,
+    results: installResults,
+  });
+
+  // Commands + agents: mise/asm don't install these, so fan them out by
+  // managed-copy into each markdown-host's native dir (Phase S2 write).
+  const surfaceResult = collectSurfaceLinks({ command: "install", scope, root: absoluteRoot, presentHosts: await presentHostSet() });
+  result.lanes.push(surfaceLane(surfaceResult, "sync"));
+  return result;
+}
+
+// A copy target only "fails" if it errored; source/unsupported/linked/missing
+// are all expected, non-failing states.
+function surfaceLane(plan, action) {
+  const copied = plan.rows.filter((r) => r.changed).length;
+  const unsupported = plan.rows.filter((r) => r.status === "unsupported").length;
+  return {
+    lane: "commands+agents",
+    backend: "link-surfaces (managed-copy)",
+    ok: plan.rows.every((r) => r.status !== "error"),
+    action,
+    count: plan.rows.length,
+    copied,
+    unsupported,
+  };
+}
+
+function sourceFiles(root) {
+  const files = [
+    join(root, ".agents", "agents.json"),
+    join(root, ".agents", "local.json"),
+    join(root, "recipe.yaml"),
+    activeSelectionPathFor(root),
+  ];
+  const dirs = [join(root, ".agents", "skills"), join(root, "recipes")];
+  for (const dir of dirs) collectFiles(dir, files);
+  return files.filter(existsSync);
+}
+
+function collectFiles(path, files) {
+  if (!existsSync(path)) return;
+  const stat = statSync(path);
+  if (stat.isFile()) {
+    files.push(path);
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  for (const child of readdirSync(path)) collectFiles(join(path, child), files);
+}
+
+function fingerprint(root) {
+  return sourceFiles(root)
+    .sort()
+    .map((path) => {
+      const stat = statSync(path);
+      return `${path}:${stat.mtimeMs}:${stat.size}`;
+    })
+    .join("|");
+}
+
+function printResult(result, json = false) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`surface ${result.mode}: ${result.lanes.every((lane) => lane.ok) ? "success" : "warning"}`);
+  for (const lane of result.lanes) {
+    const count = typeof lane.count === "number" ? ` (${lane.count} item(s))` : "";
+    console.log(`${lane.ok ? "OK  " : "FAIL"} ${lane.lane}: ${lane.backend} ${lane.action}${count}`);
+  }
+}
+
+async function runWatch({ root, scope, intervalMs, once, json }) {
+  let last = fingerprint(root);
+  let syncing = false;
+  const runOne = async () => {
+    if (syncing) return;
+    syncing = true;
+    try {
+      printResult(await syncSurfaces({ root, scope }), json);
+    } finally {
+      syncing = false;
+    }
+  };
+
+  await runOne();
+  if (once) return;
+  console.log(`watching surface sources every ${intervalMs}ms`);
+  setInterval(async () => {
+    const next = fingerprint(root);
+    if (next === last) return;
+    last = next;
+    await runOne();
+  }, intervalMs);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const root = resolve(".");
+  if (args.command === "watch") {
+    await runWatch({ root, scope: args.scope, intervalMs: args.intervalMs, once: args.once, json: args.json });
+    return;
+  }
+  const result = await syncSurfaces({ root, scope: args.scope, check: args.command === "check" });
+  printResult(result, args.json);
+  process.exitCode = result.lanes.every((lane) => lane.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/sync-surfaces.test.mjs

@@ -0,0 +1,66 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { installableEntries, parseArgs, syncSurfaces } from "./sync-surfaces.mjs";
+
+test("sync-surfaces: parses sync/check/watch commands", () => {
+  assert.equal(parseArgs(["node", "sync-surfaces.mjs"]).command, "sync");
+  assert.equal(parseArgs(["node", "sync-surfaces.mjs", "check", "--json"]).json, true);
+  assert.equal(parseArgs(["node", "sync-surfaces.mjs", "watch", "--once", "--interval", "50"]).once, true);
+  assert.throws(() => parseArgs(["node", "sync-surfaces.mjs", "wat"]), /usage/);
+  assert.throws(() => parseArgs(["node", "sync-surfaces.mjs", "sync", "--scope", "all"]), /invalid scope/);
+});
+
+test("sync-surfaces: only CLI and skill entries are installable", () => {
+  const entries = [
+    { id: "docs", type: "mcp" },
+    { id: "rg", type: "cli" },
+    { id: "pdf", type: "skill" },
+    { id: "route-only", type: "skill", install: false },
+    { id: "sync", type: "config-sync" },
+  ];
+  assert.deepEqual(
+    installableEntries(entries).map((entry) => entry.id),
+    ["rg", "pdf"],
+  );
+});
+
+test("sync-surfaces: check runs agents sync --check and does not install CLI/skills", async () => {
+  const root = mkdtempSync(join(tmpdir(), "surface-check-"));
+  writeFileSync(
+    join(root, "recipe.yaml"),
+    [
+      "- id: rg",
+      "  type: cli",
+      "  source: ripgrep",
+      "- id: pdf",
+      "  type: skill",
+      "  source: pdf",
+      "- id: docs",
+      "  type: mcp",
+      "  source: context7",
+      "",
+    ].join("\n"),
+  );
+  const calls = [];
+  const result = await syncSurfaces({
+    root,
+    check: true,
+    runner: (cmd, args) => {
+      calls.push([cmd, args]);
+      return true;
+    },
+  });
+  assert.equal(result.lanes.length, 3);
+  assert.equal(result.lanes[0].lane, "mcp");
+  assert.deepEqual(calls[0][1], ["sync", "--verbose", "--check"]);
+  assert.equal(result.lanes[1].lane, "cli+skills");
+  assert.equal(result.lanes[1].action, "planned");
+  assert.equal(result.lanes[1].count, 2);
+  // Phase S2: commands+agents managed-copy lane. The temp recipe has no
+  // command/agent entries, so it plans zero targets but the lane is present.
+  assert.equal(result.lanes[2].lane, "commands+agents");
+  assert.equal(result.lanes[2].action, "planned");
+});

package/scripts/tui-actions.mjs

@@ -0,0 +1,59 @@
+import { collectConnectorLinks } from "./link/link-connectors.mjs";
+import { collectHookLinks } from "./link/link-hooks.mjs";
+
+export const LINK_SCOPES = ["project", "global", "all"];
+
+const LINK_TABS = new Set(["connectors", "hooks"]);
+const LINK_COMMANDS = new Set(["status", "install", "remove"]);
+const COMMAND_BY_INPUT = new Map([
+  ["s", "status"],
+  ["l", "install"],
+  ["x", "remove"],
+]);
+
+const defaultCollectors = {
+  connectors: collectConnectorLinks,
+  hooks: collectHookLinks,
+};
+
+export function linkCommandForInput(tab, input) {
+  return LINK_TABS.has(tab) ? (COMMAND_BY_INPUT.get(input) ?? null) : null;
+}
+
+export function linkActionNeedsConfirmation(command) {
+  return command === "install" || command === "remove";
+}
+
+export function summarizeLinkAction(tab, result) {
+  const statuses = result.rows.map((row) => row.instructionStatus ?? row.status ?? "unknown");
+  const changed = statuses.filter((status) => status === "changed").length;
+  const unchanged = statuses.filter((status) => status === "no-op" || status === "linked").length;
+  const missing = statuses.filter((status) => status === "missing").length;
+  const unsupported = statuses.filter((status) => status === "unsupported").length;
+  const details = [];
+
+  if (changed) details.push(`${changed} changed`);
+  if (unchanged) details.push(`${unchanged} already current`);
+  if (missing) details.push(`${missing} missing`);
+  if (unsupported) details.push(`${unsupported} unsupported`);
+  return `${tab} ${result.command} ${result.scope}: ${details.join(", ") || "no targets found"}`;
+}
+
+export async function runLinkAction({ tab, command, scope, collectors = defaultCollectors } = {}) {
+  if (!LINK_TABS.has(tab)) throw new Error(`unsupported TUI action tab: ${tab}`);
+  if (!LINK_COMMANDS.has(command)) throw new Error(`unsupported link action: ${command}`);
+  if (!LINK_SCOPES.includes(scope)) throw new Error(`unsupported link scope: ${scope}`);
+
+  const collect = collectors[tab];
+  if (typeof collect !== "function") throw new Error(`missing ${tab} collector`);
+
+  const scopes = scope === "all" ? ["project", "global"] : [scope];
+  const runs = await Promise.all(scopes.map((selectedScope) => collect({ command, scope: selectedScope })));
+  const result = {
+    command,
+    scope,
+    rows: runs.flatMap((run) => run.rows ?? []),
+    runs,
+  };
+  return { ...result, summary: summarizeLinkAction(tab, result) };
+}

package/scripts/tui-actions.test.mjs

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { LINK_SCOPES, linkCommandForInput, runLinkAction } from "./tui-actions.mjs";
+
+test("connector and hook tabs expose status, repair, and remove actions", () => {
+  assert.deepEqual(LINK_SCOPES, ["project", "global", "all"]);
+  assert.equal(linkCommandForInput("connectors", "s"), "status");
+  assert.equal(linkCommandForInput("hooks", "l"), "install");
+  assert.equal(linkCommandForInput("connectors", "x"), "remove");
+  assert.equal(linkCommandForInput("sync", "l"), null);
+});
+
+test("runs a connector repair in both scopes when all is selected", async () => {
+  const calls = [];
+  const result = await runLinkAction({
+    tab: "connectors",
+    command: "install",
+    scope: "all",
+    collectors: {
+      connectors: async (options) => {
+        calls.push(options);
+        return {
+          rows: [
+            { hostId: "codex", scope: options.scope, instructionStatus: "changed" },
+            { hostId: "claude", scope: options.scope, instructionStatus: "no-op" },
+          ],
+        };
+      },
+    },
+  });
+
+  assert.deepEqual(calls, [
+    { command: "install", scope: "project" },
+    { command: "install", scope: "global" },
+  ]);
+  assert.equal(result.rows.length, 4);
+  assert.match(result.summary, /connectors install all: 2 changed, 2 already current/);
+});
+
+test("runs the selected hook action and rejects unsupported tabs", async () => {
+  const result = await runLinkAction({
+    tab: "hooks",
+    command: "remove",
+    scope: "global",
+    collectors: {
+      hooks: async (options) => ({ rows: [{ hostId: "codex", ...options, status: "changed" }] }),
+    },
+  });
+
+  assert.match(result.summary, /hooks remove global: 1 changed/);
+  await assert.rejects(() => runLinkAction({ tab: "sync", command: "install", scope: "project" }), /unsupported TUI action tab/);
+});