agent-trellis 0.1.0 → 0.3.0

package/dist/commands/mcp.d.ts

@@ -1,18 +1,32 @@
 /**
- * `trellis mcp sync` — loads canonical once, runs every present agent's
- * adapter, applies only the "mcp" slice of its plan, and reports what
- * happened. Same create/repair/refuse shape as `src/commands/sync.ts`,
- * kept as a separate command because MCP has no ownership marker for
- * automatic removal yet (trellis-mcp-sync-p2 design.md D7) — folding it
- * into bare `trellis sync` would blur that distinction.
+ * `trellis mcp sync|list|add|remove` — `sync` loads canonical once, runs
+ * every present agent's adapter, applies its full "mcp" plan (create,
+ * repair, and — since trellis-mcp-lifecycle-parity, ownership-ledger-
+ * gated — remove), and reports what happened. Kept as a separate
+ * command from bare `trellis sync` (skills/instructions) since the two
+ * have different write mechanisms entirely, not because MCP removal is
+ * unsafe (see `src/lib/mcpOwnership.ts`). `list`/`add`/`remove`
+ * (trellis-canonical-cli-crud) are canonical-side only — an alternative
+ * to hand-editing `~/.trellis/mcp/servers.yaml`, never touching any
+ * agent's native config (that stays `sync`'s job).
  */
+import { type ServersYamlWriteResult } from "../core/canonical.js";
 import type { AdapterPlanItem } from "../core/adapter.js";
-import type { AgentId } from "../core/types.js";
+import type { AgentId, McpServerDef, Transport } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
 export interface RunMcpSyncOptions {
     json?: boolean;
     /** Same test/sandbox-only seam as `RunSyncOptions.homeDir` — never a CLI
      * flag. See docs/architecture.md's testing philosophy. */
     homeDir?: string;
+    /** Compute and report the plan without calling adapter.apply(). */
+    dryRun?: boolean;
+    /** Onboard-only seam — see RunSyncOptions.managedAgents. Never a CLI
+     * flag. */
+    managedAgents?: readonly AgentId[];
+    /** Onboard-only seam — see RunSyncOptions.backupSession. Never a CLI
+     * flag. */
+    backupSession?: BackupSession;
 }
 export interface AgentMcpSyncReport {
     agent: AgentId;
@@ -26,3 +40,96 @@ export declare function collectMcpSyncReport(opts?: RunMcpSyncOptions): Promise<
 export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
     exitCode: number;
 }>;
