agent-trellis 0.1.0 → 0.2.0

package/dist/commands/rollback.js

@@ -0,0 +1,201 @@
+/**
+ * `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 { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { readlink, rm, symlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { backupsRoot } from "../lib/backup.js";
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** Newest first — run ids are ISO-timestamp-prefixed, so lexical sort is
+ * chronological sort. */
+export function listBackups(homeDir = homedir()) {
+    const root = backupsRoot(homeDir);
+    if (!existsSync(root))
+        return [];
+    const runIds = readdirSync(root).sort().reverse();
+    const summaries = [];
+    for (const runId of runIds) {
+        const manifest = tryLoadManifest(homeDir, runId);
+        if (!manifest)
+            continue;
+        summaries.push({ runId, command: manifest.command, startedAt: manifest.startedAt, operationCount: manifest.operations.length });
+    }
+    return summaries;
+}
+function tryLoadManifest(homeDir, runId) {
+    const manifestPath = join(backupsRoot(homeDir), runId, "manifest.json");
+    if (!existsSync(manifestPath))
+        return undefined;
+    return JSON.parse(readFileSync(manifestPath, "utf-8"));
+}
+export function loadManifest(homeDir, runId) {
+    const manifest = tryLoadManifest(homeDir, runId);
+    if (!manifest) {
+        throw new Error(`No backup run "${runId}" found under ${backupsRoot(homeDir)}`);
+    }
+    return manifest;
+}
+function resolveRunId(homeDir, requested) {
+    if (requested)
+        return requested;
+    const [mostRecent] = listBackups(homeDir);
+    if (!mostRecent) {
+        throw new Error(`No backup runs found under ${backupsRoot(homeDir)} — nothing to roll back`);
+    }
+    return mostRecent.runId;
+}
+async function currentLinkTarget(path) {
+    try {
+        return await readlink(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function planOperation(homeDir, runId, op) {
+    const runDir = join(backupsRoot(homeDir), runId);
+    switch (op.kind) {
+        case "file-create":
+        case "file-overwrite": {
+            if (!existsSync(op.path)) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            const currentHash = sha256(readFileSync(op.path, "utf-8"));
+            if (currentHash !== op.afterHash) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
+            }
+            if (op.kind === "file-create") {
+                return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
+            }
+            return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeFile)})` };
+        }
+        case "symlink-create":
+        case "symlink-repair": {
+            const current = await currentLinkTarget(op.path);
+            if (current === undefined) {
+                return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
+            }
+            if (current !== op.afterLinkTarget) {
+                return { action: "conflict", path: op.path, description: `${op.path} points somewhere else now — left untouched` };
+            }
+            if (op.kind === "symlink-create") {
+                return { action: "restore", path: op.path, description: `remove ${op.path} (created by this run)` };
+            }
+            return { action: "restore", path: op.path, description: `repoint ${op.path} back to ${op.beforeLinkTarget}` };
+        }
+        case "symlink-remove": {
+            if (existsSync(op.path)) {
+                return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
+            }
+            return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
+        }
+    }
+}
+export async function collectRollbackPlan(homeDirInput, runIdInput) {
+    const homeDir = homeDirInput ?? homedir();
+    const runId = resolveRunId(homeDir, runIdInput);
+    const manifest = loadManifest(homeDir, runId);
+    const items = [];
+    for (const op of manifest.operations) {
+        items.push(await planOperation(homeDir, runId, op));
+    }
+    return { runId, items };
+}
+async function restoreOperation(homeDir, runId, op) {
+    const runDir = join(backupsRoot(homeDir), runId);
+    switch (op.kind) {
+        case "file-create":
+            rmSync(op.path, { force: true });
+            return;
+        case "file-overwrite":
+            writeFileSync(op.path, readFileSync(join(runDir, op.beforeFile), "utf-8"));
+            return;
+        case "symlink-create":
+            await rm(op.path, { force: true });
+            return;
+        case "symlink-repair":
+            await rm(op.path, { force: true });
+            await symlink(op.beforeLinkTarget, op.path);
+            return;
+        case "symlink-remove":
+            await symlink(op.beforeLinkTarget, op.path);
+            return;
+    }
+}
+export async function applyRollbackPlan(homeDir, runId, manifest, items) {
+    const restorePaths = new Set(items.filter((i) => i.action === "restore").map((i) => i.path));
+    for (const op of manifest.operations) {
+        if (!restorePaths.has(op.path))
+            continue;
+        await restoreOperation(homeDir, runId, op);
+    }
+}
+export async function runRollback(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    if (opts.list) {
+        const runs = listBackups(homeDir);
+        if (opts.json) {
+            console.log(JSON.stringify(runs, null, 2));
+        }
+        else {
+            printList(runs);
+        }
+        return { exitCode: 0 };
+    }
+    let report;
+    try {
+        report = await collectRollbackPlan(homeDir, opts.runId);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (!opts.dryRun) {
+        const manifest = loadManifest(homeDir, report.runId);
+        await applyRollbackPlan(homeDir, report.runId, manifest, report.items);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report, opts.dryRun ?? false);
+    }
+    const hasConflict = report.items.some((i) => i.action === "conflict");
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+function printList(runs) {
+    if (runs.length === 0) {
+        console.log("No backup runs found under ~/.trellis/backups/.");
+        return;
+    }
+    for (const run of runs) {
+        console.log(`${run.runId} — ${run.command}, ${run.operationCount} operation(s), ${run.startedAt}`);
+    }
+}
+export function printReport(report, dryRun) {
+    if (dryRun)
+        console.log("[dry run]");
+    console.log(`rollback ${report.runId}`);
+    const restored = report.items.filter((i) => i.action === "restore");
+    const conflicts = report.items.filter((i) => i.action === "conflict");
+    const alreadyReverted = report.items.filter((i) => i.action === "already-reverted");
+    if (report.items.length === 0) {
+        console.log("  nothing recorded in this run");
+        return;
+    }
+    const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+    console.log(`${icon} ${restored.length} restored, ${conflicts.length} conflict(s), ${alreadyReverted.length} already reverted`);
+    for (const item of [...restored, ...conflicts, ...alreadyReverted]) {
+        console.log(`   - [${item.action}] ${item.description}`);
+    }
+}

package/dist/commands/secretsAudit.d.ts

@@ -17,6 +17,9 @@ export interface RunSecretsAuditOptions {
     /** Same test/sandbox-only seam as every other command — never a CLI
      * flag. See docs/architecture.md's testing philosophy. */
     homeDir?: string;
+    /** Onboard-only seam — see RunSyncOptions.managedAgents. Never a CLI
+     * flag. */
+    managedAgents?: readonly AgentId[];
 }
 export interface SecretsFinding {
     /** "environment" for `missing-env-value` — that check isn't scoped to
@@ -33,3 +36,7 @@ export declare function collectSecretsAuditReport(opts?: RunSecretsAuditOptions)
 export declare function runSecretsAudit(opts?: RunSecretsAuditOptions): Promise<{
     exitCode: number;
 }>;
+/** Exported so `onboard` prints a secrets-audit report identically to
+ * running `secrets audit` standalone, instead of a second, easily-drifting
+ * copy of this formatting. */
+export declare function printReport(report: SecretsAuditReport): void;

package/dist/commands/secretsAudit.js

@@ -20,15 +20,18 @@ import { CodexAdapter } from "../adapters/codex.js";
 import { KiroAdapter } from "../adapters/kiro.js";
 import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames } from "../lib/envVarNames.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
-function auditedAgents(homeDir) {
-    return [
+/** Only agents in `managedAgents` — a present-but-unmanaged agent's config
+ * file is never even read (trellis-managed-agents), same restriction as
+ * `sync`/`mcp sync`. pi has no static, generated MCP config file to audit
+ * regardless of management — its bridge reads mcp/servers.yaml directly at
+ * its own runtime (P4). See design.md Non-Goals in trellis-secrets-audit-p3. */
+function auditedAgents(homeDir, managedAgents) {
+    const all = [
         { id: "claude-code", probe: () => new ClaudeCodeAdapter(homeDir).probe(), configPath: (h) => join(h, ".claude.json"), extractNames: extractJsonEnvVarNames },
         { id: "codex", probe: () => new CodexAdapter(homeDir).probe(), configPath: (h) => join(h, ".codex", "config.toml"), extractNames: extractTomlEnvVarNames },
         { id: "kiro", probe: () => new KiroAdapter(homeDir).probe(), configPath: (h) => join(h, ".kiro", "settings", "mcp.json"), extractNames: extractJsonEnvVarNames },
-        // pi has no static, generated MCP config file to audit — its bridge
-        // reads mcp/servers.yaml directly at its own runtime (P4). See
-        // design.md Non-Goals in trellis-secrets-audit-p3.
     ];
+    return all.filter((a) => managedAgents.includes(a.id));
 }
 /**
  * Not scoped to any agent, present or not — a name that can't resolve is
@@ -72,8 +75,9 @@ function auditFile(agent, file, content, policy, extractNames) {
 export async function collectSecretsAuditReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     const canonical = loadCanonicalSource(homeDir);
+    const managedAgents = opts.managedAgents ?? canonical.managedAgents;
     const findings = [];
-    for (const agent of auditedAgents(homeDir)) {
+    for (const agent of auditedAgents(homeDir, managedAgents)) {
         const probeResult = await agent.probe();
         if (!probeResult.present)
             continue;
@@ -103,7 +107,10 @@ export async function runSecretsAudit(opts = {}) {
     }
     return { exitCode: report.findings.length > 0 ? 1 : 0 };
 }
-function printReport(report) {
+/** Exported so `onboard` prints a secrets-audit report identically to
+ * running `secrets audit` standalone, instead of a second, easily-drifting
+ * copy of this formatting. */
+export function printReport(report) {
     if (report.findings.length === 0) {
         console.log("✅ no findings — every present agent's real config and every declared env var passed all checks");
         return;

package/dist/commands/sync.d.ts

@@ -7,6 +7,7 @@
  */
 import type { AdapterPlanItem } from "../core/adapter.js";
 import type { AgentId } from "../core/types.js";
+import { type BackupSession } from "../lib/backup.js";
 export interface RunSyncOptions {
     /** Omit to sync both. */
     target?: "skills" | "instructions";
@@ -21,6 +22,18 @@ export interface RunSyncOptions {
     homeDir?: string;
     /** Compute and report the plan without calling adapter.apply(). */
     dryRun?: boolean;
+    /** Onboard-only seam: preview/act against a managed-agent set that
+     * hasn't been written to `~/.trellis/managed.yaml` yet (its own
+     * `--dry-run` still needs a real plan against the set the user is
+     * about to select, not the one already on disk). Never a CLI flag —
+     * standalone `trellis sync` always reads canonical's own. */
+    managedAgents?: readonly AgentId[];
+    /** Onboard-only seam (trellis-backup-rollback): a session already open
+     * for the whole onboard run, so one `trellis rollback` undoes every
+     * stage together instead of one per stage. When given, this function
+     * does NOT finalize it — only whoever opened it does. Never a CLI
+     * flag — standalone `trellis sync` always opens and finalizes its own. */
+    backupSession?: BackupSession;
 }
 export interface AgentSyncReport {
     agent: AgentId;

package/dist/commands/sync.js

@@ -11,14 +11,35 @@ 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` — an agent present on this
+ * machine but not managed gets no adapter at all, not a zero-item plan
+ * (trellis-managed-agents). */
+function buildAdapters(homeDir, managedAgents) {
+    return managedAgents.map((id) => ADAPTER_FACTORY[id](homeDir));
 }
 export async function collectSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const canonical = loadCanonicalSource(homeDir);
+    const loaded = loadCanonicalSource(homeDir);
+    // A single override point, not two: every downstream read of "who's
+    // managed" — the adapter list built here AND each adapter's own
+    // in-scope filtering via `canonical.managedAgents` — must agree, or a
+    // dry-run preview computed against a not-yet-written managed set would
+    // silently diverge from what onboard's own outer adapter list acted on.
+    const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
-    for (const adapter of buildAdapters(homeDir)) {
+    // Own session only when the caller didn't share one (trellis-backup-
+    // rollback D2) — dry-run never opens or writes one, there's nothing to
+    // record.
+    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "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: [] });
@@ -40,10 +61,11 @@ export async function collectSyncReport(opts = {}) {
             items = items.filter((item) => item.kind === kind);
         }
         if (!opts.dryRun) {
-            await adapter.apply(items);
+            await adapter.apply(items, backup);
         }
         reports.push({ agent: adapter.id, present: true, items });
     }
+    ownSession?.finalize();
     return { reports };
 }
 export async function runSync(opts = {}) {
@@ -70,6 +92,10 @@ export async function runSync(opts = {}) {
 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/core/adapter.d.ts

@@ -10,6 +10,7 @@
  */
 import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
 import { resolveScope } from "./types.js";
+import type { BackupSession } from "../lib/backup.js";
 export interface AdapterProbeResult {
     present: boolean;
     version?: string;
@@ -91,7 +92,7 @@ export interface TrellisAdapter {
      * entries, MCP servers) through its `scope` field before planning any
      * change for it — an item scoped away from `this.id` must produce no
      * plan item at all, not a plan item that's later skipped. Use
-     * `resolveScope(item.scope).includes(this.id)`. See docs/architecture.md
+     * `isInScope(this.id, item.scope, canonical.managedAgents)`. See docs/architecture.md
      * "Private / agent-specific capabilities" — the default (`scope`
      * omitted) is "all agents," so this filter is a no-op for the common
      * case and only actually excludes anything when a capability was
@@ -123,11 +124,17 @@ export interface TrellisAdapter {
      * item in the same plan from being applied. The caller (e.g. `trellis
      * sync`) is responsible for surfacing conflicts and failing the overall
      * command (non-zero exit), not `apply()` per item.
+     *
+     * MUST perform every real write through `backup` (`writeFile`/
+     * `createSymlink`/`repairSymlink`/`removeSymlink`), never directly —
+     * `backup` is the only thing that may call `fs`/`fs/promises` to
+     * mutate a path this method touches (trellis-backup-rollback design.md
+     * D3/D5). Mandatory, not optional: the caller always has one open.
      */
-    apply(plan: AdapterPlanItem[]): Promise<void>;
+    apply(plan: AdapterPlanItem[], backup: BackupSession): Promise<void>;
     /** Re-read the agent's own state and confirm it matches canonical. */
     verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
 }
 /** Convenience used by every adapter's `plan()` — see the scope-filtering
  * obligation documented above. */
-export declare function isInScope(id: AgentId, scope: Parameters<typeof resolveScope>[0]): boolean;
+export declare function isInScope(id: AgentId, scope: Parameters<typeof resolveScope>[0], managedAgents: readonly AgentId[]): boolean;

package/dist/core/adapter.js

@@ -11,6 +11,6 @@
 import { resolveScope } from "./types.js";
 /** Convenience used by every adapter's `plan()` — see the scope-filtering
  * obligation documented above. */
-export function isInScope(id, scope) {
-    return resolveScope(scope).includes(id);
+export function isInScope(id, scope, managedAgents) {
+    return resolveScope(scope, managedAgents).includes(id);
 }

package/dist/core/canonical.js

@@ -78,6 +78,26 @@ function loadSecretsPolicyYaml(path, homeDir) {
 /** `undefined` if the name has no entry in scope.yaml's map — "shared with
  * all four agents," the default. A recognized but empty list is left as
  * authored (an explicitly agent-less scope), not coerced to "all". */
+/** Missing file and `agents: []` both resolve to `[]` — zero managed
+ * agents (D1), never "everyone." An unrecognized id is dropped with a
+ * diagnostic, same posture as an unrecognized scope.yaml agent id. */
+function loadManagedYaml(path, diagnostics) {
+    if (!existsSync(path)) {
+        return [];
+    }
+    const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    const raw = parsed.agents ?? [];
+    const valid = [];
+    for (const id of raw) {
+        if (ALL_AGENTS.includes(id)) {
+            valid.push(id);
+        }
+        else {
+            diagnostics.push(`managed.yaml: "${id}" is not a recognized agent id — ignored`);
+        }
+    }
+    return valid;
+}
 function scopeFor(map, name) {
     return map?.[name];
 }
@@ -100,6 +120,7 @@ export function loadCanonicalSource(homeDir = homedir()) {
         throw new Error(`No canonical source at ${root}. Create it before running trellis sync — see docs/architecture.md's canonical schema.`);
     }
     const diagnostics = [];
+    const managedAgents = loadManagedYaml(join(root, "managed.yaml"), diagnostics);
     const scopeYaml = loadScopeYaml(join(root, "scope.yaml"));
     const skillDirs = listSkillDirs(join(root, "skills"));
     const knownSkillNames = new Set(skillDirs.map((s) => s.name));
@@ -135,6 +156,7 @@ export function loadCanonicalSource(homeDir = homedir()) {
     }
     return {
         instructionsFile: join(root, "agents.md"),
+        managedAgents,
         skills,
         agents,
         memories,

package/dist/core/types.d.ts

@@ -15,7 +15,15 @@ export declare const ALL_AGENTS: readonly AgentId[];
  * "Private / agent-specific capabilities".
  */
 export type Scope = AgentId[] | undefined;
-export declare function resolveScope(scope: Scope): readonly AgentId[];
+/**
+ * `managedAgents` is the hard outer boundary (trellis-managed-agents
+ * design.md D6): no-scope items resolve to it instead of `ALL_AGENTS`, and
+ * an item WITH an explicit scope is intersected with it, never returned
+ * verbatim — a skill scoped to `[kiro]` must still not reach Kiro if Kiro
+ * isn't in the managed set. Presence on the machine is irrelevant here;
+ * only membership in `managedAgents` is.
+ */
+export declare function resolveScope(scope: Scope, managedAgents: readonly AgentId[]): readonly AgentId[];
 export interface McpServerDef {
     transport: Transport;
     /** stdio only */
@@ -190,6 +198,9 @@ export interface CanonicalSource {
      * that decision.
      */
     instructionsFile: string;
+    /** From `~/.trellis/managed.yaml`. Missing file and `agents: []` both
+     * resolve to `[]` — zero managed agents, never "everyone" (D1). */
+    managedAgents: readonly AgentId[];
     skills: SkillRef[];
     agents: AgentProfile[];
     memories: MemoryEntry[];

package/dist/core/types.js

@@ -10,6 +10,15 @@ export const ALL_AGENTS = [
     "kiro",
     "pi",
 ];
-export function resolveScope(scope) {
-    return scope ?? ALL_AGENTS;
+/**
+ * `managedAgents` is the hard outer boundary (trellis-managed-agents
+ * design.md D6): no-scope items resolve to it instead of `ALL_AGENTS`, and
+ * an item WITH an explicit scope is intersected with it, never returned
+ * verbatim — a skill scoped to `[kiro]` must still not reach Kiro if Kiro
+ * isn't in the managed set. Presence on the machine is irrelevant here;
+ * only membership in `managedAgents` is.
+ */
+export function resolveScope(scope, managedAgents) {
+    const candidates = scope ?? managedAgents;
+    return candidates.filter((id) => managedAgents.includes(id));
 }

package/dist/lib/backup.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Structured, timestamped backup of every real write `sync`/`mcp sync`
+ * perform, and the only path any of them writes disk through — see
+ * openspec/changes/trellis-backup-rollback/design.md D3/D5 for why the
+ * write itself lives here rather than at each call site: a call site
+ * that only had to remember to *also* call a record function is exactly
+ * the class of bug trellis-managed-agents found in symlinkPlan.ts. A run
+ * directory is created lazily on the first recorded operation; a session
+ * that never records anything creates nothing on disk.
+ */
+export type BackupOperation = {
+    kind: "file-create";
+    path: string;
+    afterHash: string;
+} | {
+    kind: "file-overwrite";
+    path: string;
+    beforeFile: string;
+    beforeHash: string;
+    afterHash: string;
+} | {
+    kind: "symlink-create";
+    path: string;
+    afterLinkTarget: string;
+} | {
+    kind: "symlink-repair";
+    path: string;
+    beforeLinkTarget: string;
+    afterLinkTarget: string;
+} | {
+    kind: "symlink-remove";
+    path: string;
+    beforeLinkTarget: string;
+};
+export interface BackupManifest {
+    runId: string;
+    command: string;
+    startedAt: string;
+    operations: BackupOperation[];
+}
+export interface BackupSession {
+    writeFile(path: string, content: string): void;
+    createSymlink(path: string, linkTarget: string): Promise<void>;
+    repairSymlink(path: string, oldLinkTarget: string, newLinkTarget: string): Promise<void>;
+    removeSymlink(path: string, oldLinkTarget: string): Promise<void>;
+    /** Writes manifest.json. No-op (creates nothing) if zero operations
+     * were ever recorded. */
+    finalize(): void;
+}
+export declare function backupsRoot(homeDir: string): string;
+export declare function openBackupSession(homeDir: string, command: string): BackupSession;
+/** Used by `applySymlinkPlan` and every adapter's own read-before-repair
+ * logic — it needs the symlink's current stored target before the
+ * session's own repair/remove overwrites it. Not part of `BackupSession`
+ * itself: it's a read, not a recorded write. */
+export declare function currentLinkTarget(path: string): Promise<string | undefined>;

package/dist/lib/backup.js

@@ -0,0 +1,98 @@
+/**
+ * Structured, timestamped backup of every real write `sync`/`mcp sync`
+ * perform, and the only path any of them writes disk through — see
+ * openspec/changes/trellis-backup-rollback/design.md D3/D5 for why the
+ * write itself lives here rather than at each call site: a call site
+ * that only had to remember to *also* call a record function is exactly
+ * the class of bug trellis-managed-agents found in symlinkPlan.ts. A run
+ * directory is created lazily on the first recorded operation; a session
+ * that never records anything creates nothing on disk.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readlink, rm, symlink } from "node:fs/promises";
+import { basename, join } from "node:path";
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** `:` and `.` are legal in POSIX filenames but awkward across shells and
+ * some tooling; replaced so a run id is safe to pass around bare. */
+function runIdFor(command) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${ts}-${command}`;
+}
+export function backupsRoot(homeDir) {
+    return join(homeDir, ".trellis", "backups");
+}
+export function openBackupSession(homeDir, command) {
+    const runId = runIdFor(command);
+    const runDir = join(backupsRoot(homeDir), runId);
+    const startedAt = new Date().toISOString();
+    const operations = [];
+    let dirCreated = false;
+    let fileIndex = 0;
+    function ensureDir() {
+        if (dirCreated)
+            return;
+        mkdirSync(join(runDir, "files"), { recursive: true });
+        dirCreated = true;
+    }
+    return {
+        writeFile(path, content) {
+            ensureDir();
+            const afterHash = sha256(content);
+            if (existsSync(path)) {
+                const before = readFileSync(path, "utf-8");
+                const relSnapshot = join("files", `${fileIndex}-${basename(path)}`);
+                fileIndex += 1;
+                writeFileSync(join(runDir, relSnapshot), before);
+                operations.push({
+                    kind: "file-overwrite",
+                    path,
+                    beforeFile: relSnapshot,
+                    beforeHash: sha256(before),
+                    afterHash,
+                });
+            }
+            else {
+                operations.push({ kind: "file-create", path, afterHash });
+            }
+            writeFileSync(path, content);
+        },
+        async createSymlink(path, linkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            await symlink(linkTarget, path);
+            operations.push({ kind: "symlink-create", path, afterLinkTarget: linkTarget });
+        },
+        async repairSymlink(path, oldLinkTarget, newLinkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            await symlink(newLinkTarget, path);
+            operations.push({ kind: "symlink-repair", path, beforeLinkTarget: oldLinkTarget, afterLinkTarget: newLinkTarget });
+        },
+        async removeSymlink(path, oldLinkTarget) {
+            ensureDir();
+            await rm(path, { force: true });
+            operations.push({ kind: "symlink-remove", path, beforeLinkTarget: oldLinkTarget });
+        },
+        finalize() {
+            if (!dirCreated)
+                return;
+            const manifest = { runId, command, startedAt, operations };
+            writeFileSync(join(runDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        },
+    };
+}
+/** Used by `applySymlinkPlan` and every adapter's own read-before-repair
+ * logic — it needs the symlink's current stored target before the
+ * session's own repair/remove overwrites it. Not part of `BackupSession`
+ * itself: it's a read, not a recorded write. */
+export async function currentLinkTarget(path) {
+    try {
+        return await readlink(path);
+    }
+    catch {
+        return undefined;
+    }
+}