primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/dist/src/lib/signing-secret-status.js

@@ -0,0 +1,116 @@
+/**
+ * Platform ceiling on a webhook's `secretGracePeriodMs`, mirrored from the
+ * server's `MAX_SECRET_GRACE_PERIOD_MS` (#2383). Read-only now: the field is
+ * authored as `webhook.secretGracePeriodMs` and applied by `config push` (#2645),
+ * so this ceiling is used to RENDER a stored value, not to pre-validate a flag.
+ * The server remains the authority and returns
+ * `SECRET_GRACE_PERIOD_OUT_OF_RANGE` on a bad push.
+ */
+export const MAX_SECRET_GRACE_PERIOD_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * The platform default applied when a webhook stores no `secretGracePeriodMs`,
+ * mirrored from the server's `DEFAULT_SECRET_GRACE_PERIOD_MS` (#2383). Only
+ * used to label the unset case on a read surface — nothing is computed from it
+ * CLI-side.
+ */
+export const DEFAULT_SECRET_GRACE_PERIOD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Render a webhook's stored `secretGracePeriodMs` for a read surface.
+ *
+ * A stored `0` and an absent field mean opposite things — immediate cutover vs
+ * the 24 h platform default — so they must not render the same. Naming the
+ * default explicitly matches how `Max Body Bytes` reports its own unset case.
+ */
+export function formatGracePeriodMs(value) {
+    if (value === undefined || value === null) {
+        return `default (${DEFAULT_SECRET_GRACE_PERIOD_MS}ms, 24 h)`;
+    }
+    return `${value}ms`;
+}
+/**
+ * The operator-facing warning for a webhook whose stored `signingSecret` is not
+ * a `{{secrets.KEY}}` reference (#2332).
+ *
+ * Two commands report it — `webhooks get` on a single row and `config pull` on
+ * every pulled row — and each has two statuses to describe. Those four strings
+ * were written out in full and had already drifted twice, so the wording lives
+ * here once and the call sites supply only what genuinely differs: how the
+ * field is named in that context, and what the un-migrated value blocks.
+ *
+ * Returns `null` for a status that needs no warning (`reference`, `unset`, or
+ * anything a newer server adds), so a call site is one `if` rather than two.
+ */
+export function signingSecretStatusWarning(status, context) {
+    const remediation = 'Store the value with `primitive secrets set KEY --value <value>` and set signingSecret = "{{secrets.KEY}}".';
+    if (status === "legacy-literal") {
+        return (`${context.subject} still holds a raw value. Deliveries still verify, but ` +
+            `${context.blocks} until it is migrated. ${remediation}`);
+    }
+    // Not a working legacy literal: the stored value carries reference syntax
+    // that resolves to nothing, so it is not a usable signing key and every
+    // signed delivery is already being rejected.
+    if (status === "malformed-reference") {
+        return (`${context.subject} is neither a {{secrets.KEY}} reference nor a plain stored value — ` +
+            "it carries reference syntax that does not resolve, so every signed delivery is being REJECTED. " +
+            `${remediation}`);
+    }
+    return null;
+}
+/**
+ * The operator-facing warning for a stored signing secret whose HEALTH is not
+ * `ok` — the second axis the server reports alongside the status (#2383).
+ *
+ * Written as "anything that is not `ok` needs attention" rather than as a list
+ * of known members, so a member a newer server adds is surfaced rather than
+ * silently read as fine. `signingSecretStatusWarning` above deliberately keeps
+ * the opposite rule for the STATUS axis, whose union is closed.
+ *
+ * Returns `null` for `ok`, for an absent field (a server that predates the
+ * health axis), and when the slot holds nothing to assess.
+ */
+export function signingSecretHealthWarning(health, context) {
+    if (health === undefined || health === null || health === "ok")
+        return null;
+    if (health === "weak-literal") {
+        return (`${context.subject} is a short raw value — too short to be a strong ` +
+            "HMAC key, so a sender's signature is easier to forge. Deliveries still " +
+            "verify; replace it with a strong value stored as a secret: " +
+            '`primitive secrets set KEY --value <value>`, then set signingSecret = "{{secrets.KEY}}".');
+    }
+    return (`${context.subject} was reported as '${health}' by the server, which this ` +
+        "CLI does not recognize — upgrade the CLI for the full explanation.");
+}
+/**
+ * The warning for the GRACE SLOT — a value in `previousSigningSecret` that the
+ * receiver still accepts until the rotation window closes.
+ *
+ * Split from the current-slot wording because the remediation differs: there is
+ * nothing to migrate here, the value simply has to stop being accepted.
+ *
+ * The two statuses need separate wording, because only one of them describes
+ * live credential material. A `legacy-literal` in this slot is grandfathered
+ * and really does keep verifying deliveries until the window closes, so
+ * `secretGracePeriodMs` is the operator's lever. A `malformed-reference` is
+ * dropped by the receiver before it reaches the verifier
+ * (`webhook-receiver.ts`: an unresolved previous reference yields no grace
+ * key), so it verifies nothing and lowering the grace period does nothing to
+ * it — telling the operator otherwise points them at a knob with no effect.
+ * This is the same distinction `signingSecretStatusWarning` draws for the
+ * current slot.
+ */
+export function previousSigningSecretWarning(status, context) {
+    if (status === "legacy-literal") {
+        return (`${context.subject}: the ROTATED-OUT signing secret is a raw stored value, ` +
+            "not a {{secrets.KEY}} reference. It keeps verifying deliveries until the " +
+            "rotation grace window closes (secretRotatedAt + secretGracePeriodMs). To " +
+            "stop accepting it sooner, lower secretGracePeriodMs (0 cuts over immediately).");
+    }
+    if (status === "malformed-reference") {
+        return (`${context.subject}: the ROTATED-OUT signing secret carries reference syntax ` +
+            "that does not resolve, so it verifies nothing — it is inert, not a live " +
+            "grace key, and secretGracePeriodMs has no effect on it. No action is " +
+            "required; it clears on the next rotation.");
+    }
+    return null;
+}
+//# sourceMappingURL=signing-secret-status.js.map

