agent-trellis 0.1.0 → 0.2.0

package/dist/commands/init.js

@@ -71,6 +71,16 @@ reject_patterns:
 ${patternLines}
 `;
 }
+/** Zero managed agents is the correct starting point (trellis-managed-agents
+ * design.md D1) — `trellis onboard`'s managed-set selection is what
+ * populates this, never `init` guessing on its behalf. */
+function managedYamlTemplate() {
+    return `# Agents Trellis is authorized to write to. Empty means none yet —
+# run \`trellis onboard\` or list agent ids here yourself, e.g.:
+# agents: [pi, codex]
+agents: []
+`;
+}
 /**
  * Trellis never spawns an installer itself (global package installs are
  * exactly the kind of irreversible, system-wide action that needs the
@@ -102,6 +112,7 @@ export async function collectInitReport(homeDir = homedir()) {
         ensureFile(join(root, "agents.md"), AGENTS_MD_TEMPLATE),
         ensureFile(join(root, "mcp", "servers.yaml"), serversYamlTemplate()),
         ensureFile(join(root, "secrets.policy.yaml"), secretsPolicyYamlTemplate()),
+        ensureFile(join(root, "managed.yaml"), managedYamlTemplate()),
     ];
     const probes = [
         { agent: "claude-code", run: () => claudeCodeProbe.probe(homeDir) },

package/dist/commands/mcp.d.ts

@@ -8,11 +8,20 @@
  */
 import type { AdapterPlanItem } from "../core/adapter.js";
 import type { AgentId } 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 +35,7 @@ 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;

package/dist/commands/mcp.js

@@ -12,23 +12,38 @@ 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,12 +59,21 @@ 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)`);

package/dist/commands/onboard.d.ts

@@ -1,13 +1,22 @@
 /**
- * `trellis onboard` — chains `init` → agent detection → base-agent
- * resolution → `migrate` → `sync` into one guided flow
- * (trellis-cli-onboard). Orchestrates existing commands' own
- * plan/apply logic; no new skill-copy, symlink, or conflict-detection
- * judgment is made here.
+ * `trellis onboard` — chains `init` → agent detection → migration-source
+ * resolution → managed-agent-set selection (install-then-manage for a
+ * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
+ * `secrets audit` into one guided flow (trellis-cli-onboard,
+ * trellis-managed-agents) — a user should never have to type a second
+ * command by hand to finish onboarding. Source and managed set are
+ * independent choices (design.md D2): importing from a source never
+ * writes back to it, and it is not implicitly added to the managed set.
+ * Orchestrates existing commands' own plan/apply logic; no new
+ * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
+ * is made here.
  */
 import type { AgentId } from "../core/types.js";
 import type { MigratePlan } from "./migrate.js";
 import type { SyncReport } from "./sync.js";