+/** Exported so `onboard` prints an mcp-sync report identically to running
+ * `mcp sync` standalone, instead of a second, easily-drifting copy of this
+ * formatting. */
+export declare function printReport(report: McpSyncReport, dryRun: boolean): void;
+export interface McpListEntry {
+    name: string;
+    transport: Transport;
+    enabled: boolean;
+    agents: readonly AgentId[];
+    command?: string;
+    args?: string[];
+    url?: string;
+    /** Reference strings (e.g. `${VAR}`), not resolved secret values — see
+     * design.md D6. */
+    headers?: Record<string, string>;
+    /** Names only — `McpServerDef.env` never stores values in the first
+     * place, so there is nothing here to redact. */
+    env?: string[];
+    /** Non-secret by `McpServerDef`'s own contract (design.md D6) —
+     * printed in full. */
+    staticEnv?: Record<string, string>;
+}
+export declare function collectMcpListPlan(homeDir?: string): McpListEntry[];
+export declare function runMcpList(opts?: {
+    homeDir?: string;
+    json?: boolean;
+}): {
+    exitCode: number;
+};
+/** Raw, unvalidated CLI flag values — `collectMcpAddPlan` does the actual
+ * parsing/validation. Kept as plain strings here so `parseMcpAddArgs`
+ * stays a dumb `--flag value` reader, same posture as every other
+ * command's own inline flag parsing in src/cli.ts. */
+export interface McpAddRawArgs {
+    transport?: string;
+    command?: string;
+    /** Comma-separated. */
+    args?: string;
+    url?: string;
+    /** Comma-separated `k=v` pairs. */
+    headers?: string;
+    /** Comma-separated names. */
+    env?: string;
+    /** Comma-separated `k=v` pairs. */
+    staticEnv?: string;
+    /** Comma-separated agent ids. */
+    agents?: string;
+    /** `"true"` or `"false"`. */
+    enabled?: string;
+}
+export declare function parseMcpAddArgs(argv: readonly string[]): McpAddRawArgs;
+export type McpAddAction = "create" | "already-present" | "conflict" | "invalid-input";
+export interface McpAddPlan {
+    name: string;
+    action: McpAddAction;
+    detail: string;
+    /** Only set when action === "create"; consumed by applyMcpAddPlan. */
+    def?: McpServerDef;
+}
+/**
+ * Validates transport-specific required flags at this layer (stdio needs
+ * `--command`, http/sse need `--url`) rather than deferring to a later
+ * write failure — design.md's open question, resolved in favor of
+ * refusing early with a specific reason. No `--force`: an existing name
+ * always refuses, ever (design.md D4).
+ */
+export declare function collectMcpAddPlan(name: string | undefined, raw: McpAddRawArgs, homeDir?: string): McpAddPlan;
+export declare function applyMcpAddPlan(plan: McpAddPlan, homeDir?: string): ServersYamlWriteResult;
+export declare function runMcpAdd(name: string | undefined, raw: McpAddRawArgs, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};
+export type McpRemoveAction = "removed" | "not-found";
+export interface McpRemovePlan {
+    name: string;
+    action: McpRemoveAction;
+}
+/** Canonical-side only — never touches an agent's native config. Making
+ * an already-synced agent forget it is `mcp sync`'s own removal-
+ * propagation gap, tracked separately (roadmap.md P14), not this
+ * command's job. */
+export declare function collectMcpRemovePlan(name: string, homeDir?: string): McpRemovePlan;
+export declare function applyMcpRemovePlan(plan: McpRemovePlan, homeDir?: string): ServersYamlWriteResult;
+export declare function runMcpRemove(name: string, opts?: {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}): {
+    exitCode: number;
+};

package/dist/commands/mcp.js

@@ -1,34 +1,55 @@
 /**
- * `trellis mcp sync` — loads canonical once, runs every present agent's
- * adapter, applies only the "mcp" slice of its plan, and reports what
- * happened. Same create/repair/refuse shape as `src/commands/sync.ts`,
- * kept as a separate command because MCP has no ownership marker for
- * automatic removal yet (trellis-mcp-sync-p2 design.md D7) — folding it
- * into bare `trellis sync` would blur that distinction.
+ * `trellis mcp sync|list|add|remove` — `sync` loads canonical once, runs
+ * every present agent's adapter, applies its full "mcp" plan (create,
+ * repair, and — since trellis-mcp-lifecycle-parity, ownership-ledger-
+ * gated — remove), and reports what happened. Kept as a separate
+ * command from bare `trellis sync` (skills/instructions) since the two
+ * have different write mechanisms entirely, not because MCP removal is
+ * unsafe (see `src/lib/mcpOwnership.ts`). `list`/`add`/`remove`
+ * (trellis-canonical-cli-crud) are canonical-side only — an alternative
+ * to hand-editing `~/.trellis/mcp/servers.yaml`, never touching any
+ * agent's native config (that stays `sync`'s job).
  */
 import { homedir } from "node:os";
-import { loadCanonicalSource } from "../core/canonical.js";
+import { join } from "node:path";
+import { loadCanonicalSource, upsertServerYaml, removeServerYaml } from "../core/canonical.js";
+import { ALL_AGENTS, resolveScope } from "../core/types.js";
 import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
 import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { PiAdapter } from "../adapters/pi.js";
-function buildAdapters(homeDir) {
-    return [new ClaudeCodeAdapter(homeDir), new CodexAdapter(homeDir), new KiroAdapter(homeDir), new PiAdapter(homeDir)];
+import { openBackupSession } from "../lib/backup.js";
+const ADAPTER_FACTORY = {
+    "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
+    codex: (homeDir) => new CodexAdapter(homeDir),
+    kiro: (homeDir) => new KiroAdapter(homeDir),
+    pi: (homeDir) => new PiAdapter(homeDir),
+};
+/** Only agents in `canonical.managedAgents` — see src/commands/sync.ts's
+ * own copy of this same restriction (trellis-managed-agents). */
+function buildAdapters(homeDir, managedAgents) {
+    return managedAgents.map((id) => ADAPTER_FACTORY[id](homeDir));
 }
 export async function collectMcpSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const canonical = loadCanonicalSource(homeDir);
+    const loaded = loadCanonicalSource(homeDir);
+    const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
-    for (const adapter of buildAdapters(homeDir)) {
+    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "mcp-sync") : undefined;
+    const backup = opts.backupSession ?? ownSession;
+    for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
         if (!probeResult.present) {
             reports.push({ agent: adapter.id, present: false, items: [] });
             continue;
         }
         const items = (await adapter.plan(canonical)).filter((item) => item.kind === "mcp");
-        await adapter.apply(items);
+        if (!opts.dryRun) {
+            await adapter.apply(items, backup);
+        }
         reports.push({ agent: adapter.id, present: true, items });
     }
