nerdsystem 0.0.6 → 0.0.8

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(process.stdin.isTTY ? "Not deleted. Pass --yes to skip the question." : "Not deleted. Pass --yes to confirm.");
+    }
+    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;

package/dist/gates/text.js

@@ -19,13 +19,34 @@ export const SECRET_PATTERNS = [
     { rule: "private-key", re: /-----BEGIN (RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY( BLOCK)?-----/g },
     { rule: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
     { rule: "nerdsystem-token", re: /\bn(sk|as|bt|rt|ss|pr|iv)_[a-z0-9]{40}\b/g },
-    { rule: "db-url-with-password", re: /\b(postgres|postgresql|mysql|mongodb(\+srv)?|redis):\/\/[^:\s/]+:[^@\s/]{4,}@/g },
+    { rule: "db-url-with-password", re: /\b(postgres|postgresql|mysql|mongodb(\+srv)?|redis):\/\/[^:\s/]+:[^@\s/]{4,}@[^/\s:?"'`]+/g },
     { rule: "generic-assignment", re: /\b(api[_-]?key|secret|password|passwd|token|client[_-]?secret)\b\s*[:=]\s*["'`]([A-Za-z0-9+/_=.-]{24,})["'`]/gi },
 ];
 const ALLOW = [/example/i, /placeholder/i, /your[-_ ]?key/i, /xxxx/i, /\$\{/, /process\.env/, /c\.env\./, /import\.meta\.env/, /nsk_\.\.\./];
 export function isAllowedLine(line) {
     return ALLOW.some((a) => a.test(line));
 }
+/** Files that exist to show the shape of a secret, not to hold one. Findings in them warn instead of block. */
+export const EXAMPLE_FILE = /(\.(example|sample|template)|(^|\/)\.env\.(example|sample))$/i;
+export function isExampleFile(file) {
+    return EXAMPLE_FILE.test(file);
+}
+/** Passwords nobody would use for real: the defaults every tutorial and docker-compose file carries. */
+const PLACEHOLDER_PASSWORDS = new Set(["root", "password", "pass", "secret", "changeme", "example", "test", "your-password", "your_password", "yourpassword", "postgres", "mysql", "admin"]);
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0", "host.docker.internal"]);
+const PLACEHOLDER_VALUE = /xxx|your[_-]|example|changeme|placeholder|<|>|\.\.\./i;
+/** 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 function isPlaceholderValue(rule, value) {
+    if (rule === "db-url-with-password") {
+        const m = /:\/\/([^:]+):([^@]+)@([^/\s:?"'`]+)/.exec(value);
+        if (!m)
+            return false;
+        const password = m[2].toLowerCase();
+        const host = m[3].toLowerCase();
+        return PLACEHOLDER_PASSWORDS.has(password) || LOCAL_HOSTS.has(host) || PLACEHOLDER_VALUE.test(password);
+    }
+    return PLACEHOLDER_VALUE.test(value);
+}
 /** Type and last four characters only: "sk_live_****4f2a". Never the value. */
 export function mask(match) {
     const compact = match.replace(/\s+/g, "");
@@ -55,7 +76,8 @@ export function findSecrets(text, file, limit = 50) {
                 continue;
             hitLines.add(line);
             const matched = p.rule === "generic-assignment" ? (m[2] ?? m[0]) : m[0];
-            hits.push({ rule: p.rule, file, line, masked: p.rule === "private-key" ? "private key" : mask(matched) });
+            const downgrade = isExampleFile(file) ? "example file" : p.rule !== "private-key" && isPlaceholderValue(p.rule, matched) ? "placeholder value" : undefined;
+            hits.push({ rule: p.rule, file, line, masked: p.rule === "private-key" ? "private key" : mask(matched), ...(downgrade ? { downgrade } : {}) });
             if (hits.length >= limit)
                 return hits;
         }
@@ -70,3 +92,61 @@ export const ENV_FILES = /(^|\/)(\.env(\.[A-Za-z0-9_-]+)?|\.dev\.vars(\.[A-Za-z0
 /** Source files worth scanning for text patterns; everything else is skipped as binary or generated. */
 export const TEXT_FILE = /(\.(ts|tsx|js|jsx|mjs|cjs|json|jsonc|toml|yaml|yml|env|vars|md|html|css|sql|py|rb|go|rs|java|kt|swift|php|sh|txt|cfg|ini|conf|xml)|(^|\/)(README|LICENSE|Dockerfile|Makefile|Procfile|\.gitignore|\.npmrc))$/i;
 export const SKIP_DIR = /(^|\/)(node_modules|dist|build|\.git|\.wrangler|\.next|\.nuxt|coverage|vendor|target)(\/|$)/;
+export function normalizeSeverity(raw) {
+    const s = (raw ?? "").trim().toLowerCase();
+    if (s === "critical")
+        return "critical";
+    if (s === "high")
+        return "high";
+    if (s === "moderate" || s === "medium")
+        return "moderate";
+    if (s === "low" || s === "info" || s === "informational")
+        return "low";
+    return "unknown";
+}
+/**
+ * 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 function osvSeverity(v) {
+    const direct = normalizeSeverity(v.database_specific?.severity);
+    if (direct !== "unknown")
+        return direct;
+    for (const a of v.affected ?? []) {
+        const s = normalizeSeverity(a.ecosystem_specific?.severity);
+        if (s !== "unknown")
+            return s;
+    }
+    for (const s of v.severity ?? []) {
+        if (/^CVSS_V3/i.test(s.type ?? "") && s.score) {
+            const score = cvss3BaseScore(s.score);
+            if (score !== null)
+                return score >= 9 ? "critical" : score >= 7 ? "high" : score >= 4 ? "moderate" : score > 0 ? "low" : "unknown";
+        }
+    }
+    return "unknown";
+}
+/** CVSS v3.0/3.1 base score from a vector string, or null when the vector is malformed. */
+export function cvss3BaseScore(vector) {
+    const parts = Object.fromEntries(vector.split("/").slice(1).map((kv) => kv.split(":")));
+    const AV = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 }[parts.AV ?? ""];
+    const AC = { L: 0.77, H: 0.44 }[parts.AC ?? ""];
+    const UI = { N: 0.85, R: 0.62 }[parts.UI ?? ""];
+    const CIA = { H: 0.56, L: 0.22, N: 0 };
+    const C = CIA[(parts.C ?? "")];
+    const I = CIA[(parts.I ?? "")];
+    const A = CIA[(parts.A ?? "")];
+    const scopeChanged = parts.S === "C";
+    const PR = scopeChanged ? { N: 0.85, L: 0.68, H: 0.5 }[parts.PR ?? ""] : { N: 0.85, L: 0.62, H: 0.27 }[parts.PR ?? ""];
+    if ([AV, AC, UI, C, I, A, PR].some((x) => x === undefined) || (parts.S !== "C" && parts.S !== "U"))
+        return null;
+    const iss = 1 - (1 - C) * (1 - I) * (1 - A);
+    const impact = scopeChanged ? 7.52 * (iss - 0.029) - 3.25 * Math.pow(iss - 0.02, 15) : 6.42 * iss;
+    const exploitability = 8.22 * AV * AC * PR * UI;
+    if (impact <= 0)
+        return 0;
+    const roundUp = (x) => Math.ceil(x * 10 - 1e-9) / 10;
+    return scopeChanged ? roundUp(Math.min(1.08 * (impact + exploitability), 10)) : roundUp(Math.min(impact + exploitability, 10));
+}

package/dist/gates/types.d.ts

@@ -70,3 +70,15 @@ export declare function result(gate: Gate, status: GateStatus, summary: string,
 /** Status from findings: any block = fail, any warn = warn, else pass. */
 export declare function verdict(findings: Finding[]): GateStatus;
 export declare function counts(findings: Finding[]): string;
+export interface SkippedGate {
+    name: string;
+    title: string;
+    reason: string;
+}
+/** Gates that did not run this time (a scanner is not installed, no build output), so "passed" is never claimed for them. */
+export declare function skippedGates(results: GateResult[]): SkippedGate[];
+/**
+ * One honest line: "7 gates passed, 2 skipped (semgrep, gitleaks not installed; install them or deploy from git so the builder runs them)".
+ * Never "All gates passed" when something did not run.
+ */
+export declare function gateSummary(results: GateResult[]): string;

package/dist/gates/types.js

@@ -16,3 +16,21 @@ export function counts(findings) {
         return "No findings";
     return [b ? `${b} blocking` : "", w ? `${w} advisory` : "", findings.length - b - w ? `${findings.length - b - w} informational` : ""].filter(Boolean).join(", ");
 }
+/** Gates that did not run this time (a scanner is not installed, no build output), so "passed" is never claimed for them. */
+export function skippedGates(results) {
+    return results.filter((r) => r.status === "skip").map((r) => ({ name: r.name, title: r.title, reason: r.summary }));
+}
+/**
+ * One honest line: "7 gates passed, 2 skipped (semgrep, gitleaks not installed; install them or deploy from git so the builder runs them)".
+ * Never "All gates passed" when something did not run.
+ */
+export function gateSummary(results) {
+    const skipped = skippedGates(results);
+    const passed = results.filter((r) => r.status === "pass" || r.status === "warn").length;
+    if (!skipped.length)
+        return `All ${passed} gates passed`;
+    const tools = skipped.filter((s) => /not installed/.test(s.reason)).map((s) => s.name);
+    const other = skipped.filter((s) => !/not installed/.test(s.reason)).map((s) => `${s.name}: ${s.reason}`);
+    const why = [tools.length ? `${tools.join(", ")} not installed; install them or deploy from git so the builder runs them` : "", ...other].filter(Boolean).join("; ");
+    return `${passed} gate${passed === 1 ? "" : "s"} passed, ${skipped.length} skipped (${why})`;
+}