+import type { McpSyncReport } from "./mcp.js";
+import type { SecretsAuditReport } from "./secretsAudit.js";
+import type { ConfirmAndInstallOptions } from "../lib/installAgent.js";
 export interface OnboardAgentSummary {
     agent: AgentId;
     present: boolean;
@@ -20,7 +29,12 @@ export interface OnboardAgentSummary {
 }
 export declare function collectOnboardSummary(homeDir?: string): Promise<OnboardAgentSummary[]>;
 export interface RunOnboardOptions {
+    /** Non-interactive migration-source choice. */
     agent?: string;
+    /** Non-interactive managed-set choice: comma-separated agent ids, or
+     * the literal string "none" for "add nothing new this run" — distinct
+     * from omitting the flag, which requires a prompt or refuses. */
+    manage?: string;
     dryRun?: boolean;
     json?: boolean;
     /** Defaults to the real `~`; overridable for tests only. */
@@ -31,13 +45,34 @@ export interface RunOnboardOptions {
     /** Test-only: replaces the real readline prompt with a scripted
      * answer, so the prompt path is exercisable without a real terminal. */
     promptForAgent?: (present: OnboardAgentSummary[]) => Promise<string>;
+    /** Test-only: replaces the real readline multi-select prompt. Returns
+     * the raw answer string (same grammar as `--manage`'s value), not a
+     * pre-parsed list — so the same parsing/validation code path is
+     * exercised whether the answer came from a flag or a prompt. */
+    promptForManagedAgents?: (candidates: OnboardAgentSummary[], alreadyManaged: readonly AgentId[]) => Promise<string>;
+    /** Test-only: injected into every `confirmAndInstall` call for a
+     * selected, not-yet-present agent. Never a real terminal prompt or a
+     * real `npm install` in a unit test. */
+    install?: ConfirmAndInstallOptions;
+}
+export interface OnboardInstallResult {
+    agent: AgentId;
+    installed: boolean;
+    installable: boolean;
 }
 export interface OnboardResult {
     summary: OnboardAgentSummary[];
-    base?: AgentId;
-    baseReason?: "auto-selected" | "flag" | "prompt";
+    source?: AgentId;
+    sourceReason?: "auto-selected" | "flag" | "prompt";
+    /** The full managed set this run acted against — the union of whatever
+     * was already in `managed.yaml` plus this run's own new selections
+     * that actually resolved (D3: never a subtraction). */
+    managedAgents?: AgentId[];
+    installResults?: OnboardInstallResult[];
     migratePlan?: MigratePlan;
     syncReport?: SyncReport;
+    mcpSyncReport?: McpSyncReport;
+    secretsAuditReport?: SecretsAuditReport;
     refusal?: string;
     /** Only set when no agent is present — the same values `--json` and
      * text output both surface, so a machine caller doesn't have to

package/dist/commands/onboard.js

@@ -1,20 +1,33 @@
 /**
- * `trellis onboard` — chains `init` → agent detection → base-agent
- * resolution → `migrate` → `sync` into one guided flow
- * (trellis-cli-onboard). Orchestrates existing commands' own
- * plan/apply logic; no new skill-copy, symlink, or conflict-detection
- * judgment is made here.
+ * `trellis onboard` — chains `init` → agent detection → migration-source
+ * resolution → managed-agent-set selection (install-then-manage for a
+ * selected, not-yet-present agent) → `migrate` → `sync` → `mcp sync` →
+ * `secrets audit` into one guided flow (trellis-cli-onboard,
+ * trellis-managed-agents) — a user should never have to type a second
+ * command by hand to finish onboarding. Source and managed set are
+ * independent choices (design.md D2): importing from a source never
+ * writes back to it, and it is not implicitly added to the managed set.
+ * Orchestrates existing commands' own plan/apply logic; no new
+ * skill-copy, symlink, conflict-detection, or secrets-scanning judgment
+ * is made here.
  */
 import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
 import * as claudeCodeProbe from "../probes/claude-code.js";
 import * as codexProbe from "../probes/codex.js";
 import * as kiroProbe from "../probes/kiro.js";
 import * as piProbe from "../probes/pi.js";
 import { ALL_AGENTS } from "../core/types.js";
+import { loadCanonicalSource } from "../core/canonical.js";
 import { INSTALL_HINTS, collectInitReport } from "./init.js";
 import { applyMigratePlan, collectMigratePlan, printPlan as printMigratePlan } from "./migrate.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
+import { collectMcpSyncReport, printReport as printMcpSyncReport } from "./mcp.js";
+import { collectSecretsAuditReport, printReport as printSecretsAuditReport } from "./secretsAudit.js";
+import { openBackupSession } from "../lib/backup.js";
+import { confirmAndInstall } from "../lib/installAgent.js";
 const PROBES = {
     "claude-code": (homeDir) => claudeCodeProbe.probe(homeDir),
     codex: (homeDir) => codexProbe.probe(homeDir),
@@ -32,26 +45,100 @@ export async function collectOnboardSummary(homeDir = homedir()) {
         return { agent, present: true, skillCount: skillNames.length, skillNames, hasRealInstructions };
     }));
 }
+function hasContent(s) {
+    return s.skillCount > 0 || s.hasRealInstructions;
+}
 async function promptForAgentReal(present) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
         console.log("Multiple agents detected:");
-        for (const s of present) {
+        present.forEach((s, i) => {
             const skills = s.skillCount > 0 ? ` (${s.skillNames.join(", ")})` : "";
-            console.log(`  ${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`);
-        }
+            console.log(`  ${i + 1}) ${s.agent} — ${s.skillCount} skill(s)${skills}, instructions: ${s.hasRealInstructions ? "yes" : "no"}`);
+        });
         for (let attempt = 0; attempt < 2; attempt++) {
-            const answer = (await rl.question("Choose a base agent to migrate from: ")).trim();
+            const answer = (await rl.question(`Choose a migration source [1-${present.length}]: `)).trim();
+            // Accepts either the number shown or the literal agent id — the
+            // latter kept so `--agent`-equivalent scripted callers piping a
+            // canned answer in don't have to know the numbering.
+            const byIndex = present[Number(answer) - 1];
+            if (byIndex)
+                return byIndex.agent;
             if (present.some((s) => s.agent === answer))
                 return answer;
-            console.log(`Not one of the present agents: ${present.map((s) => s.agent).join(", ")}`);
+            console.log(`Not a valid choice: enter a number from 1-${present.length}, or one of ${present.map((s) => s.agent).join(", ")}`);
         }
-        throw new Error("no valid agent chosen after 2 attempts");
+        throw new Error("no valid migration source chosen after 2 attempts");
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForManagedAgentsReal(candidates, alreadyManaged) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("Which agents should Trellis manage? (comma-separated numbers; enter for none new)");
+        candidates.forEach((s, i) => {
+            const status = s.present ? `present, ${s.skillCount} skill(s)` : "not installed";
+            const tag = alreadyManaged.includes(s.agent) ? " [already managed]" : "";
+            console.log(`  ${i + 1}) ${s.agent} — ${status}${tag}`);
+        });
+        const answer = (await rl.question("Select: ")).trim();
+        return answer;
     }
     finally {
         rl.close();
     }
 }
