@orkestrel/scaffold 0.0.77 → 0.0.79

package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js

@@ -0,0 +1,204 @@
+// Probe a bench with one bounded round trip and resolve its entry. Run from the checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS]
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --codex [--model ID] [--sandbox MODE] [--cap SECONDS]
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --claude [--model ALIAS] [--cap SECONDS]
+// --cursor resolves the Cursor CLI entry (the newest versioned install under LOCALAPPDATA on
+// Windows, `agent` on PATH elsewhere), reads its version (an entry that cannot answer `--version` is
+// dark, with or without --resolve), and runs one bounded prompt through
+// launch.ts into tmp/cursor/bench.jsonl; --resolve stops after printing the entry. --codex reads
+// `codex --version` and `codex login status`, then runs one bounded exec into tmp/codex/bench.jsonl
+// under the sandbox the host allows (danger-full-access on Windows, read-only elsewhere). --claude
+// reads `claude --version` and runs one bounded print-mode prompt into tmp/claude/bench.jsonl. The
+// JSON summary carries the command, the version, the session id, the answer, and `live`. Exit 0 when
+// the bench answered READY, 3 when it is dark, 64 on usage.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJsonObject, readMissingFlags, readNumber, readOption, readString } from "./helpers.js";
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+// The checkout runs the `.ts` sources and a built twin under `dist/agents` runs `.js` siblings.
+const EXTENSION = extname(fileURLToPath(import.meta.url));
+const PROMPT = 'Reply with the single word READY and nothing else.';
+const CURSOR_MODEL = process.env.CURSOR_GROK_MODEL ?? 'grok-4.7-high';
+const CODEX_MODEL = process.env.CODEX_ASTRA_MODEL ?? 'gpt-6-astra';
+const CLAUDE_MODEL = 'opus';
+const DEFAULT_CAP = 180;
+function readVersion(command) {
+    const [file, ...args] = command;
+    if (file === undefined)
+        return undefined;
+    const result = spawnSync(file, [...args, '--version'], { encoding: 'utf8', windowsHide: true });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+function resolveCursor() {
+    if (process.platform !== 'win32') {
+        return { command: ['agent'], version: readVersion(['agent']), error: undefined };
+    }
+    const local = process.env.LOCALAPPDATA;
+    if (local === undefined)
+        return { command: [], version: undefined, error: 'LOCALAPPDATA is not set' };
+    const versions = join(local, 'cursor-agent', 'versions');
+    if (!existsSync(versions) || !statSync(versions).isDirectory()) {
+        return { command: [], version: undefined, error: `${versions} is not a directory` };
+    }
+    const newest = readdirSync(versions, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && /^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/u.test(entry.name))
+        .map((entry) => entry.name)
+        .sort()
+        .at(-1);
+    if (newest === undefined) {
+        return { command: [], version: undefined, error: `no versioned install under ${versions}` };
+    }
+    const node = join(versions, newest, 'node.exe');
+    const index = join(versions, newest, 'index.js');
+    if (!existsSync(node) || !existsSync(index)) {
+        return { command: [], version: undefined, error: `${newest} lacks node.exe or index.js` };
+    }
+    return { command: [node, index], version: readVersion([node, index]), error: undefined };
+}
+function runRoundTrip(bench, command, cap) {
+    const journal = `tmp/${bench}/bench.jsonl`;
+    const errors = `tmp/${bench}/bench.err`;
+    const answer = `tmp/${bench}/bench-answer.md`;
+    const launch = spawnSync(process.execPath, [
+        join(SCRIPTS, `launch${EXTENSION}`),
+        '--journal',
+        journal,
+        '--errors',
+        errors,
+        '--cap',
+        String(cap),
+        '--',
+        ...command,
+    ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true });
+    const launched = readJsonObject(launch.stdout);
+    const result = spawnSync(process.execPath, [join(SCRIPTS, `result${EXTENSION}`), `--${bench}`, journal, '--out', answer], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true });
+    const read = readJsonObject(result.stdout);
+    return {
+        session: readString(read, 'session'),
+        answer: existsSync(answer) ? readFileSync(answer, 'utf8').trim().slice(0, 200) : undefined,
+        exit: readNumber(launched, 'exit'),
+        capped: launched?.capped === true,
+        durationMs: readNumber(launched, 'durationMs'),
+    };
+}
+function isLive(summary) {
+    return (summary.session !== undefined &&
+        summary.exit === 0 &&
+        !summary.capped &&
+        summary.answer !== undefined &&
+        /^READY\.?$/u.test(summary.answer.trim()));
+}
+function probeCursor(argv) {
+    const entry = resolveCursor();
+    const model = readOption(argv, '--model') ?? CURSOR_MODEL;
+    if (entry.error !== undefined || entry.version === undefined) {
+        console.log(JSON.stringify({ bench: 'cursor', ...entry, live: false }));
+        return 3;
+    }
+    if (argv.includes('--resolve')) {
+        console.log(JSON.stringify({ bench: 'cursor', command: entry.command, version: entry.version }));
+        return 0;
+    }
+    const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP);
+    const summary = runRoundTrip('cursor', [
+        ...entry.command,
+        '-p',
+        '--trust',
+        '--mode=ask',
+        '--model',
+        model,
+        '--output-format',
+        'stream-json',
+        PROMPT,
+    ], cap);
+    const live = isLive(summary);
+    console.log(JSON.stringify({
+        bench: 'cursor',
+        command: entry.command,
+        version: entry.version,
+        model,
+        ...summary,
+        live,
+        journal: 'tmp/cursor/bench.jsonl',
+    }));
+    return live ? 0 : 3;
+}
+function probeCodex(argv) {
+    const version = readVersion(['codex']);
+    const login = spawnSync('codex', ['login', 'status'], { encoding: 'utf8', windowsHide: true });
+    const model = readOption(argv, '--model') ?? CODEX_MODEL;
+    const sandbox = readOption(argv, '--sandbox') ??
+        (process.platform === 'win32' ? 'danger-full-access' : 'read-only');
+    const status = `${login.stdout}${login.stderr}`.trim();
+    if (version === undefined || login.status !== 0) {
+        console.log(JSON.stringify({ bench: 'codex', version, login: status, live: false }));
+        return 3;
+    }
+    const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP);
+    const summary = runRoundTrip('codex', [
+        'codex',
+        'exec',
+        '--json',
+        '-C',
+        process.cwd(),
+        '--sandbox',
+        sandbox,
+        '--model',
+        model,
+        '-c',
+        'model_reasoning_effort="low"',
+        '--output-last-message',
+        'tmp/codex/bench-last.md',
+        PROMPT,
+    ], cap);
+    const live = isLive(summary);
+    console.log(JSON.stringify({
+        bench: 'codex',
+        version,
+        login: status,
+        model,
+        sandbox,
+        ...summary,
+        live,
+        journal: 'tmp/codex/bench.jsonl',
+    }));
+    return live ? 0 : 3;
+}
+function probeClaude(argv) {
+    const version = readVersion(['claude']);
+    const model = readOption(argv, '--model') ?? CLAUDE_MODEL;
+    if (version === undefined) {
+        console.log(JSON.stringify({ bench: 'claude', version, live: false }));
+        return 3;
+    }
+    const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP);
+    const summary = runRoundTrip('claude', ['claude', '-p', PROMPT, '--output-format', 'stream-json', '--verbose', '--model', model], cap);
+    const live = isLive(summary);
+    console.log(JSON.stringify({
+        bench: 'claude',
+        version,
+        model,
+        ...summary,
+        live,
+        journal: 'tmp/claude/bench.jsonl',
+    }));
+    return live ? 0 : 3;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--model', '--cap', '--sandbox']);
+    if (missing.length > 0) {
+        console.error(`bench: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    if (argv.includes('--cursor'))
+        return probeCursor(argv);
+    if (argv.includes('--codex'))
+        return probeCodex(argv);
+    if (argv.includes('--claude'))
+        return probeClaude(argv);
+    console.error('usage: bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS] | --codex [--model ID] [--sandbox MODE] [--cap SECONDS] | --claude [--model ALIAS] [--cap SECONDS]');
+    return 64;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js

@@ -0,0 +1,102 @@
+// Write a unit brief from the template, or check that every path a brief names resolves. Run from
+// the checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]
+//   node .agents/skills/orkestrel-dispatch/scripts/brief.ts --check tmp/codex/UNIT-brief.md
+// The first form copies the brief template beside this skill (`../../../templates/brief.md`, so a
+// target's installed copy finds it too) to tmp/<lane>/<unit>-brief.md with UNIT_ID and SHORT_SUBJECT
+// filled, and writes <unit>-brief-<n>.md when a brief already exists, so a launched brief is never
+// edited. The second form reads every backticked token carrying a slash (a backslash counts and is
+// read as a slash), strips a `:line` or
+// `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
+// exist; a bare filename is outside the check. Exit 3 when any is missing, 64 on usage.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readMissingFlags, readOption } from "./helpers.js";
+const TEMPLATE = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'templates', 'brief.md');
+const LANES = Object.freeze({
+    units: 'tmp/units',
+    cursor: 'tmp/cursor',
+    codex: 'tmp/codex',
+    claude: 'tmp/claude',
+});
+function readsAsPath(token) {
+    if (token.includes('://') || /[<>*{}\s]/u.test(token))
+        return false;
+    if (/[A-Z]{2,}_[A-Z]/u.test(token))
+        return false;
+    if (token.startsWith('@') || token.startsWith('-') || token.startsWith('$'))
+        return false;
+    if (!/^[A-Za-z0-9_.~/-]+$/u.test(token))
+        return false;
+    return token.includes('/');
+}
+function extractPaths(content) {
+    const found = new Set();
+    for (const match of content.matchAll(/`([^`\n]+)`/gu)) {
+        const token = (match[1] ?? '').replace(/\\/gu, '/').replace(/:\d+(?:[-–]\d+)?$/u, '');
+        if (readsAsPath(token))
+            found.add(token);
+    }
+    return [...found].sort();
+}
+function resolveBriefPath(directory, unit) {
+    const base = join(directory, `${unit}-brief.md`);
+    if (!existsSync(base))
+        return base;
+    let n = 2;
+    while (existsSync(join(directory, `${unit}-brief-${n}.md`)))
+        n += 1;
+    return join(directory, `${unit}-brief-${n}.md`);
+}
+function writeBrief(argv) {
+    const unit = readOption(argv, '--unit');
+    const lane = readOption(argv, '--lane');
+    const directory = lane === undefined ? undefined : LANES[lane];
+    if (unit === undefined || directory === undefined || !/^[A-Za-z0-9._-]+$/u.test(unit)) {
+        console.error('usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]');
+        return 64;
+    }
+    if (!existsSync(TEMPLATE)) {
+        console.error(`brief: the template is missing at ${TEMPLATE}`);
+        return 64;
+    }
+    mkdirSync(directory, { recursive: true });
+    const path = resolveBriefPath(directory, unit);
+    const subject = readOption(argv, '--subject') ?? 'SHORT_SUBJECT';
+    const content = readFileSync(TEMPLATE, 'utf8')
+        .replace(/UNIT_ID/gu, unit)
+        .replace(/SHORT_SUBJECT/gu, subject);
+    writeFileSync(path, content);
+    console.log(JSON.stringify({ brief: path, template: TEMPLATE }));
+    return 0;
+}
+function checkBrief(path) {
+    if (!existsSync(path) || !statSync(path).isFile()) {
+        console.error(`brief: ${path} is not a file`);
+        return 64;
+    }
+    const paths = extractPaths(readFileSync(path, 'utf8'));
+    const missing = paths.filter((candidate) => !existsSync(resolve(candidate)));
+    console.log(JSON.stringify({ brief: path, checked: paths.length, missing }));
+    return missing.length === 0 ? 0 : 3;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--unit', '--lane', '--subject', '--check']);
+    if (missing.length > 0) {
+        console.error(`brief: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const check = readOption(argv, '--check');
+    if (check !== undefined && argv.includes('--unit')) {
+        console.error('brief: --check and --unit are two modes; name one');
+        return 64;
+    }
+    if (check !== undefined)
+        return checkBrief(check);
+    if (argv.includes('--unit'))
+        return writeBrief(argv);
+    console.error('usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT] | --check PATH');
+    return 64;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js

@@ -0,0 +1,95 @@
+// Check that every `file:line` citation in a report, verdict, or distillate resolves. Run from the
+// checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/cite.ts PATH [--root DIR] [--json]
+// A citation resolves when its path exists under the root (a path relative to the root resolves
+// first, and a backslash reads as a slash) and the line is within the file, where a trailing line
+// break ends the last line. A citation naming a bare filename that no root-relative
+// file matches resolves when exactly one file under the root carries that name, outside
+// node_modules, dist, tmp, .git, .orkestrel, and .idea. The summary lists every citation that does
+// not resolve, with the reason. Exit 0 when all resolve, 3 when any does not, 64 on usage.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, relative, resolve } from 'node:path';
+import { listFiles, normalizeSlashes, readMissingFlags, readOption } from "./helpers.js";
+const CITATION = /(?<![\w/\\.-])((?:\.{1,2}[/\\])?\.?[A-Za-z0-9_@][A-Za-z0-9_./\\@-]*\.[a-z]{1,5}):(\d+)(?:[-–](\d+))?(?![\w:])/gu;
+function indexBasenames(root) {
+    const index = new Map();
+    for (const file of listFiles(root)) {
+        const name = basename(file.path);
+        const paths = index.get(name) ?? [];
+        paths.push(normalizeSlashes(relative(root, file.path)));
+        index.set(name, paths);
+    }
+    return index;
+}
+function countLines(path) {
+    const text = readFileSync(path, 'utf8');
+    if (text === '')
+        return 0;
+    const lines = text.split(/\r\n|\n/);
+    // A trailing line break ends the last line rather than opening a phantom one.
+    return lines.at(-1) === '' ? lines.length - 1 : lines.length;
+}
+function resolveFile(root, file, index) {
+    const direct = resolve(root, normalizeSlashes(file));
+    if (existsSync(direct) && statSync(direct).isFile())
+        return { path: direct, reason: undefined };
+    if (/[/\\]/u.test(file))
+        return { path: undefined, reason: 'file does not exist' };
+    const candidates = index().get(basename(file)) ?? [];
+    const only = candidates.length === 1 ? candidates[0] : undefined;
+    if (only !== undefined)
+        return { path: resolve(root, only), reason: undefined };
+    if (candidates.length === 0)
+        return { path: undefined, reason: 'file does not exist' };
+    return { path: undefined, reason: `ambiguous basename: ${candidates.join(', ')}` };
+}
+function judgeLines(path, line, end, counts) {
+    const total = counts.get(path) ?? countLines(path);
+    counts.set(path, total);
+    if (line < 1 || line > total)
+        return `line ${line} is outside 1-${total}`;
+    if (end !== undefined && (end < line || end > total))
+        return `range end ${end} is outside ${line}-${total}`;
+    return undefined;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--root']);
+    if (missing.length > 0) {
+        console.error(`cite: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const root = readOption(argv, '--root') ?? process.cwd();
+    const path = argv.find((argument, position) => !argument.startsWith('--') && argv[position - 1] !== '--root');
+    if (path === undefined || !existsSync(path)) {
+        console.error('usage: cite.ts PATH [--root DIR] [--json]');
+        return 64;
+    }
+    let index;
+    const counts = new Map();
+    const unresolved = [];
+    let citations = 0;
+    for (const match of readFileSync(path, 'utf8').matchAll(CITATION)) {
+        const file = match[1];
+        const line = Number(match[2]);
+        const end = match[3] === undefined ? undefined : Number(match[3]);
+        if (file === undefined)
+            continue;
+        citations += 1;
+        const resolved = resolveFile(root, file, () => (index ??= indexBasenames(root)));
+        const reason = resolved.path === undefined
+            ? (resolved.reason ?? 'file does not exist')
+            : judgeLines(resolved.path, line, end, counts);
+        if (reason !== undefined)
+            unresolved.push({ citation: match[0], reason });
+    }
+    if (argv.includes('--json')) {
+        console.log(JSON.stringify({ path, root, citations, unresolved }));
+    }
+    else {
+        console.log(`cite: ${citations} citation(s) in ${path}, ${unresolved.length} unresolved`);
+        for (const entry of unresolved)
+            console.log(`cite: ${entry.citation} — ${entry.reason}`);
+    }
+    return unresolved.length === 0 ? 0 : 3;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/agents/skills/orkestrel-dispatch/scripts/helpers.js

@@ -0,0 +1,207 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Names the directories every tree walk in a skill script skips. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * Every skill script reads `--flag value` pairs: the first occurrence of a flag wins, a following
+ * value that opens with `--` is a missing value, and the `--flag=value` form is not read.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--journal`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index === -1 ? undefined : argv[index + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+}
+/**
+ * Names the value flags a caller gave with no value.
+ *
+ * @param argv - The arguments after the script path.
+ * @param names - The flags that take a value.
+ * @returns Each named flag that appears last or is followed by another flag, in argument order.
+ */
+export function readMissingFlags(argv, names) {
+    return names.filter((name) => argv.includes(name) && readOption(argv, name) === undefined);
+}
+/**
+ * Reads every value that follows a repeatable flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--range`.
+ * @returns The values in order, empty when the flag never appears.
+ */
+export function readOptions(argv, name) {
+    const values = [];
+    argv.forEach((argument, index) => {
+        const value = argv[index + 1];
+        if (argument === name && value !== undefined && !value.startsWith('--'))
+            values.push(value);
+    });
+    return values;
+}
+/**
+ * Reads the values that follow a flag up to the next flag.
+ *
+ * @param argv - The arguments after the script path.
+ * @param name - The flag, such as `--tree`.
+ * @returns The values between the flag and the next `--` argument, empty when the flag is absent.
+ */
+export function readList(argv, name) {
+    const index = argv.indexOf(name);
+    if (index === -1)
+        return [];
+    const values = [];
+    for (const argument of argv.slice(index + 1)) {
+        if (argument.startsWith('--'))
+            break;
+        values.push(argument);
+    }
+    return values;
+}
+/**
+ * Normalizes a host path to forward slashes.
+ *
+ * @param path - A host path.
+ * @returns The same path with every backslash replaced by a slash.
+ */
+export function normalizeSlashes(path) {
+    return path.split('\\').join('/');
+}
+/**
+ * Lists every regular file beneath a directory, skipping the directories skill scripts never read.
+ *
+ * @remarks
+ * A skipped name matches a directory at any depth, exactly and case-sensitively, so a
+ * `src/dist/` directory is skipped with the build output and a `Node_Modules/` directory is not.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: {@link SKIPPED_DIRECTORIES}.
+ * @returns Each file's forward-slash path and modification time, in walk order.
+ * @throws Thrown when `directory` does not exist or cannot be read; check `existsSync` first.
+ */
+export function listFiles(directory, skipped = SKIPPED_DIRECTORIES) {
+    const files = [];
+    const pending = [directory];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            break;
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (skipped.has(entry.name))
+                continue;
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (entry.isFile()) {
+                files.push({ path: normalizeSlashes(path), modified: statSync(path).mtimeMs });
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Reads the last non-empty line of a text as a JSON object.
+ *
+ * @param text - Text whose last line a script printed as JSON.
+ * @returns The parsed object, or undefined when the last line is not a JSON object.
+ */
+export function readJsonObject(text) {
+    const line = text
+        .split(/\r\n|\n/)
+        .filter((candidate) => candidate.trim() !== '')
+        .at(-1);
+    if (line === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.fromEntries(Object.entries(parsed));
+        }
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Parses a whole text as one JSON object.
+ *
+ * @param text - A JSON document, formatted or not, such as a manifest or `npm view --json` output.
+ * @returns The parsed object, or undefined when the text is not a JSON object.
+ */
+export function parseJsonRecord(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return Object.fromEntries(Object.entries(parsed));
+        }
+    }
+    catch { }
+    return undefined;
+}
+/**
+ * Reads a string member of a record.
+ *
+ * @param record - The record, or undefined.
+ * @param key - The member name.
+ * @returns The string, or undefined when the member is absent or not a string.
+ */
+export function readString(record, key) {
+    const value = record?.[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Reads a finite number member of a record.
+ *
+ * @param record - The record, or undefined.
+ * @param key - The member name.
+ * @returns The number, or undefined when the member is absent, not a number, or not finite.
+ */
+export function readNumber(record, key) {
+    const value = record?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Resolves the npm command for this host.
+ *
+ * @remarks
+ * The `npm-cli.js` entry beside the running Node binary spawns without a shell on every host; the
+ * `npm` shim on Windows is a `.cmd` file that needs one, so that path is the fallback alone.
+ *
+ * @returns The file to spawn, the arguments that precede npm's own, and whether a shell is needed.
+ */
+export function resolveNpm() {
+    const cli = join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    if (existsSync(cli))
+        return { file: process.execPath, prefix: [cli], shell: false };
+    return { file: 'npm', prefix: [], shell: process.platform === 'win32' };
+}
+/**
+ * Runs npm with the given arguments and returns the finished child.
+ *
+ * @param args - The npm arguments, such as `['view', '@orkestrel/scaffold', 'version']`.
+ * @param cwd - The working directory. Default: the current directory.
+ * @returns The spawn result with `utf8` stdout and stderr.
+ */
+export function runNpm(args, cwd) {
+    const npm = resolveNpm();
+    return spawnSync(npm.file, [...npm.prefix, ...args], {
+        encoding: 'utf8',
+        windowsHide: true,
+        shell: npm.shell,
+        maxBuffer: 64 * 1024 * 1024,
+        ...(cwd === undefined ? {} : { cwd }),
+    });
+}