nerdsystem 0.0.24 → 0.0.26

package/dist/cli.js

@@ -9,6 +9,7 @@ import { cron, health, rollback, secretList, secretRemove, secretSet, transfer,
 import { adminHelp, adminSuspend, adminUnsuspend } from "./commands/admin.js";
 import { agentsSync } from "./commands/agents.js";
 import { upgrade } from "./commands/upgrade.js";
+import { reviewChecklist, reviewReport } from "./commands/session-review.js";
 import { review, status } from "./commands/status.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";
@@ -61,7 +62,9 @@ const HELP = `nerd: start, check, and deploy a web app on nerdsystem
   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 status                         What the platform has found for this app that needs attention (updates, review findings, vulnerable packages)
-  nerd review                         The latest model review's findings for this app, with the fix for each
+  nerd review                         What is open from the latest review of this app, with the fix for each
+  nerd review checklist               What to look for when reviewing this app's code before a deploy, and which files changed
+  nerd review report [--agent name]   Send the review written to .nerd/review.json (see the checklist for the format)
   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
@@ -143,8 +146,15 @@ export async function main(argv) {
             return status({ json: Boolean(values.json), hook: Boolean(values.hook) });
         }
         case "review": {
-            const { values } = parse({}, false);
-            return review({ json: Boolean(values.json) });
+            const { values, positionals } = parseArgs({ args: rest, options: { json: BOOL, file: STR, agent: STR }, allowPositionals: true });
+            const json = Boolean(values.json);
+            if (positionals[0] === "checklist")
+                return reviewChecklist({ json });
+            if (positionals[0] === "report")
+                return reviewReport({ json, ...(values.file ? { file: String(values.file) } : {}), ...(values.agent ? { agent: String(values.agent) } : {}) });
+            if (positionals.length)
+                throw new CliError("Usage: nerd review | nerd review checklist | nerd review report [--file path] [--agent name]");
+            return review({ json });
         }
         case "upgrade": {
             const { values } = parse({}, false);

package/dist/commands/claude-md-history.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The sha256 of every version of the starter app's CLAUDE.md this project has shipped (line endings as LF).
+ * `nerd upgrade` uses it to tell a CLAUDE.md that is still exactly the platform's text, which it replaces
+ * without ceremony, from one a person or an agent has added to, which it keeps beside the new one.
+ *
+ * When packages/template/CLAUDE.md changes, add the new hash here; a test fails until it is listed.
+ * To print it: `tr -d '\\r' < packages/template/CLAUDE.md | sha256sum`.
+ */
+export declare const KNOWN_CLAUDE_MD: Set<string>;

package/dist/commands/claude-md-history.js

@@ -0,0 +1,18 @@
+/**
+ * The sha256 of every version of the starter app's CLAUDE.md this project has shipped (line endings as LF).
+ * `nerd upgrade` uses it to tell a CLAUDE.md that is still exactly the platform's text, which it replaces
+ * without ceremony, from one a person or an agent has added to, which it keeps beside the new one.
+ *
+ * When packages/template/CLAUDE.md changes, add the new hash here; a test fails until it is listed.
+ * To print it: `tr -d '\\r' < packages/template/CLAUDE.md | sha256sum`.
+ */
+export const KNOWN_CLAUDE_MD = new Set([
+    "02eb1063cb99fca0106b0a3052872a7839782564d285527ac74a08b1ca19b9ed",
+    "30b969614ba066a6faa930d35df67da48c3a692aba66ce009543e7c0d58114ba",
+    "31b9481c380810c87dff5e6a0812274cfb7068a35e11941867ad5bd4b2dc8dbf",
+    "440751d827c9f112f584157ea08495b56c8ff111024cc52177e5aa98b07622b8",
+    "4dc0c5234ad2115e1b932396db2a6efb0329bd93cb4f8ddc9968d978ddd48389",
+    "65f97940d79e9d657bc117d1dbbf13f21e84c578301b20b13c726e00739a305b",
+    "6f21b6478d50bd599bc8833068ffa82bc7ad5434439636a81b5b35d9d8554947",
+    "887cebefb74b2187ccaea027a40074d0cd163c3e6ed6fcdb0edbcbe766c0ccdd",
+]);

package/dist/commands/deploy.d.ts

@@ -11,6 +11,12 @@ export interface BuildOutput {
     compatibilityFlags: string[];
 }
 /** Locates the Vite build output: dist/<worker>/wrangler.json names the entry and the assets dir. */
+/**
+ * The Vite plugin copies `.dev.vars` next to the built Worker so a local preview can read it. A deploy
+ * never uploads it, and it is rewritten by every build, so the copy is removed here instead of being
+ * reported on every run with nothing for anyone to do about it. The file in the app's own folder stays.
+ */
+export declare function dropLocalSecretCopies(build: BuildOutput): void;
 export declare function readBuildOutput(root: string): BuildOutput;
 export declare function applyRemoteMigrations(root: string, api: ApiClient): Promise<{
     applied: string[];

package/dist/commands/deploy.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { ApiClient } from "../api.js";
 import { findProjectRoot, projectPath, readDevVars, readNerdJson } from "../project.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 { ENV_FILES } from "../gates/text.js";
 import { platformScan } from "./platform-scan.js";
 import { platformReview, printReview } from "./platform-review.js";
 import { BUILD_GATES, gateSummary, knownSecretsFrom, probeDeployment, runGates, skippedProbe, SOURCE_GATES, waitForDeployment } from "../gates/index.js";
@@ -24,6 +25,18 @@ function walk(dir, base = dir) {
     return out;
 }
 /** Locates the Vite build output: dist/<worker>/wrangler.json names the entry and the assets dir. */
+/**
+ * The Vite plugin copies `.dev.vars` next to the built Worker so a local preview can read it. A deploy
+ * never uploads it, and it is rewritten by every build, so the copy is removed here instead of being
+ * reported on every run with nothing for anyone to do about it. The file in the app's own folder stays.
+ */
+export function dropLocalSecretCopies(build) {
+    if (!existsSync(build.workerDir))
+        return;
+    for (const name of readdirSync(build.workerDir))
+        if (ENV_FILES.test(name))
+            rmSync(path.join(build.workerDir, name), { force: true });
+}
 export function readBuildOutput(root) {
     const dist = path.join(root, "dist");
     if (!existsSync(dist))
@@ -76,10 +89,11 @@ async function probeAfterDeploy(root, deployment, url, skip) {
         return skippedProbe("the app had not started answering within 30 seconds; open the URL to check, or run nerd deploy again to probe it");
     return probeDeployment(url, undefined, { lockedGets: lockedGetPaths(root) });
 }
-function printProbe(url, probes) {
+function printProbe(url, probes, ownDomain) {
     if (probes.status === "skip")
         return log.info(`Live URL not probed: ${probes.summary}`);
-    const line = `Probed ${url}: ${probes.status === "pass" ? "all probes passed" : probes.summary}`;
+    // With the owner's domain on the app, the address above is theirs and this one is not: say why it is the one tried.
+    const line = `Probed ${url}${ownDomain ? " (the app's platform address, which keeps answering whatever happens to the domain's DNS)" : ""}: ${probes.status === "pass" ? "all probes passed" : probes.summary}`;
     if (probes.status === "pass")
         log.ok(line);
     else
@@ -224,18 +238,19 @@ export async function deploy(opts) {
         await runOrThrow("npx", ["vite", "build"], { cwd: root, stdoutToStderr: true });
     }
     const build = readBuildOutput(root);
+    dropLocalSecretCopies(build);
     const built = await runGates(BUILD_GATES, { root, build, knownSecrets, log: (l) => log.info(l) }, { stopOnFail: true });
     if (!built.ok)
         throw new CliError(`Blocked by: ${built.failed.map((g) => g.title).join(", ")}.`, 2);
     const r = await shipBuild({ root, nerd, api, build, results: [...gates.results, ...built.results], opts });
-    // The app is live at this point. The model review reads the stored code and is advice for the next change.
+    // The app is live at this point. The platform says what the review on file holds, and now and then reads the code itself.
     const reviewPage = `${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/review`;
     const wantReview = r.deployment.status === "live" && Boolean(r.source);
     if (opts.json) {
         const review = wantReview ? await platformReview(api, `${projectPath(nerd)}/sources/${r.source.id}`, reviewPage) : null;
         return printJson({ deployment: r.deployment, url: r.url, customUrl: r.customUrl, migrations: r.migrations, probes: r.probes, source: r.source, sourceSkipped: r.sourceSkipped, lineage: r.lineage.passed, warnings: r.warnings, review });
     }
-    printProbe(r.url, r.probes);
+    printProbe(r.url, r.probes, Boolean(r.customUrl));
     if (r.deployment.status === "live") {
         if (r.deployment.sourceId)
             log.ok(sourceLine(r));
@@ -243,10 +258,13 @@ export async function deploy(opts) {
             log.warn(sourceLine(r));
     }
     if (wantReview) {
-        log.step("Your app is live. Asking for a model review of how it is put together (up to a minute or two; safe to stop waiting)");
+        log.step("Your app is live. Checking in on its review (now and then nerdsystem reads the code itself, which takes a minute or two; safe to stop waiting)");
         printReview(await platformReview(api, `${projectPath(nerd)}/sources/${r.source.id}`, reviewPage));
     }
-    log.info(`First time? Sign up on your app at ${r.customUrl ?? r.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
+    // Said once, after the app's first deploy, which is when it is news.
+    const earlier = await api.get(projectPath(nerd, "/deployments?limit=2")).catch(() => null);
+    if (earlier && earlier.deployments.length <= 1)
+        log.info(`First time? Sign up on your app at ${r.customUrl ?? r.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
 }
 export async function deployments(opts) {
     const nerd = readNerdJson(findProjectRoot());

package/dist/commands/init.js

@@ -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.24";
+const SDK_VERSION = "0.0.26";

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

@@ -12,16 +12,24 @@ export type ReviewOutcome = {
     status: "done" | "declined";
     findings: ReviewFindingOut[];
     dashboard: string;
+    /** Whether the platform read the code itself just now. False means these are the findings already on file. */
+    platformRead: boolean;
+    /** Whose review the findings on file come from. */
+    kind: "platform" | "session";
 } | {
     status: "skipped";
     reason: string;
 };
 /**
- * After a deploy is live, asks the platform for the model's review of the stored code and waits for it.
+ * After a deploy is live, checks in with the platform about the review of the stored code.
+ *
+ * The platform reads the code itself only now and then (an app's first deploy, and about weekly on paid
+ * plans when the code has changed), which takes a minute or two; otherwise it answers at once with the
+ * review on file, which is usually the one this app's agent reported with `nerd review report`.
  *
  * Only the findings come back into the terminal, and only as a rule id with a file and a line: the words
- * printed are this CLI's own catalog, looked up by id, so nothing the model wrote is ever put in front of
- * the agent reading this output. The model's plain-language summary is for the person and stays in the
+ * printed are this CLI's own catalog, looked up by id, so nothing a model wrote is ever put in front of
+ * the agent reading this output. The plain-language summary is for the person and stays in the
  * dashboard. Any failure, limit, or missing configuration is a skip with a reason; a review never changes
  * whether the deploy succeeded.
  */

package/dist/commands/platform-review.js

@@ -1,11 +1,15 @@
 import { RULES } from "../gates/rules.js";
 import { CliError, log } from "../util.js";
 /**
- * After a deploy is live, asks the platform for the model's review of the stored code and waits for it.
+ * After a deploy is live, checks in with the platform about the review of the stored code.
+ *
+ * The platform reads the code itself only now and then (an app's first deploy, and about weekly on paid
+ * plans when the code has changed), which takes a minute or two; otherwise it answers at once with the
+ * review on file, which is usually the one this app's agent reported with `nerd review report`.
  *
  * Only the findings come back into the terminal, and only as a rule id with a file and a line: the words
- * printed are this CLI's own catalog, looked up by id, so nothing the model wrote is ever put in front of
- * the agent reading this output. The model's plain-language summary is for the person and stays in the
+ * printed are this CLI's own catalog, looked up by id, so nothing a model wrote is ever put in front of
+ * the agent reading this output. The plain-language summary is for the person and stays in the
  * dashboard. Any failure, limit, or missing configuration is a skip with a reason; a review never changes
  * whether the deploy succeeded.
  */
@@ -13,18 +17,23 @@ export async function platformReview(api, sourcePath, dashboard) {
     if (process.env.NERD_NO_REVIEW)
         return { status: "skipped", reason: "turned off with NERD_NO_REVIEW" };
     let review;
+    let platformRead = true;
     try {
-        review = (await api.post(`${sourcePath}/review`)).review;
+        const got = await api.post(`${sourcePath}/review`);
+        review = got.review;
+        // A platform that does not say is an older one, which read the code on every call.
+        platformRead = got.read ? got.read.ran : true;
     }
     catch (err) {
         const status = err instanceof CliError ? err.status : undefined;
         // The 402's wording is the platform's own (plan and allowance), safe to repeat.
         if (status === 402 && err instanceof Error)
             return { status: "skipped", reason: err.message.replace(/\s*\[[^\]]*\]\s*$/, "") };
-        return { status: "skipped", reason: status === 503 ? "the model review is not available on this platform yet" : "the review could not be completed this time" };
+        return { status: "skipped", reason: status === 503 ? "the platform's own review is not available here yet" : "the review could not be completed this time" };
     }
+    const kind = review.kind === "session" ? "session" : "platform";
     if (review.status !== "done")
-        return { status: "declined", findings: [], dashboard };
+        return { status: "declined", findings: [], dashboard, platformRead, kind };
     const findings = [];
     for (const f of review.findings ?? []) {
         const rule = typeof f.rule_id === "string" && f.rule_id.startsWith("review/") ? RULES[f.rule_id] : undefined;
@@ -33,22 +42,23 @@ export async function platformReview(api, sourcePath, dashboard) {
             continue;
         findings.push({ rule_id: f.rule_id, severity: rule.severity, audience: rule.audience, file: f.file, line: f.line, risk: rule.risk, fix: rule.fix });
     }
-    return { status: "done", findings, dashboard };
+    return { status: "done", findings, dashboard, platformRead, kind };
 }
 export function printReview(r) {
     if (r.status === "skipped") {
-        log.info(`Model review: not run (${r.reason}).`);
+        log.info(`Review by nerdsystem: not run (${r.reason}). Your own review before each deploy (\`nerd review checklist\`) is not affected.`);
         return;
     }
     if (r.status === "declined") {
-        log.info("Model review: the reviewer gave no answer for this app.");
+        log.info("Review by nerdsystem: the reviewer gave no answer for this app.");
         return;
     }
+    const whose = r.platformRead ? "nerdsystem read the code itself after this deploy" : r.kind === "session" ? "from the review this app's agent last reported" : "from nerdsystem's last own read of the code";
     if (!r.findings.length) {
-        log.ok(`Model review: nothing to raise. A plain-language summary for the person is at ${r.dashboard}`);
+        log.ok(`Review: nothing open (${whose}). A plain-language summary for the person is at ${r.dashboard}`);
         return;
     }
-    log.warn(`Model review: ${r.findings.length} thing(s) to look at. This is a second opinion from a model reading the code, so check each one against the code before changing anything; it can be wrong.`);
+    log.warn(`Review: ${r.findings.length} thing(s) open (${whose}). A review is a second opinion and can be wrong, so check each one against the code before changing anything. Say what you did about them in the next \`nerd review report\`.`);
     for (const f of r.findings) {
         log.info(`    ${f.severity === "info" ? "·" : "!"} ${f.rule_id} ${f.file}:${f.line}${f.audience === "human" ? "  (for the person to decide)" : ""}`);
         log.info(`      ${f.risk}`);

package/dist/commands/session-review.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The session review: the app's coding agent reads its own changes against the platform's `review/`
+ * catalog before a deploy, and reports what it found.
+ *
+ * `nerd review checklist` prints what to look for, which files changed since the last report from this
+ * folder, the findings still open from earlier reviews, and the report's format. `nerd review report`
+ * stores a snapshot of the code as reviewed and sends the report with it. The platform checks every
+ * finding against that stored code and keeps the report as the agent's own word; it does its own
+ * independent read only now and then, and compares the two.
+ *
+ * What changed is worked out on this computer, from a list of file hashes kept in `.nerd/reviewed.json`
+ * at the last report. A fresh folder has no list, so its first review covers everything.
+ */
+/** Where the agent writes its report for `nerd review report` to send. */
+export declare const REPORT_FILE = ".nerd/review.json";
+export declare const REVIEW_RULES: string[];
+type Hashes = Record<string, string>;
+/** Every file a review reads in this folder, with a hash of its contents. */
+export declare function reviewFiles(root: string): Hashes;
+/** Records the code as it stands as reviewed. */
+export declare function writeReviewed(root: string, files: Hashes): void;
+export interface ReviewDue {
+    /** Whether code a review reads has changed since the last report from this folder (styles alone do not count). */
+    due: boolean;
+    /** No report has been made from this folder: everything is unreviewed as far as this computer knows. */
+    first: boolean;
+    /** Files to read: the ones added or changed since the last report, or all of them the first time. */
+    changed: string[];
+}
+export declare function reviewDue(root: string): ReviewDue;
+interface OpenFinding {
+    rule_id: string;
+    file: string;
+    line: number;
+    origin: "platform" | "session";
+    /** Recorded earlier as real and deliberately left as it is. */
+    leftAsIs: boolean;
+}
+declare const FORMAT: {
+    summary: string;
+    does: string[];
+    missing: string[];
+    findings: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
+    leftAsIs: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
+    fixed: {
+        rule: string;
+        file: string;
+    }[];
+    dismissed: {
+        rule: string;
+        file: string;
+    }[];
+};
+export interface Checklist {
+    app: string;
+    first: boolean;
+    changed: string[];
+    open: OpenFinding[];
+    rules: {
+        rule_id: string;
+        title: string;
+        audience: "agent" | "human";
+        lookFor: string;
+        fix: string;
+    }[];
+    reportFile: string;
+    format: typeof FORMAT;
+}
+export declare function checklistText(c: Checklist): string;
+/** `nerd review checklist`: what the agent reads before it reviews. */
+export declare function reviewChecklist(opts: {
+    json: boolean;
+}): Promise<void>;
+export interface Report {
+    findings: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
+    leftAsIs: {
+        rule: string;
+        file: string;
+        line: number;
+    }[];
+    fixed: {
+        rule: string;
+        file: string;
+    }[];
+    dismissed: {
+        rule: string;
+        file: string;
+    }[];
+    summary?: string;
+    does?: string[];
+    missing?: string[];
+}
+/**
+ * Reads the agent's report strictly, so a slip is corrected here with a sentence that says what to change,
+ * instead of being dropped without a word by the platform. `files` is what a review reads in this folder.
+ */
+export declare function parseReport(text: string, files: Hashes, lineCount: (file: string) => number): Report;
+/** `nerd review report`: store the code as reviewed, and send the agent's report with it. */
+export declare function reviewReport(opts: {
+    json: boolean;
+    file?: string;
+    agent?: string;
+}): Promise<void>;
+export {};