nerdsystem 0.0.11 → 0.0.13

package/dist/commands/org.d.ts

@@ -17,7 +17,7 @@ export declare function domainsList(opts: {
 export declare function domainsAdd(hostname: string | undefined, opts: {
     json: boolean;
 }): Promise<void>;
-export declare function domainsRemove(id: string | undefined, opts: {
+export declare function domainsRemove(idOrHostname: string | undefined, opts: {
     json: boolean;
 }): Promise<void>;
 export declare function logs(opts: {

package/dist/commands/org.js

@@ -54,11 +54,21 @@ export async function domainsAdd(hostname, opts) {
         return printJson(r);
     log.ok(`Added ${r.domain.hostname}. Create this DNS record, then check with \`nerd domains\`:\n\n  ${r.domain.hostname}  CNAME  ${r.cnameTarget}`);
 }
-export async function domainsRemove(id, opts) {
-    if (!id)
-        throw new CliError("Usage: nerd domains remove <domainId>");
+export async function domainsRemove(idOrHostname, opts) {
+    if (!idOrHostname)
+        throw new CliError("Usage: nerd domains remove <hostname or domain id>");
     const nerd = readNerdJson(findProjectRoot());
-    const r = await ApiClient.fromConfig().delete(projectPath(nerd, `/domains/${id}`));
+    const api = ApiClient.fromConfig();
+    // People (and agents) pass the hostname they added; the API deletes by id, so look it up.
+    let id = idOrHostname;
+    if (!idOrHostname.startsWith("dom_")) {
+        const { domains } = await api.get(projectPath(nerd, "/domains"));
+        const match = domains.find((d) => d.hostname === idOrHostname.toLowerCase());
+        if (!match)
+            throw new CliError(`No custom domain ${idOrHostname} on this project. \`nerd domains\` lists them.`);
+        id = match.id;
+    }
+    const r = await api.delete(projectPath(nerd, `/domains/${id}`));
     if (opts.json)
         return printJson(r);
     log.ok("Removed.");

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;