toiljs 0.0.15 → 0.0.19

package/src/cli/doctor.ts

@@ -23,9 +23,12 @@ import {
     checkNode,
     checkPackageManager,
     checkPeer,
+    checkPrettierPlugin,
     checkRelativeAssets,
+    checkRestDispatch,
     checkRootElement,
     checkRoutesPresent,
+    checkRpcWiring,
     checkSeoUrl,
     checkServerEntry,
     type CheckStatus,
@@ -36,6 +39,10 @@ import {
     checkWasmBuilt,
     findRelativeAssets,
     hasFailures,
+    type RestFacts,
+    type RpcFacts,
+    RPC_TOILSCRIPT_MIN,
+    satisfiesMin,
     type SourceFile,
     summarize,
 } from './diagnostics.js';
@@ -53,6 +60,8 @@ export interface DoctorOptions {
     readonly cwd: string;
     /** Emit machine-readable JSON instead of the human report. */
     readonly json?: boolean;
+    /** Auto-fix what can be fixed in place (currently the typed-RPC wiring). */
+    readonly fix?: boolean;
 }
 
 /** Parses a JSON file into a plain object, or null on any error / non-object. */
@@ -83,6 +92,336 @@ function readFile(file: string): string | null {
     }
 }
 
+function writeFile(file: string, content: string): void {
+    fs.writeFileSync(file, content);
+}
+
+/**
+ * Whether `name` is installed for the project at `root`. Tries Node resolution first (handles
+ * hoisting), then falls back to walking `node_modules`, since a strict `exports` map can make
+ * `require.resolve('<pkg>')` throw even when the package is present (the toilscript false positive).
+ */
+function isPackageInstalled(root: string, name: string): boolean {
+    const require = createRequire(path.join(root, 'package.json'));
+    for (const id of [`${name}/package.json`, name]) {
+        try {
+            require.resolve(id);
+            return true;
+        } catch {
+            // try the next resolution strategy
+        }
+    }
+    for (let dir = root; ; ) {
+        if (fs.existsSync(path.join(dir, 'node_modules', name, 'package.json'))) return true;
+        const parent = path.dirname(dir);
+        if (parent === dir) return false;
+        dir = parent;
+    }
+}
+
+/** Narrows a value to a plain (non-array) object, or null. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : null;
+}
+
+const RPC_MODULE_FLAG = '--rpcModule shared/server.ts';
+const RPC_GITIGNORE_LINE = 'shared/server.ts';
+const RPC_GITIGNORE_RE = /(^|\n)\s*shared\/server\.ts\s*(\r?\n|$)/;
+
+/**
+ * Whether a dependency range is an ordinary registry semver range (so a deliberate
+ * `latest`/`*`/`file:`/`github:`/`workspace:`/`npm:` pin is left untouched and treated
+ * as already-OK rather than clobbered to a version).
+ */
+function looksLikeSemverRange(range: string): boolean {
+    return /^\s*[v^~>=<]*\s*\d+\.\d+/.test(range);
+}
+
+/** Reads the project and reports which parts of the typed-RPC wiring are present. */
+function gatherRpcFacts(root: string): RpcFacts {
+    const pkg = readJsonObject(path.join(root, 'package.json'));
+    const scripts = pkg ? stringRecord(pkg.scripts) : {};
+    const deps = {
+        ...(pkg ? stringRecord(pkg.dependencies) : {}),
+        ...(pkg ? stringRecord(pkg.devDependencies) : {}),
+    };
+    const tsconfig = readJsonObject(path.join(root, 'tsconfig.json'));
+    const gitignore = readFile(path.join(root, '.gitignore'));
+
+    // Either the combined `build` or `build:server` carrying --rpcModule counts (the fixer writes both).
+    const buildServerWired = [scripts['build:server'], scripts['build']].some(
+        (s) => typeof s === 'string' && s.includes('--rpcModule'),
+    );
+
+    let tsconfigWired = false;
+    if (tsconfig) {
+        // An absent `include` compiles all files, so `shared` is covered implicitly.
+        const include = tsconfig.include;
+        const hasShared = !Array.isArray(include) || include.includes('shared');
+        const paths = asRecord(asRecord(tsconfig.compilerOptions)?.paths);
+        tsconfigWired = hasShared && paths !== null && 'shared/*' in paths;
+    }
+
+    const gitignoreWired = gitignore !== null && RPC_GITIGNORE_RE.test(gitignore);
+    const range = deps.toilscript;
+    // A non-semver range (file:/github:/latest/*) can't be assessed; don't flag it.
+    const toilscriptOk =
+        range == null
+            ? false
+            : looksLikeSemverRange(range)
+              ? satisfiesMin(range, RPC_TOILSCRIPT_MIN)
+              : true;
+
+    return { buildServerWired, tsconfigWired, gitignoreWired, toilscriptOk };
+}
+
+/** The server `.ts` sources, read from the directories of the toilconfig entries (capped). */
+function serverSources(root: string, toilconfig: Record<string, unknown> | null): string[] {
+    const dirs = new Set<string>();
+    const entries = Array.isArray(toilconfig?.entries)
+        ? (toilconfig.entries as unknown[]).filter((e): e is string => typeof e === 'string')
+        : [];
+    for (const e of entries) dirs.add(path.dirname(path.resolve(root, e)));
+
+    const out: string[] = [];
+    const cap = 200;
+    const maxDepth = 16; // bounds the walk so a symlink cycle in a hostile project can't hang doctor
+    const visit = (current: string, depth: number): void => {
+        if (out.length >= cap || depth > maxDepth) return;
+        let listing: fs.Dirent[];
+        try {
+            listing = fs.readdirSync(current, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of listing) {
+            if (out.length >= cap) break;
+            const full = path.join(current, entry.name);
+            // isDirectory() follows symlinks; the depth cap keeps a symlink cycle bounded.
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules') visit(full, depth + 1);
+            } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+                const src = readFile(full);
+                if (src !== null) out.push(src);
+            }
+        }
+    };
+    for (const dir of dirs) visit(dir, 0);
+    return out;
+}
+
+/** Scans the server sources for `@rest` controllers and whether anything dispatches them. */
+function gatherRestFacts(root: string, toilconfig: Record<string, unknown> | null): RestFacts {
+    let hasControllers = false;
+    let dispatched = false;
+    for (const src of serverSources(root, toilconfig)) {
+        if (/@rest\b/.test(src)) hasControllers = true;
+        if (/\bRest\s*\.\s*dispatch\s*\(/.test(src) || /\bRestHandler\b/.test(src))
+            dispatched = true;
+        if (hasControllers && dispatched) break;
+    }
+    return { hasControllers, dispatched };
+}
+
+interface RpcFixResult {
+    /** Files written. */
+    readonly changed: string[];
+    /** Files that need a manual edit (e.g. tsconfig with comments). */
+    readonly skipped: string[];
+}
+
+/**
+ * Applies the typed-RPC wiring in place: appends `--rpcModule` to the toilscript build scripts,
+ * adds `shared` (+ the `shared/*` alias) to tsconfig, ignores the generated module, and lifts the
+ * toilscript floor. Idempotent; only writes files it actually changes.
+ */
+function applyRpcFix(root: string): RpcFixResult {
+    const changed: string[] = [];
+    const skipped: string[] = [];
+
+    const pkgPath = path.join(root, 'package.json');
+    const pkgRaw = readFile(pkgPath);
+    const pkg = pkgRaw !== null ? readJsonObject(pkgPath) : null;
+    if (pkg !== null) {
+        let touched = false;
+        const scripts = asRecord(pkg.scripts) ?? {};
+        for (const key of ['build', 'build:server']) {
+            const value = scripts[key];
+            if (
+                typeof value === 'string' &&
+                value.includes('toilscript') &&
+                !value.includes('--rpcModule')
+            ) {
+                scripts[key] = `${value} ${RPC_MODULE_FLAG}`;
+                pkg.scripts = scripts;
+                touched = true;
+            }
+        }
+        let toilscriptDeclared = false;
+        for (const field of ['devDependencies', 'dependencies']) {
+            const bag = asRecord(pkg[field]);
+            const current = bag?.toilscript;
+            if (bag && typeof current === 'string') {
+                toilscriptDeclared = true;
+                // Only lift a real semver range that floors below the minimum; leave file:/latest/* pins alone.
+                if (looksLikeSemverRange(current) && !satisfiesMin(current, RPC_TOILSCRIPT_MIN)) {
+                    bag.toilscript = `^${RPC_TOILSCRIPT_MIN}`;
+                    touched = true;
+                }
+            }
+        }
+        if (!toilscriptDeclared) {
+            // A server project needs toilscript; add it so the wiring actually resolves.
+            const dd = asRecord(pkg.devDependencies) ?? {};
+            dd.toilscript = `^${RPC_TOILSCRIPT_MIN}`;
+            pkg.devDependencies = dd;
+            touched = true;
+        }
+        if (touched) {
+            writeFile(pkgPath, JSON.stringify(pkg, null, 4) + '\n');
+            changed.push('package.json');
+        }
+    } else if (pkgRaw !== null) {
+        skipped.push('package.json (unparseable)');
+    }
+
+    const tsPath = path.join(root, 'tsconfig.json');
+    const tsRaw = readFile(tsPath);
+    const tsconfig = tsRaw !== null ? readJsonObject(tsPath) : null;
+    if (tsconfig !== null) {
+        let touched = false;
+        // Only touch `include` if it already exists; an absent `include` compiles all files,
+        // and synthesizing one would narrow what TypeScript sees.
+        if (Array.isArray(tsconfig.include)) {
+            const include = [...(tsconfig.include as unknown[])];
+            if (!include.includes('shared')) {
+                const at = include.indexOf('client');
+                include.splice(at >= 0 ? at + 1 : include.length, 0, 'shared');
+                tsconfig.include = include;
+                touched = true;
+            }
+        }
+        const co = asRecord(tsconfig.compilerOptions) ?? {};
+        const paths = asRecord(co.paths) ?? {};
+        if (!('shared/*' in paths)) {
+            paths['shared/*'] = ['./shared/*'];
+            co.paths = paths;
+            tsconfig.compilerOptions = co;
+            touched = true;
+        }
+        if (touched) {
+            writeFile(tsPath, JSON.stringify(tsconfig, null, 4) + '\n');
+            changed.push('tsconfig.json');
+        }
+    } else if (tsRaw !== null) {
+        skipped.push('tsconfig.json (JSON with comments, add "shared" + paths by hand)');
+    }
+
+    const giPath = path.join(root, '.gitignore');
+    const giRaw = readFile(giPath);
+    if (giRaw === null) {
+        writeFile(giPath, `${RPC_GITIGNORE_LINE}\n`);
+        changed.push('.gitignore');
+    } else if (!RPC_GITIGNORE_RE.test(giRaw)) {
+        const sep = giRaw.length === 0 || giRaw.endsWith('\n') ? '' : '\n';
+        writeFile(giPath, `${giRaw}${sep}${RPC_GITIGNORE_LINE}\n`);
+        changed.push('.gitignore');
+    }
+
+    return { changed, skipped };
+}
+
+const PRETTIER_PLUGIN = 'toiljs/prettier-plugin';
+const PRETTIER_MENTION = /toiljs\/prettier(-plugin)?/;
+const PRETTIER_CONFIG_FILES = [
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.json5',
+    '.prettierrc.yaml',
+    '.prettierrc.yml',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.mjs',
+    '.prettierrc.ts',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+    'prettier.config.ts',
+];
+
+/** Whether any prettier config (file or package.json field) pulls in the toilscript plugin. */
+function prettierPluginPresent(root: string, pkg: Record<string, unknown> | null): boolean {
+    if (pkg && pkg.prettier !== undefined && PRETTIER_MENTION.test(JSON.stringify(pkg.prettier))) {
+        return true;
+    }
+    for (const name of PRETTIER_CONFIG_FILES) {
+        const raw = readFile(path.join(root, name));
+        if (raw !== null && PRETTIER_MENTION.test(raw)) return true;
+    }
+    return false;
+}
+
+/**
+ * Adds `toiljs/prettier-plugin` to the project's prettier config so prettier can format the
+ * toilscript server. Handles the common cases (package.json `prettier`, a JSON `.prettierrc`,
+ * or no config at all); warns for shapes it can't safely edit (a JS config, or a string preset).
+ */
+function applyPrettierFix(root: string, pkg: Record<string, unknown> | null): RpcFixResult {
+    const changed: string[] = [];
+    const skipped: string[] = [];
+    if (prettierPluginPresent(root, pkg)) return { changed, skipped };
+
+    // package.json "prettier" object.
+    const pkgPath = path.join(root, 'package.json');
+    const pkgConfig = pkg ? asRecord(pkg.prettier) : null;
+    if (pkgConfig !== null) {
+        const full = readJsonObject(pkgPath);
+        const target = full ? asRecord(full.prettier) : null;
+        if (full && target) {
+            target.plugins = [
+                ...(Array.isArray(target.plugins) ? target.plugins : []),
+                PRETTIER_PLUGIN,
+            ];
+            writeFile(pkgPath, JSON.stringify(full, null, 4) + '\n');
+            changed.push('package.json');
+            return { changed, skipped };
+        }
+    }
+
+    // A JSON .prettierrc / .prettierrc.json object.
+    for (const name of ['.prettierrc', '.prettierrc.json']) {
+        const filePath = path.join(root, name);
+        const raw = readFile(filePath);
+        if (raw === null) continue;
+        const obj = readJsonObject(filePath);
+        if (obj === null) {
+            skipped.push(`${name} (add "${PRETTIER_PLUGIN}" to plugins by hand)`);
+            return { changed, skipped };
+        }
+        obj.plugins = [...(Array.isArray(obj.plugins) ? obj.plugins : []), PRETTIER_PLUGIN];
+        writeFile(filePath, JSON.stringify(obj, null, 4) + '\n');
+        changed.push(name);
+        return { changed, skipped };
+    }
+
+    // A JS/TS config we can't safely edit.
+    const jsConfig = PRETTIER_CONFIG_FILES.find((name) => readFile(path.join(root, name)) !== null);
+    if (jsConfig) {
+        skipped.push(`${jsConfig} (add "${PRETTIER_PLUGIN}" to its plugins by hand)`);
+        return { changed, skipped };
+    }
+
+    // No config at all: create one.
+    writeFile(
+        path.join(root, '.prettierrc.json'),
+        JSON.stringify({ plugins: [PRETTIER_PLUGIN] }, null, 4) + '\n',
+    );
+    changed.push('.prettierrc.json');
+    return { changed, skipped };
+}
+
 /** Reads the framework's own package.json (engines + peerDependencies) for the requirements. */
 function frameworkMeta(): { node: string; peers: Record<string, string> } {
     const pkgPath = path.resolve(
@@ -216,12 +555,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
             ? toilconfig.entries.filter((e): e is string => typeof e === 'string')
             : [];
         missingEntries = entries.filter((e) => !fs.existsSync(path.join(root, e)));
-        try {
-            createRequire(path.join(root, 'package.json')).resolve('toilscript');
-            toilscriptInstalled = true;
-        } catch {
-            toilscriptInstalled = false;
-        }
+        toilscriptInstalled = isPackageInstalled(root, 'toilscript');
         const targets =
             typeof toilconfig.targets === 'object' && toilconfig.targets !== null
                 ? (toilconfig.targets as Record<string, unknown>)
@@ -248,6 +582,23 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
     const peerName = (n: string): Check => checkPeer(n, deps[n] ?? null, meta.peers[n] ?? '*');
     const peerChecks = Object.keys(meta.peers).map(peerName);
 
+    // Server tooling (RPC wiring + the prettier plugin): optionally fix in place, then re-read.
+    const rpcFix = serverPresent && opts.fix ? applyRpcFix(root) : null;
+    const prettierFix = serverPresent && opts.fix ? applyPrettierFix(root, projectPkg) : null;
+    const rpcFacts = gatherRpcFacts(root);
+    const restFacts = gatherRestFacts(root, toilconfig);
+    const prettierPresent = prettierPluginPresent(
+        root,
+        readJsonObject(path.join(root, 'package.json')),
+    );
+    const serverFix =
+        rpcFix || prettierFix
+            ? {
+                  changed: [...(rpcFix?.changed ?? []), ...(prettierFix?.changed ?? [])],
+                  skipped: [...(rpcFix?.skipped ?? []), ...(prettierFix?.skipped ?? [])],
+              }
+            : null;
+
     const groups: CheckGroup[] = [
         {
             title: 'Environment',
@@ -302,6 +653,9 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
                       checkServerEntry(missingEntries),
                       checkToilscriptInstalled(toilscriptInstalled),
                       checkWasmBuilt(wasmExists),
+                      checkRpcWiring(rpcFacts),
+                      checkRestDispatch(restFacts),
+                      checkPrettierPlugin(prettierPresent),
                   ]
                 : [checkToilconfig(false)],
         },
@@ -309,10 +663,33 @@ export async function runDoctor(opts: DoctorOptions): Promise<void> {
 
     const summary = summarize(groups);
     if (opts.json) {
-        process.stdout.write(JSON.stringify({ groups, summary }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ groups, summary, fixed: serverFix }, null, 2) + '\n');
     } else {
         process.stdout.write('\n' + accent('  Doctor') + dim(`  ${root}`) + '\n\n');
         renderHuman(groups);
+        if (serverFix) renderRpcFix(serverFix);
+        else if (opts.fix && !serverPresent) {
+            process.stdout.write(
+                '  ' + dim('--fix: no server (toilconfig.json) found, nothing to wire.') + '\n\n',
+            );
+        }
     }
     if (hasFailures(summary)) process.exitCode = 1;
 }
+
+/** Prints the result of `--fix`, and whether a reinstall is needed (toilscript bump). */
+function renderRpcFix(result: RpcFixResult): void {
+    const out: string[] = [];
+    if (result.changed.length > 0) {
+        out.push('  ' + success('fixed RPC wiring') + dim(`  ${result.changed.join(', ')}`));
+        if (result.changed.includes('package.json')) {
+            out.push(
+                '  ' + dim('run your installer (npm/pnpm/yarn) if the toilscript version changed.'),
+            );
+        }
+    } else {
+        out.push('  ' + dim('RPC wiring already in place, nothing to fix.'));
+    }
+    for (const item of result.skipped) out.push('  ' + warn('skipped') + dim(`  ${item}`));
+    process.stdout.write(out.join('\n') + '\n\n');
+}

package/src/cli/index.ts

@@ -16,6 +16,7 @@ import { accent, banner, bold, danger, dim, success, version } from './ui.js';
 interface Flags {
     root?: string;
     port?: number;
+    host?: string;
     name?: string;
     template?: Template;
     preprocessor?: Preprocessor;
@@ -27,6 +28,7 @@ interface Flags {
     pm?: string;
     yes?: boolean;
     json?: boolean;
+    fix?: boolean;
     target?: string;
 }
 
@@ -43,6 +45,9 @@ function parseArgs(argv: string[]): Flags {
                 if (!Number.isNaN(port)) flags.port = port;
                 break;
             }
+            case '--host':
+                flags.host = argv[++i];
+                break;
             case '--template':
             case '-t': {
                 const t = argv[++i];
@@ -95,6 +100,9 @@ function parseArgs(argv: string[]): Flags {
             case '--json':
                 flags.json = true;
                 break;
+            case '--fix':
+                flags.fix = true;
+                break;
             case '--target':
                 flags.target = argv[++i];
                 break;
@@ -130,6 +138,7 @@ function printHelp(): void {
             cmd('-y, --yes', 'create: accept defaults (non-interactive)'),
             cmd('--no-install', "create: don't install dependencies"),
             cmd('--json', 'doctor: machine-readable output'),
+            cmd('--fix', 'doctor: auto-fix what it can (typed-RPC wiring)'),
             cmd('--target <t>', 'update: latest | minor | patch | newest | greatest'),
             cmd('-v, --version', 'print the toiljs version'),
             '',
@@ -193,7 +202,7 @@ async function main(): Promise<void> {
         case 'start': {
             banner();
             process.stdout.write(dim('  self-hosting the built app…') + '\n\n');
-            const server = await start({ root: flags.root, port: flags.port });
+            const server = await start({ root: flags.root, port: flags.port, host: flags.host });
             process.stdout.write(
                 accent('  ➜ ') +
                     bold(`http://localhost:${String(server.port)}`) +
@@ -206,7 +215,7 @@ async function main(): Promise<void> {
         case 'doctor':
             // Skip the banner for --json so stdout stays valid JSON.
             if (!flags.json) banner();
-            await runDoctor({ root: flags.root, cwd: process.cwd(), json: flags.json });
+            await runDoctor({ root: flags.root, cwd: process.cwd(), json: flags.json, fix: flags.fix });
             break;
 
         case 'update':

package/src/cli/proc.ts

@@ -1,50 +1,50 @@
-import { spawn } from 'node:child_process';
-
-/**
- * Spawns `cmd args` in `cwd`, resolving on a 0 exit code and rejecting otherwise. On Windows the
- * `npm`/`pnpm`/`yarn` shims are `.cmd` files that need a shell; passing an args array with
- * `shell: true` is deprecated (DEP0190), so the whole command is passed as one string there
- * (args are fixed/allowlisted, never raw user input). POSIX spawns directly.
- */
-export function run(cmd: string, args: string[], cwd: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-        const onWindows = process.platform === 'win32';
-        const child = onWindows
-            ? spawn([cmd, ...args].join(' '), { cwd, stdio: 'ignore', shell: true })
-            : spawn(cmd, args, { cwd, stdio: 'ignore' });
-        child.on('error', reject);
-        child.on('close', (code) =>
-            code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${String(code)}`)),
-        );
-    });
-}
-
-/**
- * Like {@link run}, but captures stdout/stderr and resolves with them plus the exit code (it never
- * rejects on a non-zero exit, the caller decides). Used to read JSON from tools like
- * `npm-check-updates`. Same Windows shell handling as {@link run}; args are fixed/allowlisted.
- */
-export function capture(
-    cmd: string,
-    args: string[],
-    cwd: string,
-): Promise<{ stdout: string; stderr: string; code: number }> {
-    return new Promise((resolve, reject) => {
-        const onWindows = process.platform === 'win32';
-        const child = onWindows
-            ? spawn([cmd, ...args].join(' '), { cwd, shell: true })
-            : spawn(cmd, args, { cwd });
-        let stdout = '';
-        let stderr = '';
-        child.stdout?.on('data', (d: Buffer) => {
-            stdout += d.toString();
-        });
-        child.stderr?.on('data', (d: Buffer) => {
-            stderr += d.toString();
-        });
-        child.on('error', reject);
-        child.on('close', (code) => {
-            resolve({ stdout, stderr, code: code ?? 1 });
-        });
-    });
-}
+import { spawn } from 'node:child_process';
+
+/**
+ * Spawns `cmd args` in `cwd`, resolving on a 0 exit code and rejecting otherwise. On Windows the
+ * `npm`/`pnpm`/`yarn` shims are `.cmd` files that need a shell; passing an args array with
+ * `shell: true` is deprecated (DEP0190), so the whole command is passed as one string there
+ * (args are fixed/allowlisted, never raw user input). POSIX spawns directly.
+ */
+export function run(cmd: string, args: string[], cwd: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const onWindows = process.platform === 'win32';
+        const child = onWindows
+            ? spawn([cmd, ...args].join(' '), { cwd, stdio: 'ignore', shell: true })
+            : spawn(cmd, args, { cwd, stdio: 'ignore' });
+        child.on('error', reject);
+        child.on('close', (code) =>
+            code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${String(code)}`)),
+        );
+    });
+}
+
+/**
+ * Like {@link run}, but captures stdout/stderr and resolves with them plus the exit code (it never
+ * rejects on a non-zero exit, the caller decides). Used to read JSON from tools like
+ * `npm-check-updates`. Same Windows shell handling as {@link run}; args are fixed/allowlisted.
+ */
+export function capture(
+    cmd: string,
+    args: string[],
+    cwd: string,
+): Promise<{ stdout: string; stderr: string; code: number }> {
+    return new Promise((resolve, reject) => {
+        const onWindows = process.platform === 'win32';
+        const child = onWindows
+            ? spawn([cmd, ...args].join(' '), { cwd, shell: true })
+            : spawn(cmd, args, { cwd });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (d: Buffer) => {
+            stdout += d.toString();
+        });
+        child.stderr?.on('data', (d: Buffer) => {
+            stderr += d.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code: code ?? 1 });
+        });
+    });
+}