@orkestrel/scaffold 0.0.107 → 0.0.109

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

@@ -0,0 +1,280 @@
+// Run a plan of commands in order and journal each one. Run from the checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/chain.ts --plan FILE.json --journal DIR
+// The plan is a JSON array of steps, each `{ "name": "...", "command": "...", "args": ["..."] }`
+// with an optional `"cwd"` (a directory, relative to the working directory) and `"env"` (a record
+// of strings laid over this process's environment). A step name is letters, digits, dots,
+// underscores, and hyphens, opens with a letter or digit, and is unique in the plan. Each step runs
+// with no shell and closed stdin, in plan order, with its standard output and standard error
+// written together to `DIR/<name>.txt`; the script prints one `name exit=N durationMs=N` line per
+// step and stops at the first step that does not exit 0. Because no shell runs, a command that is a
+// Windows `.cmd` shim, such as `npm`, starts only through the interpreter it wraps. A step that
+// must not stop the chain belongs in a second plan; launch the chain itself through `launch.ts`
+// for a cap. The script refuses a flag it does not read, the `--flag=value` form included.
+// Exit 0 when every step exited 0, the failing step's exit code when one did not, 2 when a step
+// cannot start, 64 on usage.
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS = ['--plan', '--journal'];
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = VALUE_FLAGS;
+/** Holds the usage line printed when a call names no plan or no journal. */
+export const USAGE = 'usage: chain.ts --plan FILE.json --journal DIR';
+/** Matches a step name that is safe as a journal file name. */
+export const STEP_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * 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 `--plan`.
+ * @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);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
+ * scan.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * Checks whether a value is a non-null, non-array object.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is an object other than null or an array; false otherwise.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Checks whether a value is an array of strings.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is an array whose every member is a string; false otherwise.
+ */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((member) => typeof member === 'string');
+}
+/**
+ * Checks whether a value is a record whose every member is a string.
+ *
+ * @param value - The value to inspect.
+ * @returns True if the value is a record with only string members; false otherwise.
+ */
+export function isStringRecord(value) {
+    return isRecord(value) && Object.values(value).every((member) => typeof member === 'string');
+}
+/**
+ * Quotes an untrusted text for a diagnostic, JSON-encoded and cut to a bounded length.
+ *
+ * @param text - The text to quote.
+ * @returns The JSON string literal of the text, ending in an ellipsis inside the quotes when cut.
+ */
+export function quote(text) {
+    return JSON.stringify(text.length > 80 ? `${text.slice(0, 80)}…` : text);
+}
+/**
+ * Lists what is wrong with one plan entry.
+ *
+ * @param entry - The parsed JSON value at one position of the plan.
+ * @param position - The entry's zero-based position, named in each problem.
+ * @returns Each problem in the entry, empty when the entry is a step.
+ */
+export function readStepProblems(entry, position) {
+    const where = `step ${String(position + 1)}`;
+    if (!isRecord(entry))
+        return [`${where} is not an object`];
+    const known = ['name', 'command', 'args', 'cwd', 'env'];
+    const unexpected = Object.keys(entry).filter((key) => !known.includes(key));
+    return [
+        ...(typeof entry.name === 'string' && STEP_NAME.test(entry.name)
+            ? []
+            : [
+                `${where} "name" must be letters, digits, dots, underscores, and hyphens, opening with a letter or digit`,
+            ]),
+        ...(typeof entry.command === 'string' && entry.command !== ''
+            ? []
+            : [`${where} "command" must be a non-empty string`]),
+        ...(isStringArray(entry.args) ? [] : [`${where} "args" must be an array of strings`]),
+        ...(entry.cwd === undefined || (typeof entry.cwd === 'string' && entry.cwd !== '')
+            ? []
+            : [`${where} "cwd" must be a non-empty string when present`]),
+        ...(entry.env === undefined || isStringRecord(entry.env)
+            ? []
+            : [`${where} "env" must be a record of strings when present`]),
+        ...unexpected.map((key) => `${where} carries the unexpected key ${quote(key)}`),
+    ];
+}
+/**
+ * Reads a plan from its JSON text.
+ *
+ * @param text - The plan file's text.
+ * @returns The steps in order when the plan is valid, and every problem otherwise: not JSON, not an
+ * array, empty, a malformed step, or a name used twice.
+ */
+export function parsePlan(text) {
+    const parsed = parseJson(text);
+    if (!Array.isArray(parsed))
+        return { steps: [], problems: ['the plan is not a JSON array of steps'] };
+    if (parsed.length === 0)
+        return { steps: [], problems: ['the plan holds no step'] };
+    const problems = parsed.flatMap((entry, position) => readStepProblems(entry, position));
+    const names = parsed.flatMap((entry) => isRecord(entry) && typeof entry.name === 'string' ? [entry.name] : []);
+    const repeated = [...new Set(names.filter((name, index) => names.indexOf(name) !== index))];
+    const all = [
+        ...problems,
+        ...repeated.map((name) => `the name ${quote(name)} is used by more than one step`),
+    ];
+    if (all.length > 0)
+        return { steps: [], problems: all };
+    return { steps: parsed.flatMap((entry) => readStep(entry)), problems: [] };
+}
+/**
+ * Parses a JSON text without throwing.
+ *
+ * @param text - The text to parse.
+ * @returns The parsed value, or undefined when the text is not JSON.
+ */
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reads a validated plan entry as a step.
+ *
+ * @param entry - A plan entry that `readStepProblems` found no problem in.
+ * @returns The step as a one-member list, or an empty list when the entry is not a valid step.
+ */
+export function readStep(entry) {
+    if (!isRecord(entry))
+        return [];
+    const { name, command, args, cwd, env } = entry;
+    if (typeof name !== 'string' || typeof command !== 'string' || !isStringArray(args))
+        return [];
+    return [
+        {
+            name,
+            command,
+            args,
+            cwd: typeof cwd === 'string' ? cwd : undefined,
+            env: isStringRecord(env) ? env : {},
+        },
+    ];
+}
+/**
+ * Runs one step with no shell, its output and errors written together to a file.
+ *
+ * @param step - The step to run.
+ * @param output - The file that receives the step's standard output and standard error.
+ * @returns The exit code, or undefined with the reason when the command cannot start or a signal
+ * ended it; and the duration.
+ */
+export function runStep(step, output) {
+    const started = Date.now();
+    const descriptor = openSync(output, 'w');
+    try {
+        const result = spawnSync(step.command, step.args, {
+            cwd: step.cwd === undefined ? undefined : resolve(step.cwd),
+            env: { ...process.env, ...step.env },
+            stdio: ['ignore', descriptor, descriptor],
+            windowsHide: true,
+            shell: false,
+        });
+        const error = result.error?.message ?? (result.signal === null ? undefined : `ended by ${result.signal}`);
+        return {
+            exit: error === undefined ? (result.status ?? undefined) : undefined,
+            error,
+            durationMs: Date.now() - started,
+        };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+/**
+ * Formats the line printed for a finished step.
+ *
+ * @param step - The step.
+ * @param finish - How the step ended.
+ * @returns `name exit=N durationMs=N`, with `exit=none` and the reason when it never exited.
+ */
+export function formatStep(step, finish) {
+    const exit = finish.exit === undefined ? 'none' : String(finish.exit);
+    const reason = finish.error === undefined ? '' : ` error=${quote(finish.error)}`;
+    return `${step.name} exit=${exit} durationMs=${String(finish.durationMs)}${reason}`;
+}
+/**
+ * Runs the script on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when every step exited 0, the failing step's exit code, 2 when a step
+ * cannot start, 64 on usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`chain: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
+        return 64;
+    }
+    const missing = readMissingFlags(argv, VALUE_FLAGS);
+    if (missing.length > 0) {
+        console.error(`chain: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const path = readOption(argv, '--plan');
+    const journal = readOption(argv, '--journal');
+    if (path === undefined || journal === undefined || !existsSync(path)) {
+        console.error(USAGE);
+        return 64;
+    }
+    const plan = parsePlan(readFileSync(path, 'utf8'));
+    if (plan.problems.length > 0) {
+        console.error(`chain: ${quote(path)} is not a valid plan: ${plan.problems.join('; ')}`);
+        return 64;
+    }
+    mkdirSync(journal, { recursive: true });
+    for (const step of plan.steps) {
+        const finish = runStep(step, join(journal, `${step.name}.txt`));
+        console.log(formatStep(step, finish));
+        if (finish.exit === undefined)
+            return 2;
+        if (finish.exit !== 0)
+            return finish.exit;
+    }
+    return 0;
+}
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    process.exitCode = main(process.argv.slice(2));
+}

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

@@ -6,18 +6,146 @@
 // 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) {
+// not resolve, with the reason. The script refuses a flag it does not read, the `--flag=value` form
+// included. Exit 0 when all resolve, 3 when any does not, 64 on usage.
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+/** Matches one `file:line` or `file:line-line` citation in a text. */
+export const CITATION = /(?<![\w/\\.-])((?:\.{1,2}[/\\])?\.?[A-Za-z0-9_@][A-Za-z0-9_./\\@-]*\.[a-z]{1,5}):(\d+)(?:[-–](\d+))?(?![\w:])/gu;
+/** Names the directories a tree walk skips. */
+export const SKIPPED_DIRECTORIES = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'tmp',
+    '.orkestrel',
+    '.idea',
+]);
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS = ['--root'];
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = [...VALUE_FLAGS, '--json'];
+/** Holds the usage line printed when a call names no report. */
+export const USAGE = 'usage: cite.ts PATH [--root DIR] [--json]';
+/**
+ * Reads the value that follows a flag.
+ *
+ * @remarks
+ * 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 `--root`.
+ * @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);
+}
+/**
+ * Names the flags a caller gave that the script does not read.
+ *
+ * @remarks
+ * A `--flag=value` argument is unknown, because the script reads no such form. A bare `--` ends the
+ * scan.
+ *
+ * @param argv - The arguments after the script path.
+ * @param flags - Every flag the script reads, value flags and switches alike.
+ * @returns Each argument that opens with `--` and is not a read flag, in argument order.
+ */
+export function readUnknownFlags(argv, flags) {
+    const end = argv.indexOf('--');
+    return (end === -1 ? argv : argv.slice(0, end)).filter((argument) => argument.startsWith('--') && !flags.includes(argument));
+}
+/**
+ * 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 the script never reads.
+ *
+ * @remarks
+ * A skipped name matches a directory at any depth, exactly and case-sensitively.
+ *
+ * @param directory - The directory to walk.
+ * @param skipped - The directory names to skip. Default: the 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.
+ */
+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;
+}
+/**
+ * Extracts every citation a text carries.
+ *
+ * @param text - The report text.
+ * @returns Each citation in text order, with its file, its line, and the end of a range.
+ */
+export function extractCitations(text) {
+    return [...text.matchAll(CITATION)].flatMap((match) => match[1] === undefined
+        ? []
+        : [
+            {
+                citation: match[0],
+                file: match[1],
+                line: Number(match[2]),
+                end: match[3] === undefined ? undefined : Number(match[3]),
+            },
+        ]);
+}
+/**
+ * Indexes every file under a root by its basename.
+ *
+ * @param root - The directory to walk.
+ * @returns Each basename mapped to the root-relative forward-slash paths that carry it.
+ */
+export function indexBasenames(root) {
     return new Map([...Map.groupBy(listFiles(root), (file) => basename(file.path))].map(([name, files]) => [
         name,
         files.map((file) => normalizeSlashes(relative(root, file.path))),
     ]));
 }
