primitive-admin 1.1.0-alpha.8 → 1.1.0-alpha.80

package/dist/src/lib/skill-installer.js

@@ -0,0 +1,266 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+import { readFile } from "fs/promises";
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+const CLAUDE_DIR = join(homedir(), ".claude");
+const SKILLS_DIR = join(CLAUDE_DIR, "skills");
+const SKILL_DIR = join(SKILLS_DIR, "primitive-platform");
+const SKILL_FILE = join(SKILL_DIR, "SKILL.md");
+const HASH_FILE = join(SKILL_DIR, ".version");
+// Internal skill (Primitive-Labs members only). Not bundled with the CLI —
+// fetched from the private js-bao-wss repo via `gh`, so repo access is the gate.
+const INTERNAL_SKILL_NAME = "primitive-platform-internal";
+const INTERNAL_SKILL_DIR = join(SKILLS_DIR, INTERNAL_SKILL_NAME);
+const INTERNAL_SKILL_FILE = join(INTERNAL_SKILL_DIR, "SKILL.md");
+const INTERNAL_VERSION_FILE = join(INTERNAL_SKILL_DIR, ".version");
+const INTERNAL_SKILL_REPO_PATH = "repos/Primitive-Labs/js-bao-wss/contents/internal-skills/primitive-platform-internal/SKILL.md";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function getBundledSkillPath() {
+    // In dist: dist/src/lib/skill-installer.js -> ../../../assets/...
+    // In source (tsx): src/lib/skill-installer.ts -> ../../assets/...
+    const distPath = fileURLToPath(new URL("../../../assets/skill/skills/primitive-platform/SKILL.md", import.meta.url));
+    if (existsSync(distPath))
+        return distPath;
+    return fileURLToPath(new URL("../../assets/skill/skills/primitive-platform/SKILL.md", import.meta.url));
+}
+function getCliVersion() {
+    // Same dual-path layout as getBundledSkillPath: dist/src/lib -> package root
+    // is three levels up; src/lib (tsx) -> two levels up.
+    // Both candidates can exist (from source, ../../../ is the repo root), so
+    // require the CLI's package name to pick the right one.
+    for (const rel of ["../../../package.json", "../../package.json"]) {
+        try {
+            const path = fileURLToPath(new URL(rel, import.meta.url));
+            if (!existsSync(path))
+                continue;
+            const pkg = JSON.parse(readFileSync(path, "utf-8"));
+            if (pkg.name === "primitive-admin" && typeof pkg.version === "string") {
+                return pkg.version;
+            }
+        }
+        catch {
+            // try next path
+        }
+    }
+    return null;
+}
+function computeHash(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+function getInstalledHash() {
+    try {
+        if (!existsSync(HASH_FILE))
+            return null;
+        return readFileSync(HASH_FILE, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns true if the skill is currently installed.
+ */
+export function isSkillInstalled() {
+    return getInstalledHash() !== null;
+}
+function getInternalStamp() {
+    try {
+        if (!existsSync(INTERNAL_VERSION_FILE))
+            return null;
+        const stamp = JSON.parse(readFileSync(INTERNAL_VERSION_FILE, "utf-8"));
+        if (typeof stamp.cliVersion === "string" && typeof stamp.hash === "string") {
+            return stamp;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeInternalStamp(stamp) {
+    writeFileSync(INTERNAL_VERSION_FILE, JSON.stringify(stamp, null, 2));
+}
+/**
+ * Fetch the internal skill from the private js-bao-wss repo (main branch)
+ * via `gh`. Returns null if gh is missing, unauthenticated, or the caller
+ * lacks access to the repo — access failure is how non-members are gated.
+ */
+async function fetchInternalSkill() {
+    try {
+        const { execFile } = await import("child_process");
+        const { promisify } = await import("util");
+        const { stdout } = await promisify(execFile)("gh", ["api", "-H", "Accept: application/vnd.github.raw", INTERNAL_SKILL_REPO_PATH], { timeout: 15000, maxBuffer: 4 * 1024 * 1024 });
+        // Sanity check: must be the skill file, not an error payload.
+        if (!stdout.startsWith("---") || !stdout.includes(`name: ${INTERNAL_SKILL_NAME}`)) {
+            return null;
+        }
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+}
+function writeInternalSkill(content, cliVersion) {
+    const hash = computeHash(content);
+    mkdirSync(INTERNAL_SKILL_DIR, { recursive: true });
+    writeFileSync(INTERNAL_SKILL_FILE, content);
+    writeInternalStamp({ cliVersion, hash });
+    return hash;
+}
+/**
+ * Refresh an already-installed internal skill if the CLI version changed
+ * since the last attempt. One fetch per CLI release: the stamp is advanced
+ * even when the fetch fails, so an offline or revoked user isn't retried
+ * on every command (an explicit `primitive skill install` always refetches).
+ */
+async function refreshInternalSkill() {
+    const stamp = getInternalStamp();
+    if (!stamp)
+        return; // not installed — explicit install only
+    const cliVersion = getCliVersion();
+    if (!cliVersion || stamp.cliVersion === cliVersion)
+        return;
+    const content = await fetchInternalSkill();
+    if (content) {
+        const hash = writeInternalSkill(content, cliVersion);
+        if (hash !== stamp.hash) {
+            // Diagnostic, not payload: post-command notices must stay off stdout so
+            // `primitive <verb> --json | jq .` parses (#2357). Same stream choice as
+            // the update banner in version-check.ts.
+            console.error(chalk.dim("Updated Primitive internal skill for Claude Code"));
+        }
+    }
+    else {
+        writeInternalStamp({ ...stamp, cliVersion });
+    }
+}
+/**
+ * Auto-update an already-installed skill if a newer version is bundled.
+ * Called after command execution for non-init, non-skill commands.
+ * If the skill is not installed, shows a non-blocking hint instead.
+ * Never throws — fails silently like version-check.
+ */
+export async function checkSkillStatus() {
+    try {
+        const bundledPath = getBundledSkillPath();
+        if (!existsSync(bundledPath))
+            return;
+        if (!existsSync(CLAUDE_DIR))
+            return;
+        const bundledContent = await readFile(bundledPath, "utf-8");
+        const bundledHash = computeHash(bundledContent);
+        const installedHash = getInstalledHash();
+        if (installedHash) {
+            // Already installed — silently auto-update if needed
+            if (installedHash !== bundledHash) {
+                mkdirSync(SKILL_DIR, { recursive: true });
+                writeFileSync(SKILL_FILE, bundledContent);
+                writeFileSync(HASH_FILE, bundledHash);
+                console.error(chalk.dim("Updated Primitive platform skill for Claude Code"));
+            }
+            // Internal skill (if installed) refreshes from the private repo, at
+            // most once per CLI release.
+            await refreshInternalSkill();
+        }
+        else {
+            // Not installed — show a non-blocking hint
+            console.error(chalk.dim(`Claude Code skill available — run ${chalk.cyan("primitive skill install")} to set up`));
+        }
+    }
+    catch {
+        // Never let skill check affect CLI operation
+    }
+}
+/**
+ * Explicitly install or reinstall the skill. Shows output.
+ * Also installs the internal skill when the caller has access to the
+ * private repo (Primitive-Labs members); silently skipped otherwise.
+ */
+export async function installSkillExplicit() {
+    const bundledPath = getBundledSkillPath();
+    if (!existsSync(bundledPath)) {
+        console.error(chalk.red("Skill assets not found. Reinstall the CLI."));
+        return false;
+    }
+    if (!existsSync(CLAUDE_DIR)) {
+        console.error(chalk.red("Claude Code not found (~/.claude does not exist)."));
+        console.error(chalk.dim("Install Claude Code first: https://claude.ai/code"));
+        return false;
+    }
+    const bundledContent = readFileSync(bundledPath, "utf-8");
+    const bundledHash = computeHash(bundledContent);
+    mkdirSync(SKILL_DIR, { recursive: true });
+    writeFileSync(SKILL_FILE, bundledContent);
+    writeFileSync(HASH_FILE, bundledHash);
+    console.log(chalk.green("Primitive platform skill installed for Claude Code."));
+    console.log(chalk.dim(`Location: ${SKILL_FILE}`));
+    console.log(chalk.dim(`Version: ${bundledHash}`));
+    const wasInstalled = getInternalStamp() !== null;
+    const internalContent = await fetchInternalSkill();
+    if (internalContent) {
+        const hash = writeInternalSkill(internalContent, getCliVersion() ?? "unknown");
+        console.log(chalk.green("Primitive internal skill installed (Primitive-Labs members)."));
+        console.log(chalk.dim(`Location: ${INTERNAL_SKILL_FILE}`));
+        console.log(chalk.dim(`Version: ${hash}`));
+    }
+    else if (wasInstalled) {
+        // Keep the existing copy; just tell the user the refresh didn't happen.
+        console.log(chalk.yellow("Could not refresh the internal skill (gh unavailable or no repo access); keeping the installed copy."));
+    }
+    return true;
+}
+/**
+ * Uninstall the skill (and the internal skill, if present).
+ */
+export function uninstallSkill() {
+    if (!existsSync(SKILL_DIR) && !existsSync(INTERNAL_SKILL_DIR)) {
+        console.log(chalk.dim("Skill is not installed."));
+        return true;
+    }
+    if (existsSync(SKILL_DIR)) {
+        rmSync(SKILL_DIR, { recursive: true });
+        console.log(chalk.green("Primitive platform skill uninstalled."));
+    }
+    if (existsSync(INTERNAL_SKILL_DIR)) {
+        rmSync(INTERNAL_SKILL_DIR, { recursive: true });
+        console.log(chalk.green("Primitive internal skill uninstalled."));
+    }
+    return true;
+}
+/**
+ * Show current skill installation status.
+ */
+export function skillStatus() {
+    const installedHash = getInstalledHash();
+    const bundledPath = getBundledSkillPath();
+    const bundledHash = existsSync(bundledPath)
+        ? computeHash(readFileSync(bundledPath, "utf-8"))
+        : null;
+    if (!installedHash) {
+        console.log(chalk.yellow("Skill is not installed."));
+    }
+    else {
+        console.log(chalk.green("Skill is installed."));
+        console.log(chalk.dim(`  Location: ${SKILL_FILE}`));
+        console.log(chalk.dim(`  Version:  ${installedHash}`));
+    }
+    if (bundledHash) {
+        console.log(chalk.dim(`  Bundled:  ${bundledHash}`));
+        if (installedHash && installedHash !== bundledHash) {
+            console.log(chalk.yellow("  Update available — run: primitive skill install"));
+        }
+    }
+    const internalStamp = getInternalStamp();
+    if (internalStamp) {
+        console.log(chalk.green("Internal skill is installed (Primitive-Labs members)."));
+        console.log(chalk.dim(`  Location: ${INTERNAL_SKILL_FILE}`));
+        console.log(chalk.dim(`  Version:  ${internalStamp.hash} (fetched for CLI ${internalStamp.cliVersion})`));
+    }
+    else {
+        console.log(chalk.dim("Internal skill is not installed (Primitive-Labs members: primitive skill install)."));
+    }
+}
+//# sourceMappingURL=skill-installer.js.map

package/dist/src/lib/skill-installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-installer.js","sourceRoot":"","sources":["../../../src/lib/skill-installer.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/snapshots.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Sync snapshots — point-in-time backups of a sync directory taken before a
+ * destructive `config pull` overwrites local TOML state (issue #578, Phase 1).
+ *
+ * A snapshot is a full recursive copy of the live sync tree (including
+ * `.sync-state.json`, the content-hash baseline) into a timestamped slot
+ * under the snapshots root:
+ *
+ *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
+ *       <full pre-pull copy of the sync tree, incl. .sync-state.json>
+ *       .snapshot-complete        # integrity marker, written LAST
+ *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
+ *
+ * The `.snapshot-complete` marker is written last so a partial/interrupted
+ * copy is detectable: `restoreSnapshot` refuses any snapshot missing it.
+ *
+ * Snapshots fail LOUD — `createSnapshot` throws if it can't write a complete
+ * snapshot. The caller (config pull) aborts before touching any local file so we
+ * never perform a destructive pull without a recoverable backup.
+ *
+ * Restore is staged-then-swapped: the snapshot is materialized into a sibling
+ * temp dir, then the live `configDir` is atomically replaced, so a mid-restore
+ * crash never leaves a half-written tree.
+ */
+/** Marker file written LAST inside a snapshot to prove it completed. */
+export declare const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
+/** Cross-link to the audit entry that produced the snapshot (Phase 2). */
+export declare const SNAPSHOT_AUDIT_ID_MARKER = ".audit-id";
+export interface SnapshotResult {
+    /** Snapshot id — the timestamp directory name (YYYY-MM-DDTHH-MM-SS). */
+    id: string;
+    /** Absolute path to the snapshot directory. */
+    path: string;
+}
+export interface SnapshotInfo {
+    /** Snapshot id — the timestamp directory name. */
+    id: string;
+    /** Absolute path to the snapshot directory. */
+    path: string;
+    /** Whether the `.snapshot-complete` marker is present. */
+    complete: boolean;
+    /** The audit entry id this snapshot is cross-linked to, if any. */
+    auditId: string | null;
+    /** Creation time (from the directory mtime). */
+    createdAt: Date;
+}
+/**
+ * Snapshot the current `syncDir` into a new timestamped slot under
+ * `snapshotsRoot`. Returns the created snapshot, or `null` when there's
+ * nothing to back up (missing/empty `syncDir`).
+ *
+ * Fails LOUD: throws if the copy or marker write fails. The partial snapshot
+ * dir is best-effort cleaned up before rethrowing so a failed snapshot never
+ * leaves a marker-less husk behind.
+ */
+export declare function createSnapshot(syncDir: string, snapshotsRoot: string, opts?: {
+    auditId?: string;
+    now?: Date;
+}): SnapshotResult | null;
+/**
+ * List snapshots under `snapshotsRoot`, newest-first. Returns an empty array
+ * if the root doesn't exist. Each entry reports whether it's complete and any
+ * cross-linked audit id.
+ */
+export declare function listSnapshots(snapshotsRoot: string): SnapshotInfo[];
+/**
+ * Resolve a snapshot by id within `snapshotsRoot`. Accepts either the full
+ * timestamp directory name OR a unique prefix of at least `minPrefix`
+ * characters (default 8). Returns the matching snapshot, or throws a clear
+ * error on no-match / ambiguous-prefix.
+ *
+ * When `id` is omitted, resolves to the most recent COMPLETE snapshot.
+ */
+export declare function resolveSnapshot(snapshotsRoot: string, id: string | undefined, minPrefix?: number): SnapshotInfo;
+/**
+ * Restore a snapshot into `syncDir`, replacing whatever is there.
+ *
+ * Refuses to restore a snapshot missing the `.snapshot-complete` marker
+ * (partial/corrupted snapshot). The internal marker files (`.snapshot-complete`,
+ * `.audit-id`) are NOT copied into the restored tree.
+ *
+ * Staged-then-swapped: the snapshot is materialized into a sibling temp dir,
+ * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
+ * half-written tree.
+ *
+ * Nothing has to survive the swap. Backups live under the project's
+ * machine-local `.primitive/`, outside the committed tree entirely, so the
+ * `preserveDir` parameter this took went with `--dir` (#3154) — it existed
+ * only for the case where the snapshots root sat inside the directory being
+ * replaced.
+ */
+export declare function restoreSnapshot(snapshotPath: string, syncDir: string): void;
+/**
+ * Prune snapshots older than `retentionDays` from `snapshotsRoot`. Only the
+ * given slot is touched (cross-slot retention is independent — each slot has
+ * its own snapshots root). No-op if the root doesn't exist.
+ */
+export declare function pruneSnapshots(snapshotsRoot: string, retentionDays?: number): void;

package/dist/src/lib/snapshots.js

@@ -0,0 +1,294 @@
+/**
+ * Sync snapshots — point-in-time backups of a sync directory taken before a
+ * destructive `config pull` overwrites local TOML state (issue #578, Phase 1).
+ *
+ * A snapshot is a full recursive copy of the live sync tree (including
+ * `.sync-state.json`, the content-hash baseline) into a timestamped slot
+ * under the snapshots root:
+ *
+ *   <snapshotsRoot>/<YYYY-MM-DDTHH-MM-SS>/
+ *       <full pre-pull copy of the sync tree, incl. .sync-state.json>
+ *       .snapshot-complete        # integrity marker, written LAST
+ *       .audit-id                 # ULID cross-link (Phase 2; absent in P1)
+ *
+ * The `.snapshot-complete` marker is written last so a partial/interrupted
+ * copy is detectable: `restoreSnapshot` refuses any snapshot missing it.
+ *
+ * Snapshots fail LOUD — `createSnapshot` throws if it can't write a complete
+ * snapshot. The caller (config pull) aborts before touching any local file so we
+ * never perform a destructive pull without a recoverable backup.
+ *
+ * Restore is staged-then-swapped: the snapshot is materialized into a sibling
+ * temp dir, then the live `configDir` is atomically replaced, so a mid-restore
+ * crash never leaves a half-written tree.
+ */
+import { existsSync, readdirSync, statSync, writeFileSync, readFileSync, cpSync, rmSync, renameSync, mkdirSync, } from "fs";
+import { join, dirname } from "path";
+/** Marker file written LAST inside a snapshot to prove it completed. */
+export const SNAPSHOT_COMPLETE_MARKER = ".snapshot-complete";
+/** Cross-link to the audit entry that produced the snapshot (Phase 2). */
+export const SNAPSHOT_AUDIT_ID_MARKER = ".audit-id";
+/**
+ * Produce the timestamp directory name for a snapshot, e.g.
+ * `2026-06-01T17-42-18`. Colons (illegal on Windows, awkward everywhere) are
+ * replaced with hyphens; milliseconds and the trailing `Z` are dropped.
+ */
+function snapshotTimestamp(now = new Date()) {
+    // 2026-06-01T17:42:18.401Z -> 2026-06-01T17-42-18
+    return now.toISOString().replace(/\.\d+Z$/, "").replace(/:/g, "-");
+}
+/**
+ * Returns true if `dir` exists and contains at least one entry. A fresh
+ * project (no prior sync dir, or an empty one) has nothing to back up.
+ */
+function dirHasContent(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Snapshot the current `syncDir` into a new timestamped slot under
+ * `snapshotsRoot`. Returns the created snapshot, or `null` when there's
+ * nothing to back up (missing/empty `syncDir`).
+ *
+ * Fails LOUD: throws if the copy or marker write fails. The partial snapshot
+ * dir is best-effort cleaned up before rethrowing so a failed snapshot never
+ * leaves a marker-less husk behind.
+ */
+export function createSnapshot(syncDir, snapshotsRoot, opts = {}) {
+    if (!dirHasContent(syncDir)) {
+        return null;
+    }
+    const id = snapshotTimestamp(opts.now);
+    const dest = join(snapshotsRoot, id);
+    // Guard against an id collision (two pulls within the same second). Append a
+    // numeric suffix until we find a free slot so a rapid second pull can't
+    // clobber the first snapshot.
+    let finalId = id;
+    let finalDest = dest;
+    let suffix = 1;
+    while (existsSync(finalDest)) {
+        finalId = `${id}-${suffix}`;
+        finalDest = join(snapshotsRoot, finalId);
+        suffix += 1;
+    }
+    // The backups root is machine-local, under `.primitive/backups/<env>/<appId>/`,
+    // and the tree it copies is the committed `primitive/<env>/`. The two are
+    // disjoint, so the copy can never recurse into itself — the staged-into-a-
+    // temp-dir fork this used to need existed only for `--dir`, whose snapshots
+    // root sat INSIDE the tree it was snapshotting (#3154).
+    try {
+        mkdirSync(snapshotsRoot, { recursive: true });
+        // Full recursive copy. `dereference: false` keeps symlinks from being
+        // silently followed (edge case: symlinks inside the sync tree).
+        cpSync(syncDir, finalDest, { recursive: true, dereference: false });
+        if (opts.auditId) {
+            writeFileSync(join(finalDest, SNAPSHOT_AUDIT_ID_MARKER), opts.auditId);
+        }
+        // Integrity marker written LAST — its presence proves the copy finished.
+        writeFileSync(join(finalDest, SNAPSHOT_COMPLETE_MARKER), new Date().toISOString());
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial snapshot so we don't leave an
+        // incomplete (marker-less) directory around.
+        try {
+            rmSync(finalDest, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw err;
+    }
+    return { id: finalId, path: finalDest };
+}
+/**
+ * List snapshots under `snapshotsRoot`, newest-first. Returns an empty array
+ * if the root doesn't exist. Each entry reports whether it's complete and any
+ * cross-linked audit id.
+ */
+export function listSnapshots(snapshotsRoot) {
+    if (!existsSync(snapshotsRoot))
+        return [];
+    let names;
+    try {
+        names = readdirSync(snapshotsRoot);
+    }
+    catch {
+        return [];
+    }
+    const infos = [];
+    for (const name of names) {
+        const path = join(snapshotsRoot, name);
+        let stat;
+        try {
+            stat = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const complete = existsSync(join(path, SNAPSHOT_COMPLETE_MARKER));
+        let auditId = null;
+        const auditPath = join(path, SNAPSHOT_AUDIT_ID_MARKER);
+        if (existsSync(auditPath)) {
+            try {
+                auditId = readFileSync(auditPath, "utf-8").trim() || null;
+            }
+            catch {
+                auditId = null;
+            }
+        }
+        infos.push({ id: name, path, complete, auditId, createdAt: stat.mtime });
+    }
+    // Newest first. The id is a sortable timestamp string, so a reverse string
+    // sort matches chronological order (and stays correct for the `-N` suffixed
+    // collision variants within the same second).
+    infos.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+    return infos;
+}
+/**
+ * Resolve a snapshot by id within `snapshotsRoot`. Accepts either the full
+ * timestamp directory name OR a unique prefix of at least `minPrefix`
+ * characters (default 8). Returns the matching snapshot, or throws a clear
+ * error on no-match / ambiguous-prefix.
+ *
+ * When `id` is omitted, resolves to the most recent COMPLETE snapshot.
+ */
+export function resolveSnapshot(snapshotsRoot, id, minPrefix = 8) {
+    const all = listSnapshots(snapshotsRoot);
+    if (all.length === 0) {
+        throw new Error(`No snapshots found in ${snapshotsRoot}`);
+    }
+    if (!id) {
+        const mostRecentComplete = all.find((s) => s.complete);
+        if (!mostRecentComplete) {
+            throw new Error(`No complete snapshots found in ${snapshotsRoot} (all are missing the ${SNAPSHOT_COMPLETE_MARKER} marker).`);
+        }
+        return mostRecentComplete;
+    }
+    // Exact match wins.
+    const exact = all.find((s) => s.id === id);
+    if (exact)
+        return exact;
+    // Prefix match (must be unique and >= minPrefix chars).
+    if (id.length < minPrefix) {
+        throw new Error(`Snapshot id "${id}" is too short — provide at least ${minPrefix} characters or the full timestamp.`);
+    }
+    const matches = all.filter((s) => s.id.startsWith(id));
+    if (matches.length === 0) {
+        throw new Error(`No snapshot matches "${id}" in ${snapshotsRoot}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Snapshot prefix "${id}" is ambiguous (${matches.length} matches: ${matches
+            .map((m) => m.id)
+            .join(", ")}). Provide more characters.`);
+    }
+    return matches[0];
+}
+/**
+ * Restore a snapshot into `syncDir`, replacing whatever is there.
+ *
+ * Refuses to restore a snapshot missing the `.snapshot-complete` marker
+ * (partial/corrupted snapshot). The internal marker files (`.snapshot-complete`,
+ * `.audit-id`) are NOT copied into the restored tree.
+ *
+ * Staged-then-swapped: the snapshot is materialized into a sibling temp dir,
+ * then `syncDir` is atomically replaced, so a mid-restore crash never leaves a
+ * half-written tree.
+ *
+ * Nothing has to survive the swap. Backups live under the project's
+ * machine-local `.primitive/`, outside the committed tree entirely, so the
+ * `preserveDir` parameter this took went with `--dir` (#3154) — it existed
+ * only for the case where the snapshots root sat inside the directory being
+ * replaced.
+ */
+export function restoreSnapshot(snapshotPath, syncDir) {
+    if (!existsSync(snapshotPath)) {
+        throw new Error(`Snapshot not found: ${snapshotPath}`);
+    }
+    if (!existsSync(join(snapshotPath, SNAPSHOT_COMPLETE_MARKER))) {
+        throw new Error(`Refusing to restore: snapshot ${snapshotPath} is missing the ${SNAPSHOT_COMPLETE_MARKER} marker (partial/corrupted snapshot).`);
+    }
+    const parent = dirname(syncDir);
+    mkdirSync(parent, { recursive: true });
+    const unique = `${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+    const stageDir = join(parent, `.primitive-restore-stage-${unique}`);
+    const oldDir = join(parent, `.primitive-restore-old-${unique}`);
+    try {
+        // Materialize the snapshot into the staging dir.
+        cpSync(snapshotPath, stageDir, { recursive: true, dereference: false });
+        // Drop the snapshot-internal marker files from the restored tree.
+        for (const marker of [SNAPSHOT_COMPLETE_MARKER, SNAPSHOT_AUDIT_ID_MARKER]) {
+            const markerPath = join(stageDir, marker);
+            if (existsSync(markerPath)) {
+                rmSync(markerPath, { force: true });
+            }
+        }
+        // Atomic-ish swap: move the live dir aside, move staging into place, then
+        // delete the old dir. Same-filesystem renames are atomic.
+        if (existsSync(syncDir)) {
+            renameSync(syncDir, oldDir);
+        }
+        try {
+            renameSync(stageDir, syncDir);
+        }
+        catch (err) {
+            // Swap failed — try to roll the original back so we never leave the
+            // user with no sync dir at all.
+            if (existsSync(oldDir) && !existsSync(syncDir)) {
+                try {
+                    renameSync(oldDir, syncDir);
+                }
+                catch {
+                    // ignore rollback failure; original error is more useful
+                }
+            }
+            throw err;
+        }
+        // Success — remove the displaced original.
+        if (existsSync(oldDir)) {
+            rmSync(oldDir, { recursive: true, force: true });
+        }
+    }
+    finally {
+        // Clean up any leftover staging/old dirs on failure.
+        for (const dir of [stageDir, oldDir]) {
+            if (existsSync(dir)) {
+                try {
+                    rmSync(dir, { recursive: true, force: true });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+}
+/**
+ * Prune snapshots older than `retentionDays` from `snapshotsRoot`. Only the
+ * given slot is touched (cross-slot retention is independent — each slot has
+ * its own snapshots root). No-op if the root doesn't exist.
+ */
+export function pruneSnapshots(snapshotsRoot, retentionDays = 28) {
+    if (!existsSync(snapshotsRoot))
+        return;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    for (const info of listSnapshots(snapshotsRoot)) {
+        if (info.createdAt.getTime() < cutoff) {
+            try {
+                rmSync(info.path, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort prune — a failure to delete one stale snapshot must not
+                // abort the pull that triggered the prune.
+            }
+        }
+    }
+}
+//# sourceMappingURL=snapshots.js.map