agent-trellis 0.2.0 → 0.3.0

package/dist/cli.js

@@ -9,11 +9,13 @@ import { runInit } from "./commands/init.js";
 import { runMigrate } from "./commands/migrate.js";
 import { runOnboard } from "./commands/onboard.js";
 import { runSync } from "./commands/sync.js";
-import { runMcpSync } from "./commands/mcp.js";
+import { runMcpSync, runMcpList, runMcpAdd, runMcpRemove, parseMcpAddArgs } from "./commands/mcp.js";
 import { runSecretsAudit } from "./commands/secretsAudit.js";
 import { runRollback } from "./commands/rollback.js";
+import { runSkillList, runSkillAdd, runSkillRemove } from "./commands/skill.js";
+import { runMemorySync } from "./commands/memory.js";
 import { parseSyncArgs } from "./lib/syncArgs.js";
-const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "secrets", "rollback"];
+const KNOWN_COMMANDS = ["onboard", "init", "migrate", "doctor", "sync", "mcp", "skill", "memory", "secrets", "rollback"];
 function printUsage() {
     console.log(`trellis - a single source of capability for every coding agent
 
@@ -41,9 +43,12 @@ Commands:
               missing) and prints which agents are present
               --json    machine-readable output, no report text
   migrate --from <agent>
-            Import an existing agent's real skills/instructions into
-            canonical source (claude-code | codex | kiro | pi). Never
-            overwrites differing content — reports a conflict instead.
+            Import an existing agent's real skills/instructions/MCP
+            servers into canonical source (claude-code | codex | kiro |
+            pi — pi has no static MCP config, mcp migrate-in is a no-op
+            for it). Never overwrites differing content — reports a
+            conflict instead.
+              --only skills|instructions|mcp   restrict to one category
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   doctor    Scan Claude Code / Codex / Kiro / pi for drift
@@ -56,7 +61,47 @@ Commands:
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   mcp sync  Distribute MCP servers to each agent's native config
-              (create/repair only — no automatic removal, see docs/roadmap.md)
+              (create/repair, plus ownership-ledger-gated removal — an
+              entry is only ever removed when it's still exactly what
+              Trellis itself last wrote there; see docs/roadmap.md)
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
+  mcp list  List canonical MCP servers (transport, scope, enabled;
+              never prints resolved secret values)
+              --json    machine-readable output, no report text
+  mcp add <name> --transport stdio|http|sse ...
+            Add a canonical MCP server (refuses on an existing name,
+              no overwrite): --command <cmd> [--args a,b] (stdio) or
+              --url <url> (http/sse); [--headers k=v,...]
+              [--env NAME,...] [--static-env k=v,...] [--agents id,...]
+              [--enabled true|false]
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
+  mcp remove <name>
+            Remove a canonical MCP server (canonical-side only — does
+              not touch any agent's already-synced native config)
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
+  skill list
+            List canonical skills with resolved scope
+              --json    machine-readable output, no report text
+  skill add <name> --from <path>
+            Import a real skill directory into canonical (refuses on
+              an existing name with different content, no overwrite)
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
+  skill remove <name>
+            Remove a canonical skill (the next sync auto-removes the
+              now-stale symlink on every managed agent)
+              --dry-run    preview the plan, write nothing
+              --json       machine-readable output, no report text
+  memory sync
+            Ingest canonical memories/*.md into the shared-memory MCP
+              server's own on-disk knowledge-graph file (requires a
+              "memory" server with static_env.MEMORY_FILE_PATH set in
+              servers.yaml — see schema/servers.example.yaml; a no-op,
+              not an error, if unconfigured). Never touches an entity
+              or relation this didn't create.
               --dry-run    preview the plan, write nothing
               --json       machine-readable output, no report text
   secrets audit
@@ -104,7 +149,9 @@ async function main(argv) {
     if (command === "migrate") {
         const fromIndex = rest.indexOf("--from");
         const from = fromIndex >= 0 ? rest[fromIndex + 1] : undefined;
-        const { exitCode } = await runMigrate({ from, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
+        const onlyIndex = rest.indexOf("--only");
+        const only = onlyIndex >= 0 ? rest[onlyIndex + 1] : undefined;
+        const { exitCode } = await runMigrate({ from, only, dryRun: rest.includes("--dry-run"), json: rest.includes("--json") });
         process.exitCode = exitCode;
         return;
     }
@@ -126,13 +173,79 @@ async function main(argv) {
         return;
     }
     if (command === "mcp") {
-        const [subcommand] = rest;
+        const [subcommand, ...mcpRest] = rest;
+        const json = mcpRest.includes("--json");
+        const dryRun = mcpRest.includes("--dry-run");
+        if (subcommand === "sync") {
+            const { exitCode } = await runMcpSync({ json, dryRun });
+            process.exitCode = exitCode;
+            return;
+        }
+        if (subcommand === "list") {
+            process.exitCode = runMcpList({ json }).exitCode;
+            return;
+        }
+        if (subcommand === "add") {
+            const [name] = mcpRest;
+            process.exitCode = runMcpAdd(name, parseMcpAddArgs(mcpRest), { json, dryRun }).exitCode;
+            return;
+        }
+        if (subcommand === "remove") {
+            const [name] = mcpRest;
+            if (!name) {
+                console.error("Usage: trellis mcp remove <name>");
+                process.exitCode = 1;
+                return;
+            }
+            process.exitCode = runMcpRemove(name, { json, dryRun }).exitCode;
+            return;
+        }
+        console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync|list|add <name>|remove <name>\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (command === "skill") {
+        const [subcommand, ...skillRest] = rest;
+        const json = skillRest.includes("--json");
+        const dryRun = skillRest.includes("--dry-run");
+        if (subcommand === "list") {
+            process.exitCode = runSkillList({ json }).exitCode;
+            return;
+        }
+        if (subcommand === "add") {
+            const [name] = skillRest;
+            const fromIndex = skillRest.indexOf("--from");
+            const from = fromIndex >= 0 ? skillRest[fromIndex + 1] : undefined;
+            if (!name || !from) {
+                console.error("Usage: trellis skill add <name> --from <path>");
+                process.exitCode = 1;
+                return;
+            }
+            process.exitCode = runSkillAdd(name, from, { json, dryRun }).exitCode;
+            return;
+        }
+        if (subcommand === "remove") {
+            const [name] = skillRest;
+            if (!name) {
+                console.error("Usage: trellis skill remove <name>");
+                process.exitCode = 1;
+                return;
+            }
+            process.exitCode = runSkillRemove(name, { json, dryRun }).exitCode;
+            return;
+        }
+        console.error(`Unknown skill subcommand: ${subcommand ?? "(none)"}\nUsage: trellis skill list|add <name> --from <path>|remove <name>\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (command === "memory") {
+        const [subcommand, ...memoryRest] = rest;
         if (subcommand !== "sync") {
-            console.error(`Unknown mcp subcommand: ${subcommand ?? "(none)"}\nUsage: trellis mcp sync\n`);
+            console.error(`Unknown memory subcommand: ${subcommand ?? "(none)"}\nUsage: trellis memory sync\n`);
             process.exitCode = 1;
             return;
         }
-        const { exitCode } = await runMcpSync({ json: rest.includes("--json"), dryRun: rest.includes("--dry-run") });
+        const { exitCode } = runMemorySync({ json: memoryRest.includes("--json"), dryRun: memoryRest.includes("--dry-run") });
         process.exitCode = exitCode;
         return;
     }

package/dist/commands/mcp.d.ts

@@ -1,13 +1,18 @@
 /**
- * `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;
@@ -39,3 +44,92 @@ export declare function runMcpSync(opts?: RunMcpSyncOptions): Promise<{
  * `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,13 +1,19 @@
 /**
- * `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";
@@ -80,15 +86,226 @@ export function printReport(report, dryRun) {
             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 };
+}