nerdsystem 0.0.18 → 0.0.20

package/dist/cli.js

@@ -8,6 +8,7 @@ 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 { upgrade } from "./commands/upgrade.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";
@@ -57,6 +58,7 @@ const HELP = `nerd: start, check, and deploy a web app on nerdsystem
   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 upgrade                        Bring this app up to the current SDK, agent instructions, and test harness
   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
@@ -133,6 +135,10 @@ export async function main(argv) {
             const { values } = parse({ "skip-build": BOOL, "skip-probe": BOOL, force: BOOL, note: STR });
             return deploy(values);
         }
+        case "upgrade": {
+            const { values } = parse({}, false);
+            return upgrade({ json: Boolean(values.json) });
+        }
         case "save": {
             const { values } = parse({}, false);
             return save({ json: Boolean(values.json) });

package/dist/commands/deploy.js

@@ -8,6 +8,7 @@ import { CliError, log, printJson, runOrThrow, table, dashboardUrl, ensureDeps }
 import { runChecks } from "./check.js";
 import { appendLineage, cliVersion, LOCAL_ONLY_NOTE, packProject, readLineage, uploadSnapshot, uploadStopMessage } from "./source.js";
 import { lockedGetPaths } from "../gates/tests.js";
+import { platformScan } from "./platform-scan.js";
 import { BUILD_GATES, gateSummary, knownSecretsFrom, probeDeployment, runGates, skippedProbe, SOURCE_GATES, waitForDeployment } from "../gates/index.js";
 const MODULE_EXT = new Set([".js", ".mjs", ".wasm"]);
 function walk(dir, base = dir) {
@@ -155,6 +156,8 @@ export async function shipBuild(args) {
         appendLineage(root, source.id);
         // "Stored", not "saved": the one line that says "saved" is the final one, which also says the work after it is only on this computer (invariant 7).
         log.ok(`Stored ${pack.fileCount} files (${formatMb(pack.bytes)}) as ${source.id}`);
+        // The scanners this computer lacks run on the platform against the copy just stored, before migrations or upload.
+        args.results = await platformScan(api, `${projectPath(nerd)}/sources/${source.id}`, args.results);
     }
     log.step("Applying migrations to the production database");
     const mig = await applyRemoteMigrations(root, api);

package/dist/commands/init.d.ts

@@ -1,4 +1,5 @@
 import { type Project } from "../api.js";
+export declare function templateDir(): string;
 /** Creates the remote project and writes nerd.json. Shared by init and link. */
 export declare function linkProject(root: string, args: {
     org?: string;

package/dist/commands/init.js

@@ -6,7 +6,7 @@ import { ApiClient } from "../api.js";
 import { projectPath, writeNerdJson } from "../project.js";
 import { CliError, log, printJson } from "../util.js";
 const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$/;
-function templateDir() {
+export function templateDir() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
         process.env.NERD_TEMPLATE_DIR,
@@ -192,4 +192,4 @@ export async function init(dir, args) {
     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.18";
+const SDK_VERSION = "0.0.20";

package/dist/commands/platform-scan.d.ts

@@ -0,0 +1,18 @@
+import type { ApiClient } from "../api.js";
+import type { GateResult } from "../gates/index.js";
+export interface PlatformScanOptions {
+    /** How long the deploy waits for the answer. */
+    timeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * When gitleaks or semgrep did not run here because they are not installed, has the platform run them
+ * on the copy of the code that was just stored, and waits for the answer before anything goes live.
+ * Returns the gate results with the platform's answers in place of the skipped ones.
+ *
+ * A blocking finding stops the deploy, exactly as it would have locally. Anything else that goes wrong
+ * (the scanners are busy or down, the hourly allowance is used, the answer is late) does not: the two
+ * results stay "skip" with the reason, because a platform hiccup must not be what keeps an app offline.
+ */
+export declare function platformScan(api: ApiClient, sourcePath: string, results: GateResult[], opts?: PlatformScanOptions): Promise<GateResult[]>;

package/dist/commands/platform-scan.js

@@ -0,0 +1,58 @@
+import { CliError, log } from "../util.js";
+/** The two scanners most computers do not have. The platform's builder has both. */
+const SCANNERS = ["gitleaks", "semgrep"];
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * When gitleaks or semgrep did not run here because they are not installed, has the platform run them
+ * on the copy of the code that was just stored, and waits for the answer before anything goes live.
+ * Returns the gate results with the platform's answers in place of the skipped ones.
+ *
+ * A blocking finding stops the deploy, exactly as it would have locally. Anything else that goes wrong
+ * (the scanners are busy or down, the hourly allowance is used, the answer is late) does not: the two
+ * results stay "skip" with the reason, because a platform hiccup must not be what keeps an app offline.
+ */
+export async function platformScan(api, sourcePath, results, opts = {}) {
+    const missing = results.filter((r) => SCANNERS.includes(r.name) && r.status === "skip");
+    if (!missing.length)
+        return results;
+    const sleep = opts.sleep ?? defaultSleep;
+    const pollMs = opts.pollMs ?? 2500;
+    const deadline = Date.now() + (opts.timeoutMs ?? 150_000);
+    const skipped = (reason) => results.map((r) => (missing.includes(r) ? { ...r, summary: `${r.name} is not installed here, and the platform's scan ${reason}` } : r));
+    log.step(`Scanning the stored code on the platform (${missing.map((m) => m.name).join(" and ")} are not installed here)`);
+    let scan;
+    try {
+        scan = (await api.post(`${sourcePath}/scan`)).scan;
+        while ((scan.status === "queued" || scan.status === "running") && Date.now() < deadline) {
+            await sleep(pollMs);
+            const next = (await api.get(`${sourcePath}/scan`)).scan;
+            if (next)
+                scan = next;
+        }
+    }
+    catch (err) {
+        const why = err instanceof CliError && err.status === 429 ? "was not run: this organization has used its scans for the hour" : "could not be started";
+        log.warn(`The platform's scan ${why}. Continuing with the checks that ran here.`);
+        return skipped(why);
+    }
+    if (scan.status !== "done" || !scan.results) {
+        const why = scan.status === "failed" ? "failed" : "did not answer in time";
+        log.warn(`The platform's scan ${why}. Continuing with the checks that ran here.`);
+        return skipped(why);
+    }
+    const answered = new Map(scan.results.filter((r) => SCANNERS.includes(r.name)).map((r) => [r.name, r]));
+    const merged = results.map((r) => (missing.includes(r) && answered.has(r.name) ? { ...answered.get(r.name), summary: `${answered.get(r.name).summary} (scanned on the platform)` } : r));
+    const ran = merged.filter((r) => missing.some((m) => m.name === r.name));
+    for (const r of ran) {
+        log.info(`  ${r.status === "pass" ? "✓" : r.status === "fail" ? "✗" : r.status === "warn" ? "!" : "–"} ${r.title}: ${r.summary}`);
+        for (const f of r.findings.slice(0, 20)) {
+            log.info(`    ${f.severity === "block" ? "✗" : "!"} ${f.rule_id}${f.file ? ` ${f.file}${f.line ? `:${f.line}` : ""}` : ""}${f.masked ? ` (${f.masked})` : ""}`);
+            log.info(`      ${f.risk}`);
+            log.info(`      Fix: ${f.fix}`);
+        }
+    }
+    const blocked = ran.filter((r) => r.status === "fail");
+    if (blocked.length)
+        throw new CliError(`Blocked by: ${blocked.map((g) => g.title).join(", ")}. Nothing went live. Fix the findings above, then deploy again.`, 2, { code: "gate_failed" });
+    return merged;
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,16 @@
+export interface UpgradeResult {
+    from: string | null;
+    to: string;
+    changed: string[];
+    next: string[];
+}
+/**
+ * Brings an existing app up to the current platform: the SDK version, the instructions the agent reads,
+ * and the test harness. It replaces only what the platform owns and never touches the app's own code;
+ * what the app's code should adopt is then reported by `nerd check`, as findings the agent works through.
+ * Nothing is installed, deployed, or sent anywhere.
+ */
+export declare function upgradeProject(root: string, tpl: string, version: string): UpgradeResult;
+export declare function upgrade(opts: {
+    json: boolean;
+}): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,106 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { findProjectRoot } from "../project.js";
+import { log } from "../util.js";
+import { renderAgentFiles } from "./agents.js";
+import { templateDir } from "./init.js";
+import { cliVersion } from "./source.js";
+/** Files that are the platform's, not the app's: replaced with the current version every time. */
+const OURS = [".claude/skills/nerdsystem/SKILL.md", "test/setup.ts", "test/global-setup.ts", "vitest.config.ts"];
+/** Files an app is expected to change: written only when the app has none. */
+const STARTERS = [
+    ["test/access.test.ts", "test/access.test.ts"],
+    ["pnpm-workspace.app.yaml", "pnpm-workspace.yaml"],
+];
+/**
+ * Brings an existing app up to the current platform: the SDK version, the instructions the agent reads,
+ * and the test harness. It replaces only what the platform owns and never touches the app's own code;
+ * what the app's code should adopt is then reported by `nerd check`, as findings the agent works through.
+ * Nothing is installed, deployed, or sent anywhere.
+ */
+export function upgradeProject(root, tpl, version) {
+    const changed = [];
+    const read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : null);
+    const write = (rel, content) => {
+        const p = path.join(root, rel);
+        if (read(p) === content)
+            return;
+        mkdirSync(path.dirname(p), { recursive: true });
+        writeFileSync(p, content);
+        changed.push(rel);
+    };
+    const pkgPath = path.join(root, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const tplPkg = JSON.parse(readFileSync(path.join(tpl, "package.json"), "utf8"));
+    const before = JSON.stringify(pkg);
+    const current = pkg.dependencies?.["@nerdsystem/sdk"];
+    const from = /(\d+\.\d+\.\d+)/.exec(current ?? "")?.[1] ?? null;
+    pkg.dependencies ??= {};
+    pkg.devDependencies ??= {};
+    pkg.scripts ??= {};
+    // A workspace or file link is someone developing the platform itself; leave it alone.
+    if (!current || !/^(workspace|file|link):/.test(current))
+        pkg.dependencies["@nerdsystem/sdk"] = `^${version}`;
+    if (!pkg.dependencies.zod && tplPkg.dependencies?.zod)
+        pkg.dependencies.zod = tplPkg.dependencies.zod;
+    if (!pkg.devDependencies.vitest && tplPkg.devDependencies?.vitest)
+        pkg.devDependencies.vitest = tplPkg.devDependencies.vitest;
+    if (!pkg.scripts.test)
+        pkg.scripts.test = "vitest run";
+    if (JSON.stringify(pkg) !== before) {
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+        changed.push("package.json");
+    }
+    for (const rel of OURS) {
+        const content = read(path.join(tpl, rel));
+        if (content !== null)
+            write(rel, content);
+    }
+    const startersWritten = [];
+    for (const [fromRel, toRel] of STARTERS) {
+        const content = read(path.join(tpl, fromRel));
+        if (content !== null && !existsSync(path.join(root, toRel))) {
+            write(toRel, content);
+            startersWritten.push(toRel);
+        }
+    }
+    // CLAUDE.md is the platform's text, but people and agents add notes to it. A changed one is kept beside the new one.
+    const newClaude = read(path.join(tpl, "CLAUDE.md"));
+    const oldClaude = read(path.join(root, "CLAUDE.md"));
+    let keptOld = false;
+    if (newClaude !== null && oldClaude !== newClaude) {
+        if (oldClaude !== null && !existsSync(path.join(root, "CLAUDE.previous.md"))) {
+            renameSync(path.join(root, "CLAUDE.md"), path.join(root, "CLAUDE.previous.md"));
+            changed.push("CLAUDE.previous.md");
+            keptOld = true;
+        }
+        write("CLAUDE.md", newClaude);
+    }
+    // The files other agents read are generated from the skill that was just replaced.
+    for (const [rel, content] of Object.entries(renderAgentFiles(root).files))
+        write(rel, content);
+    const ignore = read(path.join(root, ".gitignore")) ?? "";
+    if (!/^\.nerd\/?$/m.test(ignore))
+        write(".gitignore", `${ignore}${ignore.endsWith("\n") || !ignore ? "" : "\n"}.nerd/\n`);
+    const next = ["Run `pnpm install`.", "Run `nerd check` and work through what it reports. It names what this app's own code should adopt (for example sign-in for every route, checked input, access tests)."];
+    if (startersWritten.includes("test/access.test.ts"))
+        next.push("`test/access.test.ts` is the starter's: keep the first test, and rewrite the owner test for this app's own routes. Then set `\"tests\": \"required\"` in nerd.json.");
+    if (keptOld)
+        next.push("Your earlier `CLAUDE.md` is now `CLAUDE.previous.md`. Move anything the person added into the new `CLAUDE.md`, then delete the old file.");
+    next.push("Tell the person in plain words what changed, then run `nerd deploy` when the check passes.");
+    return { from, to: version, changed, next };
+}
+export async function upgrade(opts) {
+    const root = findProjectRoot();
+    const r = upgradeProject(root, templateDir(), cliVersion());
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        return;
+    }
+    if (!r.changed.length)
+        log.ok(`Already current with nerd ${r.to}. Nothing was changed.`);
+    else
+        log.ok(`Updated ${r.changed.length} file(s) for nerd ${r.to}${r.from && r.from !== r.to ? ` (the app was on SDK ${r.from})` : ""}: ${r.changed.join(", ")}`);
+    log.info("Your app's own code was not touched. Next:");
+    r.next.forEach((n, i) => log.info(`  ${i + 1}. ${n}`));
+}