package/dist/src/lib/signing-secret-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing-secret-status.js","sourceRoot":"","sources":["../../../src/lib/signing-secret-status.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAGlE;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAgC;IAEhC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,YAAY,8BAA8B,WAAW,CAAC;IAC/D,CAAC;IACD,OAAO,GAAG,KAAK,IAAI,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAiC,EACjC,OAKC;IAED,MAAM,WAAW,GACf,6GAA6G,CAAC;IAChH,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAChC,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,yDAAyD;YAC3E,GAAG,OAAO,CAAC,MAAM,0BAA0B,WAAW,EAAE,CACzD,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,wEAAwE;IACxE,6CAA6C;IAC7C,IAAI,MAAM,KAAK,qBAAqB,EAAE,CAAC;QACrC,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,qEAAqE;YACvF,iGAAiG;YACjG,GAAG,WAAW,EAAE,CACjB,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAiC,EACjC,OAGC;IAED,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5E,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAC9B,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,mDAAmD;YACrE,yEAAyE;YACzE,6DAA6D;YAC7D,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,qBAAqB,MAAM,8BAA8B;QAC3E,oEAAoE,CACrE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAAiC,EACjC,OAGC;IAED,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAChC,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,0DAA0D;YAC5E,2EAA2E;YAC3E,2EAA2E;YAC3E,gFAAgF,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,qBAAqB,EAAE,CAAC;QACrC,OAAO,CACL,GAAG,OAAO,CAAC,OAAO,4DAA4D;YAC9E,0EAA0E;YAC1E,uEAAuE;YACvE,2CAA2C,CAC5C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/lib/skill-installer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns true if the skill is currently installed.
+ */
+export declare function isSkillInstalled(): boolean;
+/**
+ * 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 declare function checkSkillStatus(): Promise<void>;
+/**
+ * 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 declare function installSkillExplicit(): Promise<boolean>;
+/**
+ * Uninstall the skill (and the internal skill, if present).
+ */
+export declare function uninstallSkill(): boolean;
+/**
+ * Show current skill installation status.
+ */
+export declare function skillStatus(): void;

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,99 @@
+/**
+ * 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
+ * `.primitive-sync.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. .primitive-sync.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.
+ *
+ * `opts.preserveDir` names a directory (the snapshots root) that lives INSIDE
+ * `syncDir` and must survive the full-tree swap — the Fork-4 legacy `--dir`
+ * case, where backups sit at `<syncDir>/.snapshots/`. Without preserving it,
+ * the swap would wipe the user's entire snapshot history on restore.
+ */
+export declare function restoreSnapshot(snapshotPath: string, syncDir: string, opts?: {
+    preserveDir?: 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;