-function countLines(path) {
+/**
+ * Counts the lines of a file.
+ *
+ * @param path - The file to read.
+ * @returns The number of lines, where a trailing line break ends the last line and an empty file has none.
+ */
+export function countLines(path) {
     const text = readFileSync(path, 'utf8');
     if (text === '')
         return 0;
@@ -25,15 +153,36 @@ function countLines(path) {
     // A trailing line break ends the last line rather than opening a phantom one.
     return lines.at(-1) === '' ? lines.length - 1 : lines.length;
 }
-function resolveDirect(root, file) {
+/**
+ * Resolves a citation's file directly under the root.
+ *
+ * @param root - The directory a citation's path is relative to.
+ * @param file - The cited path, a backslash read as a slash.
+ * @returns The absolute path of the file, or undefined when no regular file sits there.
+ */
+export function resolveDirect(root, file) {
     const direct = resolve(root, normalizeSlashes(file));
     return existsSync(direct) && statSync(direct).isFile() ? direct : undefined;
 }
-// A bare filename that no root-relative file matches is the one citation the basename index serves.
-function needsIndex(root, file) {
+/**
+ * Checks whether a citation can resolve only through the basename index.
+ *
+ * @param root - The directory a citation's path is relative to.
+ * @param file - The cited path.
+ * @returns True if no root-relative file matches and the path is a bare filename; false otherwise.
+ */
+export function needsIndex(root, file) {
     return resolveDirect(root, file) === undefined && !/[/\\]/u.test(file);
 }
-function resolveFile(root, file, index) {
+/**
+ * Resolves a citation's file, directly or through the basename index.
+ *
+ * @param root - The directory a citation's path is relative to.
+ * @param file - The cited path.
+ * @param index - The basename index, or undefined when no citation needed one.
+ * @returns The resolved absolute path, or the reason the file did not resolve.
+ */
+export function resolveFile(root, file, index) {
     const direct = resolveDirect(root, file);
     if (direct !== undefined)
         return { path: direct, reason: undefined };
@@ -47,7 +196,16 @@ function resolveFile(root, file, index) {
         return { path: undefined, reason: 'file does not exist' };
     return { path: undefined, reason: `ambiguous basename: ${candidates.join(', ')}` };
 }
-function judgeLines(path, line, end, counts) {
+/**
+ * Judges whether a cited line or range lies within a file.
+ *
+ * @param path - The resolved file.
+ * @param line - The cited line.
+ * @param end - The end of a cited range, or undefined for a single line.
+ * @param counts - The line counts already read, by file.
+ * @returns The reason the line or range is outside the file, or undefined when it is inside.
+ */
+export function judgeLines(path, line, end, counts) {
     const total = counts.get(path) ?? countLines(path);
     if (line < 1 || line > total)
         return `line ${line} is outside 1-${total}`;
@@ -55,8 +213,19 @@ function judgeLines(path, line, end, counts) {
         return `range end ${end} is outside ${line}-${total}`;
     return undefined;
 }
-function main(argv) {
-    const missing = readMissingFlags(argv, ['--root']);
+/**
+ * Runs the script on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 when every citation resolves, 3 when one does not, 64 on usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    if (unknown.length > 0) {
+        console.error(`cite: ${unknown.join(', ')} is not a flag this script reads; ${USAGE}`);
+        return 64;
+    }
+    const missing = readMissingFlags(argv, VALUE_FLAGS);
     if (missing.length > 0) {
         console.error(`cite: ${missing.join(', ')} given with no value`);
         return 64;
@@ -64,19 +233,10 @@ function main(argv) {
     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]');
+        console.error(USAGE);
         return 64;
     }
-    const named = [...readFileSync(path, 'utf8').matchAll(CITATION)].flatMap((match) => match[1] === undefined
-        ? []
-        : [
-            {
-                citation: match[0],
-                file: match[1],
-                line: Number(match[2]),
-                end: match[3] === undefined ? undefined : Number(match[3]),
-            },
-        ]);
+    const named = extractCitations(readFileSync(path, 'utf8'));
     const citations = named.length;
     // The basename index walks the root, so it is built once and only when a citation needs it.
     const index = named.some(({ file }) => needsIndex(root, file)) ? indexBasenames(root) : undefined;
@@ -105,4 +265,6 @@ function main(argv) {
     }
     return unresolved.length === 0 ? 0 : 3;
 }
-process.exitCode = main(process.argv.slice(2));
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+    process.exitCode = main(process.argv.slice(2));
+}