nerdsystem 0.0.5 → 0.0.7

package/README.md

@@ -6,8 +6,19 @@
 npx nerdsystem init my-app
 cd my-app && pnpm install
 nerd dev       # run locally with real sign-in
-nerd verify    # secrets, dependencies, policy, PII, types
+nerd check     # every gate a deploy runs: secrets, dependencies, policy, PII, types (alias: nerd verify)
 nerd deploy    # checks, builds, migrates, ships
 ```
 
 Every command takes `--json` for agents. `nerd help` lists them all.
+
+More you will reach for:
+
+```sh
+nerd db export                 # SQL dump of the production database to <slug>-<date>.sql (--out file.sql)
+nerd delete --yes              # take the app offline; data kept a week in the trash
+nerd trash                     # deleted projects you can still restore
+nerd trash restore <slug>      # bring one back, then nerd deploy or roll back
+```
+
+`nerd check` prints how many gates ran and which were skipped (semgrep and gitleaks are optional locally; git builds run them in the builder). Platform operators also have `nerd admin --help`.

package/dist/api.js

@@ -1,5 +1,5 @@
 import { loadConfig } from "./config.js";
-import { CliError } from "./util.js";
+import { CliError, NOT_LOGGED_IN } from "./util.js";
 export class ApiClient {
     apiUrl;
     token;
@@ -10,7 +10,7 @@ export class ApiClient {
     static fromConfig(opts = {}) {
         const cfg = loadConfig();
         if (opts.requireAuth !== false && !cfg.token) {
-            throw new CliError("Not logged in. Run `nerd login` (or set NERD_TOKEN).");
+            throw new CliError(NOT_LOGGED_IN);
         }
         return new ApiClient(cfg.apiUrl, cfg.token);
     }
@@ -37,7 +37,8 @@ export class ApiClient {
         if (!res.ok) {
             const err = json?.error;
             const details = err?.details ? `\n${JSON.stringify(err.details, null, 2)}` : "";
-            throw new CliError(`${err?.code ?? "error"} (${res.status}): ${err?.message ?? "request failed"}${details}`);
+            // The message leads; the code and status follow for people who need them.
+            throw new CliError(`${err?.message ?? "request failed"} [${err?.code ?? "error"} ${res.status}]${details}`, 1, { code: err?.code ?? "error", status: res.status });
         }
         return json;
     }

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+export declare function main(argv: string[]): Promise<void>;
+/**
+ * Runs one command and turns any failure into a non-zero exit code. `process.exitCode` is set
+ * rather than calling `process.exit()`, so piped stdout (including `--json` output) is flushed
+ * before the process ends. Returns the exit code for tests.
+ */
+export declare function runCli(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,311 @@
+import { parseArgs } from "node:util";
+import { authConfig, authSecret } from "./commands/auth.js";
+import { check } from "./commands/check.js";
+import { dbExport, dbMigrate, dbMigrations, dbQuery } from "./commands/db.js";
+import { deploy, deployments } from "./commands/deploy.js";
+import { dev } from "./commands/dev.js";
+import { doctor } from "./commands/doctor.js";
+import { cron, health, rollback, secretList, secretRemove, secretSet, transfer, waitlist } from "./commands/ops.js";
+import { adminHelp, adminSuspend, adminUnsuspend } from "./commands/admin.js";
+import { agentsSync } from "./commands/agents.js";
+import { billingPortal, billingShow, billingUpgrade } from "./commands/billing.js";
+import { auditExport, clientsCreate, clientsList, clientsRelease, domainsAdd, domainsList, domainsRemove, logs, membersInvite, membersList, membersRemove } from "./commands/org.js";
+import { buildsList, buildsShow, buildsTrigger } from "./commands/builds.js";
+import { githubConnect, githubLink, githubStatus, githubUnlink } from "./commands/github.js";
+import { init, linkProject } from "./commands/init.js";
+import { login, whoami } from "./commands/login.js";
+import { deleteProject, trashList, trashRestore } from "./commands/trash.js";
+import { findProjectRoot } from "./project.js";
+import { CliError, log } from "./util.js";
+const HELP = `nerd — deploy apps to nerdsystem
+
+  nerd login [--email you@x.com]      Sign in or sign up: prints a link to approve in the browser (--email sends it; --token nsk_... for scripts)
+  nerd whoami                         Show the current user and orgs
+  nerd doctor                         Check Node, pnpm, git, login, and the project
+  nerd init <dir> [--org] [--name] [--describe "what it does"]   Create an app and a project for it
+  nerd link --slug <project> [--org]  Link this directory to an existing or new project
+  nerd dev [vite args]                Run locally (writes .dev.vars, applies local migrations)
+  nerd check [--no-build] [--rule id] [--json]   Run every gate a deploy runs; --json gives failures the agent can fix (alias: nerd verify)
+  nerd deploy [--note "what changed"] Check, build, migrate, upload. Prints the URL
+  nerd rollback [deploymentId]        Re-publish the previous production bundle
+  nerd cron [off|hourly|daily]        Scheduled job: the platform calls POST /api/cron
+  nerd transfer <org>                 Move this project to another org you administer
+  nerd delete [--slug p] [--org o] --yes   Take the app offline; data kept a week in the trash
+  nerd trash [--org o]                Deleted projects you can still restore
+  nerd trash restore <slug> [--org o] Bring a deleted project back (then deploy or roll back)
+  nerd health                         Platform component health (operators)
+  nerd waitlist [approve <id>]        Who is waiting for access while sign-up is invite-only (operators)
+  nerd deployments                    List recent deployments
+  nerd db query "<sql>"               Run SQL on the production database
+  nerd db migrate                     Apply pending migrations to production
+  nerd db migrations                  List applied migrations
+  nerd db export [--out file.sql]     Download a SQL dump of the production database
+  nerd auth config [--roles a,b] [--default-role r] [--signup on|off]
+  nerd auth secret                    Mint a dev tenant secret into .dev.vars
+  nerd secret set NAME [value]        App secret for production (c.env.NAME); value from stdin when omitted
+  nerd secret list | rm NAME          Names only; values are never shown
+  nerd github connect                 Install the GitHub App for this org (prints a link)
+  nerd github link owner/repo [--branch main] [--root-dir dir] [--no-previews] [--require-pr] [--agent @claude]
+  nerd github status | unlink
+  nerd builds [--limit n]             List git-triggered builds
+  nerd builds show <id>               Build details and log
+  nerd builds trigger [--branch b] [--commit sha]
+  nerd agents sync                    Regenerate AGENTS.md, Cursor, Copilot, Gemini files from the skill
+  nerd billing [--org slug]           Plan, limits, and usage for the org
+  nerd billing upgrade --plan pro|studio [--annual]   Start checkout
+  nerd billing portal                 Manage cards, invoices, and plan
+  nerd members [invite <email> --role r | remove <userId>]   Org members and invitations
+  nerd clients [create <slug> --name n | release <slug>]     Studio: one org per client, billed through yours
+  nerd domains [add <hostname> | remove <id>]                Custom domains for this project
+  nerd logs [--since 30m] [--limit 100] [--q text] [--pr n]  Logs from the deployed app
+  nerd audit [--out file.csv]         Export deployments and builds (Studio)
+
+Every command accepts --json for machine-readable output.
+Operator: nerd admin --help`;
+const BOOL = { type: "boolean", default: false };
+const STR = { type: "string" };
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+        console.log(HELP);
+        return;
+    }
+    const parse = (options, allowPositionals = true) => parseArgs({ args: rest, options: { json: BOOL, ...options }, allowPositionals, strict: cmd !== "dev" });
+    switch (cmd) {
+        case "login": {
+            const { values } = parse({ token: STR, "api-url": STR, email: STR });
+            return login(values);
+        }
+        case "doctor": {
+            const { values } = parse({});
+            return doctor({ json: Boolean(values.json) });
+        }
+        case "whoami": {
+            const { values } = parse({});
+            return whoami({ json: Boolean(values.json) });
+        }
+        case "init": {
+            const { values, positionals } = parse({ org: STR, name: STR, slug: STR, describe: STR, "no-create": BOOL });
+            return init(positionals[0], values);
+        }
+        case "link": {
+            const { values } = parse({ org: STR, slug: STR, name: STR, "no-create": BOOL });
+            if (!values.slug)
+                throw new CliError("Usage: nerd link --slug <project> [--org <org>] [--name 'My App']");
+            const root = (() => {
+                try {
+                    return findProjectRoot();
+                }
+                catch {
+                    return process.cwd();
+                }
+            })();
+            await linkProject(root, { ...(values.org ? { org: values.org } : {}), slug: values.slug, name: values.name ?? values.slug, create: !values["no-create"] });
+            return;
+        }
+        case "dev":
+            return dev(rest);
+        case "check":
+        case "verify": {
+            const { values } = parse({ "no-build": BOOL, "no-remote": BOOL, "no-typecheck": BOOL, rule: STR });
+            return check({ json: Boolean(values.json), "no-build": Boolean(values["no-build"]), "no-remote": Boolean(values["no-remote"]), ...(values.rule ? { rule: values.rule } : {}) });
+        }
+        case "deploy": {
+            const { values } = parse({ "skip-check": BOOL, "skip-build": BOOL, note: STR });
+            return deploy(values);
+        }
+        case "rollback": {
+            const { values, positionals } = parse({ note: STR });
+            return rollback(positionals[0], { json: Boolean(values.json), ...(values.note ? { note: values.note } : {}) });
+        }
+        case "cron": {
+            const { values, positionals } = parse({});
+            return cron(positionals[0], { json: Boolean(values.json) });
+        }
+        case "transfer": {
+            const { values, positionals } = parse({});
+            return transfer(positionals[0], { json: Boolean(values.json) });
+        }
+        case "delete": {
+            const { values } = parse({ org: STR, slug: STR, yes: BOOL, force: BOOL }, false);
+            return deleteProject({ json: Boolean(values.json), yes: Boolean(values.yes || values.force), ...(values.org ? { org: values.org } : {}), ...(values.slug ? { slug: values.slug } : {}) });
+        }
+        case "trash": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "restore" || sub === "list";
+            const { values, positionals } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL, org: STR }, allowPositionals: true });
+            const o = { json: Boolean(values.json), ...(values.org ? { org: values.org } : {}) };
+            if (sub === "restore")
+                return trashRestore(positionals[0], o);
+            return trashList(o);
+        }
+        case "health": {
+            const { values } = parse({});
+            return health({ json: Boolean(values.json) });
+        }
+        case "waitlist": {
+            const [sub, ...subRest] = rest;
+            const { values, positionals } = parseArgs({ args: sub === "approve" ? subRest : rest, options: { json: BOOL }, allowPositionals: true });
+            return waitlist({ json: Boolean(values.json), ...(sub === "approve" ? { approve: positionals[0] } : {}) });
+        }
+        case "deployments": {
+            const { values } = parse({ limit: { type: "string", default: "10" } });
+            return deployments(values);
+        }
+        case "db": {
+            const [sub, ...subRest] = rest;
+            const { values, positionals } = parseArgs({ args: subRest, options: { json: BOOL, out: STR }, allowPositionals: true });
+            if (sub === "query")
+                return dbQuery(positionals[0], { json: Boolean(values.json) });
+            if (sub === "migrate")
+                return dbMigrate({ json: Boolean(values.json) });
+            if (sub === "migrations")
+                return dbMigrations({ json: Boolean(values.json) });
+            if (sub === "export")
+                return dbExport({ json: Boolean(values.json), ...(values.out ? { out: values.out } : {}) });
+            throw new CliError("Usage: nerd db query|migrate|migrations|export [--out file.sql]");
+        }
+        case "auth": {
+            const [sub, ...subRest] = rest;
+            const { values } = parseArgs({ args: subRest, options: { json: BOOL, roles: STR, "default-role": STR, signup: STR }, allowPositionals: false });
+            if (sub === "config")
+                return authConfig(values);
+            if (sub === "secret")
+                return authSecret();
+            throw new CliError("Usage: nerd auth config|secret");
+        }
+        case "billing": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "upgrade" || sub === "portal" || sub === "show";
+            const { values } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL, org: STR, plan: STR, annual: BOOL }, allowPositionals: false });
+            const o = { json: Boolean(values.json), ...(values.org ? { org: values.org } : {}) };
+            if (sub === "upgrade")
+                return billingUpgrade({ ...o, ...(values.plan ? { plan: values.plan } : {}), annual: Boolean(values.annual) });
+            if (sub === "portal")
+                return billingPortal(o);
+            return billingShow(o);
+        }
+        case "members": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "invite" || sub === "remove" || sub === "list";
+            const { values, positionals } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL, org: STR, role: STR }, allowPositionals: true });
+            const o = { json: Boolean(values.json), ...(values.org ? { org: values.org } : {}) };
+            if (sub === "invite")
+                return membersInvite(positionals[0], { ...o, ...(values.role ? { role: values.role } : {}) });
+            if (sub === "remove")
+                return membersRemove(positionals[0], o);
+            return membersList(o);
+        }
+        case "clients": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "create" || sub === "release" || sub === "list";
+            const { values, positionals } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL, org: STR, name: STR }, allowPositionals: true });
+            const o = { json: Boolean(values.json), ...(values.org ? { org: values.org } : {}) };
+            if (sub === "create")
+                return clientsCreate(positionals[0], { ...o, ...(values.name ? { name: values.name } : {}) });
+            if (sub === "release")
+                return clientsRelease(positionals[0], o);
+            return clientsList(o);
+        }
+        case "secret": {
+            const [sub, ...subRest] = rest;
+            const { values, positionals } = parseArgs({ args: subRest, options: { json: BOOL, previews: BOOL }, allowPositionals: true });
+            const json = Boolean(values.json);
+            if (sub === "set")
+                return secretSet(positionals[0], positionals[1], { json, previews: Boolean(values.previews) });
+            if (sub === "rm" || sub === "remove" || sub === "delete")
+                return secretRemove(positionals[0], { json });
+            if (sub === "list" || sub === "ls" || sub === undefined)
+                return secretList({ json });
+            throw new CliError("Usage: nerd secret set NAME [value] [--previews] | list | rm NAME");
+        }
+        case "domains": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "add" || sub === "remove" || sub === "list";
+            const { values, positionals } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL }, allowPositionals: true });
+            const o = { json: Boolean(values.json) };
+            if (sub === "add")
+                return domainsAdd(positionals[0], o);
+            if (sub === "remove")
+                return domainsRemove(positionals[0], o);
+            return domainsList(o);
+        }
+        case "logs": {
+            const { values } = parse({ since: STR, limit: STR, q: STR, pr: STR });
+            return logs({ json: Boolean(values.json), ...(values.since ? { since: values.since } : {}), ...(values.limit ? { limit: values.limit } : {}), ...(values.q ? { q: values.q } : {}), ...(values.pr ? { pr: values.pr } : {}) });
+        }
+        case "audit": {
+            const { values } = parse({ org: STR, out: STR });
+            return auditExport({ json: Boolean(values.json), ...(values.org ? { org: values.org } : {}), ...(values.out ? { out: values.out } : {}) });
+        }
+        case "admin": {
+            const [sub, ...subRest] = rest;
+            if (!sub || sub === "--help" || sub === "-h" || sub === "help")
+                return adminHelp();
+            const { values } = parseArgs({ args: subRest, options: { json: BOOL, org: STR, reason: STR }, allowPositionals: false });
+            const o = { json: Boolean(values.json), ...(values.org ? { org: values.org } : {}) };
+            if (sub === "suspend")
+                return adminSuspend({ ...o, ...(values.reason ? { reason: values.reason } : {}) });
+            if (sub === "unsuspend")
+                return adminUnsuspend(o);
+            throw new CliError("Usage: nerd admin suspend|unsuspend (see `nerd admin --help`)");
+        }
+        case "agents": {
+            const [sub, ...subRest] = rest;
+            const { values } = parseArgs({ args: subRest, options: { json: BOOL }, allowPositionals: false });
+            if (sub === "sync")
+                return agentsSync({ json: Boolean(values.json) });
+            throw new CliError("Usage: nerd agents sync");
+        }
+        case "github": {
+            const [sub, ...subRest] = rest;
+            const { values, positionals } = parseArgs({ args: subRest, options: { json: BOOL, branch: STR, "root-dir": STR, "no-previews": BOOL, "require-pr": BOOL, installation: STR, agent: STR }, allowPositionals: true });
+            const json = Boolean(values.json);
+            if (sub === "connect")
+                return githubConnect({ json });
+            if (sub === "link")
+                return githubLink(positionals[0], { json, "no-previews": Boolean(values["no-previews"]), "require-pr": Boolean(values["require-pr"]), ...(values.agent ? { agent: String(values.agent) } : {}), ...(values.branch ? { branch: values.branch } : {}), ...(values["root-dir"] ? { "root-dir": values["root-dir"] } : {}), ...(values.installation ? { installation: values.installation } : {}) });
+            if (sub === "unlink")
+                return githubUnlink({ json });
+            if (sub === "status" || sub === undefined)
+                return githubStatus({ json });
+            throw new CliError("Usage: nerd github connect|link|unlink|status");
+        }
+        case "builds": {
+            const [sub, ...subRest] = rest;
+            const isSub = sub === "show" || sub === "trigger" || sub === "list";
+            const { values, positionals } = parseArgs({ args: isSub ? subRest : rest, options: { json: BOOL, limit: { type: "string", default: "10" }, branch: STR, commit: STR }, allowPositionals: true });
+            const json = Boolean(values.json);
+            if (sub === "show")
+                return buildsShow(positionals[0], { json });
+            if (sub === "trigger")
+                return buildsTrigger({ json, ...(values.branch ? { branch: values.branch } : {}), ...(values.commit ? { commit: values.commit } : {}) });
+            return buildsList({ json, limit: values.limit });
+        }
+        default:
+            throw new CliError(`Unknown command "${cmd}". Run \`nerd help\`.`);
+    }
+}
+/**
+ * Runs one command and turns any failure into a non-zero exit code. `process.exitCode` is set
+ * rather than calling `process.exit()`, so piped stdout (including `--json` output) is flushed
+ * before the process ends. Returns the exit code for tests.
+ */
+export async function runCli(argv) {
+    let code = 0;
+    try {
+        await main(argv);
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            log.warn(err.message);
+            code = err.exitCode > 0 ? err.exitCode : 1;
+        }
+        else {
+            console.error(err);
+            code = 1;
+        }
+    }
+    process.exitCode = code;
+    return code;
+}