+    ownSession?.finalize();
     return { reports };
 }
 export async function runMcpSync(opts = {}) {
@@ -44,27 +65,247 @@ export async function runMcpSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report);
+        printReport(report, opts.dryRun ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
     return { exitCode: hasConflict ? 1 : 0 };
 }
-function printReport(report) {
+/** Exported so `onboard` prints an mcp-sync report identically to running
+ * `mcp sync` standalone, instead of a second, easily-drifting copy of this
+ * formatting. */
+export function printReport(report, dryRun) {
+    if (dryRun)
+        console.log("[dry run]");
+    if (report.reports.length === 0) {
+        console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
+        return;
+    }
     for (const { agent, present, items } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
         }
         const created = items.filter((i) => i.action === "create");
+        const removed = items.filter((i) => i.action === "remove");
         const conflicts = items.filter((i) => i.action === "conflict");
-        if (created.length === 0 && conflicts.length === 0) {
+        if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
             console.log(`✅ ${agent} — already in sync`);
             continue;
         }
         const icon = conflicts.length > 0 ? "⚠️ " : "✅";
-        console.log(`${icon} ${agent} — ${created.length} created/updated, ${conflicts.length} conflict(s)`);
-        for (const item of [...created, ...conflicts]) {
+        console.log(`${icon} ${agent} — ${created.length} created/updated, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+        for (const item of [...created, ...removed, ...conflicts]) {
             console.log(`   - [${item.action}] ${item.description}`);
         }
     }
 }
+function serversYamlPath(homeDir) {
+    return join(homeDir, ".trellis", "mcp", "servers.yaml");
+}
+export function collectMcpListPlan(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return Object.entries(canonical.mcp.servers).map(([name, def]) => ({
+        name,
+        transport: def.transport,
+        enabled: def.enabled ?? true,
+        agents: resolveScope(def.agents, canonical.managedAgents),
+        command: def.command,
+        args: def.args,
+        url: def.url,
+        headers: def.headers,
+        env: def.env,
+        staticEnv: def.staticEnv,
+    }));
+}
+export function runMcpList(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let entries;
+    try {
+        entries = collectMcpListPlan(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(entries, null, 2));
+    }
+    else if (entries.length === 0) {
+        console.log("No MCP servers in canonical source yet.");
+    }
+    else {
+        for (const e of entries) {
+            const scope = e.agents.length > 0 ? e.agents.join(", ") : "(no managed agent reaches it)";
+            console.log(`${e.name} (${e.transport})${e.enabled ? "" : " [disabled]"} — ${scope}`);
+            if (e.env && e.env.length > 0)
+                console.log(`   env: ${e.env.join(", ")} (values never read/printed)`);
+            if (e.staticEnv)
+                console.log(`   static_env: ${Object.entries(e.staticEnv).map(([k, v]) => `${k}=${v}`).join(", ")}`);
+        }
+    }
+    return { exitCode: 0 };
+}
+export function parseMcpAddArgs(argv) {
+    const flag = (name) => {
+        const i = argv.indexOf(name);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    return {
+        transport: flag("--transport"),
+        command: flag("--command"),
+        args: flag("--args"),
+        url: flag("--url"),
+        headers: flag("--headers"),
+        env: flag("--env"),
+        staticEnv: flag("--static-env"),
+        agents: flag("--agents"),
+        enabled: flag("--enabled"),
+    };
+}
+function parseCsv(raw) {
+    if (!raw)
+        return undefined;
+    const items = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+function parseKvList(raw) {
+    if (!raw)
+        return undefined;
+    const out = {};
+    for (const pair of raw.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            continue;
+        out[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+const TRANSPORTS = ["stdio", "http", "sse"];
+/**
+ * Validates transport-specific required flags at this layer (stdio needs
+ * `--command`, http/sse need `--url`) rather than deferring to a later
+ * write failure — design.md's open question, resolved in favor of
+ * refusing early with a specific reason. No `--force`: an existing name
+ * always refuses, ever (design.md D4).
+ */
+export function collectMcpAddPlan(name, raw, homeDir = homedir()) {
+    if (!name) {
+        return { name: "(none)", action: "invalid-input", detail: "a name is required: trellis mcp add <name> --transport ..." };
+    }
+    if (!raw.transport || !TRANSPORTS.includes(raw.transport)) {
+        return { name, action: "invalid-input", detail: `--transport must be one of: ${TRANSPORTS.join(", ")}` };
+    }
+    const transport = raw.transport;
+    if (transport === "stdio" && !raw.command) {
+        return { name, action: "invalid-input", detail: "--transport stdio requires --command" };
+    }
+    if ((transport === "http" || transport === "sse") && !raw.url) {
+        return { name, action: "invalid-input", detail: `--transport ${transport} requires --url` };
+    }
+    const agentsList = parseCsv(raw.agents);
+    if (agentsList) {
+        for (const id of agentsList) {
+            if (!ALL_AGENTS.includes(id)) {
+                return { name, action: "invalid-input", detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` };
+            }
+        }
+    }
+    if (raw.enabled !== undefined && raw.enabled !== "true" && raw.enabled !== "false") {
+        return { name, action: "invalid-input", detail: `--enabled must be "true" or "false" (got ${raw.enabled})` };
+    }
+    const def = {
+        transport,
+        ...(raw.command ? { command: raw.command } : {}),
+        ...(parseCsv(raw.args) ? { args: parseCsv(raw.args) } : {}),
+        ...(raw.url ? { url: raw.url } : {}),
+        ...(parseKvList(raw.headers) ? { headers: parseKvList(raw.headers) } : {}),
+        ...(parseCsv(raw.env) ? { env: parseCsv(raw.env) } : {}),
+        ...(parseKvList(raw.staticEnv) ? { staticEnv: parseKvList(raw.staticEnv) } : {}),
+        ...(raw.enabled !== undefined ? { enabled: raw.enabled === "true" } : {}),
+        ...(agentsList ? { agents: agentsList } : {}),
+    };
+    const canonical = loadCanonicalSource(homeDir);
+    const existing = canonical.mcp.servers[name];
+    if (existing) {
+        if (JSON.stringify(existing) === JSON.stringify(def)) {
+            return { name, action: "already-present", detail: "canonical entry is already identical" };
+        }
+        return { name, action: "conflict", detail: `servers.yaml already has "${name}" with different settings — resolve by hand (no --force, design.md D4)` };
+    }
+    return { name, action: "create", detail: "will add to servers.yaml", def };
+}
+export function applyMcpAddPlan(plan, homeDir = homedir()) {
+    if (plan.action !== "create" || !plan.def)
+        return { ok: true };
+    return upsertServerYaml(serversYamlPath(homeDir), plan.name, plan.def);
+}
+export function runMcpAdd(name, raw, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let plan;
+    try {
+        plan = collectMcpAddPlan(name, raw, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    let writeError;
+    if (!opts.dryRun && plan.action === "create") {
+        const result = applyMcpAddPlan(plan, homeDir);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(writeError ? { ...plan, writeError } : plan, null, 2));
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}mcp add ${plan.name}`);
+        console.log(`  [${plan.action}] ${plan.detail}`);
+        if (writeError)
+            console.error(`  write failed: ${writeError}`);
+    }
+    return { exitCode: plan.action === "conflict" || plan.action === "invalid-input" || writeError ? 1 : 0 };
+}
+/** Canonical-side only — never touches an agent's native config. Making
+ * an already-synced agent forget it is `mcp sync`'s own removal-
+ * propagation gap, tracked separately (roadmap.md P14), not this
+ * command's job. */
+export function collectMcpRemovePlan(name, homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    return { name, action: canonical.mcp.servers[name] ? "removed" : "not-found" };
+}
+export function applyMcpRemovePlan(plan, homeDir = homedir()) {
+    if (plan.action !== "removed")
+        return { ok: true };
+    return removeServerYaml(serversYamlPath(homeDir), plan.name);
+}
+export function runMcpRemove(name, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let plan;
+    try {
+        plan = collectMcpRemovePlan(name, homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    let writeError;
+    if (!opts.dryRun && plan.action === "removed") {
+        const result = applyMcpRemovePlan(plan, homeDir);
+        if (!result.ok)
+            writeError = result.error;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(writeError ? { ...plan, writeError } : plan, null, 2));
+    }
+    else if (plan.action === "not-found") {
+        console.error(`"${name}" is not a canonical MCP server — nothing to remove.`);
+    }
+    else if (writeError) {
+        console.error(`  write failed: ${writeError}`);
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}removed MCP server "${name}" from canonical source.`);
+    }
+    return { exitCode: plan.action === "not-found" || writeError ? 1 : 0 };
+}

