nerdsystem 0.0.27 → 0.0.28

package/dist/commands/deploy.d.ts

@@ -16,7 +16,12 @@ export interface BuildOutput {
  * 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 dropLocalSecretCopies(build: BuildOutput): number;
+/**
+ * The build's own output lists that copy ("Using secrets defined in .dev.vars", then the file among what
+ * it wrote), which reads as if local secrets were about to be uploaded. Said once, right after the build.
+ */
+export declare const SECRET_COPY_NOTE = "The build tool listed a copy of your local secrets file (.dev.vars) in its output folder; it makes one for local previews. nerd has deleted that copy. It is never uploaded: the live app gets its secrets from `nerd secret set`.";
 export declare function readBuildOutput(root: string): BuildOutput;
 export declare function applyRemoteMigrations(root: string, api: ApiClient): Promise<{
     applied: string[];

package/dist/commands/deploy.js

@@ -32,11 +32,21 @@ function walk(dir, base = dir) {
  */
 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 });
+        return 0;
+    let dropped = 0;
+    for (const name of readdirSync(build.workerDir)) {
+        if (!ENV_FILES.test(name))
+            continue;
+        rmSync(path.join(build.workerDir, name), { force: true });
+        dropped++;
+    }
+    return dropped;
 }
+/**
+ * The build's own output lists that copy ("Using secrets defined in .dev.vars", then the file among what
+ * it wrote), which reads as if local secrets were about to be uploaded. Said once, right after the build.
+ */
+export const SECRET_COPY_NOTE = "The build tool listed a copy of your local secrets file (.dev.vars) in its output folder; it makes one for local previews. nerd has deleted that copy. It is never uploaded: the live app gets its secrets from `nerd secret set`.";
 export function readBuildOutput(root) {
     const dist = path.join(root, "dist");
     if (!existsSync(dist))
@@ -238,7 +248,8 @@ export async function deploy(opts) {
         await runOrThrow("npx", ["vite", "build"], { cwd: root, stdoutToStderr: true });
     }
     const build = readBuildOutput(root);
-    dropLocalSecretCopies(build);
+    if (dropLocalSecretCopies(build))
+        log.info(SECRET_COPY_NOTE);
     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);

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.27";
+const SDK_VERSION = "0.0.28";

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

@@ -20,7 +20,7 @@ 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). */
+    /** Whether the app's own code under `src/` has changed since the last report from this folder (a stylesheet, the README, or package.json alone does not count). */
     due: boolean;
     /** No report has been made from this folder: everything is unreviewed as far as this computer knows. */
     first: boolean;

package/dist/commands/session-review.js