package/dist/commands/admin.d.ts

@@ -0,0 +1,10 @@
+export declare function adminHelp(): void;
+export declare function adminSuspend(opts: {
+    json: boolean;
+    org?: string | undefined;
+    reason?: string | undefined;
+}): Promise<void>;
+export declare function adminUnsuspend(opts: {
+    json: boolean;
+    org?: string | undefined;
+}): Promise<void>;

package/dist/commands/admin.js

@@ -0,0 +1,36 @@
+import { ApiClient } from "../api.js";
+import { CliError, log, printJson } from "../util.js";
+const ADMIN_HELP = `nerd admin — platform operator commands (anyone else gets "not found")
+
+  nerd admin suspend --org <slug> --reason "<text>"   Suspend an org: apps offline, users and tokens locked
+  nerd admin unsuspend --org <slug>                   Lift the suspension`;
+export function adminHelp() {
+    console.log(ADMIN_HELP);
+}
+const OPERATOR_ONLY = "Only the platform operator can do this.";
+async function operatorPost(path, body) {
+    try {
+        return await ApiClient.fromConfig().post(path, body);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.status === 404)
+            throw new CliError(OPERATOR_ONLY);
+        throw err;
+    }
+}
+export async function adminSuspend(opts) {
+    if (!opts.org || !opts.reason)
+        throw new CliError('Usage: nerd admin suspend --org <slug> --reason "<why>"');
+    const r = await operatorPost("/v1/admin/suspend", { orgSlug: opts.org, reason: opts.reason });
+    if (opts.json)
+        return printJson(r);
+    log.ok(`Suspended ${r.org} at ${r.suspendedAt}: ${r.projectsTrashed} project(s) trashed, ${r.usersSuspended} user(s) suspended, ${r.tokensRevoked} token(s) revoked.`);
+}
+export async function adminUnsuspend(opts) {
+    if (!opts.org)
+        throw new CliError("Usage: nerd admin unsuspend --org <slug>");
+    const r = await operatorPost("/v1/admin/unsuspend", { orgSlug: opts.org });
+    if (opts.json)
+        return printJson(r);
+    log.ok(`Unsuspended ${r.org}: ${r.usersRestored} user(s) restored. Trashed projects stay in the trash until restored with \`nerd trash restore\`.`);
+}

