portawhip 0.1.0

package/scripts/sync/import-surfaces.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// Import direction (Phase S1): read what's actually installed across hosts
+// (via the same core/discover.mjs the router already uses) and PROPOSE it as
+// persistent, shareable canonical entries — CLI/skill into recipes/
+// imported.yaml, MCP into .agents/agents.json's mcp.servers block (which
+// @agents-dev/cli then fans out to other hosts).
+//
+// This owns no discovery or sync logic: discovery is discover.mjs, fan-out is
+// the existing loader/agents-dotdir lanes. Import only diffs "installed
+// somewhere" against "already canonical" and writes the gap where the user
+// approves it. Same status -> preview -> apply gate as sync-config.mjs;
+// silence (nothing new) is a valid, expected result.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { readActiveSelection, resolveRecipePaths } from "../../core/state/bundle-state.mjs";
+import { readRawEntries } from "../../core/registry/registry.mjs";
+import { discoverAll } from "../../core/registry/discover.mjs";
+import { enrichCliLadder } from "../../core/registry/cli-enrich.mjs";
+
+const VALID_ACTIONS = new Set(["status", "preview", "apply"]);
+const IMPORTED_RECIPE = ["cli", "skill", "command", "agent"]; // land in imported.yaml
+const AGENTS_MCP = ["mcp"]; // land in .agents/agents.json
+// Surfaces shown in full (every id listed) vs summarized (count + sample);
+// nothing is hidden — large groups just don't flood the preview. No type is
+// suppressed by default: display groups by surface, apply still needs an
+// explicit selector for the big groups so nothing pours in unintentionally.
+const FULL_LIST_TYPES = new Set(["cli", "mcp"]);
+const SAMPLE = 6;
+
+export function parseArgs(argv) {
+  const args = {
+    action: argv[2] ?? "status",
+    types: null,
+    include: null,
+    json: false,
+    allowApply: false,
+  };
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--type" || arg === "--types") {
+      args.types = String(argv[i + 1] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      i += 1;
+    } else if (arg === "--include") {
+      args.include = String(argv[i + 1] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      i += 1;
+    } else if (arg === "--json") {
+      args.json = true;
+    } else if (arg === "--apply") {
+      args.allowApply = true;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!VALID_ACTIONS.has(args.action)) {
+    throw new Error("usage: import-surfaces.mjs <status|preview|apply> [--type cli,mcp,skill,command,agent] [--include id,id] [--json] [--apply]");
+  }
+  if (args.action === "apply" && !args.allowApply) {
+    throw new Error("apply requires an explicit --apply flag; run preview first");
+  }
+  return args;
+}
+
+// Ids already canonical: curated recipe/bundle/imported entries + MCP servers
+// already declared in .agents/agents.json. A candidate matching any of these
+// is not "new" and is skipped.
+export function knownIds({ root, recipePaths, agentsJson }) {
+  const ids = new Set();
+  for (const path of recipePaths) {
+    if (!existsSync(path)) continue;
+    for (const entry of readRawEntries(path)) if (entry.id) ids.add(entry.id);
+  }
+  const servers = agentsJson?.mcp?.servers ?? {};
+  for (const name of Object.keys(servers)) ids.add(name);
+  return ids;
+}
+
+// Pure: filter discovered entries down to the ones worth proposing. No type
+// is suppressed by default (grouped display handles volume); an explicit
+// --type or --include narrows it.
+export function computeCandidates({ discovered, known, types, include }) {
+  const typeSet = types && types.length ? new Set(types) : null;
+  const includeSet = include && include.length ? new Set(include) : null;
+  return discovered.filter((entry) => {
+    if (known.has(entry.id)) return false;
+    if (includeSet) return includeSet.has(entry.id) || includeSet.has(`${entry.type}:${entry.id}`);
+    if (typeSet) return typeSet.has(entry.type);
+    return true;
+  });
+}
+
+// Pure: a discovered entry is "bare" if discovery gave it no real trigger
+// surface beyond its own name (the dead-weight case the enrich ladder exists
+// to fix). Used as the auto-junk gate for CLI import.
+export function isBare(entry) {
+  const triggers = entry.route?.triggers ?? [];
+  const nonSelf = triggers.filter((t) => t !== entry.id && t !== entry.source);
+  return nonSelf.length === 0;
+}
+
+// Pure: shape a discovered entry into a recipe-file entry, recording
+// provenance so a later forget/doctor can see it was imported (and when).
+// `enrichment` (optional) is the CLI ladder result — when present its
+// triggers/description win (promote bare -> useful). Returns null to HOLD
+// BACK a still-bare CLI entry: the auto-junk gate that replaces manual
+// approval (an entry that would only ever match its own name isn't worth
+// fanning out to every host).
+export function toRecipeEntry(entry, enrichment = null) {
+  const route = enrichment
+    ? {
+        triggers: enrichment.triggers,
+        description: enrichment.description,
+        when: entry.route?.when ?? ["user_prompt"],
+        inject: entry.route?.inject ?? "hint",
+      }
+    : {
+        triggers: entry.route?.triggers ?? [entry.id],
+        description: entry.route?.description ?? `${entry.type}: ${entry.id}`,
+        when: entry.route?.when ?? ["user_prompt"],
+        inject: entry.route?.inject ?? "hint",
+      };
+  if (entry.type === "cli" && !enrichment && isBare(entry)) return null;
+  const out = {
+    id: entry.id,
+    type: entry.type,
+    source: entry.source ?? entry.id,
+    route,
+    imported: {
+      at: new Date().toISOString(),
+      via: `discover:${entry.type}`,
+      ...(enrichment ? { enriched: enrichment.sources } : {}),
+    },
+  };
+  if (entry.path) out.path = entry.path;
+  return out;
+}
+
+// Pure: merge new recipe entries into an existing imported.yaml list,
+// first-seen (existing) wins so re-running apply is idempotent.
+export function mergeImported(existing, additions) {
+  const byId = new Map();
+  for (const entry of existing) byId.set(entry.id, entry);
+  for (const entry of additions) if (!byId.has(entry.id)) byId.set(entry.id, entry);
+  return [...byId.values()];
+}
+
+function readYamlList(path) {
+  if (!existsSync(path)) return [];
+  const raw = yaml.load(readFileSync(path, "utf8"));
+  return Array.isArray(raw) ? raw : [];
+}
+
+function readAgentsJson(root) {
+  const path = join(root, ".agents", "agents.json");
+  if (!existsSync(path)) return { path, json: null };
+  try {
+    return { path, json: JSON.parse(readFileSync(path, "utf8")) };
+  } catch {
+    return { path, json: null };
+  }
+}
+
+// MCP launch config isn't carried by discoverMcp (it dedups to id+source), so
+// fetch it from add-mcp the same way core/enrich.mjs does, only for the
+// servers actually being imported.
+async function mcpConfigs(serverNames) {
+  if (!serverNames.length) return {};
+  const { listInstalledServers } = await import("add-mcp");
+  const hosts = await listInstalledServers({ global: true });
+  const configs = {};
+  for (const host of hosts) {
+    for (const server of host.servers ?? []) {
+      if (serverNames.includes(server.serverName) && server.config && !configs[server.serverName]) {
+        configs[server.serverName] = server.config;
+      }
+    }
+  }
+  return configs;
+}
+
+// Pure: add imported MCP servers into an agents.json object's mcp.servers.
+export function mergeAgentsMcp(agentsJson, mcpEntries, configs) {
+  const json = agentsJson ? structuredClone(agentsJson) : { schemaVersion: 3, mcp: { servers: {} } };
+  json.mcp = json.mcp ?? {};
+  json.mcp.servers = json.mcp.servers ?? {};
+  const added = [];
+  for (const entry of mcpEntries) {
+    if (json.mcp.servers[entry.id]) continue;
+    const config = configs[entry.id];
+    if (!config) continue; // no launch config recoverable -> skip, report
+    json.mcp.servers[entry.id] = {
+      transport: config.url ? "http" : "stdio",
+      enabled: true,
+      description: entry.route?.description ?? `Imported MCP server: ${entry.id}`,
+      ...(config.url ? { url: config.url } : { command: config.command, args: config.args ?? [] }),
+      imported: { at: new Date().toISOString() },
+    };
+    added.push(entry.id);
+  }
+  return { json, added };
+}
+
+export async function collectImport({ root = resolve("."), action = "status", types = null, include = null } = {}) {
+  const selection = readActiveSelection(root);
+  const recipePaths = resolveRecipePaths(root, selection);
+  const { json: agentsJson, path: agentsPath } = readAgentsJson(root);
+  const known = knownIds({ root, recipePaths, agentsJson });
+  const discovered = await discoverAll();
+  const candidates = computeCandidates({ discovered, known, types, include });
+
+  const byLane = { recipe: [], agentsMcp: [] };
+  for (const entry of candidates) {
+    if (AGENTS_MCP.includes(entry.type)) byLane.agentsMcp.push(entry);
+    else if (IMPORTED_RECIPE.includes(entry.type)) byLane.recipe.push(entry);
+  }
+
+  const result = {
+    root,
+    action,
+    discoveredCount: discovered.length,
+    knownCount: known.size,
+    candidates: candidates.map((e) => ({ id: e.id, type: e.type })),
+    lanes: {
+      recipe: byLane.recipe.map((e) => e.id),
+      agentsMcp: byLane.agentsMcp.map((e) => e.id),
+    },
+    applied: null,
+  };
+
+  // Group counts for display are useful in every mode.
+  result.groups = groupByType(candidates);
+
+  if (action !== "apply") return result;
+
+  // apply
+  const importedPath = join(root, "recipes", "imported.yaml");
+  const existing = readYamlList(importedPath);
+
+  // Auto-enrich CLI candidates inline (promote bare -> useful) so imported
+  // entries route on natural phrasing, not just their own name. The ladder is
+  // the quality gate: a CLI that can't be enriched and is still bare is held
+  // back by toRecipeEntry (returns null).
+  const cliIds = byLane.recipe.filter((e) => e.type === "cli").map((e) => e.id);
+  const enrichment = cliIds.length ? await enrichCliLadder(cliIds) : {};
+
+  const additions = [];
+  const heldBack = [];
+  for (const entry of byLane.recipe) {
+    const built = toRecipeEntry(entry, entry.type === "cli" ? enrichment[entry.id] ?? null : null);
+    if (built) additions.push(built);
+    else heldBack.push(entry.id);
+  }
+  const merged = mergeImported(existing, additions);
+  const configs = await mcpConfigs(byLane.agentsMcp.map((e) => e.id));
+  const { json: newAgents, added: mcpAdded } = mergeAgentsMcp(agentsJson, byLane.agentsMcp, configs);
+
+  const wrote = [];
+  if (additions.length) {
+    writeFileSync(importedPath, yaml.dump(merged, { lineWidth: 100 }));
+    wrote.push({ path: importedPath, added: additions.map((e) => e.id) });
+  }
+  if (mcpAdded.length) {
+    writeFileSync(agentsPath, `${JSON.stringify(newAgents, null, 2)}\n`);
+    wrote.push({ path: agentsPath, added: mcpAdded });
+  }
+  const mcpSkipped = byLane.agentsMcp.map((e) => e.id).filter((id) => !mcpAdded.includes(id));
+  result.applied = { wrote, mcpSkipped, heldBack };
+  return result;
+}
+
+// Pure: group candidate {id,type} rows by surface type.
+export function groupByType(candidates) {
+  const groups = {};
+  for (const c of candidates) (groups[c.type] ??= []).push(c.id);
+  return groups;
+}
+
+function printText(result) {
+  console.log(`import ${result.action}`);
+  console.log(`discovered ${result.discoveredCount} across hosts; ${result.knownCount} already canonical`);
+  console.log(`new candidates: ${result.candidates.length}`);
+  // Grouped by surface with real counts; nothing hidden. Small groups list
+  // every id; large groups show a sample + how to import fully.
+  const groups = result.groups ?? {};
+  for (const type of Object.keys(groups).sort()) {
+    const ids = groups[type];
+    if (FULL_LIST_TYPES.has(type) || ids.length <= SAMPLE) {
+      console.log(`  ${type} (${ids.length}): ${ids.join(", ")}`);
+    } else {
+      console.log(`  ${type} (${ids.length}): ${ids.slice(0, SAMPLE).join(", ")}, … +${ids.length - SAMPLE}`);
+      console.log(`      import all: --type ${type}   |   one: --include ${type}:<id>`);
+    }
+  }
+  if (!result.candidates.length) console.log("  (nothing new to import — silence is a valid result)");
+  if (result.applied) {
+    for (const w of result.applied.wrote) console.log(`WROTE ${w.path}: +${w.added.length} (${w.added.join(", ")})`);
+    if (result.applied.heldBack?.length) {
+      console.log(`HELD BACK (bare, could not enrich — not worth fanning out): ${result.applied.heldBack.join(", ")}`);
+    }
+    if (result.applied.mcpSkipped.length) {
+      console.log(`SKIPPED (no recoverable launch config): ${result.applied.mcpSkipped.join(", ")}`);
+    }
+    console.log("next: run `npm run sync-surfaces sync` (or agents sync) to fan out to other hosts.");
+  } else if (result.action === "preview") {
+    console.log("next: re-run with `apply --apply` to write these; hand-curated recipe.yaml always wins on id collision.");
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const result = await collectImport({
+    root: resolve("."),
+    action: args.action,
+    types: args.types,
+    include: args.include,
+  });
+  if (args.json) console.log(JSON.stringify(result, null, 2));
+  else printText(result);
+  process.exitCode = 0;
+}
+
+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/import-surfaces.test.mjs

@@ -0,0 +1,106 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  computeCandidates,
+  groupByType,
+  isBare,
+  mergeAgentsMcp,
+  mergeImported,
+  parseArgs,
+  toRecipeEntry,
+} from "./import-surfaces.mjs";
+
+const disc = (id, type, extra = {}) => ({ id, type, source: id, route: { triggers: [id], description: `${type}: ${id}` }, ...extra });
+
+test("parseArgs: apply without --apply is rejected", () => {
+  assert.throws(() => parseArgs(["node", "import.mjs", "apply"]), /requires an explicit --apply/);
+  assert.equal(parseArgs(["node", "import.mjs", "apply", "--apply"]).action, "apply");
+});
+
+test("computeCandidates: no filter = all surfaces, only known excluded", () => {
+  const discovered = [disc("rg", "cli"), disc("srv", "mcp"), disc("pdf", "skill"), disc("dup", "cli")];
+  const known = new Set(["dup"]);
+  const out = computeCandidates({ discovered, known, types: null, include: null });
+  assert.deepEqual(out.map((e) => e.id).sort(), ["pdf", "rg", "srv"]);
+});
+
+test("computeCandidates: --type narrows to the given surfaces", () => {
+  const discovered = [disc("rg", "cli"), disc("srv", "mcp"), disc("pdf", "skill")];
+  const out = computeCandidates({ discovered, known: new Set(), types: ["cli"], include: null });
+  assert.deepEqual(out.map((e) => e.id), ["rg"]);
+});
+
+test("isBare: only-self triggers = bare; extra trigger = not bare", () => {
+  assert.equal(isBare(disc("rg", "cli")), true);
+  assert.equal(isBare({ id: "rg", source: "ripgrep", type: "cli", route: { triggers: ["rg", "search"] } }), false);
+});
+
+test("groupByType: buckets ids by surface", () => {
+  const g = groupByType([{ id: "a", type: "cli" }, { id: "b", type: "cli" }, { id: "c", type: "mcp" }]);
+  assert.deepEqual(g, { cli: ["a", "b"], mcp: ["c"] });
+});
+
+test("toRecipeEntry: bare CLI with no enrichment is held back (null)", () => {
+  assert.equal(toRecipeEntry(disc("rg", "cli"), null), null);
+});
+
+test("toRecipeEntry: enrichment promotes a bare CLI (triggers/desc win)", () => {
+  const enr = { triggers: ["rg", "search", "grep"], description: "CLI tool: rg — fast search", sources: { description: "package" } };
+  const entry = toRecipeEntry(disc("rg", "cli"), enr);
+  assert.deepEqual(entry.route.triggers, ["rg", "search", "grep"]);
+  assert.equal(entry.imported.enriched.description, "package");
+});
+
+test("toRecipeEntry: non-CLI keeps its discovered route, never gated", () => {
+  const entry = toRecipeEntry(disc("pdf", "skill", { route: { triggers: ["pdf"], description: "PDF skill" } }), null);
+  assert.ok(entry);
+  assert.equal(entry.type, "skill");
+});
+
+test("computeCandidates: --include overrides the type filter and matches type:id", () => {
+  const discovered = [disc("pdf", "skill"), disc("rg", "cli")];
+  const known = new Set();
+  assert.deepEqual(
+    computeCandidates({ discovered, known, types: null, include: ["skill:pdf"] }).map((e) => e.id),
+    ["pdf"],
+  );
+  assert.deepEqual(
+    computeCandidates({ discovered, known, types: null, include: ["pdf"] }).map((e) => e.id),
+    ["pdf"],
+  );
+});
+
+test("toRecipeEntry: carries route + provenance, keeps path when present", () => {
+  const entry = toRecipeEntry(disc("pdf", "skill", { path: "/x/pdf" }));
+  assert.equal(entry.id, "pdf");
+  assert.equal(entry.path, "/x/pdf");
+  assert.equal(entry.imported.via, "discover:skill");
+  assert.ok(entry.route.triggers.includes("pdf"));
+});
+
+test("mergeImported: existing wins on id, so re-apply is idempotent", () => {
+  const existing = [{ id: "rg", type: "cli", note: "kept" }];
+  const additions = [{ id: "rg", type: "cli", note: "new" }, { id: "jq", type: "cli" }];
+  const merged = mergeImported(existing, additions);
+  assert.equal(merged.length, 2);
+  assert.equal(merged.find((e) => e.id === "rg").note, "kept");
+});
+
+test("mergeAgentsMcp: adds stdio server with config, skips one with no recoverable config", () => {
+  const agents = { schemaVersion: 3, mcp: { servers: { existing: {} } } };
+  const entries = [disc("withcfg", "mcp"), disc("nocfg", "mcp"), disc("existing", "mcp")];
+  const configs = { withcfg: { command: "node", args: ["x.js"] } };
+  const { json, added } = mergeAgentsMcp(agents, entries, configs);
+  assert.deepEqual(added, ["withcfg"]);
+  assert.equal(json.mcp.servers.withcfg.transport, "stdio");
+  assert.equal(json.mcp.servers.withcfg.command, "node");
+  assert.ok(!json.mcp.servers.nocfg, "no-config server is not written");
+  assert.ok(json.mcp.servers.existing, "pre-existing server untouched");
+});
+
+test("mergeAgentsMcp: http transport when config has url", () => {
+  const { json, added } = mergeAgentsMcp(null, [disc("remote", "mcp")], { remote: { url: "https://x/y" } });
+  assert.deepEqual(added, ["remote"]);
+  assert.equal(json.mcp.servers.remote.transport, "http");
+  assert.equal(json.mcp.servers.remote.url, "https://x/y");
+});

package/scripts/sync/sync-config.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Cross-host config sync facade.
+//
+// This script deliberately delegates real sync to existing backends instead of
+// inventing another config reconciler here. It gives portawhip one stable
+// command surface for status/preview/apply while preserving backend ownership.
+
+import { CONFIG_SYNC_BACKENDS, backendById, normalizeBackendId, runBackend } from "../../core/surface/config-sync-backends.mjs";
+
+const VALID_ACTIONS = new Set(["status", "preview", "apply"]);
+const VALID_SCOPES = new Set(["all", "project", "global"]);
+const PROFILES = {
+  "ai-project-instructions": {
+    backends: ["ai-config-sync"],
+    scope: "project",
+    include: "instructions",
+  },
+  "ai-global-instructions": {
+    backends: ["ai-config-sync"],
+    scope: "global",
+    include: "instructions",
+  },
+  "ai-project-mcp": {
+    backends: ["ai-config-sync"],
+    scope: "project",
+    include: "mcp",
+  },
+  "asm-status": {
+    backends: ["agent-skill-manager"],
+  },
+  "agents-check": {
+    backends: ["agents-dotdir"],
+  },
+};
+
+function parseCsv(value) {
+  return String(value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function parseArgs(argv) {
+  const args = {
+    action: argv[2] ?? "status",
+    backends: ["ai-config-sync"],
+    json: false,
+    allowApply: false,
+    allowNpx: false,
+    scope: "all",
+    include: null,
+    exclude: null,
+    from: null,
+    to: null,
+    profile: null,
+  };
+
+  for (let i = 3; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--backend") {
+      args.backends = [argv[i + 1]];
+      i += 1;
+    } else if (arg === "--backends") {
+      args.backends = parseCsv(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--all-backends") {
+      args.backends = Object.keys(CONFIG_SYNC_BACKENDS);
+    } else if (arg === "--json") {
+      args.json = true;
+    } else if (arg === "--apply") {
+      args.allowApply = true;
+    } else if (arg === "--allow-npx") {
+      args.allowNpx = true;
+    } else if (arg === "--profile") {
+      args.profile = argv[i + 1];
+      i += 1;
+    } else if (arg === "--scope") {
+      args.scope = argv[i + 1];
+      i += 1;
+    } else if (arg === "--include") {
+      args.include = argv[i + 1];
+      i += 1;
+    } else if (arg === "--exclude") {
+      args.exclude = argv[i + 1];
+      i += 1;
+    } else if (arg === "--from") {
+      args.from = argv[i + 1];
+      i += 1;
+    } else if (arg === "--to") {
+      args.to = argv[i + 1];
+      i += 1;
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+
+  if (!VALID_ACTIONS.has(args.action)) {
+    throw new Error(
+      "usage: sync-config.mjs <status|preview|apply> [--backend id|--profile name|--all-backends] [--json] [--allow-npx]",
+    );
+  }
+  applyProfile(args);
+  if (!VALID_SCOPES.has(args.scope)) {
+    throw new Error(`invalid scope "${args.scope}"`);
+  }
+  if (args.action === "apply" && !args.allowApply) {
+    throw new Error("apply requires an explicit --apply flag; run preview first");
+  }
+  if (args.action === "apply") validateApplySafety(args);
+  args.backends = args.backends.map(normalizeBackendId);
+  for (const backend of args.backends) backendById(backend);
+  return args;
+}
+
+function applyProfile(args) {
+  if (!args.profile) return;
+  const profile = PROFILES[args.profile];
+  if (!profile) throw new Error(`unknown profile "${args.profile}". valid: ${Object.keys(PROFILES).join(", ")}`);
+  args.backends = profile.backends ?? args.backends;
+  args.scope = profile.scope ?? args.scope;
+  args.include = profile.include ?? args.include;
+  args.exclude = profile.exclude ?? args.exclude;
+}
+
+function validateApplySafety(args) {
+  if (!args.include) {
+    throw new Error("apply requires --include or a --profile; broad all-area apply is blocked");
+  }
+  const selectors = parseCsv(args.include);
+  if (selectors.some((selector) => selector === "skills")) {
+    throw new Error("apply of all skills is blocked; use item selectors like --include skills:pdf");
+  }
+}
+
+function optionsFromArgs(args) {
+  return {
+    scope: args.scope,
+    include: args.include,
+    exclude: args.exclude,
+    from: args.from,
+    to: args.to,
+    cwd: process.cwd(),
+    allowNpx: args.allowNpx,
+  };
+}
+
+export function collectSyncConfig({
+  action = "status",
+  backends = ["ai-config-sync"],
+  options = {},
+  runner = null,
+} = {}) {
+  const rows = [];
+  for (const backend of backends) {
+    try {
+      rows.push(runner ? runBackend(backend, action, options, runner) : runBackend(backend, action, options));
+    } catch (error) {
+      const unsupported = /does not support/.test(error.message);
+      rows.push({
+        backend: normalizeBackendId(backend),
+        label: normalizeBackendId(backend),
+        action,
+        command: [],
+        ok: unsupported,
+        status: unsupported ? "unsupported" : "error",
+        summary: error.message,
+        output: "",
+        installHint: null,
+        next_actions: unsupported ? ["Use status for probe-only backends."] : ["Use a supported backend/action combination."],
+        artifacts: [],
+      });
+    }
+  }
+  const ok = rows.every((row) => row.ok);
+  return {
+    status: ok ? "success" : "warning",
+    summary: ok ? `${action} succeeded for ${rows.length} backend(s)` : `${action} needs attention`,
+    action,
+    rows,
+    next_actions: ok ? ["Review backend output for drift details."] : summarizeNextActions(rows),
+    artifacts: [],
+  };
+}
+
+function summarizeNextActions(rows) {
+  const actions = rows.flatMap((row) => row.next_actions ?? []);
+  return [...new Set(actions.length ? actions : ["Inspect failed backend output."])];
+}
+
+function printText(result) {
+  console.log(`sync-config action: ${result.action}`);
+  console.log(`status: ${result.status}`);
+  console.log(result.summary);
+  console.log("\n== backends ==");
+  for (const row of result.rows) {
+    const command = row.command.length ? ` (${row.command.join(" ")})` : "";
+    console.log(`${row.backend}: ${row.ok ? "OK" : "FAIL"} ${row.summary}${command}`);
+    if (!row.ok && row.installHint) console.log(`  install: ${row.installHint}`);
+    if (row.output.trim()) {
+      const lines = row.output.trim().split(/\r?\n/).slice(0, 20);
+      for (const line of lines) console.log(`  ${line}`);
+      if (row.output.trim().split(/\r?\n/).length > lines.length) console.log("  ...");
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const result = collectSyncConfig({
+    action: args.action,
+    backends: args.backends,
+    options: optionsFromArgs(args),
+  });
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printText(result);
+  }
+  process.exitCode = result.status === "success" ? 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;
+  });
+}