@@ -64,7 +64,10 @@ export function reviewDue(root) {
         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 asks for a review is the app's own code. A stylesheet, the README, or package.json alone (which
+    // `nerd upgrade` itself rewrites when it moves the SDK's version) is read with the next review and does not ask for one.
+    const code = (p) => p.startsWith("src/") && !p.endsWith(".css");
+    return { due: [...changed, ...removed].some(code), 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) {

package/dist/commands/status.d.ts

@@ -15,6 +15,12 @@ export interface Attention {
     items: AttentionItem[];
     /** When the review the findings come from was made, so a finding already fixed since is not a surprise. */
     reviewedAt?: string;
+    /**
+     * The app's own code has changed since the last review reported from this folder, so `nerd check` will
+     * ask for one before the next deploy. Not something to raise with the person, and never part of what a
+     * new session is shown: work in progress is the normal state of a folder.
+     */
+    reviewDue?: boolean;
 }
 /** 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<{
@@ -32,6 +38,8 @@ export declare function reviewItems(api: ApiClient, base: string): Promise<{
  * that any of it exists, let alone open a dashboard to find it.
  */
 export declare function gatherAttention(root: string): Promise<Attention>;
+/** Said by `nerd status` when asked directly, so it does not answer "nothing" a moment before `nerd check` asks for a review. */
+export declare const REVIEW_DUE_NOTE = "The app's code as it is now has not been reviewed from this folder. Nothing to raise with the person: `nerd check` will ask for the review (`nerd review checklist`) before the next deploy.";
 /** Short enough to sit at the top of a session: what, where, and one line on what to do about each kind. */
 export declare function attentionText(a: Attention): string;
 /**

package/dist/commands/status.js

@@ -5,6 +5,7 @@ import { RULES } from "../gates/rules.js";
 import { currentVersions, pinned, versionFindings } from "../gates/versions.js";
 import { findProjectRoot, projectPath, readNerdJson } from "../project.js";
 import { localDay, log } from "../util.js";
+import { reviewDue } from "./session-review.js";
 import { cliVersion } from "./source.js";
 const within = (p, ms) => Promise.race([p.catch(() => null), new Promise((r) => setTimeout(() => r(null), ms))]);
 const item = (rule_id, extra = {}) => {
@@ -56,11 +57,19 @@ export async function gatherAttention(root) {
                 items.push(it);
         }
     let reviewedAt;
+    let due = false;
     try {
         const nerd = readNerdJson(root);
         app = `${nerd.org}/${nerd.project}`;
         const api = ApiClient.fromConfig();
         const base = projectPath(nerd);
+        try {
+            // The same question the `review` check asks, under the same conditions (linked and signed in), so the two agree.
+            due = reviewDue(root).due;
+        }
+        catch {
+            // a folder that cannot be listed has nothing to say here
+        }
         const [review, project] = await Promise.all([reviewItems(api, base), within(api.get(base), 5000)]);
         items.push(...review.items);
         reviewedAt = review.reviewedAt;
@@ -78,8 +87,10 @@ export async function gatherAttention(root) {
     catch {
         // not linked, or not signed in: the versions above are all there is to say
     }
-    return { app, items, ...(reviewedAt ? { reviewedAt } : {}) };
+    return { app, items, ...(reviewedAt ? { reviewedAt } : {}), ...(due ? { reviewDue: true } : {}) };
 }
+/** Said by `nerd status` when asked directly, so it does not answer "nothing" a moment before `nerd check` asks for a review. */
+export const REVIEW_DUE_NOTE = "The app's code as it is now has not been reviewed from this folder. Nothing to raise with the person: `nerd check` will ask for the review (`nerd review checklist`) before the next deploy.";
 /** Short enough to sit at the top of a session: what, where, and one line on what to do about each kind. */
 export function attentionText(a) {
     if (!a.items.length)
@@ -120,6 +131,9 @@ export async function status(opts) {
         process.stdout.write(`${text}\n`);
     else if (!opts.hook)
         log.ok(`Nothing needs attention${a.app ? ` for ${a.app}` : ""}.`);
+    // A new session is not told: unreviewed work in progress is not news, and the check asks at the right moment.
+    if (!opts.hook && a.reviewDue)
+        process.stdout.write(`${text ? "\n" : ""}${REVIEW_DUE_NOTE}\n`);
 }
 /** `nerd review`: only what is open from the latest review, with every fix written out. */
 export async function review(opts) {

package/dist/commands/upgrade.js

@@ -43,6 +43,8 @@ export function upgradeProject(root, tpl, version) {
     // 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}`;
+    // Whether moving the SDK's version is all that happens to package.json: nothing below adds to it.
+    const versionOnly = JSON.stringify(pkg) !== before && Boolean(pkg.dependencies.zod && pkg.devDependencies.vitest && pkg.scripts.test);
     if (!pkg.dependencies.zod && tplPkg.dependencies?.zod)
         pkg.dependencies.zod = tplPkg.dependencies.zod;
     if (!pkg.devDependencies.vitest && tplPkg.devDependencies?.vitest)
@@ -116,6 +118,22 @@ export function upgradeProject(root, tpl, version) {
     const ignore = read(path.join(root, ".gitignore")) ?? "";
     if (!/^\.nerd\/?$/m.test(ignore))
         write(".gitignore", `${ignore}${ignore.endsWith("\n") || !ignore ? "" : "\n"}.nerd/\n`);
+    // Nothing to do after an upgrade that found everything current. When the only change is the SDK's version
+    // in package.json, the steps say so: the longer wording reads as if the app's code were behind.
+    if (!changed.length)
+        return { from, to: version, changed, next: [] };
+    if (versionOnly && changed.length === 1 && changed[0] === "package.json") {
+        return {
+            from,
+            to: version,
+            changed,
+            next: [
+                "Run `pnpm install`.",
+                "Run `nerd check`. Only the SDK's version changed, so expect what it reported before. Anything new is something the newer version checks that the older one did not: work through it as usual.",
+                "Run `nerd deploy` when the check passes, and tell the person in a sentence that the app was brought up to date.",
+            ],
+        };
+    }
     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.");
@@ -134,9 +152,8 @@ export async function upgrade(opts) {
         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(", ")}`);
+        return log.ok(`Already current with nerd ${r.to}. Nothing was changed, and there is nothing to do.`);
+    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/code.d.ts

@@ -13,5 +13,13 @@ export declare const typecheckGate: Gate;
 export declare function depsRuleFor(severity: AdvisorySeverity): string;
 export declare const depsGate: Gate;
 export declare const policyGate: Gate;
+/**
+ * Whether the code at `index` sits in a route that only people with a given role can call: the route
+ * names `requireRole("admin")` itself, or its app does with `.use(...)` before the route is declared.
+ * Reading every user's rows is what such a route is for (an admin's list, a count across everyone), so
+ * a query there with no user filter is not reported. A route that asks only for the role every new
+ * user gets is open to everyone signed in and does not count. `text` must have its comments blanked.
+ */
+export declare function inRoleOnlyRoute(text: string, index: number): boolean;
 /** Heuristics for careless handling of personal data. Advisory: warns, never blocks. */
 export declare const piiGate: Gate;

package/dist/gates/code.js

@@ -2,13 +2,15 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { staticChecks } from "../commands/check.js";
-import { lineOf, sourceFiles } from "./fs.js";
+import { shellCommand } from "../util.js";
+import { lineOf, sourceFiles, withoutComments } from "./fs.js";
 import { finding } from "./secrets.js";
 import { BLOCKED_PACKAGES, MINING_POOLS, normalizeSeverity, osvSeverity } from "./text.js";
 import { counts, result, verdict } from "./types.js";
 export function exec(cmd, args, cwd) {
     return new Promise((resolve) => {
-        const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32" });
+        const how = shellCommand(cmd, args);
+        const child = spawn(how.file, how.args, { cwd, stdio: ["ignore", "pipe", "pipe"], shell: how.shell });
         let stdout = "";
         let stderr = "";
         child.stdout.on("data", (d) => (stdout += d));
@@ -165,6 +167,50 @@ export const policyGate = {
         return result(this, verdict(findings), findings.length ? counts(findings) : "No policy violations", findings, t);
     },
 };
+/** Roles named in a `requireRole(...)` call that not every signed-in person has. "member" is what a new user gets. */
+function restrictedRoles(args) {
+    if (!/^\s*(["'`][\w-]+["'`]\s*,?\s*)+$/.test(args))
+        return false;
+    return ![...args.matchAll(/["'`]([\w-]+)["'`]/g)].some((m) => m[1] === "member");
+}
+/**
+ * Whether the code at `index` sits in a route that only people with a given role can call: the route
+ * names `requireRole("admin")` itself, or its app does with `.use(...)` before the route is declared.
+ * Reading every user's rows is what such a route is for (an admin's list, a count across everyone), so
+ * a query there with no user filter is not reported. A route that asks only for the role every new
+ * user gets is open to everyone signed in and does not count. `text` must have its comments blanked.
+ */
+export function inRoleOnlyRoute(text, index) {
+    const routeRe = /\b(\w+)\.(get|post|put|patch|delete|all)\(\s*(["'`])(\/[^"'`\n]*|\*)\3/g;
+    let route = null;
+    for (let m = routeRe.exec(text); m && m.index < index; m = routeRe.exec(text))
+        route = { app: m[1], path: m[4], index: m.index, open: m.index + m[0].indexOf("(") };
+    if (!route)
+        return false;
+    // The code has to be inside that route's own call, not in a function written after it.
+    let depth = 0;
+    for (let i = route.open; i < index; i++) {
+        const ch = text.charCodeAt(i);
+        if (ch === 40)
+            depth++;
+        else if (ch === 41 && --depth === 0)
+            return false;
+    }
+    const inline = /\brequireRole\(([^)]*)\)/.exec(text.slice(route.open, index));
+    if (inline && restrictedRoles(inline[1]))
+        return true;
+    const useRe = /\b(\w+)\.use\(\s*(?:(["'`])([^"'`\n]*)\2\s*,\s*)?requireRole\(([^)]*)\)/g;
+    for (let u = useRe.exec(text); u && u.index < route.index; u = useRe.exec(text)) {
+        if (u[1] !== route.app || !restrictedRoles(u[4]))
+            continue;
+        const pattern = u[3];
+        if (pattern === undefined || pattern === "*" || pattern === "/*" || pattern === route.path)
+            return true;
+        if (pattern.endsWith("/*") && (route.path === pattern.slice(0, -2) || route.path.startsWith(pattern.slice(0, -1))))
+            return true;
+    }
+    return false;
+}
 /** Heuristics for careless handling of personal data. Advisory: warns, never blocks. */
 export const piiGate = {
     name: "pii",
@@ -185,6 +231,7 @@ export const piiGate = {
         for (const f of sourceFiles(ctx.root)) {
             if (!/\.(ts|tsx|js|jsx|mjs)$/.test(f.rel) || !f.rel.startsWith("src/"))
                 continue;
+            let bare;
             for (const c of checks) {
                 if (c.files && !c.files.test(f.rel))
                     continue;
@@ -193,6 +240,9 @@ export const piiGate = {
                 while ((m = c.re.exec(f.text))) {
                     if (c.rule === "pii/unscoped-user-table" && !/user_id|userId/.test(f.text))
                         continue;
+                    // An admin's view across everyone is meant to have no user filter.
+                    if (c.rule === "pii/unscoped-user-table" && inRoleOnlyRoute((bare ??= withoutComments(f.text)), m.index))
+                        continue;
                     findings.push(finding(c.rule, { file: f.rel, line: lineOf(f.text, m.index) }));
                 }
             }

package/dist/gates/design.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { lineOf, sourceFiles } from "./fs.js";
+import { lineOf, sourceFiles, withoutComments } from "./fs.js";
 import { finding } from "./secrets.js";
 import { counts, result, verdict } from "./types.js";
 /**
@@ -16,10 +16,6 @@ import { counts, result, verdict } from "./types.js";
  */
 const CODE = /\.(ts|tsx|js|jsx|mjs)$/;
 const LONG_FILE_LINES = 400;
-/** Blanks out comments, keeping every character position. */
-function withoutComments(text) {
-    return text.replace(/\/\*[\s\S]*?\*\/|(^|[^:"'`\\])\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, " "));
-}
 /** "/api/todos/:id" → a pattern; ":id" and "*" match one or more characters of a segment. */
 function routePattern(p) {
     return new RegExp(`^${p.split("/").map((seg) => (seg.startsWith(":") ? "[^/]+" : seg === "*" ? ".*" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))).join("/")}/?$`);

package/dist/gates/fs.d.ts

@@ -4,4 +4,6 @@ export interface SourceFile {
 }
 /** Text files under root, skipping dependencies and build output. */
 export declare function sourceFiles(root: string): SourceFile[];
+/** Blanks out comments, keeping every character position, so a pattern inside a comment is not a finding. */
+export declare function withoutComments(text: string): string;
 export declare function lineOf(text: string, index: number): number;

package/dist/gates/fs.js

@@ -26,6 +26,10 @@ export function sourceFiles(root) {
     walk(root);
     return out;
 }
+/** Blanks out comments, keeping every character position, so a pattern inside a comment is not a finding. */
+export function withoutComments(text) {
+    return text.replace(/\/\*[\s\S]*?\*\/|(^|[^:"'`\\])\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, " "));
+}
 export function lineOf(text, index) {
     let line = 1;
     for (let i = 0; i < index && i < text.length; i++)

package/dist/gates/rules.js

@@ -87,7 +87,7 @@ export const RULES = {
     "pii/log-request-body": { title: "Logging a request body", severity: "warn", audience: "agent", risk: "Request bodies often carry personal data; logging them keeps copies you did not mean to keep.", fix: "Log only the fields you need, never the whole body." },
     "pii/email-in-query-string": { title: "Email address in a URL", severity: "warn", audience: "agent", risk: "URLs end up in browser history, logs, and referrer headers.", fix: "Send it in the request body or use an id." },
     "pii/plaintext-password-column": { title: "A password column in the schema", severity: "warn", audience: "agent", risk: "Storing passwords yourself is unnecessary here and easy to get wrong.", fix: "Remove the column; the platform handles passwords. If you must store a secret, store a hash." },
-    "pii/unscoped-user-table": { title: "Query on user data without a user filter", severity: "warn", audience: "agent", risk: "One user could see or change another user's rows.", fix: "Add .where(eq(table.userId, c.var.user.id)) to every read and write on tables with a user_id column.", example: { wrong: "db.select().from(schema.notes).all()", right: "db.select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all()" } },
+    "pii/unscoped-user-table": { title: "Query on user data without a user filter", severity: "warn", audience: "agent", risk: "One user could see or change another user's rows.", fix: "Add .where(eq(table.userId, c.var.user.id)) to every read and write on tables with a user_id column. A route that only a role such as admin can call (`requireRole(\"admin\")` on the route or on its app) is expected to read across users and is not reported.", example: { wrong: "db.select().from(schema.notes).all()", right: "db.select().from(schema.notes).where(eq(schema.notes.userId, c.var.user!.id)).all()" } },
     "pii/wildcard-cors": { title: "Wildcard CORS with cookies", severity: "warn", audience: "agent", risk: "Any website could call your API with the visitor's cookies.", fix: "Remove the wildcard. Same-origin requests need no CORS headers." },
     "suppressions/ignore-comment": { title: "A scanner ignore comment was added", severity: "block", audience: "human", risk: "Ignore comments turn off a check for that line. They are sometimes right and sometimes a way to hide a problem.", fix: "Review the line in the dashboard and approve the suppression if it is correct; the agent must not add or approve suppressions itself." },
     "suppressions/ignore-file": { title: "A scanner ignore file was changed", severity: "block", audience: "human", risk: "Ignore files silence checks across the whole project.", fix: "Review the change in the dashboard and approve it if it is correct." },

package/dist/gates/static.js

@@ -1,4 +1,4 @@
-import { lineOf, sourceFiles } from "./fs.js";
+import { lineOf, sourceFiles, withoutComments } from "./fs.js";
 import { finding } from "./secrets.js";
 import { counts, result, verdict } from "./types.js";
 const SERVER = /^src\/server\//;
@@ -21,10 +21,6 @@ const CHECKS = [
     // An unchecked body: c.req.json() used directly instead of readBody(c, schema).
     { rule: "code/unvalidated-body", re: /\bc\.req\.(json|parseBody|formData)\(\)/g, files: SERVER },
 ];
-/** Blanks out comments, keeping every character position, so a pattern inside a comment is not a finding. */
-function withoutComments(text) {
-    return text.replace(/\/\*[\s\S]*?\*\/|(^|[^:"'`\\])\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, " "));
-}
 export const staticGate = {
     name: "static",
     title: "Unsafe code patterns",

package/dist/util.d.ts

@@ -23,6 +23,17 @@ export interface RunOptions {
     /** Send the child's stdout to our stderr, so stdout stays reserved for `--json` output. */
     stdoutToStderr?: boolean;
 }
+/**
+ * How a command is started. On Windows the tools an app uses (npx, pnpm) are `.cmd` files, which only
+ * start through the shell, and a shell takes one line. Handed a separate list of arguments, Node joins
+ * them with spaces and no quotes (and prints the DEP0190 warning about it), so a folder with a space in
+ * its name arrives as two arguments. The line is built here instead, with quotes round whatever needs them.
+ */
+export declare function shellCommand(cmd: string, args: string[], platform?: NodeJS.Platform): {
+    file: string;
+    args: string[];
+    shell: boolean;
+};
 /** Runs a command, streaming output. Resolves with the exit code. */
 export declare function run(cmd: string, args: string[], opts?: RunOptions): Promise<number>;
 export declare function runOrThrow(cmd: string, args: string[], opts?: RunOptions): Promise<void>;

package/dist/util.js

@@ -22,10 +22,24 @@ export const log = {
     ok: (msg) => console.error(`\x1b[32m✓\x1b[0m ${msg}`),
     warn: (msg) => console.error(`\x1b[33m!\x1b[0m ${msg}`),
 };
+/**
+ * How a command is started. On Windows the tools an app uses (npx, pnpm) are `.cmd` files, which only
+ * start through the shell, and a shell takes one line. Handed a separate list of arguments, Node joins
+ * them with spaces and no quotes (and prints the DEP0190 warning about it), so a folder with a space in
+ * its name arrives as two arguments. The line is built here instead, with quotes round whatever needs them.
+ */
+export function shellCommand(cmd, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { file: cmd, args, shell: false };
+    // Inside quotes, a program's own argument parser reads backslashes literally unless a quote follows them.
+    const quote = (a) => (/^[\w./:=@\\,+-]+$/.test(a) ? a : `"${a.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`);
+    return { file: [cmd, ...args].map(quote).join(" "), args: [], shell: true };
+}
 /** Runs a command, streaming output. Resolves with the exit code. */
 export function run(cmd, args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, { cwd: opts.cwd, env: { ...process.env, ...opts.env }, stdio: ["inherit", opts.stdoutToStderr ? "pipe" : "inherit", "inherit"], shell: process.platform === "win32" });
+        const how = shellCommand(cmd, args);
+        const child = spawn(how.file, how.args, { cwd: opts.cwd, env: { ...process.env, ...opts.env }, stdio: ["inherit", opts.stdoutToStderr ? "pipe" : "inherit", "inherit"], shell: how.shell });
         child.stdout?.pipe(process.stderr);
         child.on("error", reject);
         child.on("exit", (code) => resolve(code ?? 1));

package/package.json

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