package/dist/gates/index.js

@@ -4,6 +4,7 @@ import { gitleaksGate, semgrepGate } from "./tools.js";
 import { suppressionsGate } from "./suppressions.js";
 import { staticGate } from "./static.js";
 import { testsGate } from "./tests.js";
+import { versionsGate } from "./versions.js";
 import { applyAttempts, MAX_ATTEMPTS } from "./attempts.js";
 export { gateSummary, skippedGates } from "./types.js";
 export { RULES, ruleFor } from "./rules.js";
@@ -11,7 +12,7 @@ export { mask } from "./secrets.js";
 export { MAX_ATTEMPTS, readAttempts } from "./attempts.js";
 export { probeDeployment, skippedProbe, waitForDeployment } from "./smoke.js";
 /** Gates that run on source, before the build. Suppressions first so a human sees them before anything else. */
-export const SOURCE_GATES = [suppressionsGate, secretsGate, gitleaksGate, depsGate, rulesGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate];
+export const SOURCE_GATES = [suppressionsGate, secretsGate, gitleaksGate, depsGate, rulesGate, versionsGate, staticGate, semgrepGate, policyGate, piiGate, typecheckGate, testsGate];
 /** Gates that need the built output. */
 export const BUILD_GATES = [bundleGate, policyGate];
 function selectGates(gates, onlyRules) {

package/dist/gates/rules.js

@@ -36,6 +36,9 @@ export const RULES = {
     "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." },
     "rules/shape": { title: "Not in the nerdsystem shape", severity: "warn", audience: "human", risk: "Every app on nerdsystem is one shape: a Vite client, a Hono server on @nerdsystem/sdk, SQLite on D1, and a bucket. This repository is not in that shape. A clean scan says nothing about whether it would deploy here.", fix: "Start a project with `nerd init` and have the agent port the screens into it. The server and the login are rebuilt on the platform's sign-in and database. The compare pages on nerdsystem.com say what carries over." },
     "typecheck/error": { title: "TypeScript error", severity: "block", audience: "agent", risk: "The code would not compile reliably; the build may fail or behave unexpectedly.", fix: "Fix the type error at the file and line shown. Run `npx tsc -b` for the full message." },
+    "versions/cli-outdated": { title: "The nerd command is behind", severity: "warn", audience: "agent", risk: "An older nerd runs fewer checks and may not know about newer platform features.", fix: "Run `npm install -g nerdsystem@latest`." },
+    "versions/sdk-outdated": { title: "The app's SDK is behind", severity: "warn", audience: "agent", risk: "The app is missing fixes and safeguards that newer versions of the platform's library and instructions carry.", fix: "Run `nerd upgrade`, then `pnpm install` and `nerd check`." },
+    "versions/sdk-unsupported": { title: "The app's SDK is too old for the platform", severity: "block", audience: "agent", risk: "This version of the platform's library lacks something the platform now depends on to keep apps safe, so it is no longer accepted.", fix: "Run `nerd upgrade`, then `pnpm install` and `nerd check`." },
     "code/raw-sql": { title: "SQL built from values", severity: "block", audience: "agent", risk: "A value from a request placed straight into SQL lets a visitor rewrite the query and read or delete other people's data.", fix: "Use the Drizzle query builder, or bind values as parameters (`.prepare(\"... where id = ?\").bind(id)`). Never put a variable inside the SQL text.", example: { wrong: "c.env.DB.prepare(`select * from notes where id = ${id}`)", right: "db(c.env.DB).select().from(schema.notes).where(eq(schema.notes.id, id))" } },
     "code/eval": { title: "eval or new Function", severity: "block", audience: "agent", risk: "Running text as code lets anyone who can influence that text run their own code in the app.", fix: "Remove it. Parse data with JSON.parse and choose behaviour with ordinary code." },
     "code/password-in-app": { title: "Password handling in app code", severity: "block", audience: "agent", risk: "Storing or comparing passwords yourself is unnecessary here and easy to get wrong.", fix: "Remove it. Sign-in is provided by the platform: read the signed-in user from `c.var.user` and protect routes with `requireAuth()`.", example: { wrong: "if (user.password === body.password) { ... }", right: "app.get(\"/api/me\", requireAuth(), (c) => c.json(c.var.user));" } },

package/dist/gates/tools.js

@@ -53,6 +53,10 @@ export const semgrepGate = {
         const findings = [];
         try {
             const json = JSON.parse(r.stdout);
+            // Semgrep exits 0 and reports nothing when its rules file does not load, which reads exactly like a clean
+            // scan. That hid a broken rules file from 2026-11-02 to 2026-11-10: a run that could not use the rules is not a pass.
+            if ((json.errors ?? []).some((e) => e.level === "error" && /SemgrepError|InvalidRule|config/i.test(e.type ?? "")))
+                return result(this, "warn", "semgrep could not load its rules", [], t, "semgrep");
             for (const x of json.results.slice(0, 100)) {
                 const short = x.check_id.split(".").pop() ?? x.check_id;
                 const rule_id = `semgrep/${short}`;

package/dist/gates/versions.d.ts

@@ -0,0 +1,32 @@
+import { type Finding, type Gate } from "./types.js";
+export interface Versions {
+    latest: string | null;
+    minSdk: string;
+}
+/** -1, 0, or 1; anything that is not three numbers compares as equal, so a strange value never produces a finding. */
+export declare function compareVersions(a: string, b: string): number;
+/** The first x.y.z in a dependency range: "^0.0.13" → "0.0.13". Null for workspace:, file:, and tags. */
+export declare function pinned(range: string | undefined): string | null;
+/**
+ * What the platform says is current, asked at most once a day and remembered in between. Never throws
+ * and never takes long: without an answer there is simply nothing to say about versions.
+ */
+export declare function currentVersions(opts?: {
+    apiUrl?: string;
+    now?: number;
+    fetchImpl?: typeof fetch;
+    cache?: string;
+}): Promise<Versions | null>;
+/** The findings for a given state of the world. Separate from the gate so it can be tested without a network. */
+export declare function versionFindings(input: {
+    cli: string;
+    sdk: string | null;
+    versions: Versions;
+    inBuilder?: boolean;
+}): Finding[];
+/**
+ * Says when the `nerd` command or the app's SDK has fallen behind. Advice only, with one exception:
+ * an SDK older than the platform still accepts blocks the deploy, because that floor is only raised
+ * for a safety reason. Version numbers in the text come from the platform, never from the app.
+ */
+export declare const versionsGate: Gate;

package/dist/gates/versions.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { finding } from "./secrets.js";
+import { result, verdict } from "./types.js";
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+const DAY = 24 * 60 * 60 * 1000;
+/** -1, 0, or 1; anything that is not three numbers compares as equal, so a strange value never produces a finding. */
+export function compareVersions(a, b) {
+    const x = SEMVER.exec(a);
+    const y = SEMVER.exec(b);
+    if (!x || !y)
+        return 0;
+    for (let i = 1; i <= 3; i++) {
+        const d = Number(x[i]) - Number(y[i]);
+        if (d)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** The first x.y.z in a dependency range: "^0.0.13" → "0.0.13". Null for workspace:, file:, and tags. */
+export function pinned(range) {
+    const m = /(\d+\.\d+\.\d+)/.exec(range ?? "");
+    return m && !/^(workspace|file|link|npm):/.test(range ?? "") ? m[1] : null;
+}
+function cacheFile() {
+    return path.join(process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"), "nerdsystem", "versions.json");
+}
+/**
+ * What the platform says is current, asked at most once a day and remembered in between. Never throws
+ * and never takes long: without an answer there is simply nothing to say about versions.
+ */
+export async function currentVersions(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const file = opts.cache ?? cacheFile();
+    try {
+        if (existsSync(file)) {
+            const c = JSON.parse(readFileSync(file, "utf8"));
+            if (now - c.checkedAt < DAY && typeof c.minSdk === "string")
+                return { latest: c.latest, minSdk: c.minSdk };
+        }
+    }
+    catch {
+        // unreadable cache: ask again
+    }
+    try {
+        const base = (opts.apiUrl ?? process.env.NERD_API_URL ?? "https://api.nerdsystem.com").replace(/\/$/, "");
+        const res = await (opts.fetchImpl ?? fetch)(`${base}/public/versions`, { signal: AbortSignal.timeout(4000) });
+        if (!res.ok)
+            return null;
+        const v = (await res.json());
+        if (typeof v.minSdk !== "string" || !SEMVER.test(v.minSdk))
+            return null;
+        const out = { latest: typeof v.latest === "string" && SEMVER.test(v.latest) ? v.latest : null, minSdk: v.minSdk };
+        try {
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, `${JSON.stringify({ ...out, checkedAt: now })}\n`);
+        }
+        catch {
+            // a read-only home is fine; it just asks again next time
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function installedCli() {
+    return createRequire(import.meta.url)("../../package.json").version;
+}
+/** The findings for a given state of the world. Separate from the gate so it can be tested without a network. */
+export function versionFindings(input) {
+    const { cli, sdk, versions } = input;
+    const out = [];
+    if (sdk && compareVersions(sdk, versions.minSdk) < 0) {
+        out.push(finding("versions/sdk-unsupported", { file: "package.json", fix: `Run \`nerd upgrade\`, then \`pnpm install\` and \`nerd check\`. This app is on @nerdsystem/sdk ${sdk}; the platform needs ${versions.minSdk} or newer.` }));
+    }
+    const latest = versions.latest;
+    if (!latest)
+        return out;
+    // The builder's own copy of the command is the platform's business, not the app's.
+    if (!input.inBuilder && compareVersions(cli, latest) < 0) {
+        out.push(finding("versions/cli-outdated", { fix: `Run \`npm install -g nerdsystem@latest\` (nerd ${cli} is installed; ${latest} is current), then run \`nerd check\` again. If the global install is refused, use \`npx nerdsystem@latest\` in place of \`nerd\`.` }));
+    }
+    if (sdk && compareVersions(sdk, latest) < 0 && compareVersions(sdk, versions.minSdk) >= 0) {
+        out.push(finding("versions/sdk-outdated", { file: "package.json", fix: `Run \`nerd upgrade\` (this app is on @nerdsystem/sdk ${sdk}; ${latest} is current), then \`pnpm install\` and \`nerd check\`, and follow what the check reports. Tell the person what changed before deploying.` }));
+    }
+    return out;
+}
+/**
+ * Says when the `nerd` command or the app's SDK has fallen behind. Advice only, with one exception:
+ * an SDK older than the platform still accepts blocks the deploy, because that floor is only raised
+ * for a safety reason. Version numbers in the text come from the platform, never from the app.
+ */
+export const versionsGate = {
+    name: "versions",
+    title: "Up to date",
+    blocking: true,
+    rulePrefixes: ["versions/"],
+    async run(ctx) {
+        const t = Date.now();
+        if (process.env.NERD_NO_VERSION_CHECK)
+            return result(this, "skip", "Version check turned off", [], t);
+        const versions = await currentVersions();
+        if (!versions)
+            return result(this, "skip", "Could not ask the platform what is current", [], t);
+        let sdk = null;
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(ctx.root, "package.json"), "utf8"));
+            sdk = pinned(pkg.dependencies?.["@nerdsystem/sdk"]);
+        }
+        catch {
+            // no package.json: the rules gate says so
+        }
+        const findings = versionFindings({ cli: installedCli(), sdk, versions, inBuilder: Boolean(ctx.committed) });
+        const summary = findings.length ? findings.map((f) => f.rule_id.split("/")[1]).join(", ") : versions.latest ? `nerd and the SDK are current (${versions.latest})` : "Nothing older than the platform accepts";
+        return result(this, verdict(findings), summary, findings, t);
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nerdsystem",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "nerd: start, check, and deploy a web app on nerdsystem from the terminal or a coding agent.",
   "type": "module",
   "bin": {

package/rules/semgrep.yml

@@ -22,8 +22,9 @@ rules:
     severity: WARNING
     message: dangerouslySetInnerHTML with a non-literal value can inject scripts. Sanitize or avoid.
     patterns:
-      - pattern: dangerouslySetInnerHTML={{ __html: $X }}
-      - pattern-not: dangerouslySetInnerHTML={{ __html: "..." }}
+      # Quoted: an unquoted "__html: $X" reads as a YAML mapping and makes the whole file invalid.
+      - pattern: '<$EL dangerouslySetInnerHTML={{ __html: $X }} />'
+      - pattern-not: '<$EL dangerouslySetInnerHTML={{ __html: "..." }} />'
   - id: nerd-innerhtml-assignment
     languages: [typescript, javascript]
     severity: WARNING

package/template/.claude/skills/nerdsystem/SKILL.md

@@ -39,7 +39,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 

package/template/.cursor/rules/nerdsystem.mdc

@@ -2,7 +2,7 @@
 description: How to build, run, and deploy this app on nerdsystem. Applies to server, database, auth, and deploy work.
 alwaysApply: true
 ---
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2b225a0c3327); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -40,7 +40,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 

package/template/.github/copilot-instructions.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2b225a0c3327); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 

package/template/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2b225a0c3327); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code
 

package/template/GEMINI.md

@@ -1,4 +1,4 @@
-<!-- generated from .claude/skills/nerdsystem/SKILL.md (f814c3a452ab); edit the skill, then run: nerd agents sync -->
+<!-- generated from .claude/skills/nerdsystem/SKILL.md (2b225a0c3327); edit the skill, then run: nerd agents sync -->
 
 # Building on nerdsystem
 
@@ -36,7 +36,9 @@ Tell the person plainly what does not carry. Their users sign up again on the ne
 4. `nerd deploy` when it is ready. It runs the checks, builds, stores a copy of the code, applies pending migrations, uploads, prints the URL, and probes the live URL (headers, the sign-in routes, and a signed-out GET of every route the tests found locked; a `smoke/route-open` finding means a locked route is answering strangers on the live app, so run `nerd rollback` first and investigate second). With `--json` the output carries `probes`, the same shape as a check result, with `status: "skip"` and the reason when it did not run; probe findings never fail the deploy.
 5. If something is wrong after deploying: `nerd logs` shows recent output from the deployed app (`--q` to search, `--pr 12` for a preview), `nerd deployments` shows status and errors, `nerd db query "..."` inspects production data.
 
-Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed; git builds always run them in the builder.
+`nerd check` also says when the `nerd` command or this app's SDK has fallen behind (the `versions/` rules; it asks the platform once a day). For the command, run `npm install -g nerdsystem@latest`. For the app, run `nerd upgrade`: it updates the SDK version, these instructions, and the test harness, and leaves the app's own code alone; then `pnpm install`, `nerd check`, and work through what it reports. Tell the person what changed before you deploy. Never update the app's dependencies or instructions on your own initiative in the middle of other work; do it when the check asks or the person does.
+
+Run `nerd check --json` when you want a machine-readable list of problems. Its summary says how many gates ran and which were skipped (`skipped` in the JSON): semgrep and gitleaks only run locally when installed. `nerd deploy` has the platform run whichever is missing on the stored copy of the code before anything goes live (a finding from it stops the deploy like any other), and git builds always run both in the builder.
 
 ## Saving and restoring the code