nerdsystem 0.0.11 → 0.0.12

package/dist/commands/pull.d.ts

@@ -0,0 +1,31 @@
+import { ApiClient, type Source } from "../api.js";
+import { type NerdJson } from "../project.js";
+export interface PullOptions {
+    json: boolean;
+    latest?: boolean | undefined;
+    source?: string | undefined;
+    deployment?: string | undefined;
+    trashed?: boolean | undefined;
+    dir?: string | undefined;
+    force?: boolean | undefined;
+}
+/** `org/project` from the command line, or null when nothing was given. */
+export declare function parseTarget(arg: string | undefined): NerdJson | null;
+export interface PullOutcome {
+    restored: number;
+    dir: string;
+    source: Source | null;
+    sourceId: string;
+    sha256: string;
+}
+/**
+ * Downloads one snapshot, verifies its hash against the row (or the download header), extracts it
+ * with every hardening rule, and leaves a folder a person can work in: a git repository with one
+ * commit, nerd.json, and the lineage file. Nothing is written when the hash does not match.
+ */
+export declare function restoreSnapshot(api: ApiClient, nerd: NerdJson, dir: string, opts: {
+    trashed?: boolean | undefined;
+    force?: boolean | undefined;
+} & Pick<PullOptions, "latest" | "source" | "deployment">): Promise<PullOutcome>;
+/** `nerd pull`: get a saved copy of the code back onto this computer. */
+export declare function pull(target: string | undefined, opts: PullOptions): Promise<void>;

