nerdsystem 0.0.5 → 0.0.7

package/dist/commands/init.js

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -41,7 +42,7 @@ export async function linkProject(root, args) {
         log.ok(`Linked to existing project ${org}/${args.slug}`);
     }
     catch (err) {
-        if (!args.create || !(err instanceof CliError) || !err.message.startsWith("not_found"))
+        if (!args.create || !(err instanceof CliError) || err.code !== "not_found")
             throw err;
         log.step(`Creating project ${org}/${args.slug} (provisions a database and a bucket)`);
         project = (await api.post(`/v1/orgs/${org}/projects`, { slug: args.slug, name: args.name })).project;
@@ -69,6 +70,50 @@ function seedDescription(root, name, description) {
     const heading = `# ${name}\n\n${description ? `${description}\n\n` : "(Describe what this app does here; the agent starts from it.)\n\n"}`;
     writeFileSync(p, heading + readFileSync(p, "utf8").replace(/^# This app runs on nerdsystem\n/, "## This app runs on nerdsystem\n"));
 }
+/** Ten lines a person can read before opening the agent. */
+function writeReadme(root, name, description) {
+    const lines = [
+        `# ${name}`,
+        "",
+        description ?? "An app built with a coding agent and deployed on nerdsystem.",
+        "",
+        "- `nerd dev` runs it locally with real sign-in.",
+        "- `nerd check` runs every gate a deploy runs (secrets, dependencies, platform rules, types).",
+        "- `nerd deploy` checks, builds, migrates, and ships it; the URL is printed at the end.",
+        "",
+        "Guides for each coding agent: https://nerdsystem.com/guides",
+        "",
+    ];
+    writeFileSync(path.join(root, "README.md"), lines.join("\n"));
+}
+/**
+ * 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.
+ */
+function initGitRepo(root) {
+    try {
+        try {
+            execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "ignore" });
+            return; // already a repository, or inside one
+        }
+        catch {
+            // not a repository yet
+        }
+        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"];
+        try {
+            execFileSync("git", commit, { cwd: root, stdio: "ignore" });
+        }
+        catch {
+            // No identity configured on this machine yet: commit under a placeholder rather than leave the tree uncommitted.
+            execFileSync("git", ["-c", "user.name=nerd", "-c", "user.email=nerd@nerdsystem.com", ...commit], { cwd: root, stdio: "ignore" });
+        }
+    }
+    catch {
+        // git missing or not configured: fine, the person can init later
+    }
+}
 export async function init(dir, args) {
     if (!dir)
         throw new CliError("Usage: nerd init <directory> [--org slug] [--name 'My App'] [--slug my-app]");
@@ -77,8 +122,19 @@ export async function init(dir, args) {
     if (!SLUG_RE.test(slug))
         throw new CliError(`"${slug}" is not a valid project slug (lowercase letters, digits, hyphens). Pass --slug.`);
     const name = args.name ?? slug;
-    if (existsSync(root) && readdirSync(root).length > 0)
-        throw new CliError(`${root} is not empty.`);
+    if (existsSync(root) && readdirSync(root).length > 0) {
+        throw new CliError(`${root} is not empty. If an earlier \`nerd init\` stopped partway, run \`nerd link --slug ${slug}\` inside it instead; otherwise pick a new folder name.`);
+    }
+    // Everything that can fail remotely is checked before a single file is written, so a failure never
+    // leaves a half-made folder behind.
+    if (!args["no-create"]) {
+        const api = ApiClient.fromConfig(); // throws "Not logged in" with the fix
+        const me = await api.get("/v1/me");
+        if (me.orgs.length === 0)
+            throw new CliError("Your account has no organization yet. Sign in to the dashboard once, or ask the person who invited you for the link.");
+        if (args.org && !me.orgs.some((o) => o.slug === args.org))
+            throw new CliError(`You are not in an org called "${args.org}". Yours: ${me.orgs.map((o) => o.slug).join(", ")}`);
+    }
     const src = templateDir();
     log.step(`Copying template into ${root}`);
     mkdirSync(root, { recursive: true });
@@ -87,6 +143,7 @@ export async function init(dir, args) {
     // The published template carries ".gitignore" as "gitignore" (npm strips the dotted name from packages).
     if (existsSync(path.join(root, "gitignore")) && !existsSync(path.join(root, ".gitignore")))
         renameSync(path.join(root, "gitignore"), path.join(root, ".gitignore"));
+    const description = args.describe ?? (await askDescription());
     // Rename the app and point the SDK dependency somewhere installable.
     const pkgPath = path.join(root, "package.json");
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
@@ -98,10 +155,23 @@ export async function init(dir, args) {
         const p = path.join(root, f);
         writeFileSync(p, readFileSync(p, "utf8").replaceAll("nerd-app", slug));
     }
-    const description = args.describe ?? (await askDescription());
+    // The visible brand in the client: the display name, unless it would break JSX text.
+    const display = /[<>{}]/.test(name) ? slug : name;
+    const appTsx = path.join(root, "src/client/App.tsx");
+    if (existsSync(appTsx))
+        writeFileSync(appTsx, readFileSync(appTsx, "utf8").replaceAll("nerd-app", display));
+    writeReadme(root, name, description);
     seedDescription(root, name, description);
-    const project = await linkProject(root, { ...(args.org !== undefined ? { org: args.org } : {}), slug, name, create: !args["no-create"] });
+    let project;
+    try {
+        project = await linkProject(root, { ...(args.org !== undefined ? { org: args.org } : {}), slug, name, create: !args["no-create"] });
+    }
+    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}` : ""}`);
+    }
+    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.5";
+const SDK_VERSION = "0.0.7";

package/dist/commands/login.js

@@ -28,7 +28,7 @@ export async function login(args) {
         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 with the same link went to ${args.email}.`);
+                log.info(`An email went to ${args.email}: one click signs you in (creating your account if you are new) and approves.`);
             log.info("Waiting for approval…");
         }
     }

package/dist/commands/ops.d.ts

@@ -23,6 +23,7 @@ export declare function secretList(opts: {
 /** Value from the argument, or from stdin when omitted, so keys stay out of shell history. */
 export declare function secretSet(name: string | undefined, value: string | undefined, opts: {
     json: boolean;
+    previews?: boolean;
 }): Promise<void>;
 export declare function secretRemove(name: string | undefined, opts: {
     json: boolean;

package/dist/commands/ops.js

@@ -81,13 +81,13 @@ export async function secretList(opts) {
         return printJson(r);
     if (!r.secrets.length)
         return log.info("No app secrets yet. Set one with: nerd secret set STRIPE_SECRET_KEY");
-    table(r.secrets.map((s) => ({ name: s.name, updated: s.updatedAt })), ["name", "updated"]);
+    table(r.secrets.map((s) => ({ name: s.name, previews: s.scope === "all" ? "yes" : "no", updated: s.updatedAt })), ["name", "previews", "updated"]);
     log.info(`\n${r.note}`);
 }
 /** Value from the argument, or from stdin when omitted, so keys stay out of shell history. */
 export async function secretSet(name, value, opts) {
     if (!name)
-        throw new CliError("Usage: nerd secret set NAME [value]   (omit the value to read it from stdin)");
+        throw new CliError("Usage: nerd secret set NAME [value] [--previews]   (omit the value to read it from stdin; --previews also gives it to pull request previews)");
     let v = value;
     if (v === undefined) {
         if (process.stdin.isTTY)
@@ -97,7 +97,7 @@ export async function secretSet(name, value, opts) {
     if (!v)
         throw new CliError("Empty value.");
     const nerd = readNerdJson(findProjectRoot());
-    const r = await ApiClient.fromConfig().put(projectPath(nerd, `/secrets/${name}`), { value: v });
+    const r = await ApiClient.fromConfig().put(projectPath(nerd, `/secrets/${name}`), { value: v, scope: opts.previews ? "all" : "production" });
     if (opts.json)
         return printJson(r);
     log.ok(`Set ${r.secret.name}. ${r.note} For local dev, add ${name}=... to .dev.vars (never commit it).`);

package/dist/commands/org.js

@@ -76,7 +76,7 @@ export async function logs(opts) {
     if (!r.events.length)
         return log.info(`No log events for ${r.scriptName} in the last ${opts.since ?? "30m"}.`);
     for (const e of [...r.events].reverse())
-        process.stdout.write(`${e.timestamp} ${e.level.padEnd(5)} ${e.context ? `${e.context} ` : ""}${e.message}\n`);
+        process.stdout.write(`${e.timestamp} ${e.level.padEnd(5)} ${e.context && e.context !== e.message ? `${e.context} ` : ""}${e.message}\n`);
 }
 export async function auditExport(opts) {
     const org = orgSlug(opts);

package/dist/commands/trash.d.ts

@@ -0,0 +1,17 @@
+/** `nerd delete`: the app goes offline now; the API keeps the data for a grace period and can restore it. */
+export declare function deleteProject(opts: {
+    json: boolean;
+    yes: boolean;
+    org?: string | undefined;
+    slug?: string | undefined;
+}): Promise<void>;
+/** `nerd trash`: deleted projects still inside their grace period. */
+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. */
+export declare function trashRestore(slug: string | undefined, opts: {
+    json: boolean;
+    org?: string | undefined;
+}): Promise<void>;

package/dist/commands/trash.js

@@ -0,0 +1,84 @@
+import { ApiClient } from "../api.js";
+import { findProjectRoot, readNerdJson } from "../project.js";
+import { CliError, log, printJson, table } from "../util.js";
+/** The project named on the command line, or the one this directory is linked to. */
+async function target(opts) {
+    if (opts.slug) {
+        if (opts.org)
+            return { org: opts.org, project: opts.slug };
+        try {
+            return { org: readNerdJson(findProjectRoot()).org, project: opts.slug };
+        }
+        catch {
+            const me = await ApiClient.fromConfig().get("/v1/me");
+            if (me.orgs.length === 1)
+                return { org: me.orgs[0].slug, project: opts.slug };
+            throw new CliError(`Pass --org too. Yours: ${me.orgs.map((o) => o.slug).join(", ")}`);
+        }
+    }
+    const nerd = readNerdJson(findProjectRoot());
+    return { org: opts.org ?? nerd.org, project: nerd.project };
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY || process.env.CI)
+        return false;
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await rl.question(`${question} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/** `nerd delete`: the app goes offline now; the API keeps the data for a grace period and can restore it. */
+export async function deleteProject(opts) {
+    const t = await target(opts);
+    const name = `${t.org}/${t.project}`;
+    if (!opts.yes) {
+        if (opts.json)
+            throw new CliError(`Refusing to delete ${name} without --yes.`);
+        const ok = await confirm(`Delete ${name}? The app goes offline now; its database and files are kept for a week and can be restored with \`nerd trash restore ${t.project}\`.`);
+        if (!ok)
+            throw new CliError(`Not deleted. Pass --yes to skip the question.`);
+    }
+    const r = await ApiClient.fromConfig().delete(`/v1/orgs/${t.org}/projects/${t.project}`);
+    if (opts.json)
+        return printJson({ ...r, org: t.org, project: t.project });
+    log.ok(`Deleted ${name}. The app is offline; its data is destroyed after ${r.purgeAfter.slice(0, 10)}.`);
+    log.info(`Changed your mind? \`nerd trash restore ${t.project}${opts.org ? ` --org ${t.org}` : ""}\` before then (API: ${r.restore}).`);
+}
+/** `nerd trash`: deleted projects still inside their grace period. */
+export async function trashList(opts) {
+    let org = opts.org;
+    if (!org) {
+        try {
+            org = readNerdJson(findProjectRoot()).org;
+        }
+        catch {
+            const me = await ApiClient.fromConfig().get("/v1/me");
+            if (me.orgs.length !== 1)
+                throw new CliError(`Pass --org. Yours: ${me.orgs.map((o) => o.slug).join(", ")}`);
+            org = me.orgs[0].slug;
+        }
+    }
+    const r = await ApiClient.fromConfig().get(`/v1/orgs/${org}/trash`);
+    if (opts.json)
+        return printJson(r);
+    if (!r.projects.length)
+        return log.info(`Nothing in the trash for ${org}.`);
+    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. */
+export async function trashRestore(slug, opts) {
+    if (!slug)
+        throw new CliError("Usage: nerd trash restore <slug> [--org <org>]");
+    const t = await target({ org: opts.org, slug });
+    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);
+}

package/dist/commands/verify.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { ApiClient } from "../api.js";
-import { BUILD_GATES, knownSecretsFrom, runGates, SOURCE_GATES } from "../gates/index.js";
+import { BUILD_GATES, gateSummary, knownSecretsFrom, runGates, skippedGates, SOURCE_GATES } from "../gates/index.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson } from "../project.js";
 import { CliError, log } from "../util.js";
 import { readBuildOutput } from "./deploy.js";
@@ -39,9 +39,9 @@ export async function verify(opts) {
     const root = findProjectRoot();
     const out = await runVerify(root, { withBuild: !opts["no-build"], stopOnFail: false, quiet: opts.json, onlyRules: opts.rule ? [opts.rule] : undefined });
     if (opts.json)
-        process.stdout.write(`${JSON.stringify({ ok: out.ok, failures: out.failures, stop: out.stop }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ok: out.ok, failures: out.failures, stop: out.stop, skipped: skippedGates(out.results) }, null, 2)}\n`);
     else if (out.ok)
-        log.ok("All gates passed");
+        log.ok(gateSummary(out.results));
     const human = out.failures.filter((f) => f.audience === "human" && f.severity === "block");
     if (!opts.json && human.length)
         log.warn(`${human.length} finding(s) need a person, not the agent: ${human.map((f) => f.rule_id).join(", ")}`);

package/dist/gates/code.d.ts

@@ -1,3 +1,4 @@
+import { type AdvisorySeverity } from "./text.js";
 import { type Gate } from "./types.js";
 export declare function exec(cmd: string, args: string[], cwd: string): Promise<{
     code: number;
@@ -8,7 +9,9 @@ export declare function hasTool(name: string): Promise<boolean>;
 /** Platform rules, as `nerd check` enforces them. The rule text is ours, so it is safe to show verbatim. */
 export declare const rulesGate: Gate;
 export declare const typecheckGate: Gate;
-/** Known vulnerabilities in dependencies. Critical blocks; high warns. Package names come from the registry, not the repo. */
+/** The catalog rule for an advisory severity. Critical and high block, as the homepage promises; moderate warns; low and unrated inform. */
+export declare function depsRuleFor(severity: AdvisorySeverity): string;
+/** Known vulnerabilities in dependencies. Critical and high block; moderate warns. Package names come from the registry, not the repo. */
 export declare const depsGate: Gate;
 export declare const policyGate: Gate;
 /** Heuristics for careless handling of personal data. Advisory: warns, never blocks. */

package/dist/gates/code.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { staticChecks } from "../commands/check.js";
 import { lineOf, sourceFiles } from "./fs.js";
 import { finding } from "./secrets.js";
+import { BLOCKED_PACKAGES, MINING_POOLS, normalizeSeverity, osvSeverity } from "./text.js";
 import { counts, result, verdict } from "./types.js";
 export function exec(cmd, args, cwd) {
     return new Promise((resolve) => {
@@ -66,7 +67,11 @@ function depsVerdictSummary(findings) {
         return "No lockfile; commit one so installs are reproducible";
     return findings.length ? counts(findings) : "No known vulnerabilities";
 }
-/** Known vulnerabilities in dependencies. Critical blocks; high warns. Package names come from the registry, not the repo. */
+/** The catalog rule for an advisory severity. Critical and high block, as the homepage promises; moderate warns; low and unrated inform. */
+export function depsRuleFor(severity) {
+    return severity === "critical" ? "deps/critical-vulnerability" : severity === "high" ? "deps/high-vulnerability" : severity === "moderate" ? "deps/moderate-vulnerability" : severity === "low" ? "deps/low-vulnerability" : "deps/advisory";
+}
+/** Known vulnerabilities in dependencies. Critical and high block; moderate warns. Package names come from the registry, not the repo. */
 export const depsGate = {
     name: "dependencies",
     title: "Dependency vulnerabilities",
@@ -78,7 +83,6 @@ export const depsGate = {
         const lock = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock"].find((f) => existsSync(path.join(ctx.root, f)));
         if (!lock)
             findings.push(finding("deps/lockfile-required", {}));
-        const sev = (s) => (s.toUpperCase() === "CRITICAL" ? "deps/critical-vulnerability" : s.toUpperCase() === "HIGH" ? "deps/high-vulnerability" : "deps/advisory");
         if (await hasTool("osv-scanner")) {
             const r = await exec("osv-scanner", ["scan", "source", "--format", "json", "--lockfile", lock ?? "pnpm-lock.yaml"], ctx.root);
             try {
@@ -86,7 +90,7 @@ export const depsGate = {
                 for (const res of json.results ?? [])
                     for (const p of res.packages ?? [])
                         for (const v of p.vulnerabilities) {
-                            const id = sev(v.database_specific?.severity ?? "MODERATE");
+                            const id = depsRuleFor(osvSeverity(v));
                             findings.push(finding(id, { file: lock, fix: `Update ${p.package.name} from ${p.package.version} to a version without ${v.id} (https://osv.dev/vulnerability/${v.id}); \`pnpm update ${p.package.name}\`.`, fingerprint: `${v.id}:${p.package.name}` }));
                         }
                 return result(this, verdict(findings), depsVerdictSummary(findings), findings, t, "osv-scanner");
@@ -100,7 +104,7 @@ export const depsGate = {
         try {
             const json = JSON.parse(r.stdout);
             for (const a of Object.values(json.advisories ?? {})) {
-                findings.push(finding(sev(a.severity), { file: lock, fix: `Update ${a.module_name} to a fixed version${a.url ? ` (${a.url})` : ""}; \`${pm} update ${a.module_name}\`.`, fingerprint: `${a.url ?? a.module_name}` }));
+                findings.push(finding(depsRuleFor(normalizeSeverity(a.severity)), { file: lock, fix: `Update ${a.module_name} to a fixed version${a.url ? ` (${a.url})` : ""}; \`${pm} update ${a.module_name}\`.`, fingerprint: `${a.url ?? a.module_name}` }));
             }
         }
         catch {
@@ -111,7 +115,6 @@ export const depsGate = {
     },
 };
 /** Packages that have no place in a hosted web app, and size caps. Deterministic policy only. */
-import { BLOCKED_PACKAGES, MINING_POOLS } from "./text.js";
 const MAX_WORKER_BYTES = 10 * 1024 * 1024;
 const MAX_ASSET_BYTES = 25 * 1024 * 1024;
 export const policyGate = {

package/dist/gates/fs.js

@@ -1,7 +1,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".wrangler", ".vite", "coverage"]);
-const TEXT_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".jsonc", ".md", ".mdc", ".yml", ".yaml", ".toml", ".env", ".txt", ".html", ".css", ".sql", ".example"]);
+const TEXT_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".jsonc", ".md", ".mdc", ".yml", ".yaml", ".toml", ".env", ".txt", ".html", ".css", ".sql", ".example", ".sample", ".template"]);
 const MAX_BYTES = 2 * 1024 * 1024;
 /** Text files under root, skipping dependencies and build output. */
 export function sourceFiles(root) {

package/dist/gates/index.d.ts

@@ -1,5 +1,6 @@
 import type { Finding, Gate, GateContext, GateResult } from "./types.js";
-export type { Audience, Finding, Gate, GateContext, GateResult, GateStatus, Severity } from "./types.js";
+export type { Audience, Finding, Gate, GateContext, GateResult, GateStatus, Severity, SkippedGate } from "./types.js";
+export { gateSummary, skippedGates } from "./types.js";
 export { RULES, ruleFor, type RuleDef } from "./rules.js";
 export { mask } from "./secrets.js";
 export { MAX_ATTEMPTS, readAttempts } from "./attempts.js";

package/dist/gates/index.js

@@ -3,6 +3,7 @@ import { depsGate, piiGate, policyGate, rulesGate, typecheckGate } from "./code.
 import { gitleaksGate, semgrepGate } from "./tools.js";
 import { suppressionsGate } from "./suppressions.js";
 import { applyAttempts, MAX_ATTEMPTS } from "./attempts.js";
+export { gateSummary, skippedGates } from "./types.js";
 export { RULES, ruleFor } from "./rules.js";
 export { mask } from "./secrets.js";
 export { MAX_ATTEMPTS, readAttempts } from "./attempts.js";

package/dist/gates/rules.js

@@ -23,11 +23,14 @@ export const RULES = {
     "secrets/rotate-committed-secret": { title: "A committed secret must be rotated", severity: "block", audience: "human", risk: "Removing a secret from the code does not remove it from git history; anyone who fetched the repository still has it.", fix: "Rotate the credential at the provider that issued it (create a new one, update the platform secret, revoke the old one). Then the agent can remove it from the code.", example: { wrong: "Delete the line and commit", right: "Rotate at the provider first, then delete the line" } },
     "bundle/known-secret-in-client": { title: "A server secret is in the client bundle", severity: "block", audience: "agent", risk: "A value from .dev.vars is compiled into JavaScript that every visitor downloads.", fix: "Only VITE_-prefixed variables belong in the client, and none of them may be secrets. Move the call that needs the secret to a server route.", example: { wrong: "fetch(api, { headers: { Authorization: import.meta.env.VITE_API_SECRET } })", right: "app.post('/api/thing', async (c) => fetch(api, { headers: { Authorization: c.env.API_SECRET } }))" } },
     "bundle/known-secret-in-server": { title: "A local secret value is in the server bundle", severity: "block", audience: "agent", risk: "A value that should come from platform secrets is hard-coded in the built server.", fix: "Read it from c.env instead of embedding it." },
+    "bundle/local-secrets-in-dist": { title: "Local secrets file copied into build output", severity: "warn", audience: "agent", risk: "A local secrets file (.dev.vars or .env*) was copied into dist/ by the build. It is not uploaded, but anyone who zips or shares dist/ ships the secrets with it.", fix: "Nothing to change in the code: do not zip or share dist/. Delete the copy with `rm dist/*/.dev.vars` before handing the folder to anyone, and keep .dev.vars and .env* in .gitignore." },
     "bundle/vite-secret-exposed": { title: "A VITE_ variable looks like a secret", severity: "block", audience: "agent", risk: "VITE_ variables are public: this one is compiled into the client where anyone can read it.", fix: "Rename it without the VITE_ prefix, set it as a server secret, and use it only in server code.", example: { wrong: "VITE_STRIPE_SECRET_KEY=sk_live_...", right: "STRIPE_SECRET_KEY as a platform secret, read on the server" } },
     "deps/lockfile-required": { title: "No lockfile", severity: "block", audience: "agent", risk: "Without a lockfile every install can pull different versions, so what passed checks is not what deploys.", fix: "Run `pnpm install` and commit pnpm-lock.yaml." },
-    "deps/critical-vulnerability": { title: "Dependency with a critical vulnerability", severity: "block", audience: "agent", risk: "A known, exploitable bug in a package your app ships.", fix: "Update the package to a fixed version (`pnpm update <name>`), or replace it if no fix exists. Dependabot pull requests do this automatically.", example: { wrong: '"lodash": "4.17.15"', right: '"lodash": "^4.17.21"' } },
-    "deps/high-vulnerability": { title: "Dependency with a high-severity advisory", severity: "warn", audience: "agent", risk: "A known bug in a package your app ships; exploitable in some setups.", fix: "Update the package when a fixed version exists." },
-    "deps/advisory": { title: "Dependency advisory", severity: "info", audience: "agent", risk: "A known issue of lower severity.", fix: "Update when convenient." },
+    "deps/critical-vulnerability": { title: "Dependency with a critical vulnerability", severity: "block", audience: "agent", risk: "A package your app ships has a critical, known, exploitable bug; attackers scan for exactly these.", fix: "Update the package to a fixed version (`pnpm update <name>`), or replace it if no fix exists. Dependabot pull requests do this automatically.", example: { wrong: '"lodash": "4.17.15"', right: '"lodash": "^4.17.21"' } },
+    "deps/high-vulnerability": { title: "Dependency with a high-severity vulnerability", severity: "block", audience: "agent", risk: "A package your app ships has a high-severity known bug that is exploitable in common setups.", fix: "Update the package to a fixed version (`pnpm update <name>`), or replace it if no fix exists.", example: { wrong: '"lodash": "4.17.15"', right: '"lodash": "^4.17.21"' } },
+    "deps/moderate-vulnerability": { title: "Dependency with a moderate-severity advisory", severity: "warn", audience: "agent", risk: "A package your app ships has a known bug of moderate severity; exploitable only in some setups, but still worth fixing before it grows.", fix: "Update the package when a fixed version exists (`pnpm update <name>`)." },
+    "deps/low-vulnerability": { title: "Dependency with a low-severity advisory", severity: "info", audience: "agent", risk: "A package your app ships has a known issue of low severity.", fix: "Update when convenient." },
+    "deps/advisory": { title: "Dependency advisory", severity: "info", audience: "agent", risk: "A package your app ships has a published advisory whose severity is not rated yet.", fix: "Read the advisory at the link in the finding and update if it applies to how you use the package." },
     "deps/audit-unavailable": { title: "Dependency audit could not run", severity: "warn", audience: "human", risk: "Vulnerable packages would not be detected this run.", fix: "Check network access and the package manager, then run `nerd verify` again." },
     "rules/platform": { title: "Platform rule", severity: "block", audience: "agent", risk: "The app would not run correctly on the platform.", fix: "Follow the instruction in the finding; the rules are listed in the nerdsystem skill." },
     "rules/advisory": { title: "Platform advisory", severity: "warn", audience: "agent", risk: "Not blocking, but the project is missing something the platform expects.", fix: "Follow the instruction in the finding." },

package/dist/gates/secrets.d.ts

@@ -5,6 +5,11 @@ export declare function finding(ruleId: string, extra: Partial<Finding> & {
     file?: string | undefined;
     line?: number | undefined;
 }): Finding;
+/**
+ * Findings for every credential-shaped value in a text. A hit in an example file or with an obvious
+ * placeholder value is reported as a warning with the reason in its risk text, so it is seen but
+ * never blocks a deploy and never asks a person to rotate anything.
+ */
 export declare function scanText(text: string, file: string): Finding[];
 export declare const secretsGate: Gate;
 /** Built output must not carry server secrets or anything that looks like one. */

package/dist/gates/secrets.js

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { exec } from "./code.js";
 import { sourceFiles } from "./fs.js";
-import { findSecrets, mask } from "./text.js";
+import { ENV_FILES, findSecrets, isExampleFile, mask } from "./text.js";
 import { RULES } from "./rules.js";
 import { counts, result, verdict } from "./types.js";
 export { mask } from "./text.js";
@@ -26,8 +26,19 @@ export function finding(ruleId, extra) {
         fingerprint: extra.fingerprint ?? fingerprint(ruleId, extra.file, extra.line),
     };
 }
+/**
+ * Findings for every credential-shaped value in a text. A hit in an example file or with an obvious
+ * placeholder value is reported as a warning with the reason in its risk text, so it is seen but
+ * never blocks a deploy and never asks a person to rotate anything.
+ */
 export function scanText(text, file) {
-    return findSecrets(text, file).map((h) => finding(`secrets/${h.rule}`, { file: h.file, line: h.line, masked: h.masked }));
+    return findSecrets(text, file).map((h) => {
+        const f = finding(`secrets/${h.rule}`, { file: h.file, line: h.line, masked: h.masked });
+        if (!h.downgrade)
+            return f;
+        const note = h.downgrade === "example file" ? "This is an example file, so it is shown as a warning; keep only placeholder values in it." : "The value looks like a placeholder (default password, local host, or stand-in text), so this is a warning, not a block; replace it with an environment reference anyway.";
+        return { ...f, severity: f.severity === "block" ? "warn" : f.severity, risk: `${f.risk} (${h.downgrade}) ${note}` };
+    });
 }
 async function isTracked(root, file) {
     if (!existsSync(path.join(root, ".git")))
@@ -44,28 +55,39 @@ export const secretsGate = {
         const t = Date.now();
         const findings = [];
         for (const f of sourceFiles(ctx.root)) {
-            if (/(^|\/)\.env(\.|$)/.test(f.rel) && !f.rel.endsWith(".example") && !f.rel.endsWith(".dev.vars.example"))
+            if (/(^|\/)\.env(\.|$)/.test(f.rel) && !isExampleFile(f.rel))
                 findings.push(finding("secrets/env-file-committed", { file: f.rel }));
             if (/(^|\/)\.dev\.vars$/.test(f.rel))
                 findings.push(finding("secrets/dev-vars-committed", { file: f.rel }));
-            if (f.rel.endsWith(".example"))
-                continue;
             findings.push(...scanText(f.text, f.rel));
         }
         const gitignore = path.join(ctx.root, ".gitignore");
         if (!existsSync(gitignore) || !/\.dev\.vars/.test(readFileSync(gitignore, "utf8")))
             findings.push(finding("secrets/gitignore-dev-vars", { file: ".gitignore" }));
         // A secret in a committed file is already in history: removing it is not enough, a person must rotate it.
-        const credentialFiles = Array.from(new Set(findings.filter((f) => f.file && f.masked).map((f) => f.file)));
+        // Only a blocking finding counts: example files and placeholder values are warnings and need no rotation.
+        const credentialFiles = Array.from(new Set(findings.filter((f) => f.file && f.masked && f.severity === "block").map((f) => f.file)));
         for (const file of credentialFiles) {
             if (ctx.committed || (await isTracked(ctx.root, file))) {
-                const first = findings.find((f) => f.file === file && f.masked);
+                const first = findings.find((f) => f.file === file && f.masked && f.severity === "block");
                 findings.push(finding("secrets/rotate-committed-secret", { file, line: first.line, masked: first.masked }));
             }
         }
         return result(this, verdict(findings), findings.length ? counts(findings) : "No credentials found in source", findings, t);
     },
 };
+const MAX_SCAN_BYTES = 8 * 1024 * 1024;
+function walkFiles(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        const full = path.join(dir, entry);
+        if (statSync(full).isDirectory())
+            out.push(...walkFiles(full));
+        else
+            out.push(full);
+    }
+    return out;
+}
 /** Built output must not carry server secrets or anything that looks like one. */
 export const bundleGate = {
     name: "bundle",
@@ -86,12 +108,30 @@ export const bundleGate = {
             if (isClient && /VITE_[A-Z0-9_]*(SECRET|PRIVATE|PASSWORD|TOKEN|API_KEY)[A-Z0-9_]*/.test(text))
                 findings.push(finding("bundle/vite-secret-exposed", { file: rel }));
         };
+        // The whole dist/ tree, not only what is uploaded: the Vite plugin copies .dev.vars next to the
+        // Worker, and anything else that lands here travels with the folder when someone zips it.
+        const dist = path.join(ctx.root, "dist");
+        const assetsDir = ctx.build.assetsDir ? path.resolve(ctx.build.assetsDir) : undefined;
+        const seen = new Set();
+        for (const full of existsSync(dist) ? walkFiles(dist) : []) {
+            const rel = path.relative(ctx.root, full).split(path.sep).join("/");
+            seen.add(path.resolve(full));
+            if (ENV_FILES.test(rel)) {
+                findings.push(finding("bundle/local-secrets-in-dist", { file: rel }));
+                continue;
+            }
+            if (!/\.(js|mjs|html|css|json|map|txt)$/.test(rel) || statSync(full).size > MAX_SCAN_BYTES)
+                continue;
+            const isClient = assetsDir ? path.resolve(full).startsWith(`${assetsDir}${path.sep}`) : rel.startsWith("dist/client/");
+            scan(rel, readFileSync(full, "utf8"), isClient);
+        }
+        // Build output that lives outside dist/ (tests, custom layouts): scan what the upload will carry.
         for (const m of ctx.build.modules)
-            if (/\.(js|mjs)$/.test(m))
+            if (/\.(js|mjs)$/.test(m) && !seen.has(path.resolve(ctx.build.workerDir, m)))
                 scan(`dist/worker/${m}`, readFileSync(path.join(ctx.build.workerDir, m), "utf8"), false);
         if (ctx.build.assetsDir)
             for (const a of ctx.build.assets)
-                if (/\.(js|mjs|html|css|json|map)$/.test(a))
+                if (/\.(js|mjs|html|css|json|map)$/.test(a) && !seen.has(path.resolve(ctx.build.assetsDir, a)))
                     scan(`dist/client/${a}`, readFileSync(path.join(ctx.build.assetsDir, a), "utf8"), true);
         return result(this, verdict(findings), findings.length ? counts(findings) : "Built output is clean", findings, t);
     },

package/dist/gates/text.d.ts

@@ -9,6 +9,11 @@ export declare const SECRET_PATTERNS: {
     re: RegExp;
 }[];
 export declare function isAllowedLine(line: string): boolean;
+/** Files that exist to show the shape of a secret, not to hold one. Findings in them warn instead of block. */
+export declare const EXAMPLE_FILE: RegExp;
+export declare function isExampleFile(file: string): boolean;
+/** True when a matched credential is clearly a stand-in: a placeholder token, or a database URL with a default password or a local host. */
+export declare function isPlaceholderValue(rule: string, value: string): boolean;
 /** Type and last four characters only: "sk_live_****4f2a". Never the value. */
 export declare function mask(match: string): string;
 export declare function lineAt(text: string, index: number): number;
@@ -18,6 +23,12 @@ export interface SecretHit {
     file: string;
     line: number;
     masked: string;
+    /**
+     * Why this hit should warn rather than block: the file is an example (`.env.example`, `*.sample`,
+     * `*.template`) or the value is an obvious stand-in (default password, local host, `xxx`, `your_`).
+     * Absent for a real-looking credential.
+     */
+    downgrade?: "example file" | "placeholder value";
 }
 /** Every credential-shaped value in a text, one hit per line, masked. */
 export declare function findSecrets(text: string, file: string, limit?: number): SecretHit[];
@@ -29,3 +40,31 @@ export declare const ENV_FILES: RegExp;
 /** Source files worth scanning for text patterns; everything else is skipped as binary or generated. */
 export declare const TEXT_FILE: RegExp;
 export declare const SKIP_DIR: RegExp;
+/** Advisory severity as the catalog names it. "unknown" when the database published none. */
+export type AdvisorySeverity = "critical" | "high" | "moderate" | "low" | "unknown";
+export declare function normalizeSeverity(raw: string | undefined | null): AdvisorySeverity;
+/** The parts of an OSV vulnerability record that carry a severity. Matches osv-scanner's JSON and GET /v1/vulns/{id}. */
+export interface OsvVulnerability {
+    id?: string;
+    database_specific?: {
+        severity?: string;
+    } | undefined;
+    severity?: {
+        type?: string;
+        score?: string;
+    }[] | undefined;
+    affected?: {
+        ecosystem_specific?: {
+            severity?: string;
+        };
+    }[] | undefined;
+}
+/**
+ * Severity of one OSV record: `database_specific.severity` (what GHSA publishes: CRITICAL, HIGH,
+ * MODERATE, LOW), else any `affected[].ecosystem_specific.severity`, else the CVSS 3.x base score
+ * computed from the vector in `severity[]`. The OSV batch query (`/v1/querybatch`) returns only ids;
+ * fetch `/v1/vulns/{id}` to get these fields.
+ */
+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;