package/dist/commands/memory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `trellis memory sync` — ingests canonical `memories/*.md` into the
+ * on-disk knowledge-graph file `@modelcontextprotocol/server-memory`
+ * itself reads at startup, closing P6's explicitly-left-open "auto-
+ * ingesting memories/*.md content into the running memory server's
+ * store" gap (trellis-memory-sync). Never spawns or talks to a running
+ * server process — this is a plain file write, same posture as every
+ * other Trellis write.
+ */
+import { type MemorySyncPlan } from "../lib/memoryGraph.js";
+export interface RunMemorySyncOptions {
+    homeDir?: string;
+    json?: boolean;
+    dryRun?: boolean;
+}
+export type MemorySyncResult = {
+    configured: true;
+    graphPath: string;
+    plan: MemorySyncPlan;
+} | {
+    configured: false;
+    reason: string;
+};
+/**
+ * Looks up `mcp.servers["memory"]` specifically (matching `schema/
+ * servers.example.yaml`'s own naming convention for the default shared-
+ * memory backend) — not a heuristic scan for any server whose command
+ * happens to mention `@modelcontextprotocol/server-memory`, since a
+ * user could reasonably name or configure it differently and this
+ * would then silently miss it. `static_env.MEMORY_FILE_PATH` must be
+ * set explicitly: the server's own unset-env default resolves relative
+ * to wherever `npx` cached the package, a location Trellis has no
+ * reliable way to predict.
+ */
+export declare function collectMemorySyncResult(homeDir?: string): MemorySyncResult;
+export declare function applyMemorySync(result: MemorySyncResult): void;
+export declare function runMemorySync(opts?: RunMemorySyncOptions): {
+    exitCode: number;
+};

