nerdsystem 0.0.10 → 0.0.12

package/dist/commands/init.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { ApiClient } from "../api.js";
 import { projectPath, writeNerdJson } from "../project.js";
-import { CliError, log } from "../util.js";
+import { CliError, log, printJson } from "../util.js";
 const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/;
 function templateDir() {
     const here = path.dirname(fileURLToPath(import.meta.url));
@@ -88,9 +88,10 @@ function writeReadme(root, name, description) {
 }
 /**
  * A repository from the first minute: deploy-on-push and the agent's commits both expect one. Skipped
- * silently when git is missing, and when the folder already sits inside a repository.
+ * silently when git is missing, and when the folder already sits inside a repository. `nerd pull`
+ * uses it too, with its own commit message.
  */
-function initGitRepo(root) {
+export function initGitRepo(root, message = "Start from the nerdsystem template") {
     try {
         try {
             execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "ignore" });
@@ -101,7 +102,7 @@ function initGitRepo(root) {
         }
         execFileSync("git", ["init", "-q"], { cwd: root, stdio: "ignore" });
         execFileSync("git", ["add", "-A"], { cwd: root, stdio: "ignore" });
-        const commit = ["commit", "-q", "-m", "Start from the nerdsystem template"];
+        const commit = ["commit", "-q", "-m", message];
         try {
             execFileSync("git", commit, { cwd: root, stdio: "ignore" });
         }
@@ -168,10 +169,18 @@ export async function init(dir, args) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        throw new CliError(`The folder is ready but the project was not created: ${reason}\nFix that, then run: cd ${dir} && nerd link --slug ${slug}${args.org ? ` --org ${args.org}` : ""}`);
+        const code = err instanceof CliError && err.code ? err.code : "error";
+        // A plan limit is not something to fix in the folder: the API's message says how to free a slot.
+        const link = `cd ${dir} && nerd link --slug ${slug}${args.org ? ` --org ${args.org}` : ""}`;
+        const next = code === "plan_limit" ? `When a slot is free, run: ${link}` : `Fix that, then run: ${link}`;
+        const message = `The folder is ready but the project was not created: ${reason}`;
+        // Same pattern as `nerd check --json`: the JSON goes to stdout, the exit code stays non-zero.
+        if (args.json)
+            printJson({ error: { code, message }, dir, slug, next });
+        throw new CliError(`${message}\n${next}`, 1, { code });
     }
     initGitRepo(root);
     log.ok(`Ready. Next:\n  cd ${dir}\n  pnpm install\n  nerd dev\n\nThen open the folder in your coding agent and ask it to build the first feature; the nerdsystem skill walks it through.\nDeploys go to ${project.url}`);
 }
 // Kept in sync with packages/sdk/package.json by the release script.
-const SDK_VERSION = "0.0.10";
+const SDK_VERSION = "0.0.12";

package/dist/commands/login.d.ts

@@ -2,7 +2,8 @@
  * `nerd login` with no token starts a device login: prints a link, the person approves it in the
  * dashboard (or from the email when --email is given), and the token arrives here. `--token` still
  * works for scripts. A pending login is remembered, so running `nerd login` again after approving
- * picks it up instead of starting over.
+ * picks it up instead of starting over. `--email` with a different address than the pending login's
+ * starts a fresh one, so a typo does not lock the person out until the code expires.
  */
 export declare function login(args: {
     token?: string;

package/dist/commands/login.js

@@ -8,7 +8,8 @@ const WAIT_S = 90;
  * `nerd login` with no token starts a device login: prints a link, the person approves it in the
  * dashboard (or from the email when --email is given), and the token arrives here. `--token` still
  * works for scripts. A pending login is remembered, so running `nerd login` again after approving
- * picks it up instead of starting over.
+ * picks it up instead of starting over. `--email` with a different address than the pending login's
+ * starts a fresh one, so a typo does not lock the person out until the code expires.
  */
 export async function login(args) {
     const cfg = loadConfig();
@@ -17,23 +18,30 @@ export async function login(args) {
     if (token)
         return finish(apiUrl, token, args.json);
     const anon = new ApiClient(apiUrl, undefined);
-    let pending = cfg.pendingLogin && cfg.pendingLogin.apiUrl === apiUrl && cfg.pendingLogin.expiresAt > Date.now() ? cfg.pendingLogin : undefined;
+    const email = args.email?.trim().toLowerCase() || undefined;
+    const saved = cfg.pendingLogin;
+    // Resume only a login for this API that has not expired and, when --email is given, that went to the same address.
+    const resumable = saved && saved.apiUrl === apiUrl && saved.expiresAt > Date.now() && (!email || saved.email === email);
+    let pending = resumable ? saved : undefined;
     if (!pending) {
         const client = `nerd CLI on ${os.hostname()} (${os.platform()})`;
-        const start = await anon.post("/session/device", { client, ...(args.email ? { email: args.email } : {}) });
-        pending = { apiUrl, deviceCode: start.deviceCode, userCode: start.userCode, verificationUrl: start.verificationUrl, interval: start.interval, expiresAt: Date.now() + start.expiresIn * 1000 };
+        const start = await anon.post("/session/device", { client, ...(email ? { email } : {}) });
+        pending = { apiUrl, deviceCode: start.deviceCode, userCode: start.userCode, verificationUrl: start.verificationUrl, interval: start.interval, expiresAt: Date.now() + start.expiresIn * 1000, ...(email ? { email } : {}) };
         saveConfig({ ...cfg, pendingLogin: pending });
         if (args.json)
             printJson({ status: "pending", userCode: start.userCode, verificationUrl: start.verificationUrl, expiresIn: start.expiresIn });
         else {
-            log.info(`Open this link in your browser and approve code ${start.userCode}:\n\n  ${start.verificationUrl}\n`);
-            if (args.email)
-                log.info(`An email went to ${args.email}: the link signs you in (creating your account if you are new) and opens a page where you press Approve.`);
+            if (email) {
+                log.info(`An email went to ${email}. Click the link in it (check spam if nothing arrives within a minute), then press Approve on the page it opens. The link works once and expires in 15 minutes. If it never arrives, open ${start.verificationUrl} and sign in there.`);
+            }
+            else {
+                log.info(`Open this link in your browser and approve code ${start.userCode}:\n\n  ${start.verificationUrl}\n`);
+            }
             log.info("Waiting for approval…");
         }
     }
     else if (!args.json) {
-        log.info(`Still waiting for code ${pending.userCode} to be approved at:\n\n  ${pending.verificationUrl}\n`);
+        log.info(`Still waiting for code ${pending.userCode} to be approved at:\n\n  ${pending.verificationUrl}\n\n(run nerd login --email <address> with a different address to start over)`);
     }
     const deadline = Math.min(Date.now() + WAIT_S * 1000, pending.expiresAt);
     while (Date.now() < deadline) {

package/dist/commands/ops.d.ts

@@ -1,8 +1,22 @@
+interface Deployment {
+    id: string;
+    status: string;
+    environment: string;
+    note: string | null;
+    commitSha: string | null;
+    createdAt: string;
+    artifactStored: boolean;
+    rolledBackFrom: string | null;
+    sourceId?: string | null;
+    sourceSkippedReason?: string | null;
+}
 /** Re-publish the previous production deployment, or a specific one. */
 export declare function rollback(target: string | undefined, opts: {
     json: boolean;
     note?: string;
 }): Promise<void>;
+/** The folder did not move with the rollback; say so, and how to get the rolled-back code when it was saved. */
+export declare function rollbackFolderNote(deployment: Pick<Deployment, "id" | "sourceId" | "sourceSkippedReason">, project: string): string;
 export declare function cron(schedule: string | undefined, opts: {
     json: boolean;
 }): Promise<void>;
@@ -28,3 +42,4 @@ export declare function secretSet(name: string | undefined, value: string | unde
 export declare function secretRemove(name: string | undefined, opts: {
     json: boolean;
 }): Promise<void>;
+export {};

package/dist/commands/ops.js

@@ -19,6 +19,13 @@ export async function rollback(target, opts) {
     if (opts.json)
         return printJson(r);
     log.ok(`Live again as ${r.deployment.id}. The database was not changed.`);
+    log.info(rollbackFolderNote(r.deployment, nerd.project));
+}
+/** The folder did not move with the rollback; say so, and how to get the rolled-back code when it was saved. */
+export function rollbackFolderNote(deployment, project) {
+    if (deployment.sourceId)
+        return `The folder on this computer still has the newer code. To work from the version you rolled back to, run: nerd pull --deployment ${deployment.id} --dir ${project}-rolled-back`;
+    return `The folder on this computer still has the newer code. The version you rolled back to has no saved code (${deployment.sourceSkippedReason ?? "it was deployed with an older nerd"}), so nerd pull has nothing to give back for it.`;
 }
 export async function cron(schedule, opts) {
     const nerd = readNerdJson(findProjectRoot());

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/config.d.ts

@@ -1,7 +1,7 @@
 export interface GlobalConfig {
     apiUrl: string;
     token?: string;
-    /** A device login that was started but not yet approved; `nerd login` resumes it. */
+    /** A device login that was started but not yet approved; `nerd login` resumes it. `email` is the address the link went to, so `--email` with another address starts over. */
     pendingLogin?: {
         apiUrl: string;
         deviceCode: string;
@@ -9,6 +9,7 @@ export interface GlobalConfig {
         verificationUrl: string;
         interval: number;
         expiresAt: number;
+        email?: string;
     };
 }
 export declare const DEFAULT_API_URL = "https://api.nerdsystem.com";