nerdsystem 0.0.23 → 0.0.25

package/dist/api.d.ts

@@ -53,6 +53,8 @@ export interface Project {
     name: string;
     scriptName: string;
     url: string;
+    /** The address on the owner's own domain, once one is verified. Absent from an older platform. */
+    customUrl?: string | null;
 }
 export interface Deployment {
     id: string;

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/deploy.d.ts

@@ -46,6 +46,8 @@ export declare function checksMetadata(results: GateResult[]): {
 export interface ShipResult {
     deployment: Deployment;
     url: string;
+    /** The app's address on the owner's own domain, once one is verified; null otherwise. */
+    customUrl: string | null;
     migrations: {
         applied: string[];
         skipped: string[];

package/dist/commands/deploy.js

@@ -185,11 +185,14 @@ export async function shipBuild(args) {
     }
     const { deployment } = await api.post(projectPath(nerd, "/deployments"), form);
     const { project } = await api.get(projectPath(nerd));
-    log.ok(`Deployed ${deployment.id} (${deployment.status}) → ${project.url}`);
+    log.ok(`Deployed ${deployment.id} (${deployment.status}) → ${project.customUrl ?? project.url}`);
+    // The owner knows the app by their own domain; the platform address is the one that is probed, because it always resolves.
+    if (project.customUrl)
+        log.info(`Also at ${project.url}`);
     if (!opts["skip-probe"] && deployment.status === "live")
         log.step(`Probing ${project.url}`);
     const probes = await probeAfterDeploy(root, deployment, project.url, Boolean(opts["skip-probe"]));
-    return { deployment, url: project.url, migrations: mig, probes, source, sourceSkipped, lineage, warnings: pack.warnings };
+    return { deployment, url: project.url, customUrl: project.customUrl ?? null, migrations: mig, probes, source, sourceSkipped, lineage, warnings: pack.warnings };
 }
 /** The one line about the code after a live deploy, keyed on what the API recorded, not on what we sent. */
 export function sourceLine(r) {
@@ -225,12 +228,12 @@ export async function deploy(opts) {
     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, migrations: r.migrations, probes: r.probes, source: r.source, sourceSkipped: r.sourceSkipped, lineage: r.lineage.passed, warnings: r.warnings, review });
+        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);
     if (r.deployment.status === "live") {
@@ -240,10 +243,10 @@ 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.url}, then make yourself admin in the dashboard's Auth tab: ${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/auth`);
+    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.23";
+const SDK_VERSION = "0.0.25";

package/dist/commands/org.js

@@ -52,6 +52,16 @@ export function setupText(s) {
         "If you are a coding agent: give the owner these steps as they are, numbered, and nothing else to decide. Do not ask which company they use (it was looked up) and do not offer other record types. When they say it is done, run `nerd domains` until the status is active, then open the address to confirm.",
     ].join("\n");
 }
+/** Whether the domain without www forwards to the app yet, in words an agent can pass on. */
+function bareText(b) {
+    if (!b)
+        return "";
+    if (b.status === "forwarding")
+        return `${b.hostname} forwards here`;
+    if (b.status === "starting")
+        return `${b.hostname} is starting (certificate, under a minute)`;
+    return `${b.hostname} does not point here yet`;
+}
 export async function domainsList(opts) {
     const nerd = readNerdJson(findProjectRoot());
     const r = await ApiClient.fromConfig().get(projectPath(nerd, "/domains"));
@@ -59,7 +69,7 @@ export async function domainsList(opts) {
         return printJson(r);
     if (!r.domains.length)
         return log.info(`No custom domains. Add one: nerd domains add example.com`);
-    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", does: d.redirectTo ? `forwards to ${d.redirectTo}` : "the app", error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "does", "error", "id"]);
+    table(r.domains.map((d) => ({ hostname: d.hostname, status: d.status, ssl: d.sslStatus ?? "", does: d.redirectTo ? `forwards to ${d.redirectTo}` : "the app", "bare name": bareText(d.bare), error: d.lastError ?? "", id: d.id })), ["hostname", "status", "ssl", "does", "bare name", "error", "id"]);
     // Only addresses still waiting for their DNS records have steps left to do.
     for (const s of r.setups ?? [])
         log.info(`\n${setupText(s)}`);

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,104 @@
+/**
+ * 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";
+}
+declare const FORMAT: {
+    summary: string;
+    does: string[];
+    missing: string[];
+    findings: {
+        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;
+    }[];
+    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 {};

package/dist/commands/session-review.js

@@ -0,0 +1,262 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ApiClient } from "../api.js";
+import { RULES } from "../gates/rules.js";
+import { isReviewFile } from "../gates/text.js";
+import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
+import { listSnapshotFiles } from "../snapshot.js";
+import { CliError, dashboardUrl, log, printJson } from "../util.js";
+import { saveSnapshot } from "./save.js";
+/**
+ * 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 const REPORT_FILE = ".nerd/review.json";
+const REVIEWED_FILE = ".nerd/reviewed.json";
+const SAFE_FILE = /^[\w./@-]{1,200}$/;
+export const REVIEW_RULES = Object.keys(RULES)
+    .filter((k) => k.startsWith("review/"))
+    .sort();
+/** Every file a review reads in this folder, with a hash of its contents. */
+export function reviewFiles(root) {
+    const out = {};
+    for (const f of listSnapshotFiles(root).files) {
+        if (!isReviewFile(f.path))
+            continue;
+        try {
+            out[f.path] = createHash("sha256").update(readFileSync(f.abs)).digest("hex");
+        }
+        catch {
+            // gone between the listing and the read: not part of the code any more
+        }
+    }
+    return out;
+}
+function readReviewed(root) {
+    try {
+        const v = JSON.parse(readFileSync(path.join(root, REVIEWED_FILE), "utf8"));
+        return v.files && typeof v.files === "object" ? v.files : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Records the code as it stands as reviewed. */
+export function writeReviewed(root, files) {
+    mkdirSync(path.join(root, ".nerd"), { recursive: true });
+    writeFileSync(path.join(root, REVIEWED_FILE), `${JSON.stringify({ at: new Date().toISOString(), files }, null, 2)}\n`);
+}
+export function reviewDue(root) {
+    const now = reviewFiles(root);
+    const before = readReviewed(root);
+    if (!before)
+        return { due: Object.keys(now).length > 0, first: true, changed: Object.keys(now).sort() };
+    const changed = Object.keys(now).filter((p) => before[p] !== now[p]).sort();
+    const removed = Object.keys(before).filter((p) => !(p in now));
+    return { due: [...changed, ...removed].some((p) => !p.endsWith(".css")), first: false, changed };
+}
+/** What is open from earlier reviews, as rule ids and places only. Empty when the platform cannot be asked. */
+async function openFindings(api, base) {
+    let got = null;
+    try {
+        got = await Promise.race([api.get(`${base}/review`), new Promise((r) => setTimeout(() => r(null), 5000))]);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of got?.review?.findings ?? []) {
+        if (typeof f.rule_id !== "string" || !REVIEW_RULES.includes(f.rule_id) || typeof f.file !== "string" || !SAFE_FILE.test(f.file) || !Number.isInteger(f.line))
+            continue;
+        out.push({ rule_id: f.rule_id, file: f.file, line: f.line, origin: f.origin === "session" ? "session" : "platform" });
+    }
+    return out;
+}
+const FORMAT = {
+    summary: "Two or three plain sentences for the app's owner: what the app is and the shape it is in. No code, no file names, no jargon.",
+    does: ["Up to six short phrases, each something a person can do in the app today"],
+    missing: ["Up to five short phrases, each something the owner asked for or the description promises that is not built yet"],
+    findings: [{ rule: "review/<id>", file: "src/server/index.ts", line: 42 }],
+    fixed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
+    dismissed: [{ rule: "review/<id>", file: "src/server/index.ts" }],
+};
+export function checklistText(c) {
+    const lines = [
+        `Review of ${c.app} before it is deployed`,
+        "",
+        "This is the review of this app's own code for what tests cannot see. You do it, as part of the work. nerdsystem reads the code itself only now and then, and compares what it finds with what you report here.",
+        "",
+        "How to do it:",
+        "1. Use a reviewer with fresh eyes when you have one. In Claude Code, hand this whole output to the `nerd-reviewer` subagent that ships with the app (if it is not there yet, any read-only subagent). In another agent, use a subagent or a new task that has not seen this conversation. With neither, do it yourself and read the files again from disk, not from memory.",
+        c.first
+            ? "2. No review has been reported from this folder yet, so read all of the app's own code: `src/server` and the database schema first, then `src/client`, plus README.md."
+            : c.changed.length
+                ? "2. Read the files that changed since the last review, and the code they call or are called by when a finding depends on it:"
+                : "2. No file a review reads has changed since the last review. Check the open findings below, if any, and report.",
+    ];
+    if (!c.first)
+        for (const f of c.changed.slice(0, 60))
+            lines.push(`   - ${f}`);
+    if (!c.first && c.changed.length > 60)
+        lines.push(`   … and ${c.changed.length - 60} more`);
+    lines.push("3. For each kind of problem under \"What to look for\", ask whether this code has it. Raise one only when you can point at the line that shows it. Finding nothing is a normal answer for a small change.", "4. Fix what is real and yours to fix. Anything marked [for the person to decide] is a plain question for them: ask it without file names or jargon, and wait for the answer.", `5. Write ${c.reportFile} in the format at the end and run \`nerd review report\`. Then \`nerd check\` and \`nerd deploy\` as usual.`, "");
+    if (c.open.length) {
+        lines.push("Open from earlier reviews. Check each against the code as it is now and answer it in the report:");
+        for (const f of c.open)
+            lines.push(`- ${f.rule_id} at ${f.file}:${f.line}${f.origin === "platform" ? "  (from nerdsystem's own read)" : ""}`);
+        lines.push("");
+    }
+    lines.push("What to look for:");
+    for (const r of c.rules) {
+        lines.push(`- ${r.rule_id}: ${r.title}${r.audience === "human" ? " [for the person to decide]" : ""}`, `  Look for: ${r.lookFor}`, `  Fix: ${r.fix}`);
+    }
+    lines.push("", `The report, written to ${c.reportFile}:`, JSON.stringify(c.format, null, 2), "", "- findings: what is still in the code after your fixes, each with the rule, the file, and the line that shows it. Leave it empty when there is nothing.", "- fixed: what this review found and you then fixed, including findings from the open list above.", "- dismissed: only for a finding from nerdsystem's own read that you checked against the code and that does not apply. The owner sees this as your judgement, so use it when you are sure.", "- A finding from nerdsystem's own read that the report does not mention stays open.", "- summary, does, missing are for the owner and are shown on their dashboard as written. Plain words only.", "", "Report what you found, not what would look good. The report is stored as this agent's own review, it never decides whether a deploy goes out, and a clean report that nerdsystem's own read later contradicts is recorded as a miss.");
+    return lines.join("\n");
+}
+/** `nerd review checklist`: what the agent reads before it reviews. */
+export async function reviewChecklist(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const due = reviewDue(root);
+    let open = [];
+    try {
+        open = await openFindings(ApiClient.fromConfig(), projectPath(nerd));
+    }
+    catch {
+        // not signed in: the checklist is still worth printing
+    }
+    const c = {
+        app: `${nerd.org}/${nerd.project}`,
+        first: due.first,
+        changed: due.changed,
+        open,
+        rules: REVIEW_RULES.map((id) => ({ rule_id: id, title: RULES[id].title, audience: RULES[id].audience, lookFor: RULES[id].when ?? RULES[id].risk, fix: RULES[id].fix })),
+        reportFile: REPORT_FILE,
+        format: FORMAT,
+    };
+    if (opts.json)
+        return printJson(c);
+    process.stdout.write(`${checklistText(c)}\n`);
+}
+/**
+ * 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 function parseReport(text, files, lineCount) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new CliError(`${REPORT_FILE} is not valid JSON. Run \`nerd review checklist\` for the format.`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new CliError(`${REPORT_FILE} must be a JSON object. Run \`nerd review checklist\` for the format.`);
+    const r = raw;
+    const problems = [];
+    const rule = (v, where) => {
+        const id = typeof v === "string" ? (v.startsWith("review/") ? v : `review/${v}`) : "";
+        if (REVIEW_RULES.includes(id))
+            return id;
+        problems.push(`${where}: "${typeof v === "string" ? v.slice(0, 60) : typeof v}" is not a rule in the checklist`);
+        return null;
+    };
+    const list = (key) => {
+        const v = r[key];
+        if (v === undefined || v === null)
+            return [];
+        if (!Array.isArray(v)) {
+            problems.push(`${key} must be a list`);
+            return [];
+        }
+        return v.map((x) => (x && typeof x === "object" ? x : {}));
+    };
+    const findings = [];
+    list("findings").forEach((f, i) => {
+        const where = `findings[${i}]`;
+        const id = rule(f.rule, where);
+        if (typeof f.file !== "string" || !(f.file in files))
+            return void problems.push(`${where}: "${String(f.file).slice(0, 80)}" is not a file a review reads (the app's own code under src/, README.md, package.json), or it does not exist`);
+        if (typeof f.line !== "number" || !Number.isInteger(f.line) || f.line < 1 || f.line > lineCount(f.file))
+            return void problems.push(`${where}: line ${String(f.line)} is not a line of ${f.file}`);
+        if (id)
+            findings.push({ rule: id, file: f.file, line: f.line });
+    });
+    const notes = (key) => {
+        const out = [];
+        list(key).forEach((f, i) => {
+            const id = rule(f.rule, `${key}[${i}]`);
+            if (typeof f.file !== "string" || !SAFE_FILE.test(f.file))
+                return void problems.push(`${key}[${i}]: give the file the finding was in`);
+            if (id)
+                out.push({ rule: id, file: f.file });
+        });
+        return out;
+    };
+    const fixed = notes("fixed");
+    const dismissed = notes("dismissed");
+    const words = (key) => {
+        const v = r[key];
+        if (v === undefined || v === null)
+            return undefined;
+        if (!Array.isArray(v) || v.some((x) => typeof x !== "string")) {
+            problems.push(`${key} must be a list of short phrases`);
+            return undefined;
+        }
+        return v.map((x) => x.slice(0, 400)).slice(0, 12);
+    };
+    const does = words("does");
+    const missing = words("missing");
+    if (r.summary !== undefined && r.summary !== null && typeof r.summary !== "string")
+        problems.push("summary must be a sentence or two of plain text");
+    if (problems.length)
+        throw new CliError(`${REPORT_FILE} needs ${problems.length === 1 ? "a correction" : "corrections"} before it can be sent:\n${problems.map((p) => `  - ${p}`).join("\n")}\nFix the file and run \`nerd review report\` again.`);
+    return { findings, fixed, dismissed, ...(typeof r.summary === "string" && r.summary.trim() ? { summary: r.summary.slice(0, 2000) } : {}), ...(does ? { does } : {}), ...(missing ? { missing } : {}) };
+}
+/** The name sent with a report. Only an agent this CLI can recognise for certain is named without being told. */
+function agentName(given) {
+    if (given)
+        return /^[a-z0-9][a-z0-9-]{0,29}$/.test(given) ? given : undefined;
+    return process.env.CLAUDECODE ? "claude-code" : undefined;
+}
+/** `nerd review report`: store the code as reviewed, and send the agent's report with it. */
+export async function reviewReport(opts) {
+    const root = findProjectRoot();
+    const nerd = readNerdJson(root);
+    const rel = opts.file ?? REPORT_FILE;
+    const file = path.resolve(root, rel);
+    if (!existsSync(file))
+        throw new CliError(`There is no review to report: ${rel} was not found. Run \`nerd review checklist\` for what to look for and the format to write.`);
+    const files = reviewFiles(root);
+    const report = parseReport(readFileSync(file, "utf8"), files, (f) => readFileSync(path.join(root, f), "utf8").split("\n").length);
+    const api = ApiClient.fromConfig();
+    const saved = await saveSnapshot(root, nerd, api, { quiet: true });
+    const agent = agentName(opts.agent);
+    const answer = await api.post(projectPath(nerd, `/sources/${saved.source.id}/review/report`), { ...report, ...(agent ? { agent } : {}) });
+    // From here the code as it stands counts as reviewed, and the report cannot be sent again by mistake against later code.
+    writeReviewed(root, files);
+    if (!opts.file)
+        rmSync(file, { force: true });
+    const page = `${dashboardUrl(api.apiUrl)}/app/${nerd.org}/projects/${nerd.project}/review`;
+    // Only the counts: the stored review carries a summary that may be a model's words, and those never go to a terminal.
+    if (opts.json)
+        return printJson({ accepted: answer.accepted, dropped: answer.dropped, carried: answer.carried, source: saved.source.id, dashboard: page });
+    const a = answer.accepted;
+    log.ok(`Review reported for ${nerd.org}/${nerd.project}: ${a.findings} open, ${a.fixed} fixed${a.dismissed ? `, ${a.dismissed} judged not to apply` : ""}.`);
+    if (answer.dropped)
+        log.warn(`${answer.dropped} finding(s) were left out because the rule, the file, or the line did not match the stored code.`);
+    if (answer.carried)
+        log.warn(`${answer.carried} finding(s) from nerdsystem's own read are still open because the report did not answer them. \`nerd review\` lists them.`);
+    log.info(`The owner's page for this review: ${page}`);
+}

package/dist/commands/status.d.ts

@@ -16,7 +16,7 @@ export interface Attention {
     /** When the review the findings come from was made, so a finding already fixed since is not a surprise. */
     reviewedAt?: string;
 }
-/** The latest model review's findings for this app, mapped through this CLI's own catalog. */
+/** What is open from the latest review of this app (its agent's own, or the platform's read), mapped through this CLI's own catalog. */
 export declare function reviewItems(api: ApiClient, base: string): Promise<{
     items: AttentionItem[];
     reviewedAt?: string;
@@ -41,7 +41,7 @@ export declare function status(opts: {
     json: boolean;
     hook: boolean;
 }): Promise<void>;
-/** `nerd review`: only the model review's findings, with every fix written out. */
+/** `nerd review`: only what is open from the latest review, with every fix written out. */
 export declare function review(opts: {
     json: boolean;
 }): Promise<void>;