package/dist/commands/memory.js

@@ -0,0 +1,78 @@
+/**
+ * `trellis memory sync` — ingests canonical `memories/*.md` into the
+ * on-disk knowledge-graph file `@modelcontextprotocol/server-memory`
+ * itself reads at startup, closing P6's explicitly-left-open "auto-
+ * ingesting memories/*.md content into the running memory server's
+ * store" gap (trellis-memory-sync). Never spawns or talks to a running
+ * server process — this is a plain file write, same posture as every
+ * other Trellis write.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { planMemorySync, renderMemoryGraph } from "../lib/memoryGraph.js";
+const MEMORY_SERVER_NAME = "memory";
+/**
+ * Looks up `mcp.servers["memory"]` specifically (matching `schema/
+ * servers.example.yaml`'s own naming convention for the default shared-
+ * memory backend) — not a heuristic scan for any server whose command
+ * happens to mention `@modelcontextprotocol/server-memory`, since a
+ * user could reasonably name or configure it differently and this
+ * would then silently miss it. `static_env.MEMORY_FILE_PATH` must be
+ * set explicitly: the server's own unset-env default resolves relative
+ * to wherever `npx` cached the package, a location Trellis has no
+ * reliable way to predict.
+ */
+export function collectMemorySyncResult(homeDir = homedir()) {
+    const canonical = loadCanonicalSource(homeDir);
+    const server = canonical.mcp.servers[MEMORY_SERVER_NAME];
+    const rawPath = server?.staticEnv?.MEMORY_FILE_PATH;
+    if (!server || !rawPath) {
+        return {
+            configured: false,
+            reason: `no "${MEMORY_SERVER_NAME}" MCP server with static_env.MEMORY_FILE_PATH configured in servers.yaml — see schema/servers.example.yaml`,
+        };
+    }
+    const graphPath = rawPath.replace(/^~(?=$|\/)/, homeDir);
+    const currentContent = existsSync(graphPath) ? readFileSync(graphPath, "utf-8") : undefined;
+    const plan = planMemorySync(canonical, currentContent);
+    return { configured: true, graphPath, plan };
+}
+export function applyMemorySync(result) {
+    if (!result.configured || !result.plan.nextGraph)
+        return;
+    mkdirSync(dirname(result.graphPath), { recursive: true });
+    writeFileSync(result.graphPath, renderMemoryGraph(result.plan.nextGraph));
+}
+export function runMemorySync(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    let result;
+    try {
+        result = collectMemorySyncResult(homeDir);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        applyMemorySync(result);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (!result.configured) {
+        console.log(result.reason);
+    }
+    else {
+        console.log(`${opts.dryRun ? "[dry run] " : ""}memory sync — ${result.graphPath}`);
+        if (result.plan.items.length === 0) {
+            console.log("  nothing in canonical memories/ yet");
+        }
+        for (const item of result.plan.items) {
+            console.log(`  [${item.action}] "${item.name}" — ${item.detail}`);
+        }
+    }
+    const hasConflict = result.configured && result.plan.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}

package/dist/commands/migrate.d.ts

@@ -4,26 +4,52 @@
  * Pure `collectMigratePlan` / effectful `applyMigratePlan`, same
  * plan-then-apply split every adapter already uses.
  */
-import type { AgentId } from "../core/types.js";
-export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "already-migrated" | "conflict";
+import type { AgentId, McpServerDef } from "../core/types.js";
+export type MigrateAction = "create" | "skip-symlink" | "skip-case-broken" | "skip-unsupported" | "already-migrated" | "conflict";
+/** Internal kind naming, unchanged since before `--only` existed
+ * (trellis-migrate-category-selection design.md D2) — the CLI-facing
+ * flag value is the plural `"skills"`, mapped to this singular `"skill"`
+ * in `runMigrate`, not renamed here to avoid touching every existing
+ * `MigratePlanItem.kind` comparison for no functional reason. */
+export type MigrateKind = "skill" | "instructions" | "mcp";
 export interface MigratePlanItem {
-    kind: "skill" | "instructions";
+    kind: MigrateKind;
     name: string;
     action: MigrateAction;
     detail: string;
     /** Only set when action === "create"; consumed by applyMigratePlan. */
     sourceDir?: string;
     sourceContent?: string;
+    /** Only set when kind === "mcp" && action === "create". */
+    mcpDef?: McpServerDef;
 }
 export interface MigratePlan {
     agent: AgentId;
     present: boolean;
     items: MigratePlanItem[];
 }
-export declare function collectMigratePlan(agent: AgentId, homeDir?: string): Promise<MigratePlan>;
+/**
+ * `only` restricts which kind(s) are even considered — not a post-hoc
+ * filter on a fully-computed plan (trellis-migrate-category-selection
+ * design.md D3): the excluded kind's canonical path is never read for
+ * comparison and never appears in the plan, not even as a suppressed
+ * conflict. Omitting `only` (or passing both kinds) is exactly today's
+ * behavior.
+ */
+export declare function collectMigratePlan(agent: AgentId, homeDir?: string, only?: readonly MigrateKind[]): Promise<MigratePlan>;
 export declare function applyMigratePlan(plan: MigratePlan, homeDir?: string): void;
+/** CLI-facing spelling: `"skills"` (plural — a run usually touches more
+ * than one), `"instructions"` (already singular-shaped), or `"mcp"`
+ * (already the CLI's own convention, matching `trellis mcp`'s own
+ * command name). Mapped to `MigrateKind` in `runMigrate`, the one place
+ * this translation lives. */
+export type MigrateOnlyValue = "skills" | "instructions" | "mcp";
 export interface RunMigrateOptions {
     from?: string;
+    /** Restricts the run to one category (`"skills"`, `"instructions"`, or
+     * `"mcp"`, raw and unvalidated same as `from` — `runMigrate` checks
+     * it). `undefined` means all three, exactly as before `"mcp"` existed. */
+    only?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */