@klhapp/skillmux 1.0.0 → 1.1.0

package/src/cli.ts

@@ -2,8 +2,7 @@
 import { Database } from "bun:sqlite";
 import { existsSync, lstatSync, mkdirSync, rmSync } from "node:fs";
 import { hostname } from "node:os";
-import { basename, join } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { join } from "node:path";
 import { generateDataset } from "./dataset-generator";
 
 import { createClients } from "./clients";
@@ -48,20 +47,12 @@ import {
 } from "./install";
 import {
   parseManifest,
-  pinCore,
-  pinProject,
   resolveManifestPath,
   serializeManifest,
-  unpinCore,
-  unpinProject,
-  upsertProject,
-  updateProjectPaths,
-  updateProjectTargets,
   validateManifest,
-  writeManifestAtomic,
 } from "./manifest";
 import { downloadLocalModels } from "./models";
-import { resolveProjectDirectory, suggestProjectName } from "./project-setup";
+
 import {
   parseCommaList,
   promptMultiSelect,
@@ -113,6 +104,11 @@ import {
   suggestCorrection,
 } from "./output";
 import { generateCompletions, type ShellType } from "./completions";
+import { handleConfigCommand } from "./commands/config";
+import { runCore } from "./commands/core";
+import { configuredTargetForSurface, runProject } from "./commands/project";
+import { confirmAction, confirmIfNeeded } from "./commands/shared";
+import { runTarget } from "./commands/target";
 
 const KNOWN_COMMANDS = [
   "context",
@@ -244,7 +240,11 @@ async function main() {
         await runInit(rawArgv.slice(1), { isJson, dryRun: isDryRun });
         break;
       case "project":
-        await runProject(subCommand, commandArgs, { isJson, dryRun: isDryRun });
+        await runProject(subCommand, commandArgs, {
+          isJson,
+          dryRun: isDryRun,
+          sync: runSync,
+        });
         break;
       case "target":
         await runTarget(subCommand, commandArgs, { isJson, dryRun: isDryRun });
@@ -391,230 +391,60 @@ async function handleContextCommand(
   throw new Error("usage: skillmux context <add|list|current|use|remove>");
 }
 
-function emitConfigInitOutcome(
-  ctx: { isJson: boolean },
-  opts: {
-    phase: "plan" | "result";
-    dryRun: boolean;
-    applied: boolean;
-    plan: ConfigInitPlan;
-    action: "create" | "preserve";
-    text: string;
-  },
-): void {
-  if (ctx.isJson) {
-    console.log(
-      JSON.stringify({
-        schema_version: 1,
-        ok: true,
-        command: "config init",
-        phase: opts.phase,
-        dry_run: opts.dryRun,
-        applied: opts.applied,
-        plan: {
-          config_path: opts.plan.configPath,
-          vault_path: opts.plan.vaultPath,
-          action: opts.action,
-        },
-      }),
-    );
-    return;
-  }
-  console.log(opts.text);
-}
-
-async function handleConfigCommand(
+async function handleCalibrateCommand(
   adapter: TargetAdapter,
   sub: string,
   args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean; dryRun: boolean },
+  ctx: { target: ResolvedTarget; isJson: boolean },
 ) {
-  if (sub === "init") {
-    let vaultPath: string | undefined;
-    let yes = false;
+  if (sub === "run") {
+    let datasetPath: string | undefined;
+    let minAutoMatchPrecision: number | undefined;
+    let minRetrievalRecallAtK: number | undefined;
+    let minDeliveredShortlistRecallAtK: number | undefined;
+    let minAutoMatchCount: number | undefined;
+    const readNumber = (flag: string, raw: string | undefined): number => {
+      if (raw === undefined) throw new Error(`${flag} requires a value`);
+      const value = Number(raw);
+      if (!Number.isFinite(value)) throw new Error(`${flag} must be a number`);
+      return value;
+    };
     for (let i = 0; i < args.length; i++) {
       const option = args[i];
-      if (option === "--vault") {
-        vaultPath = args[++i];
-        if (!vaultPath)
-          throw new Error("usage: skillmux config init --vault <path> --yes");
-      } else if (option === "--yes") {
-        yes = true;
-      } else if (option === "--dry-run" || option === "--json") {
-        continue;
-      } else {
-        throw new Error(`unknown config init option: ${option}`);
-      }
-    }
-    if (!vaultPath) {
-      if (isInteractive() && !ctx.isJson) {
-        vaultPath = "~/skills";
-      } else {
-        throw new Error("usage: skillmux config init --vault <path> --yes");
-      }
-    }
-
-    migrateLegacyPaths();
-    const plan = planConfigInit(resolveConfigPath(), expandHome(vaultPath));
-    if (plan.action === "preserve") {
-      emitConfigInitOutcome(ctx, {
-        phase: "result",
-        dryRun: ctx.dryRun,
-        applied: false,
-        plan,
-        action: "preserve",
-        text: `preserved existing config: ${plan.configPath}`,
-      });
-      return;
-    }
-    if (ctx.dryRun) {
-      emitConfigInitOutcome(ctx, {
-        phase: "plan",
-        dryRun: true,
-        applied: false,
-        plan,
-        action: "create",
-        text: `config create: ${plan.configPath} (dry-run)`,
-      });
-      return;
-    }
-    if (!yes) {
-      if (!ctx.isJson && isInteractive()) {
-        if (
-          !(await confirmAction(
-            `Create ${plan.configPath} with vault_path ${plan.vaultPath}?`,
-          ))
-        ) {
-          console.log("config init cancelled; nothing written");
-          return;
+      if (option === "--dataset") {
+        datasetPath = args[++i];
+        if (!datasetPath) throw new Error("--dataset requires a path value");
+      } else if (option === "--min-auto-match-precision") {
+        minAutoMatchPrecision = readNumber(option, args[++i]);
+      } else if (option === "--min-retrieval-recall-at-k") {
+        minRetrievalRecallAtK = readNumber(option, args[++i]);
+      } else if (option === "--min-delivered-shortlist-recall-at-k") {
+        minDeliveredShortlistRecallAtK = readNumber(option, args[++i]);
+      } else if (option === "--min-auto-match-count") {
+        minAutoMatchCount = readNumber(option, args[++i]);
+        if (!Number.isInteger(minAutoMatchCount) || minAutoMatchCount < 1) {
+          throw new Error("--min-auto-match-count must be a positive integer");
         }
       } else {
-        throw new Error(
-          "config initialization requires --yes in noninteractive mode",
-        );
+        throw new Error(`unknown calibrate run option: ${option}`);
       }
     }
-
-    const result = applyConfigInit(plan);
-    emitConfigInitOutcome(ctx, {
-      phase: "result",
-      dryRun: false,
-      applied: result === "created",
-      plan,
-      action: plan.action,
-      text:
-        result === "created"
-          ? `created ${plan.configPath}`
-          : `preserved existing config: ${plan.configPath}`,
-    });
-    return;
-  }
-
-  if (sub === "show") {
-    const data = await adapter.getConfigShow();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, data, () => {
-      renderTargetBanner(ctx.target);
-      console.log(JSON.stringify(data.effective, null, 2));
-    });
-    return;
-  }
-
-  if (sub === "get") {
-    const key = args[0];
-    if (!key) throw new Error("usage: skillmux config get <key>");
-    const val = await adapter.getConfigGet(key);
-    emitSuccess(
-      { isJson: ctx.isJson, target: ctx.target },
-      { key, value: val },
-      () => {
-        console.log(
-          typeof val === "object" ? JSON.stringify(val) : String(val),
-        );
-      },
-    );
-    return;
-  }
-
-  if (sub === "validate") {
-    const res = await adapter.configValidate();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      console.log(
-        res.valid ? "Configuration is valid." : "Configuration is invalid.",
-      );
-    });
-    return;
-  }
-
-  if (sub === "diff") {
-    const res = await adapter.configDiff();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
-      console.log(JSON.stringify(res.diff, null, 2));
-    });
-    return;
-  }
-
-  if (sub === "set") {
-    const key = args[0];
-    const value = args[1];
-    if (!key || value === undefined) {
-      throw new Error("usage: skillmux config set <key> <value> [--dry-run]");
+    for (const [flag, value] of [
+      ["--min-auto-match-precision", minAutoMatchPrecision],
+      ["--min-retrieval-recall-at-k", minRetrievalRecallAtK],
+      ["--min-delivered-shortlist-recall-at-k", minDeliveredShortlistRecallAtK],
+    ] as const) {
+      if (value !== undefined && (value < 0 || value > 1)) {
+        throw new Error(`${flag} must be between 0 and 1`);
+      }
     }
-    const res = await adapter.configSet(key, value, { dryRun: ctx.dryRun });
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
-      const prefix = ctx.dryRun ? "[dry-run] " : "";
-      console.log(
-        `${prefix}${key}: ${JSON.stringify(res.prior_val)} -> ${JSON.stringify(res.resulting_val)}`,
-      );
-      console.log(
-        `Persistence: ${res.persistence}, Application: ${res.application}`,
-      );
-    });
-    return;
-  }
-
-  if (sub === "status") {
-    const res = await adapter.configStatus();
-    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
-      renderTargetBanner(ctx.target);
-      console.log(`Runtime: ${res.runtime}`);
-      console.log(`Active revision: ${res.active_revision}`);
-      console.log(`Readiness: ${res.readiness.status}`);
+    const res = await adapter.calibrateRun({
+      datasetPath,
+      minAutoMatchPrecision,
+      minRetrievalRecallAtK,
+      minDeliveredShortlistRecallAtK,
+      minAutoMatchCount,
     });
-    return;
-  }
-
-  throw new Error("usage: skillmux config show");
-}
-
-async function confirmAction(prompt: string): Promise<boolean> {
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    const answer = (await readline.question(`${prompt} [y/N] `))
-      .trim()
-      .toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    readline.close();
-  }
-}
-
-async function handleCalibrateCommand(
-  adapter: TargetAdapter,
-  sub: string,
-  args: string[],
-  ctx: { target: ResolvedTarget; isJson: boolean },
-) {
-  if (sub === "run") {
-    let datasetPath: string | undefined;
-    for (let i = 0; i < args.length; i++) {
-      if (args[i] === "--dataset") datasetPath = args[++i];
-    }
-    const res = await adapter.calibrateRun({ datasetPath });
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Calibration run complete.`);
@@ -851,576 +681,6 @@ async function runWhich(args: string[]): Promise<void> {
     console.log(`  shadows: ${shadowedRoot}`);
 }
 
-const PROJECT_INIT_USAGE =
-  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
-
-interface ProjectInitArgs {
-  path: string;
-  name: string;
-  skills: string[];
-  clients: string[];
-  targets: string[];
-  yes: boolean;
-  sync: boolean;
-}
-
-function configuredTargetForSurface(
-  manifest: ReturnType<typeof parseManifest>,
-  surface: { targetName: string; path: string },
-): string | undefined {
-  if (manifest.targets[surface.targetName]) return surface.targetName;
-  return Object.entries(manifest.targets).find(
-    ([, target]) => expandHome(target.dir) === surface.path,
-  )?.[0];
-}
-
-function configuredTargetsForClients(
-  manifest: ReturnType<typeof parseManifest>,
-  clients: readonly string[],
-): string[] {
-  return planClientSurfaces(clients).surfaces.map((surface) => {
-    const target = configuredTargetForSurface(manifest, surface);
-    if (target) return target;
-    const client = surface.clients[0]!;
-    throw new Error(
-      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
-    );
-  });
-}
-
-function parseProjectInitArgs(args: string[]): ProjectInitArgs {
-  let projectPath: string | undefined;
-  let name: string | undefined;
-  const skills: string[] = [];
-  const clients: string[] = [];
-  const targets: string[] = [];
-  let yes = false;
-  let sync = true;
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]!;
-    if (arg === "--name") {
-      name = args[++i];
-      if (!name) throw new Error("--name requires a group name");
-    } else if (arg === "--skill") {
-      const skill = args[++i];
-      if (!skill) throw new Error("--skill requires a skill_id");
-      skills.push(skill);
-    } else if (arg === "--target") {
-      const target = args[++i];
-      if (!target) throw new Error("--target requires a name");
-      targets.push(target);
-    } else if (arg === "--client") {
-      const client = args[++i];
-      if (!client) throw new Error("--client requires a name");
-      clients.push(client);
-    } else if (arg === "--yes") {
-      yes = true;
-    } else if (arg === "--no-sync") {
-      sync = false;
-    } else if (
-      arg === "--dry-run" ||
-      arg === "--json" ||
-      arg === "--interactive"
-    ) {
-      continue;
-    } else if (arg.startsWith("-")) {
-      throw new Error(`unknown project init option: ${arg}`);
-    } else if (projectPath) {
-      throw new Error(PROJECT_INIT_USAGE);
-    } else {
-      projectPath = arg;
-    }
-  }
-
-  const path = resolveProjectDirectory(
-    projectPath ? expandHome(projectPath) : undefined,
-  );
-  return {
-    path,
-    name: name ?? suggestProjectName(basename(path)),
-    skills,
-    clients,
-    targets,
-    yes,
-    sync,
-  };
-}
-
-async function loadManifestContext() {
-  const config = await loadConfig();
-  const vaultPath = expandHome(config.vault_path);
-  const manifestPath = resolveManifestPath(vaultPath);
-  if (!manifestPath) {
-    throw new Error(
-      `no skillmux.toml found at ${vaultPath}; run skillmux init first`,
-    );
-  }
-  const manifest = parseManifest(await Bun.file(manifestPath).text());
-  return { config, vaultPath, manifestPath, manifest };
-}
-
-async function confirmIfNeeded(opts: {
-  confirmed: boolean;
-  isJson: boolean;
-  prompt: string;
-  nonInteractiveError: string;
-}): Promise<boolean> {
-  if (opts.confirmed) return true;
-  if (opts.isJson || !isInteractive()) {
-    throw new Error(opts.nonInteractiveError);
-  }
-  return confirmAction(opts.prompt);
-}
-
-async function runProject(
-  subCommand: string,
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean },
-): Promise<void> {
-  if (subCommand === "list" || subCommand === "show") {
-    const { manifest } = await loadManifestContext();
-    const names =
-      subCommand === "show"
-        ? [args[0] ?? ""]
-        : Object.keys(manifest.project ?? {});
-    if (subCommand === "show" && !manifest.project?.[names[0]!]) {
-      throw new Error(`[project.${names[0]}] does not exist`);
-    }
-    const projects = names.map((name) => ({
-      name,
-      paths: manifest.project?.[name]!.paths ?? [],
-      skills: manifest.project?.[name]!.skills ?? [],
-      targets: Object.entries(manifest.targets)
-        .filter(([, target]) => target.project_groups.includes(name))
-        .map(([target]) => target),
-    }));
-    if (options.isJson) {
-      console.log(JSON.stringify({ schema_version: 1, projects }));
-    } else if (projects.length === 0) {
-      console.log("no project groups configured");
-    } else {
-      for (const project of projects) {
-        console.log(`${project.name}:`);
-        console.log(`  paths: ${project.paths.join(", ") || "(none)"}`);
-        console.log(`  skills: ${project.skills.join(", ") || "(none)"}`);
-        console.log(`  targets: ${project.targets.join(", ") || "(none)"}`);
-      }
-    }
-    return;
-  }
-  if (subCommand === "add-path" || subCommand === "remove-path") {
-    const group = args[0];
-    if (!group)
-      throw new Error(
-        `usage: skillmux project ${subCommand} <group> [path] --yes`,
-      );
-    const rawPath = args[1]?.startsWith("-") ? undefined : args[1];
-    const projectPath = resolveProjectDirectory(
-      rawPath ? expandHome(rawPath) : undefined,
-    );
-    const yes = args.includes("--yes");
-    if (!existsSync(projectPath) || !lstatSync(projectPath).isDirectory()) {
-      throw new Error(`project path is not a directory: ${projectPath}`);
-    }
-    const { config, vaultPath, manifestPath, manifest } =
-      await loadManifestContext();
-    const updated = updateProjectPaths(manifest, group, {
-      ...(subCommand === "add-path"
-        ? { add: [projectPath] }
-        : { remove: [projectPath] }),
-    });
-    validateManifest(
-      updated,
-      vaultPath,
-      config.local_vault_paths.map(expandHome),
-    );
-    if (options.dryRun) {
-      console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`);
-      return;
-    }
-    if (
-      !(await confirmIfNeeded({
-        confirmed: yes,
-        isJson: options.isJson,
-        prompt: `${subCommand} ${projectPath} in [project.${group}]?`,
-        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
-      }))
-    )
-      return;
-    writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${projectPath}`);
-    return;
-  }
-  if (subCommand === "pin" || subCommand === "unpin") {
-    const group = args[0];
-    const skills = args.slice(1).filter((arg) => !arg.startsWith("-"));
-    if (!group || skills.length === 0) {
-      throw new Error(
-        `usage: skillmux project ${subCommand} <group> <skill_id>... --yes`,
-      );
-    }
-    const yes = args.includes("--yes");
-    const { config, vaultPath, manifestPath, manifest } =
-      await loadManifestContext();
-    let updated = manifest;
-    for (const skill of skills) {
-      updated =
-        subCommand === "pin"
-          ? pinProject(updated, skill, group)
-          : unpinProject(updated, skill, group);
-    }
-    validateManifest(
-      updated,
-      vaultPath,
-      config.local_vault_paths.map(expandHome),
-    );
-    if (options.dryRun) {
-      console.log(
-        `${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`,
-      );
-      return;
-    }
-    if (
-      !(await confirmIfNeeded({
-        confirmed: yes,
-        isJson: options.isJson,
-        prompt: `${subCommand} ${skills.join(", ")} in [project.${group}]?`,
-        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
-      }))
-    )
-      return;
-    writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${skills.join(", ")}`);
-    return;
-  }
-  if (subCommand === "attach" || subCommand === "detach") {
-    const group = args[0];
-    if (!group)
-      throw new Error(
-        `usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`,
-      );
-    const clients: string[] = [];
-    const requestedTargets: string[] = [];
-    for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--client") {
-        const value = args[++i];
-        if (!value) throw new Error("--client requires a name");
-        clients.push(value);
-      } else if (args[i] === "--target") {
-        const value = args[++i];
-        if (!value) throw new Error("--target requires a name");
-        requestedTargets.push(value);
-      } else if (
-        args[i] !== "--yes" &&
-        args[i] !== "--dry-run" &&
-        args[i] !== "--json"
-      ) {
-        throw new Error(`unknown project ${subCommand} option: ${args[i]}`);
-      }
-    }
-    const { config, vaultPath, manifestPath, manifest } =
-      await loadManifestContext();
-    const clientTargets = configuredTargetsForClients(manifest, clients);
-    const targets = [...new Set([...requestedTargets, ...clientTargets])];
-    if (targets.length === 0) {
-      throw new Error(`project ${subCommand} requires --client or --target`);
-    }
-    const updated = updateProjectTargets(manifest, group, {
-      ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
-    });
-    validateManifest(
-      updated,
-      vaultPath,
-      config.local_vault_paths.map(expandHome),
-    );
-    if (options.dryRun) {
-      console.log(
-        `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
-      );
-      return;
-    }
-    if (
-      !(await confirmIfNeeded({
-        confirmed: args.includes("--yes"),
-        isJson: options.isJson,
-        prompt: `${subCommand} [project.${group}] to ${targets.join(", ")}?`,
-        nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
-      }))
-    )
-      return;
-    writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`);
-    return;
-  }
-  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
-  let request = parseProjectInitArgs(args);
-  const guided = shouldUseWizard(args, {
-    interactive: isInteractive(),
-    json: options.isJson,
-    dryRun: options.dryRun,
-  });
-  if (!existsSync(request.path))
-    throw new Error(`project path does not exist: ${request.path}`);
-  if (!lstatSync(request.path).isDirectory()) {
-    throw new Error(`project path is not a directory: ${request.path}`);
-  }
-
-  const { config, vaultPath, manifestPath, manifest } =
-    await loadManifestContext();
-  const localVaultPaths = config.local_vault_paths.map(expandHome);
-  if (guided) {
-    const name = await promptText("Project group", request.name);
-    const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
-      const surface = planClientSurfaces([client]).surfaces[0];
-      return (
-        surface !== undefined &&
-        configuredTargetForSurface(manifest, surface) !== undefined
-      );
-    });
-    const clients = await promptMultiSelect(
-      "Which clients should receive project skills?",
-      availableClients.map((client) => ({
-        value: client,
-        label: client,
-        selected:
-          request.clients.length === 0 || request.clients.includes(client),
-      })),
-    );
-    const skills = parseCommaList(
-      await promptText(
-        "Project skill IDs, comma-separated",
-        request.skills.join(","),
-      ),
-    );
-    request = { ...request, name, clients, skills };
-  }
-  const clientTargets = configuredTargetsForClients(manifest, request.clients);
-  const targets = [...new Set([...request.targets, ...clientTargets])];
-  const updated = upsertProject(manifest, {
-    name: request.name,
-    paths: [request.path],
-    skills: request.skills,
-    targets,
-  });
-  const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
-  const plan = {
-    mode: "project",
-    project: request.name,
-    path: request.path,
-    skills: request.skills,
-    clients: request.clients,
-    targets,
-    sync: request.sync,
-    notes,
-  };
-
-  if (options.dryRun) {
-    console.log(
-      options.isJson
-        ? JSON.stringify({ schema_version: 1, plan })
-        : `project plan: ${JSON.stringify(plan)}`,
-    );
-    return;
-  }
-  if (!request.yes) {
-    if (!options.isJson && isInteractive()) {
-      if (guided) {
-        console.log("\nReview");
-        console.log(`  project: ${request.name}`);
-        console.log(`  path: ${request.path}`);
-        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
-        console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
-        console.log(`  sync: ${request.sync ? "yes" : "no"}`);
-      }
-      if (
-        !(await confirmAction(
-          `Apply project setup for ${request.name} at ${request.path}?`,
-        ))
-      ) {
-        console.log("project setup cancelled");
-        return;
-      }
-    } else {
-      throw new Error(
-        "skillmux project init requires --yes when run non-interactively",
-      );
-    }
-  }
-
-  writeManifestAtomic(manifestPath, updated);
-  if (request.sync) {
-    try {
-      await runSync([]);
-    } catch (error) {
-      throw new Error(
-        `project configuration was saved, but sync failed; fix the reported issue and run "skillmux sync": ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  }
-  if (options.isJson) {
-    console.log(JSON.stringify({ schema_version: 1, result: plan }));
-  } else {
-    console.log(`project "${request.name}" ready at ${request.path}`);
-  }
-}
-
-async function runCore(
-  subCommand: string,
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean },
-): Promise<void> {
-  if (subCommand !== "pin" && subCommand !== "unpin") {
-    throw new Error("usage: skillmux core <pin|unpin>");
-  }
-  const skillIds = args.filter((arg) => !arg.startsWith("-"));
-  if (skillIds.length === 0) {
-    throw new Error(`usage: skillmux core ${subCommand} <skill_id>... --yes`);
-  }
-  const yes = args.includes("--yes");
-  const { config, vaultPath, manifestPath, manifest } =
-    await loadManifestContext();
-  let updated = manifest;
-  for (const skillId of skillIds) {
-    updated =
-      subCommand === "pin"
-        ? pinCore(updated, skillId)
-        : unpinCore(updated, skillId);
-  }
-  validateManifest(
-    updated,
-    vaultPath,
-    config.local_vault_paths.map(expandHome),
-  );
-  if (options.dryRun) {
-    emitSuccess(
-      { isJson: options.isJson },
-      { subcommand: subCommand, skill_ids: skillIds },
-      () =>
-        console.log(`${subCommand}: [core] ${skillIds.join(", ")} (dry-run)`),
-    );
-    return;
-  }
-  if (
-    !(await confirmIfNeeded({
-      confirmed: yes,
-      isJson: options.isJson,
-      prompt: `${subCommand} ${skillIds.join(", ")} in [core]?`,
-      nonInteractiveError: `skillmux core ${subCommand} requires --yes when run non-interactively`,
-    }))
-  )
-    return;
-  writeManifestAtomic(manifestPath, updated);
-  console.log(`${subCommand}: [core] ${skillIds.join(", ")}`);
-}
-
-async function runTarget(
-  subCommand: string,
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean },
-): Promise<void> {
-  const { vaultPath, manifestPath, manifest } = await loadManifestContext();
-
-  if (subCommand === "list" || subCommand === "show") {
-    const names =
-      subCommand === "show" ? [args[0] ?? ""] : Object.keys(manifest.targets);
-    if (subCommand === "show" && !manifest.targets[names[0]!]) {
-      throw new Error(`target "${names[0]}" does not exist`);
-    }
-    const targets = names.map((name) => {
-      const target = manifest.targets[name]!;
-      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
-        const surface = planClientSurfaces([client]).surfaces[0];
-        return surface !== undefined && surface.path === expandHome(target.dir);
-      });
-      return { name, ...target, clients };
-    });
-    if (options.isJson) {
-      console.log(JSON.stringify({ schema_version: 1, targets }));
-    } else if (targets.length === 0) {
-      console.log("no targets configured");
-    } else {
-      for (const target of targets) {
-        console.log(`${target.name}:`);
-        console.log(`  dir: ${target.dir}`);
-        console.log(`  host: ${target.host ?? "(global)"}`);
-        console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
-        console.log(
-          `  projects: ${target.project_groups.join(", ") || "(none)"}`,
-        );
-      }
-    }
-    return;
-  }
-
-  if (subCommand === "add") {
-    const name = args[0];
-    const dirIndex = args.indexOf("--dir");
-    const rawPath = dirIndex === -1 ? undefined : args[dirIndex + 1];
-    if (!name || !rawPath)
-      throw new Error("usage: skillmux target add <name> --dir <dir> --yes");
-    const path = expandHome(rawPath);
-    if (options.dryRun) {
-      const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
-      console.log(
-        options.isJson
-          ? JSON.stringify({ schema_version: 1, target: planned.targets[name] })
-          : `target add: ${name} -> ${path} (dry-run)`,
-      );
-      return;
-    }
-    if (
-      !(await confirmIfNeeded({
-        confirmed: args.includes("--yes"),
-        isJson: options.isJson,
-        prompt: `Adopt target ${name} at ${path}?`,
-        nonInteractiveError:
-          "skillmux target add requires --yes when run non-interactively",
-      }))
-    )
-      return;
-    applyInit(vaultPath, [{ name, dir: path }]);
-    console.log(`target "${name}" added at ${path}`);
-    return;
-  }
-
-  if (subCommand === "remove") {
-    const name = args[0];
-    if (!name || !manifest.targets[name]) {
-      throw new Error(
-        name
-          ? `target "${name}" does not exist`
-          : "usage: skillmux target remove <name> --yes",
-      );
-    }
-    if (options.dryRun) {
-      console.log(`target remove: ${name} (files preserved, dry-run)`);
-      return;
-    }
-    if (
-      !(await confirmIfNeeded({
-        confirmed: args.includes("--yes"),
-        isJson: options.isJson,
-        prompt: `Remove target ${name} from the manifest and preserve its files?`,
-        nonInteractiveError:
-          "skillmux target remove requires --yes when run non-interactively",
-      }))
-    )
-      return;
-    const targets = { ...manifest.targets };
-    delete targets[name];
-    writeManifestAtomic(manifestPath, { ...manifest, targets });
-    console.log(
-      `target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`,
-    );
-    return;
-  }
-
-  throw new Error("usage: skillmux target <list|show|add|remove>");
-}
-
 async function runLocalVaultInit(
   args: string[],
   options: { isJson: boolean; dryRun: boolean },
@@ -1438,14 +698,16 @@ async function runLocalVaultInit(
   if (!existsSync(expanded)) throw new Error(`"${path}" does not exist`);
   const markerPath = join(expanded, ".skillmux");
   if (options.dryRun) {
-    console.log(
-      options.isJson
-        ? JSON.stringify({
-            schema_version: 1,
-            marker_path: markerPath,
-            vault_path: expandHome(config.vault_path),
-          })
-        : `local-vault init: ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)}) (dry-run)`,
+    emitSuccess(
+      { isJson: options.isJson },
+      {
+        marker_path: markerPath,
+        vault_path: expandHome(config.vault_path),
+      },
+      () =>
+        console.log(
+          `local-vault init: ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)}) (dry-run)`,
+        ),
     );
     return;
   }
@@ -1460,19 +722,17 @@ async function runLocalVaultInit(
   )
     return;
   writeLocalVaultMarker(expanded, expandHome(config.vault_path));
-  if (options.isJson) {
-    console.log(
-      JSON.stringify({
-        schema_version: 1,
-        marker_path: markerPath,
-        vault_path: expandHome(config.vault_path),
-      }),
-    );
-  } else {
-    console.log(
-      `wrote ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`,
-    );
-  }
+  emitSuccess(
+    { isJson: options.isJson },
+    {
+      marker_path: markerPath,
+      vault_path: expandHome(config.vault_path),
+    },
+    () =>
+      console.log(
+        `wrote ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`,
+      ),
+  );
 }
 
 async function runModelDownload(options: { isJson: boolean }): Promise<void> {