+/** Shared by `--manage` and the interactive prompt's answer — same
+ * grammar either way (design.md D4): a real agent id list, comma- or
+ * whitespace-separated numbers referring to `candidates`' own order, or
+ * the literal `none`. Never guesses on an unparseable token. */
+function parseManagedSelection(raw, candidates) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed.toLowerCase() === "none") {
+        return { agents: [] };
+    }
+    const tokens = trimmed.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    const agents = [];
+    for (const token of tokens) {
+        const byIndex = candidates[Number(token) - 1];
+        if (byIndex) {
+            agents.push(byIndex.agent);
+            continue;
+        }
+        if (ALL_AGENTS.includes(token)) {
+            agents.push(token);
+            continue;
+        }
+        return { error: `"${token}" is not a valid choice — use a number from 1-${candidates.length} or an agent id` };
+    }
+    return { agents: [...new Set(agents)] };
+}
+async function resolveManagedAgents(opts, summary, alreadyManaged) {
+    if (opts.manage !== undefined) {
+        const parsed = parseManagedSelection(opts.manage, summary);
+        if ("error" in parsed)
+            return { refusal: parsed.error };
+        return { newlySelected: parsed.agents };
+    }
+    const canPrompt = !opts.json && (opts.isTTY ?? process.stdin.isTTY === true);
+    if (!canPrompt) {
+        return { refusal: "no managed-agent selection given and no terminal to prompt in — pass --manage <ids> or --manage none" };
+    }
+    const prompt = opts.promptForManagedAgents ?? promptForManagedAgentsReal;
+    const answer = await prompt(summary, alreadyManaged);
+    const parsed = parseManagedSelection(answer, summary);
+    if ("error" in parsed)
+        return { refusal: parsed.error };
+    return { newlySelected: parsed.agents };
+}
+function readManagedYaml(homeDir) {
+    return loadCanonicalSource(homeDir).managedAgents;
+}
+function writeManagedYaml(homeDir, agents) {
+    writeFileSync(join(homeDir, ".trellis", "managed.yaml"), `agents: [${agents.join(", ")}]\n`);
+}
 export async function collectOnboardPlan(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     await collectInitReport(homeDir);
@@ -60,8 +147,9 @@ export async function collectOnboardPlan(opts = {}) {
     if (present.length === 0) {
         return { summary, installHints: { ...INSTALL_HINTS } };
     }
-    let base;
-    let baseReason;
+    const sourceCandidates = present.filter(hasContent);
+    let source;
+    let sourceReason;
     if (opts.agent) {
         const match = present.find((s) => s.agent === opts.agent);
         if (!match) {
@@ -70,36 +158,101 @@ export async function collectOnboardPlan(opts = {}) {
                 refusal: `"${opts.agent}" is not one of the present agents (${present.map((s) => s.agent).join(", ")})`,
             };
         }
-        base = match.agent;
-        baseReason = "flag";
+        source = match.agent;
+        sourceReason = "flag";
     }
-    else if (present.length === 1) {
-        base = present[0].agent;
-        baseReason = "auto-selected";
+    else if (sourceCandidates.length === 1) {
+        source = sourceCandidates[0].agent;
+        sourceReason = "auto-selected";
     }
-    else {
+    else if (sourceCandidates.length > 1) {
         const canPrompt = !opts.json && (opts.isTTY ?? process.stdin.isTTY === true);
         if (!canPrompt) {
             return {
                 summary,
-                refusal: `multiple agents detected (${present.map((s) => s.agent).join(", ")}) and no terminal to prompt in — pass --agent <id>`,
+                refusal: `multiple agents detected (${sourceCandidates.map((s) => s.agent).join(", ")}) and no terminal to prompt in — pass --agent <id>`,
             };
         }
         const prompt = opts.promptForAgent ?? promptForAgentReal;
         try {
-            base = (await prompt(present));
+            source = (await prompt(sourceCandidates));
         }
         catch (err) {
             return { summary, refusal: err instanceof Error ? err.message : String(err) };
         }
-        baseReason = "prompt";
+        sourceReason = "prompt";
+    }
+    // sourceCandidates.length === 0: nothing with real content to migrate
+    // from — source stays undefined, managed-set selection still proceeds.
+    const alreadyManaged = readManagedYaml(homeDir);
+    const managedResult = await resolveManagedAgents(opts, summary, alreadyManaged);
+    if ("refusal" in managedResult) {
+        return { summary, source, sourceReason, refusal: managedResult.refusal };
     }
-    const migratePlan = await collectMigratePlan(base, homeDir);
+    const installResults = [];
+    const resolvedNew = [];
+    for (const agent of managedResult.newlySelected) {
+        const alreadyPresent = summary.find((s) => s.agent === agent)?.present ?? false;
+        if (alreadyPresent) {
+            resolvedNew.push(agent);
+            continue;
+        }
+        // A selected, not-yet-present agent: install-then-manage (design.md
+        // D5). `--json`/non-interactive callers still get a real confirm
+        // step here (never silently installed) — with no injected `confirm`
+        // and no TTY, the real readline prompt itself will simply never
+        // resolve to "yes" in a non-interactive run, so nothing installs;
+        // callers that want this path automated must inject `opts.install`.
+        if (opts.json && !opts.install?.confirm) {
+            return {
+                summary,
+                source,
+                sourceReason,
+                refusal: `"${agent}" is not installed — installing it requires a confirmation, which --json never prompts for. Inject a confirm handler or install ${agent} first.`,
+            };
+        }
+        const result = await confirmAndInstall(agent, opts.install);
+        installResults.push({ agent, installed: result.installed, installable: result.installable });
+        if (result.installed) {
+            resolvedNew.push(agent);
+        }
+        // Declined or (Kiro) not installable: excluded from this run's
+        // managed set, not an abort of the rest of the flow.
+    }
+    const managedAgents = [...new Set([...alreadyManaged, ...resolvedNew])];
     if (!opts.dryRun) {
-        applyMigratePlan(migratePlan, homeDir);
+        writeManagedYaml(homeDir, managedAgents);
+    }
+    let migratePlan;
+    if (source) {
+        migratePlan = await collectMigratePlan(source, homeDir);
+        if (!opts.dryRun) {
+            applyMigratePlan(migratePlan, homeDir);
+        }
     }
-    const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun });
-    return { summary, base, baseReason, migratePlan, syncReport };
+    // One session for the whole chained run (trellis-backup-rollback) —
+    // `--dry-run` opens none, there's nothing either stage will write.
+    // Neither collectSyncReport nor collectMcpSyncReport finalizes a
+    // session they were handed; only this caller does, once, after both.
+    const backupSession = opts.dryRun ? undefined : openBackupSession(homeDir, "onboard");
+    const syncReport = await collectSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
+    const mcpSyncReport = await collectMcpSyncReport({ homeDir, dryRun: opts.dryRun, managedAgents, backupSession });
+    backupSession?.finalize();
+    // Read-only, no dryRun concept — same report either way, run last since
+    // it audits the config mcp sync just wrote (or, on --dry-run, whatever
+    // was already there before this run).
+    const secretsAuditReport = await collectSecretsAuditReport({ homeDir, managedAgents });
+    return {
+        summary,
+        source,
+        sourceReason,
+        managedAgents,
+        installResults: installResults.length > 0 ? installResults : undefined,
+        migratePlan,
+        syncReport,
+        mcpSyncReport,
+        secretsAuditReport,
+    };
 }
 export async function runOnboard(opts = {}) {
     const result = await collectOnboardPlan(opts);
@@ -112,7 +265,9 @@ export async function runOnboard(opts = {}) {
     if (result.refusal)
         return { exitCode: 1 };
     const hasConflict = (result.migratePlan?.items.some((i) => i.action === "conflict") ?? false) ||
-        (result.syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false);
+        (result.syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
+        (result.mcpSyncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false) ||
+        (result.secretsAuditReport?.findings.length ?? 0) > 0;
     return { exitCode: hasConflict ? 1 : 0 };
 }
 function printResult(result, dryRun) {
@@ -130,15 +285,26 @@ function printResult(result, dryRun) {
         console.error(result.refusal);
         return;
     }
-    if (result.baseReason === "auto-selected") {
-        console.log(`Only ${result.base} detected — using it as the migration base.`);
+    if (result.sourceReason === "auto-selected") {
+        console.log(`Only ${result.source} has real content — using it as the migration source.`);
+    }
+    else if (result.sourceReason === "flag") {
+        console.log(`Using ${result.source} as the migration source (--agent).`);
     }
-    else if (result.baseReason === "flag") {
-        console.log(`Using ${result.base} as the migration base (--agent).`);
+    else if (result.sourceReason === "prompt") {
+        console.log(`Using ${result.source} as the migration source.`);
     }
-    else if (result.baseReason === "prompt") {
-        console.log(`Using ${result.base} as the migration base.`);
+    else {
+        console.log("No agent has real content to migrate from — starting from canonical's placeholder.");
+    }
+    for (const install of result.installResults ?? []) {
+        console.log(install.installed
+            ? `Installed ${install.agent}.`
+            : install.installable
+                ? `${install.agent} was not installed and the install was declined — left out of this run's managed set.`
+                : `${install.agent} has no npm package to install (see \`trellis init\`'s install hint) — left out of this run's managed set.`);
     }
+    console.log(`Managed agents: ${result.managedAgents && result.managedAgents.length > 0 ? result.managedAgents.join(", ") : "(none)"}`);
     // Reuse `migrate`/`sync`'s own printing verbatim (including the
     // "nothing to migrate" / "already in sync" cases) rather than a second,
     // easily-drifting copy of this formatting. `dryRun: false` here since
@@ -151,5 +317,12 @@ function printResult(result, dryRun) {
         console.log("\nsync");
         printSyncReport(result.syncReport, false);
     }
-    console.log("\nNext: `trellis mcp sync` to distribute MCP servers, `trellis secrets audit` to check for leaked credentials.");
+    if (result.mcpSyncReport) {
+        console.log("\nmcp sync");
+        printMcpSyncReport(result.mcpSyncReport, false);
+    }
+    if (result.secretsAuditReport) {
+        console.log("\nsecrets audit");
+        printSecretsAuditReport(result.secretsAuditReport);
+    }
 }

package/dist/commands/rollback.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `trellis rollback` — restores exactly what one recorded backup run
+ * changed (trellis-backup-rollback). Every operation is checked against
+ * its target path's *current* state before touching anything: if the
+ * path still matches what the run itself left behind, it's restored; if
+ * something else has touched it since, that's a conflict, reported and
+ * left untouched — same "verify, never guess" posture `sync`/`mcp sync`
+ * already hold themselves to for every other kind of conflict.
+ */
+import type { BackupManifest } from "../lib/backup.js";
+export interface RunRollbackOptions {
+    runId?: string;
+    list?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    /** Test/sandbox-only seam, same as every other command. Never a CLI
+     * flag. */
+    homeDir?: string;
+}
+export interface BackupRunSummary {
+    runId: string;
+    command: string;
+    startedAt: string;
+    operationCount: number;
+}
+export interface RollbackPlanItem {
+    action: "restore" | "conflict" | "already-reverted";
+    path: string;
+    description: string;
+}
+export interface RollbackReport {
+    runId: string;
+    items: RollbackPlanItem[];
+}
+/** Newest first — run ids are ISO-timestamp-prefixed, so lexical sort is
+ * chronological sort. */
+export declare function listBackups(homeDir?: string): BackupRunSummary[];
+export declare function loadManifest(homeDir: string, runId: string): BackupManifest;
+export declare function collectRollbackPlan(homeDirInput: string | undefined, runIdInput: string | undefined): Promise<RollbackReport>;
+export declare function applyRollbackPlan(homeDir: string, runId: string, manifest: BackupManifest, items: RollbackPlanItem[]): Promise<void>;
+export declare function runRollback(opts?: RunRollbackOptions): Promise<{
+    exitCode: number;
+}>;
+export declare function printReport(report: RollbackReport, dryRun: boolean): void;