package/dist/commands/pull.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { ApiClient } from "../api.js";
+import { findProjectRoot, readNerdJson, writeNerdJson } from "../project.js";
+import { extractSnapshot, SnapshotError } from "../snapshot.js";
+import { CliError, log, printJson } from "../util.js";
+import { initGitRepo } from "./init.js";
+import { appendLineage } from "./source.js";
+const USAGE = "Usage: nerd pull <org>/<project> [--latest | --source <id> | --deployment <id>] [--trashed] [--dir <name>] [--force]";
+const SLUG = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+/** `org/project` from the command line, or null when nothing was given. */
+export function parseTarget(arg) {
+    if (arg === undefined)
+        return null;
+    const m = /^([^/\s]+)\/([^/\s]+)$/.exec(arg.trim());
+    if (!m || !SLUG.test(m[1]) || !SLUG.test(m[2]))
+        throw new CliError(`"${arg}" is not an org/project pair. ${USAGE}`);
+    return { org: m[1], project: m[2] };
+}
+/** The project to pull: the positional, else nerd.json above cwd, else a question on a TTY. */
+async function resolveTarget(arg, api, trashed) {
+    const given = parseTarget(arg);
+    if (given)
+        return { ...given, defaultDir: path.resolve(given.project) };
+    try {
+        const root = findProjectRoot();
+        const nerd = readNerdJson(root);
+        return { ...nerd, defaultDir: root };
+    }
+    catch {
+        // not inside a project
+    }
+    const me = await api.get("/v1/me");
+    const choices = [];
+    for (const org of me.orgs) {
+        const r = trashed ? await api.get(`/v1/orgs/${org.slug}/trash`) : await api.get(`/v1/orgs/${org.slug}/projects`);
+        for (const p of r.projects)
+            choices.push({ org: org.slug, project: p.slug, name: p.name });
+    }
+    if (choices.length === 0)
+        throw new CliError(trashed ? "Nothing in the trash. Drop --trashed to pull a live project." : "Your account has no projects yet. Create one with `nerd init <dir>`.");
+    if (!process.stdin.isTTY || process.env.CI) {
+        const list = choices.map((c) => `${c.org}/${c.project}`).join(", ");
+        throw new CliError(`Name the project: nerd pull <org>/<project>. Yours: ${list}`);
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        process.stderr.write(`Which project?\n${choices.map((c, i) => `  ${i + 1}. ${c.org}/${c.project}  ${c.name}`).join("\n")}\n`);
+        const answer = (await rl.question(`Number (1-${choices.length}): `)).trim();
+        const n = Number(answer);
+        const pick = Number.isInteger(n) && n >= 1 && n <= choices.length ? choices[n - 1] : choices.find((c) => `${c.org}/${c.project}` === answer);
+        if (!pick)
+            throw new CliError(`Not a choice. ${USAGE}`);
+        return { org: pick.org, project: pick.project, defaultDir: path.resolve(pick.project) };
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Picks the snapshot row: --source, --deployment (through its sourceId), or the newest. */
+async function pickSource(api, base, nerd, opts) {
+    const given = [opts.source, opts.deployment, opts.latest].filter(Boolean).length;
+    if (given > 1)
+        throw new CliError(`Pick one of --latest, --source, or --deployment. ${USAGE}`);
+    if (opts.deployment) {
+        if (opts.trashed)
+            throw new CliError("--deployment does not work with --trashed; use --source <id> or --latest for a trashed project.");
+        const list = await api.get(`${base}/deployments?limit=100`);
+        const d = list.deployments.find((x) => x.id === opts.deployment);
+        if (!d)
+            throw new CliError(`Deployment ${opts.deployment} was not found among the last 100 of ${nerd.org}/${nerd.project}.`);
+        if (!d.sourceId)
+            throw new CliError(`Deployment ${d.id} has no saved code${d.sourceSkippedReason ? ` (${d.sourceSkippedReason})` : " (it was deployed with an older nerd)"}. Pick another with nerd deployments, or use --latest.`);
+        const sources = await api.get(`${base}/sources?limit=100`);
+        return { source: sources.sources.find((s) => s.id === d.sourceId) ?? null, id: d.sourceId };
+    }
+    if (opts.source) {
+        const sources = await api.get(`${base}/sources?limit=100`);
+        return { source: sources.sources.find((s) => s.id === opts.source) ?? null, id: opts.source };
+    }
+    const r = await api.get(`${base}/sources?limit=1`);
+    const newest = r.sources[0];
+    if (!newest)
+        throw new CliError(`No saved code for ${nerd.org}/${nerd.project} yet. Deploy it or run nerd save first.`);
+    return { source: newest, id: newest.id };
+}
+/**
+ * Downloads one snapshot, verifies its hash against the row (or the download header), extracts it
+ * with every hardening rule, and leaves a folder a person can work in: a git repository with one
+ * commit, nerd.json, and the lineage file. Nothing is written when the hash does not match.
+ */
+export async function restoreSnapshot(api, nerd, dir, opts) {
+    const base = opts.trashed ? `/v1/orgs/${nerd.org}/trash/${nerd.project}` : `/v1/orgs/${nerd.org}/projects/${nerd.project}`;
+    const picked = await pickSource(api, base, nerd, { json: false, ...opts });
+    const target = path.resolve(dir);
+    // Refuse early, before the download, so a full folder costs nothing.
+    if (existsSync(target) && readdirSync(target).length > 0 && !opts.force)
+        throw new CliError(`${target} is not empty. Use --force to write into it anyway; files with the same names are replaced, other files stay.`, 1, { code: "not_empty" });
+    const { bytes, headers } = await api.download(`${base}/sources/${picked.id}/download`);
+    const expected = picked.source?.sha256 ?? headers.get("x-nerd-source-sha256");
+    if (!expected || !/^[0-9a-f]{64}$/.test(expected))
+        throw new CliError("The API did not say what hash the saved copy should have. Nothing was written. Update nerd and try again.");
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    if (actual !== expected)
+        throw new CliError("The downloaded copy did not match its recorded hash. Nothing was written. Try again in a minute.", 1, { code: "hash_mismatch" });
+    let restored;
+    try {
+        restored = extractSnapshot(bytes, target, { force: Boolean(opts.force) }).files;
+    }
+    catch (err) {
+        if (err instanceof SnapshotError && err.code === "not_empty")
+            throw new CliError(err.message, 1, { code: "not_empty" });
+        if (err instanceof SnapshotError)
+            throw new CliError(`The saved copy failed a safety check and was not restored: ${err.message}`, 1, { code: err.code });
+        throw err;
+    }
+    if (!existsSync(path.join(target, "nerd.json")))
+        writeNerdJson(target, { org: nerd.org, project: nerd.project });
+    if (!existsSync(path.join(target, ".git")))
+        initGitRepo(target, `Restore from nerdsystem snapshot ${picked.id}`);
+    appendLineage(target, picked.id);
+    return { restored, dir: target, source: picked.source, sourceId: picked.id, sha256: actual };
+}
+/** `nerd pull`: get a saved copy of the code back onto this computer. */
+export async function pull(target, opts) {
+    const api = ApiClient.fromConfig();
+    const resolved = await resolveTarget(target, api, Boolean(opts.trashed));
+    const dir = opts.dir ? path.resolve(opts.dir) : resolved.defaultDir;
+    const nerd = { org: resolved.org, project: resolved.project };
+    const out = await restoreSnapshot(api, nerd, dir, opts);
+    const shown = path.relative(process.cwd(), out.dir) || ".";
+    if (opts.json)
+        return printJson({ ...out, org: nerd.org, project: nerd.project, next: `cd ${shown} && pnpm install && nerd dev` });
+    log.ok(`Restored ${out.restored} files to ${shown}. Next: cd ${shown} && pnpm install && nerd dev`);
+}

package/dist/commands/save.d.ts

@@ -0,0 +1,27 @@
+import { ApiClient, type Source } from "../api.js";
+import { type NerdJson } from "../project.js";
+export interface SaveOutcome {
+    /** True when a new snapshot was stored; false when the newest one already had this tree. */
+    saved: boolean;
+    source: Source;
+    fileCount: number;
+    bytes: number;
+    treeHash: string;
+    warnings: string[];
+}
+/**
+ * Packs the folder and stores it as a `save` snapshot unless the newest stored snapshot already has
+ * the same tree. Throws CliError when the folder is over a cap (nothing to save) or the API refuses.
+ */
+export declare function saveSnapshot(root: string, nerd: NerdJson, api: ApiClient, opts?: {
+    quiet?: boolean;
+}): Promise<SaveOutcome>;
+/** `nerd save`: keep the code on nerdsystem without deploying it. */
+export declare function save(opts: {
+    json: boolean;
+}): Promise<void>;
+/**
+ * The save `nerd dev` runs on start: silent when nothing changed, one warning when it did not go
+ * through, never fatal. A person starting their app should never be stopped by the backup.
+ */
+export declare function silentSave(root: string): Promise<void>;

package/dist/commands/save.js

@@ -0,0 +1,67 @@
+import { ApiClient } from "../api.js";
+import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
+import { CliError, log, printJson } from "../util.js";
+import { appendLineage, LOCAL_ONLY_NOTE, packProject, printPackWarnings, secretWarnings, uploadSnapshot } from "./source.js";
+/**
+ * Packs the folder and stores it as a `save` snapshot unless the newest stored snapshot already has
+ * the same tree. Throws CliError when the folder is over a cap (nothing to save) or the API refuses.
+ */
+export async function saveSnapshot(root, nerd, api, opts = {}) {
+    const pack = await packProject(root, "save");
+    if (!opts.quiet)
+        printPackWarnings(pack);
+    if (pack.tooLarge)
+        throw new CliError(pack.tooLarge.message, 1, { code: "too_large" });
+    if (!opts.quiet)
+        for (const w of secretWarnings(root, pack))
+            log.warn(w);
+    const base = projectPath(nerd);
+    const latest = await api.get(`${base}/sources/latest?treeHash=${pack.treeHash}`);
+    if (latest.same && latest.source) {
+        appendLineage(root, latest.source.id);
+        return { saved: false, source: latest.source, fileCount: pack.fileCount, bytes: pack.bytes, treeHash: pack.treeHash, warnings: pack.warnings };
+    }
+    const source = await uploadSnapshot(api, base, pack, "save");
+    appendLineage(root, source.id);
+    return { saved: true, source, fileCount: pack.fileCount, bytes: pack.bytes, treeHash: pack.treeHash, warnings: pack.warnings };
+}
+/** `nerd save`: keep the code on nerdsystem without deploying it. */
+export async function save(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const api = ApiClient.fromConfig();
+    const out = await saveSnapshot(root, nerd, api, { quiet: opts.json });
+    if (opts.json)
+        return printJson({ saved: out.saved, source: out.source, fileCount: out.fileCount, bytes: out.bytes, treeHash: out.treeHash, warnings: out.warnings, pull: `nerd pull ${nerd.org}/${nerd.project}` });
+    if (!out.saved) {
+        log.ok("Nothing changed since the last save.");
+        log.info(`Get it back on any computer with: nerd pull ${nerd.org}/${nerd.project}`);
+        return;
+    }
+    log.ok(`Saved ${out.fileCount} files. Get it back on any computer with: nerd pull ${nerd.org}/${nerd.project}`);
+    log.info(LOCAL_ONLY_NOTE);
+}
+/**
+ * The save `nerd dev` runs on start: silent when nothing changed, one warning when it did not go
+ * through, never fatal. A person starting their app should never be stopped by the backup.
+ */
+export async function silentSave(root) {
+    try {
+        const nerd = readNerdJson(root);
+        const api = ApiClient.fromConfig();
+        const out = await saveSnapshot(root, nerd, api, { quiet: true });
+        if (out.saved)
+            log.ok(`Saved ${out.fileCount} files to nerdsystem. ${LOCAL_ONLY_NOTE}`);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message.replace(/\s+\[[a-z_]+ \d{3}\]$/, "") : String(err);
+        const goesOn = "nerd dev continues; run nerd save later to keep a copy.";
+        if (/^Code not saved/.test(reason))
+            log.warn(reason);
+        // A pack failure already reads "Your code could not be saved (...)." in full; only the next step is added.
+        else if (/^Your code could not be saved/.test(reason))
+            log.warn(`${reason} ${goesOn}`);
+        else
+            log.warn(`Code not saved: ${reason}. ${goesOn}`);
+    }
+}

package/dist/commands/source.d.ts

@@ -0,0 +1,38 @@
+import type { ApiClient, Source } from "../api.js";
+import { type PackOk, type PackResult } from "../snapshot.js";
+/** The published version, read from package.json so a release bump is the only place it changes. */
+export declare function cliVersion(): string;
+/** Invariant 7: every surface that says "saved" also says this, in one short sentence. */
+export declare const LOCAL_ONLY_NOTE = "Work after this point is only on this computer until the next deploy or nerd save.";
+/** Snapshot ids this copy of the code has deployed, saved, or pulled; newest last. Empty when unknown. */
+export declare function readLineage(root: string): string[];
+/** Records a snapshot id for the lineage guard, keeping the newest 50. Never throws: the deploy already happened. */
+export declare function appendLineage(root: string, id: string): void;
+/**
+ * The sentence for a pack that did not go through (a file nerd could not read, one that vanished
+ * between listing and hashing, a second change under the retry). On the deploy path it also says
+ * nothing was deployed; on the save path there is no deploy to mention.
+ */
+export declare function packStopMessage(err: unknown, purpose: "deploy" | "save"): string;
+/**
+ * Packs the folder, trying once more when a file changed under the first attempt (an editor save
+ * mid-pack). Any other failure to read the folder becomes a CliError with the sentence for `purpose`,
+ * never a raw Node error.
+ */
+export declare function packProject(root: string, purpose?: "deploy" | "save"): Promise<PackResult>;
+/**
+ * POST .../sources with the headers the API verifies the bytes against. Only machine values travel as
+ * headers: a header value must be Latin-1 with no line breaks, so anything a person typed (the deploy
+ * note) goes in the JSON metadata of the deploy itself.
+ */
+export declare function uploadSnapshot(api: ApiClient, basePath: string, pack: PackOk, kind: "deploy" | "save"): Promise<Source>;
+/** One line for an upload that did not go through, in the spec's words. The deploy stops; nothing was published. */
+export declare function uploadStopMessage(err: unknown): string;
+/** Prints the selection warnings (forced ignored files, oversized files left out). */
+export declare function printPackWarnings(pack: PackResult): void;
+/**
+ * Credential-shaped values in the text files a snapshot holds. A warning, never a block: `nerd deploy`
+ * already refuses a committed secret, and a save must not lose work over a key the agent is about to
+ * fix. Values are never printed; the mask carries the type and the last four characters.
+ */
+export declare function secretWarnings(root: string, pack: PackResult): string[];

package/dist/commands/source.js

@@ -0,0 +1,145 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { findSecrets, TEXT_FILE } from "../gates/text.js";
+import { packSnapshot, SnapshotError } from "../snapshot.js";
+import { CliError, log } from "../util.js";
+/*
+ * Shared pieces of the source-snapshot commands (docs/source-snapshots.md): packing with one retry,
+ * the upload with its headers, the lineage file, and the sentences every surface prints the same way.
+ */
+/** The published version, read from package.json so a release bump is the only place it changes. */
+export function cliVersion() {
+    return createRequire(import.meta.url)("../../package.json").version;
+}
+/** Invariant 7: every surface that says "saved" also says this, in one short sentence. */
+export const LOCAL_ONLY_NOTE = "Work after this point is only on this computer until the next deploy or nerd save.";
+// ---------------------------------------------------------------------------------------------
+// Lineage: the snapshot ids this folder deployed, saved, or pulled
+// ---------------------------------------------------------------------------------------------
+const LINEAGE_KEEP = 50;
+function lineageFile(root) {
+    return path.join(root, ".nerd", "lineage.json");
+}
+/** Snapshot ids this copy of the code has deployed, saved, or pulled; newest last. Empty when unknown. */
+export function readLineage(root) {
+    try {
+        const raw = JSON.parse(readFileSync(lineageFile(root), "utf8"));
+        return Array.isArray(raw.ids) ? raw.ids.filter((x) => typeof x === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Records a snapshot id for the lineage guard, keeping the newest 50. Never throws: the deploy already happened. */
+export function appendLineage(root, id) {
+    try {
+        const ids = readLineage(root).filter((x) => x !== id);
+        ids.push(id);
+        const file = lineageFile(root);
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify({ ids: ids.slice(-LINEAGE_KEEP) }, null, 2)}\n`);
+        // .nerd/ holds machine state (attempt counts, lineage), never code: keep it out of the repository.
+        const gi = path.join(root, ".gitignore");
+        if (existsSync(gi) && !readFileSync(gi, "utf8").includes(".nerd/"))
+            writeFileSync(gi, `${readFileSync(gi, "utf8").replace(/\n?$/, "\n")}.nerd/\n`);
+    }
+    catch {
+        // best effort
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Pack and upload
+// ---------------------------------------------------------------------------------------------
+/**
+ * The sentence for a pack that did not go through (a file nerd could not read, one that vanished
+ * between listing and hashing, a second change under the retry). On the deploy path it also says
+ * nothing was deployed; on the save path there is no deploy to mention.
+ */
+export function packStopMessage(err, purpose) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return purpose === "deploy" ? `Your code could not be saved (${reason}). Nothing was deployed.` : `Your code could not be saved (${reason}).`;
+}
+/**
+ * Packs the folder, trying once more when a file changed under the first attempt (an editor save
+ * mid-pack). Any other failure to read the folder becomes a CliError with the sentence for `purpose`,
+ * never a raw Node error.
+ */
+export async function packProject(root, purpose = "deploy") {
+    const opts = { cli: cliVersion() };
+    try {
+        try {
+            return await packSnapshot(root, opts);
+        }
+        catch (err) {
+            if (err instanceof SnapshotError && err.code === "changed")
+                return await packSnapshot(root, opts);
+            throw err;
+        }
+    }
+    catch (err) {
+        throw new CliError(packStopMessage(err, purpose), 1, { code: "pack_failed" });
+    }
+}
+/**
+ * POST .../sources with the headers the API verifies the bytes against. Only machine values travel as
+ * headers: a header value must be Latin-1 with no line breaks, so anything a person typed (the deploy
+ * note) goes in the JSON metadata of the deploy itself.
+ */
+export async function uploadSnapshot(api, basePath, pack, kind) {
+    const headers = {
+        "content-type": "application/gzip",
+        "x-nerd-source-kind": kind,
+        "x-nerd-source-sha256": pack.sha256,
+        "x-nerd-tree-hash": pack.treeHash,
+        "x-nerd-file-count": String(pack.fileCount),
+        "x-nerd-cli-version": pack.manifest.cli,
+        ...(pack.manifest.git ? { "x-nerd-git-sha": pack.manifest.git.sha } : {}),
+    };
+    const r = await api.postRaw(`${basePath}/sources`, pack.gz, headers);
+    if (!r?.source?.id)
+        throw new CliError("The API accepted the upload but did not return a snapshot id.", 1, { code: "storage_unavailable", status: 502 });
+    return r.source;
+}
+/** One line for an upload that did not go through, in the spec's words. The deploy stops; nothing was published. */
+export function uploadStopMessage(err) {
+    const reason = err instanceof Error ? err.message.replace(/\s+\[[a-z_]+ \d{3}\]$/, "") : String(err);
+    const status = err instanceof CliError ? err.status : undefined;
+    const infra = status === undefined || status >= 500 || status === 429;
+    const next = infra ? "Try again in a minute." : "Update nerd with `npm install -g nerdsystem@latest` and try again; if it keeps happening, report it.";
+    return `Your code could not be saved (${reason}). Nothing was deployed. ${next}`;
+}
+/** Prints the selection warnings (forced ignored files, oversized files left out). */
+export function printPackWarnings(pack) {
+    for (const w of pack.warnings)
+        log.warn(w);
+}
+const SECRET_SCAN_MAX_BYTES = 1024 * 1024;
+const SECRET_WARNING_LIMIT = 10;
+/**
+ * Credential-shaped values in the text files a snapshot holds. A warning, never a block: `nerd deploy`
+ * already refuses a committed secret, and a save must not lose work over a key the agent is about to
+ * fix. Values are never printed; the mask carries the type and the last four characters.
+ */
+export function secretWarnings(root, pack) {
+    const out = [];
+    for (const f of pack.manifest.files) {
+        if (!TEXT_FILE.test(f.path) || f.size > SECRET_SCAN_MAX_BYTES)
+            continue;
+        let text;
+        try {
+            text = readFileSync(path.join(root, ...f.path.split("/")), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const hit of findSecrets(text, f.path, 5)) {
+            if (hit.downgrade)
+                continue;
+            out.push(`${hit.file}:${hit.line} looks like a ${hit.rule.replace(/-/g, " ")} (${hit.masked}). It is in the saved copy; keep secrets in \`nerd secret set\` and rotate this one if it is real.`);
+            if (out.length >= SECRET_WARNING_LIMIT)
+                return out;
+        }
+    }
+    return out;
+}

package/dist/commands/trash.d.ts

@@ -10,7 +10,7 @@ export declare function trashList(opts: {
     json: boolean;
     org?: string | undefined;
 }): Promise<void>;
-/** `nerd trash restore <slug>`: undo a delete. The app stays offline until the next deploy or rollback. */
+/** `nerd trash restore <slug>`: undo a delete. The API re-publishes the last live version when it has one stored. */
 export declare function trashRestore(slug: string | undefined, opts: {
     json: boolean;
     org?: string | undefined;

package/dist/commands/trash.js

@@ -71,7 +71,7 @@ export async function trashList(opts) {
     table(r.projects.map((p) => ({ slug: p.slug, name: p.name, purgeAfter: p.purgeAfter.slice(0, 10) })), ["slug", "name", "purgeAfter"]);
     log.info(`Restore one with: nerd trash restore <slug>${opts.org ? ` --org ${org}` : ""}`);
 }
-/** `nerd trash restore <slug>`: undo a delete. The app stays offline until the next deploy or rollback. */
+/** `nerd trash restore <slug>`: undo a delete. The API re-publishes the last live version when it has one stored. */
 export async function trashRestore(slug, opts) {
     if (!slug)
         throw new CliError("Usage: nerd trash restore <slug> [--org <org>]");
@@ -79,6 +79,5 @@ export async function trashRestore(slug, opts) {
     const r = await ApiClient.fromConfig().post(`/v1/orgs/${t.org}/trash/${t.project}`, {});
     if (opts.json)
         return printJson(r);
-    log.ok(`Restored ${t.org}/${r.project.slug}.`);
-    log.info(r.next);
+    log.ok(`Restored ${t.org}/${r.project.slug}. ${r.next}`);
 }

package/dist/gates/text.d.ts

@@ -68,3 +68,68 @@ export interface OsvVulnerability {
 export declare function osvSeverity(v: OsvVulnerability): AdvisorySeverity;
 /** CVSS v3.0/3.1 base score from a vector string, or null when the vector is malformed. */
 export declare function cvss3BaseScore(vector: string): number | null;
+/** Name of the first entry in every snapshot tar. */
+export declare const SNAPSHOT_MANIFEST = ".nerd-snapshot.json";
+/** Most files one snapshot may hold. */
+export declare const MAX_SOURCE_FILES = 20000;
+/** Largest compressed snapshot accepted, in bytes (25 MB). */
+export declare const MAX_SOURCE_BYTES: number;
+/** Largest uncompressed tar stream accepted, in bytes (200 MB). */
+export declare const MAX_SOURCE_UNPACKED: number;
+/** A single file over this is left out of the snapshot with a warning (50 MB). */
+export declare const MAX_SNAPSHOT_FILE_BYTES: number;
+/** A PAX or GNU long-name header larger than this is refused; real ones are a few hundred bytes. */
+export declare const MAX_SNAPSHOT_HEADER_BYTES: number;
+/** Longest entry name accepted, in UTF-16 code units. */
+export declare const MAX_SNAPSHOT_NAME_LENGTH = 4096;
+export interface SnapshotFile {
+    /** Posix path relative to the app root. */
+    path: string;
+    size: number;
+    /** Hex sha256 of the file content. */
+    sha256: string;
+    /** 0o644 (420) or 0o755 (493). */
+    mode: number;
+}
+export interface SnapshotManifest {
+    version: 1;
+    createdAt: string;
+    cli: string;
+    node: string;
+    git: {
+        sha: string;
+        branch: string;
+    } | null;
+    files: SnapshotFile[];
+}
+/**
+ * Never in a snapshot, whatever git or the include list says: repository internals, build output,
+ * caches, local databases, env files, keys, package-manager credentials, and agent chat history.
+ * Matched against the posix path relative to the app root at any depth.
+ */
+export declare const SNAPSHOT_EXCLUDE: RegExp[];
+export declare function isSnapshotExcluded(posixPath: string): boolean;
+/** Directories at the app root whose whole tree a rebuild needs even when .gitignore hides it. */
+export declare const SNAPSHOT_INCLUDE_DIRS: string[];
+/**
+ * Files a rebuild needs; when .gitignore hides one it still goes into the snapshot, with a warning.
+ * Root-level config files and the trees in SNAPSHOT_INCLUDE_DIRS. The hard exclude still wins.
+ */
+export declare const SNAPSHOT_INCLUDE: RegExp[];
+export declare function isSnapshotForced(posixPath: string): boolean;
+/** True when an ignored directory may hold forced files, so a walker should still descend into it. */
+export declare function isSnapshotForcedDir(posixDir: string): boolean;
+/** The warning printed for every ignored file the snapshot keeps anyway. */
+export declare function snapshotForcedWarning(posixPath: string): string;
+/** Tar entry types a snapshot may hold: regular files, directories, PAX headers, GNU long names. */
+export declare const SNAPSHOT_ENTRY_TYPES: Set<string>;
+/**
+ * Checks one tar entry against the snapshot rules. Returns null when it passes, else a short reason.
+ * The same check runs on the control plane while the upload streams and in the CLI before a file
+ * is written on restore. `type` is the one-character typeflag ("" counts as "\0").
+ */
+export declare function validateSnapshotEntry(entry: {
+    name: string;
+    type: string;
+    size: number;
+}): string | null;

package/dist/gates/text.js

@@ -150,3 +150,111 @@ export function cvss3BaseScore(vector) {
     const roundUp = (x) => Math.ceil(x * 10 - 1e-9) / 10;
     return scopeChanged ? roundUp(Math.min(1.08 * (impact + exploitability), 10)) : roundUp(Math.min(impact + exploitability, 10));
 }
+/*
+ * Source snapshots (docs/source-snapshots.md). The CLI packs them, the control plane validates
+ * them while streaming, and both read the lists below, so a rule added here holds on both sides.
+ */
+/** Name of the first entry in every snapshot tar. */
+export const SNAPSHOT_MANIFEST = ".nerd-snapshot.json";
+/** Most files one snapshot may hold. */
+export const MAX_SOURCE_FILES = 20_000;
+/** Largest compressed snapshot accepted, in bytes (25 MB). */
+export const MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+/** Largest uncompressed tar stream accepted, in bytes (200 MB). */
+export const MAX_SOURCE_UNPACKED = 200 * 1024 * 1024;
+/** A single file over this is left out of the snapshot with a warning (50 MB). */
+export const MAX_SNAPSHOT_FILE_BYTES = 50 * 1024 * 1024;
+/** A PAX or GNU long-name header larger than this is refused; real ones are a few hundred bytes. */
+export const MAX_SNAPSHOT_HEADER_BYTES = 1024 * 1024;
+/** Longest entry name accepted, in UTF-16 code units. */
+export const MAX_SNAPSHOT_NAME_LENGTH = 4096;
+/**
+ * Never in a snapshot, whatever git or the include list says: repository internals, build output,
+ * caches, local databases, env files, keys, package-manager credentials, and agent chat history.
+ * Matched against the posix path relative to the app root at any depth.
+ */
+export const SNAPSHOT_EXCLUDE = [
+    /(^|\/)(\.git|node_modules|dist|\.wrangler|\.vite|coverage|\.nerd|\.turbo|\.cache|\.aws|\.ssh|\.specstory)(\/|$)/,
+    /(^|\/)\.aider[^/]*(\/|$)/,
+    /(^|\/)(\.DS_Store|Thumbs\.db|\.npmrc|\.yarnrc\.yml|\.netrc)$/i,
+    ENV_FILES,
+    /\.(pem|key|p12|pfx|jks|keystore|sqlite|sqlite3|db|db-journal|log)$/i,
+    /(^|\/)(id_rsa|id_ed25519)[^/]*$/,
+    /(^|\/)\.claude\/settings\.local\.json$/,
+    /^\.nerd-snapshot\.json$/,
+];
+export function isSnapshotExcluded(posixPath) {
+    return SNAPSHOT_EXCLUDE.some((re) => re.test(posixPath));
+}
+/** Directories at the app root whose whole tree a rebuild needs even when .gitignore hides it. */
+export const SNAPSHOT_INCLUDE_DIRS = ["migrations", "src", "public", ".claude", ".cursor", ".github"];
+/**
+ * Files a rebuild needs; when .gitignore hides one it still goes into the snapshot, with a warning.
+ * Root-level config files and the trees in SNAPSHOT_INCLUDE_DIRS. The hard exclude still wins.
+ */
+export const SNAPSHOT_INCLUDE = [
+    /^(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock|nerd\.json|wrangler\.json[^/]*|vite\.config\.[^/]+|tsconfig[^/]*\.json|drizzle\.config\.[^/]+|index\.html|CLAUDE\.md|AGENTS\.md|GEMINI\.md|\.mcp\.json|README\.md|\.gitignore)$/,
+    new RegExp(`^(${SNAPSHOT_INCLUDE_DIRS.map((d) => d.replace(/\./g, "\\.")).join("|")})/`),
+];
+export function isSnapshotForced(posixPath) {
+    return !isSnapshotExcluded(posixPath) && SNAPSHOT_INCLUDE.some((re) => re.test(posixPath));
+}
+/** True when an ignored directory may hold forced files, so a walker should still descend into it. */
+export function isSnapshotForcedDir(posixDir) {
+    const dir = posixDir.replace(/\/+$/, "");
+    if (dir === "" || isSnapshotExcluded(`${dir}/`))
+        return false;
+    return SNAPSHOT_INCLUDE_DIRS.some((d) => dir === d || dir.startsWith(`${d}/`));
+}
+/** The warning printed for every ignored file the snapshot keeps anyway. */
+export function snapshotForcedWarning(posixPath) {
+    return `\`${posixPath}\` is in .gitignore but a rebuild needs it; it is in the saved copy`;
+}
+/** Tar entry types a snapshot may hold: regular files, directories, PAX headers, GNU long names. */
+export const SNAPSHOT_ENTRY_TYPES = new Set(["0", "\0", "5", "x", "L"]);
+const TYPE_NAMES = { "1": "hard link", "2": "symbolic link", "3": "character device", "4": "block device", "6": "fifo", "7": "contiguous file", g: "global PAX header", K: "GNU long link", S: "sparse file" };
+function shortName(name) {
+    const clean = name.replace(/[^\x20-\x7e]/g, "?");
+    return clean.length > 120 ? `${clean.slice(0, 117)}...` : clean;
+}
+/**
+ * Checks one tar entry against the snapshot rules. Returns null when it passes, else a short reason.
+ * The same check runs on the control plane while the upload streams and in the CLI before a file
+ * is written on restore. `type` is the one-character typeflag ("" counts as "\0").
+ */
+export function validateSnapshotEntry(entry) {
+    const type = entry.type === "" ? "\0" : entry.type;
+    const name = entry.name;
+    if (!SNAPSHOT_ENTRY_TYPES.has(type)) {
+        const what = TYPE_NAMES[type] ?? `type ${JSON.stringify(type)}`;
+        return `entry "${shortName(name)}" is a ${what}; only regular files are allowed`;
+    }
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0)
+        return `entry "${shortName(name)}" has an invalid size`;
+    if ((type === "0" || type === "\0") && entry.size > MAX_SNAPSHOT_FILE_BYTES)
+        return `entry "${shortName(name)}" is larger than ${MAX_SNAPSHOT_FILE_BYTES / (1024 * 1024)} MB`;
+    if ((type === "x" || type === "L") && entry.size > MAX_SNAPSHOT_HEADER_BYTES)
+        return `entry "${shortName(name)}" has an oversized ${type === "x" ? "PAX" : "long-name"} header`;
+    if (name.length === 0)
+        return "an entry has no name";
+    if (name.length > MAX_SNAPSHOT_NAME_LENGTH)
+        return `entry "${shortName(name)}" has a name longer than ${MAX_SNAPSHOT_NAME_LENGTH} characters`;
+    if (name.includes("\0"))
+        return `entry "${shortName(name)}" has a NUL byte in its name`;
+    if (name.includes("\\"))
+        return `entry "${shortName(name)}" has a backslash in its name; paths must use /`;
+    if (name.startsWith("/"))
+        return `entry "${shortName(name)}" is an absolute path`;
+    const relative = type === "5" && name.endsWith("/") ? name.slice(0, -1) : name;
+    for (const segment of relative.split("/")) {
+        if (segment === "")
+            return `entry "${shortName(name)}" has an empty path segment`;
+        if (segment === ".")
+            return `entry "${shortName(name)}" has a "." path segment`;
+        if (segment === "..")
+            return `entry "${shortName(name)}" has a ".." path segment`;
+        if (segment === ".git")
+            return `entry "${shortName(name)}" is inside a .git directory`;
+    }
+    return null;
+}