package/dist/commands/check.d.ts

@@ -13,8 +13,13 @@ export declare function runChecks(root: string, opts: {
     remote: boolean;
     typecheck: boolean;
 }): Promise<CheckResult>;
+/**
+ * `nerd check` (and its alias `nerd verify`): every gate a deploy runs, plus a check that the linked
+ * project still exists. One command, one output shape, so agents learn one thing.
+ */
 export declare function check(opts: {
     json: boolean;
-    "no-typecheck": boolean;
+    "no-build": boolean;
     "no-remote": boolean;
+    rule?: string | undefined;
 }): Promise<void>;

package/dist/commands/check.js

@@ -4,6 +4,7 @@ import { ApiClient } from "../api.js";
 import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
 import { CliError, log, run } from "../util.js";
 import { staleAgentFiles } from "./agents.js";
+import { gateSummary, skippedGates } from "../gates/types.js";
 const ALLOWED_BINDINGS = new Set(["DB", "STORAGE", "ASSETS"]);
 /** Removes line and block comments and trailing commas from JSONC without touching string contents. */
 export function stripJsonComments(input) {
@@ -126,20 +127,37 @@ export async function runChecks(root, opts) {
     }
     return { ok: problems.length === 0, problems };
 }
+/**
+ * `nerd check` (and its alias `nerd verify`): every gate a deploy runs, plus a check that the linked
+ * project still exists. One command, one output shape, so agents learn one thing.
+ */
 export async function check(opts) {
     const root = findProjectRoot();
-    const result = await runChecks(root, { remote: !opts["no-remote"], typecheck: !opts["no-typecheck"] });
-    if (opts.json) {
-        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    }
-    else if (result.ok) {
-        log.ok("All checks passed");
+    const problems = [];
+    if (!opts["no-remote"] && !opts.rule) {
+        const nerd = readNerdJson(root);
+        try {
+            await ApiClient.fromConfig().get(projectPath(nerd));
+        }
+        catch (err) {
+            problems.push(`The linked project ${nerd.org}/${nerd.project} is not reachable: ${err.message}`);
+        }
     }
+    // Loaded here, not at the top: the gates import staticChecks from this file.
+    const { runVerify } = await import("./verify.js");
+    const out = await runVerify(root, { withBuild: !opts["no-build"], stopOnFail: false, quiet: opts.json, onlyRules: opts.rule ? [opts.rule] : undefined });
+    const failed = out.results.filter((r) => r.status === "fail").length;
+    if (opts.json)
+        process.stdout.write(`${JSON.stringify({ ok: out.ok && problems.length === 0, failures: out.failures, stop: out.stop, problems, skipped: skippedGates(out.results) }, null, 2)}\n`);
     else {
-        for (const p of result.problems)
+        for (const p of problems)
             log.warn(p);
+        if (out.ok && problems.length === 0)
+            log.ok(gateSummary(out.results));
+        const human = out.failures.filter((f) => f.audience === "human" && f.severity === "block");
+        if (human.length)
+            log.warn(`${human.length} finding(s) need a person, not the agent: ${human.map((f) => f.rule_id).join(", ")}`);
     }
-    const blocking = result.problems.filter((p) => !p.endsWith("(warning)") && !p.startsWith("Agent instruction files"));
-    if (blocking.length)
-        throw new CliError(`${blocking.length} problem(s) found`, 2);
+    if (failed || problems.length)
+        throw new CliError(failed ? `${failed} gate(s) failed. Fix what is listed above, then run nerd check again.` : problems[0], 2);
 }

package/dist/commands/db.d.ts

@@ -7,3 +7,11 @@ export declare function dbMigrate(opts: {
 export declare function dbMigrations(opts: {
     json: boolean;
 }): Promise<void>;
+/**
+ * `nerd db export`: asks the API for a SQL dump of the production database and downloads it. With
+ * --json the response is printed and nothing is downloaded, so scripts can fetch the URL themselves.
+ */
+export declare function dbExport(opts: {
+    json: boolean;
+    out?: string | undefined;
+}): Promise<void>;

package/dist/commands/db.js

@@ -30,3 +30,28 @@ export async function dbMigrations(opts) {
         return printJson(r);
     table(r.migrations, ["name", "appliedAt"]);
 }
+/**
+ * `nerd db export`: asks the API for a SQL dump of the production database and downloads it. With
+ * --json the response is printed and nothing is downloaded, so scripts can fetch the URL themselves.
+ */
+export async function dbExport(opts) {
+    const nerd = readNerdJson(findProjectRoot());
+    const r = await ApiClient.fromConfig().post(projectPath(nerd, "/db/export"), {});
+    if (opts.json)
+        return printJson(r);
+    if (r.url.startsWith("fake://")) {
+        log.info(`Export ready at ${r.url} (dev mode, nothing downloaded). ${r.note}`);
+        return;
+    }
+    const { writeFileSync } = await import("node:fs");
+    const path = await import("node:path");
+    const out = path.resolve(opts.out ?? `${nerd.project}-${new Date().toISOString().slice(0, 10)}.sql`);
+    const res = await fetch(r.url).catch((err) => {
+        throw new CliError(`Could not download the export: ${err.message}`);
+    });
+    if (!res.ok)
+        throw new CliError(`Download failed (${res.status}). The link may have expired${r.expiresAt ? ` at ${r.expiresAt}` : ""}; run \`nerd db export\` again.`);
+    writeFileSync(out, Buffer.from(await res.arrayBuffer()));
+    log.ok(`Wrote ${out}`);
+    log.info(r.note);
+}

package/dist/commands/deploy.js

@@ -2,9 +2,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { ApiClient } from "../api.js";
 import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
-import { CliError, log, printJson, runOrThrow, table } from "../util.js";
+import { CliError, log, printJson, runOrThrow, table, dashboardUrl, ensureDeps } from "../util.js";
 import { runChecks } from "./check.js";
-import { BUILD_GATES, knownSecretsFrom, runGates, SOURCE_GATES } from "../gates/index.js";
+import { BUILD_GATES, gateSummary, knownSecretsFrom, runGates, SOURCE_GATES } from "../gates/index.js";
 import { readDevVars } from "../project.js";
 const MODULE_EXT = new Set([".js", ".mjs", ".wasm"]);
 function walk(dir, base = dir) {
@@ -72,10 +72,11 @@ export async function deploy(opts) {
         const gates = await runGates(SOURCE_GATES, { root, knownSecrets, approvedSuppressions: await approvedSuppressions(root), log: (l) => log.info(l) }, { stopOnFail: true });
         if (!gates.ok)
             throw new CliError(`Blocked by: ${gates.failed.map((g) => g.title).join(", ")}. Fix the findings above, then deploy again.`, 2);
-        log.ok("Gates passed");
+        log.ok(gateSummary(gates.results));
     }
     if (!opts["skip-build"]) {
         log.step("Building with vite");
+        ensureDeps(root);
         await runOrThrow("npx", ["vite", "build"], { cwd: root });
     }
     const build = readBuildOutput(root);
@@ -109,6 +110,7 @@ export async function deploy(opts) {
     if (opts.json)
         return printJson({ deployment, url: project.url, migrations: mig });
     log.ok(`Deployed ${deployment.id} (${deployment.status}) → ${project.url}`);
+    log.info(`First time? Sign up on your app at ${project.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
 }
 export async function deployments(opts) {
     const nerd = readNerdJson(findProjectRoot());

package/dist/commands/dev.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { ApiClient } from "../api.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson, writeDevVars } from "../project.js";
-import { log, run, runOrThrow } from "../util.js";
+import { log, run, runOrThrow, ensureDeps } from "../util.js";
 /** Makes sure .dev.vars carries the platform bindings for local dev, minting a dev tenant secret once. */
 export async function ensureDevVars(root) {
     const nerd = readNerdJson(root);
@@ -33,6 +33,7 @@ export async function dev(extra) {
         await runOrThrow("npx", ["wrangler", "d1", "migrations", "apply", "DB", "--local"], { cwd: root });
     }
     log.step("Starting vite dev");
+    ensureDeps(root);
     const code = await run("npx", ["vite", ...extra], { cwd: root });
     process.exitCode = code;
 }

package/dist/commands/doctor.js

@@ -30,7 +30,7 @@ export async function doctor(opts) {
     }
     for (const tool of ["gitleaks", "semgrep", "osv-scanner"]) {
         const ok = await hasTool(tool);
-        checks.push({ name: `${tool} (optional)`, ok, detail: ok ? "installed" : "not installed; the builder runs it for you", fix: `Optional for \`nerd verify\` locally.` });
+        checks.push({ name: `${tool} (optional)`, ok, detail: ok ? "installed" : "not installed; git builds run it in the builder, but `nerd check` and `nerd deploy` from this machine skip it", fix: `Optional for \`nerd verify\` locally.` });
     }
     if (opts.json)
         return printJson({ ok: checks.filter((c) => !c.name.includes("optional")).every((c) => c.ok), checks });

package/dist/commands/github.d.ts

@@ -7,6 +7,7 @@ export declare function githubLink(fullName: string | undefined, opts: {
     "root-dir"?: string;
     "no-previews": boolean;
     "require-pr": boolean;
+    agent?: string;
     installation?: string;
 }): Promise<void>;
 export declare function githubUnlink(opts: {

package/dist/commands/github.js

@@ -10,9 +10,9 @@ export async function githubConnect(opts) {
 }
 export async function githubLink(fullName, opts) {
     if (!fullName)
-        throw new CliError("Usage: nerd github link owner/repo [--branch main] [--root-dir apps/web] [--no-previews] [--require-pr]");
+        throw new CliError("Usage: nerd github link owner/repo [--branch main] [--root-dir apps/web] [--no-previews] [--require-pr] [--agent @claude]");
     const nerd = readNerdJson(findProjectRoot());
-    const body = { fullName, previews: !opts["no-previews"], rootDir: opts["root-dir"] ?? "", requirePr: opts["require-pr"] };
+    const body = { fullName, previews: !opts["no-previews"], rootDir: opts["root-dir"] ?? "", requirePr: opts["require-pr"], ...(opts.agent ? { agentMention: opts.agent } : {}) };
     if (opts.branch)
         body.productionBranch = opts.branch;
     if (opts.installation)