@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts

@@ -6,32 +6,183 @@
 // 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.ts'
+// 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'
 
-const CITATION =
+/** 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
 
-interface Unresolved {
+/** Names the directories a tree walk skips. */
+export const SKIPPED_DIRECTORIES: ReadonlySet<string> = new Set([
+	'node_modules',
+	'.git',
+	'dist',
+	'tmp',
+	'.orkestrel',
+	'.idea',
+])
+
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS: readonly string[] = ['--root']
+
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--json']
+
+/** Holds the usage line printed when a call names no report. */
+export const USAGE = 'usage: cite.ts PATH [--root DIR] [--json]'
+
+/** Describes one citation that did not resolve and why. */
+export interface Unresolved {
 	readonly citation: string
 	readonly reason: string
 }
 
-interface Resolution {
+/** Describes where a citation's file resolved, or why it did not. */
+export interface Resolution {
 	readonly path: string | undefined
 	readonly reason: string | undefined
 }
 
-interface Citation {
+/** Describes one citation read from a text: its file, its line, and the end of its range. */
+export interface Citation {
 	readonly citation: string
 	readonly file: string
 	readonly line: number
 	readonly end: number | undefined
 }
 
-function indexBasenames(root: string): ReadonlyMap<string, readonly string[]> {
+/** Describes one file a tree walk found, with the modification time it carries. */
+export interface WalkedFile {
+	readonly path: string
+	readonly modified: number
+}
+
+/**
+ * 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: readonly string[], name: string): string | undefined {
+	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: readonly string[],
+	names: readonly string[],
+): readonly string[] {
+	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: readonly string[],
+	flags: readonly string[],
+): readonly string[] {
+	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: string): string {
+	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: string,
+	skipped: ReadonlySet<string> = SKIPPED_DIRECTORIES,
+): readonly WalkedFile[] {
+	const files: WalkedFile[] = []
+	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: string): readonly Citation[] {
+	return [...text.matchAll(CITATION)].flatMap((match): Citation[] =>
+		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: string): ReadonlyMap<string, readonly string[]> {
 	return new Map(
 		[...Map.groupBy(listFiles(root), (file) => basename(file.path))].map(([name, files]) => [
 			name,
@@ -40,7 +191,13 @@ function indexBasenames(root: string): ReadonlyMap<string, readonly string[]> {
 	)
 }
 
-function countLines(path: string): number {
+/**
+ * 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: string): number {
 	const text = readFileSync(path, 'utf8')
 	if (text === '') return 0
 	const lines = text.split(/\r\n|\n/)
@@ -48,17 +205,38 @@ function countLines(path: string): number {
 	return lines.at(-1) === '' ? lines.length - 1 : lines.length
 }
 
-function resolveDirect(root: string, file: string): string | undefined {
+/**
+ * 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: string, file: string): string | undefined {
 	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: string, file: string): boolean {
+/**
+ * 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: string, file: string): boolean {
 	return resolveDirect(root, file) === undefined && !/[/\\]/u.test(file)
 }
 
-function resolveFile(
+/**
+ * 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: string,
 	file: string,
 	index: ReadonlyMap<string, readonly string[]> | undefined,
@@ -73,7 +251,16 @@ function resolveFile(
 	return { path: undefined, reason: `ambiguous basename: ${candidates.join(', ')}` }
 }
 
-function judgeLines(
+/**
+ * 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: string,
 	line: number,
 	end: number | undefined,
@@ -86,8 +273,19 @@ function judgeLines(
 	return undefined
 }
 
-function main(argv: readonly string[]): number {
-	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: readonly string[]): number {
+	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
@@ -97,21 +295,10 @@ function main(argv: readonly string[]): number {
 		(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): Citation[] =>
-		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
@@ -142,4 +329,6 @@ function main(argv: readonly string[]): number {
 	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))
+}

package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts

@@ -2,7 +2,8 @@
 //   node .agents/skills/orkestrel-dispatch/scripts/launch.ts --journal tmp/codex/UNIT.jsonl --errors tmp/codex/UNIT.err --cap 1500 [--status] -- codex exec --json ...
 // The command's stdout goes to --journal and its stderr to --errors; stdin is closed. Arguments after
 // `--` pass to the command verbatim, so no shell quoting is involved. --cap is in seconds: when it
-// expires the process tree is killed and the errors file records `capped=true`. A fractional cap
+// expires the process tree is killed and the errors file records `capped=true`; a command that had
+// already exited when the cap expired is not capped. A fractional cap
 // truncates to whole milliseconds, with 1 ms the least. --status records
 // `git status --porcelain` before and after beside the journal, which is how a read-only lane's
 // containment is checked. Stdout carries up to two JSON lines. The spawn line
@@ -11,31 +12,133 @@
 // removed before the spawn, so neither appears when the command cannot start. The summary line
 // prints last, after the command exits, and the errors file ends with `exit=<code>`. At the cap,
 // Windows kills the process tree; any other host kills the command alone, not its descendants.
-// The launcher's own flags are read before `--` alone. Exit: the command's code; 124 when capped;
+// The launcher's own flags are read before `--` alone, and it refuses a flag it does not read there,
+// the `--flag=value` form included. Exit: the command's code; 124 when capped;
 // 127 when the command could not start (the errors file names why); 64 on usage, including a
 // journal and errors path that are the same file and a cap that is not a number of seconds from 0
 // to 2147483.
+import type { ChildProcess } from 'node:child_process'
 import { spawn, spawnSync } from 'node:child_process'
-import { appendFileSync, closeSync, mkdirSync, openSync, rmSync, writeFileSync } from 'node:fs'
+import {
+	appendFileSync,
+	closeSync,
+	mkdirSync,
+	openSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
 import { dirname } from 'node:path'
-import { readMissingFlags, readOption } from './helpers.ts'
 
-// The longest wait a Node timer holds is 2147483647 ms; floored to whole seconds, a longer cap would
-// throw from `AbortSignal.timeout` after the spawn or clamp to 1 ms and kill the command at once.
-const MAX_CAP_SECONDS = 2_147_483
+/**
+ * Holds the longest cap in whole seconds.
+ *
+ * @remarks
+ * The longest wait a Node timer holds is 2147483647 ms; floored to whole seconds, a longer cap would
+ * throw from `AbortSignal.timeout` after the spawn or clamp to 1 ms and kill the command at once.
+ */
+export const MAX_CAP_SECONDS = 2_147_483
 
-// `AbortSignal.timeout` throws on a fractional delay, which `setTimeout` truncates and raises to 1 ms
-// from below, so the cap takes that form before the command starts.
-function computeCapMilliseconds(cap: number): number {
+/** Lists the flags that take a value. */
+export const VALUE_FLAGS: readonly string[] = ['--journal', '--errors', '--cap']
+
+/** Lists every flag the launcher reads before the separator, value flags and switches alike. */
+export const FLAGS: readonly string[] = [...VALUE_FLAGS, '--status']
+
+/** Describes how the command ended: its code, its signal, or the reason it could not start. */
+export interface Exit {
+	readonly code: number | null
+	readonly signal: NodeJS.Signals | null
+	readonly error: string | undefined
+}
+
+/**
+ * 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 `--journal`.
+ * @returns The value after the flag, or undefined when the flag is absent, last, or followed by
+ * another flag.
+ */
+export function readOption(argv: readonly string[], name: string): string | undefined {
+	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: readonly string[],
+	names: readonly string[],
+): readonly string[] {
+	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, so the command after it keeps every argument.
+ *
+ * @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: readonly string[],
+	flags: readonly string[],
+): readonly string[] {
+	const end = argv.indexOf('--')
+	return (end === -1 ? argv : argv.slice(0, end)).filter(
+		(argument) => argument.startsWith('--') && !flags.includes(argument),
+	)
+}
+
+/**
+ * Computes the cap in whole milliseconds that the timer takes.
+ *
+ * @remarks
+ * `AbortSignal.timeout` throws on a fractional delay, which `setTimeout` truncates and raises to 1 ms
+ * from below, so the cap takes that form before the command starts.
+ *
+ * @param cap - The cap in seconds.
+ * @returns The whole milliseconds, at least 1.
+ */
+export function computeCapMilliseconds(cap: number): number {
 	return Math.max(1, Math.trunc(cap * 1000))
 }
 
-function readStatus(): string {
-	const result = spawnSync('git', ['status', '--porcelain'], { encoding: 'utf8' })
+/**
+ * Reads the working tree's `git status --porcelain` output.
+ *
+ * @param cwd - The directory to read the status in. Default: the current directory.
+ * @returns The porcelain text, or a `git status failed:` line carrying git's own message.
+ */
+export function readGitStatus(cwd?: string): string {
+	const result = spawnSync('git', ['status', '--porcelain'], {
+		encoding: 'utf8',
+		...(cwd === undefined ? {} : { cwd }),
+	})
 	return result.status === 0 ? result.stdout : `git status failed: ${result.stderr}`
 }
 
-function killTree(pid: number): void {
+/**
+ * Kills a process and every process it started, at once and without a chance to clean up.
+ *
+ * @param pid - The process to kill. A process that is already gone is not an error.
+ */
+export function forceKillTree(pid: number): void {
 	if (process.platform === 'win32') {
 		spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
 		return
@@ -45,18 +148,39 @@ function killTree(pid: number): void {
 	} catch {}
 }
 
-interface Exit {
-	readonly code: number | null
-	readonly signal: NodeJS.Signals | null
-	readonly error: string | undefined
+/**
+ * Ends a command that is still running and aborts the controller to say the cap ended it.
+ *
+ * @remarks
+ * The cap's timer cannot be cleared, so it can elapse after the command exited on its own. The
+ * controller aborts only when the command is still running at that moment, which is how the run
+ * records that the cap, and not the command, ended it; a reused pid is never this command's.
+ *
+ * @param child - The running command.
+ * @param ended - The controller that aborts when the cap ended the command.
+ */
+export function endRunning(child: ChildProcess, ended: AbortController): void {
+	if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+		ended.abort()
+		forceKillTree(child.pid)
+	}
 }
 
-function startCommand(
+/**
+ * Starts the command with its output sent to the journal and errors files.
+ *
+ * @param command - The executable.
+ * @param args - The command's arguments, passed verbatim.
+ * @param journal - The open journal file descriptor that receives stdout.
+ * @param errors - The open errors file descriptor that receives stderr.
+ * @returns The child process, or the failure when the spawn throws.
+ */
+export function startCommand(
 	command: string,
 	args: readonly string[],
 	journal: number,
 	errors: number,
-): ReturnType<typeof spawn> | Exit {
+): ChildProcess | Exit {
 	try {
 		return spawn(command, args, { stdio: ['ignore', journal, errors], windowsHide: true })
 	} catch (error) {
@@ -68,17 +192,36 @@ function startCommand(
 	}
 }
 
-function waitForExit(child: ReturnType<typeof spawn>): Promise<Exit> {
+/**
+ * Waits for a started command to close.
+ *
+ * @param child - The started command.
+ * @returns How it ended: its code and signal, or the error that stopped it.
+ */
+export function waitForExit(child: ChildProcess): Promise<Exit> {
 	return new Promise((resolve) => {
 		child.on('error', (error) => resolve({ code: null, signal: null, error: error.message }))
 		child.on('close', (code, signal) => resolve({ code, signal, error: undefined }))
 	})
 }
 
-async function main(argv: readonly string[]): Promise<number> {
+/**
+ * Runs the launcher on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: the command's, 124 when capped, 127 when it could not start, 64 on usage.
+ */
+export async function main(argv: readonly string[]): Promise<number> {
 	const separator = argv.indexOf('--')
 	// The launcher's own flags end at the separator; everything after it belongs to the command.
 	const own = separator === -1 ? argv : argv.slice(0, separator)
+	const unknown = readUnknownFlags(argv, FLAGS)
+	if (unknown.length > 0) {
+		console.error(
+			`launch: ${unknown.join(', ')} is not a flag this launcher reads before --; flags: ${FLAGS.join(' ')}`,
+		)
+		return 64
+	}
 	const journal = readOption(own, '--journal')
 	const errors = readOption(own, '--errors')
 	const cap =
@@ -106,7 +249,7 @@ async function main(argv: readonly string[]): Promise<number> {
 	const capMilliseconds = cap > 0 ? computeCapMilliseconds(cap) : undefined
 	mkdirSync(dirname(journal), { recursive: true })
 	mkdirSync(dirname(errors), { recursive: true })
-	if (status) writeFileSync(`${journal}.status-before.txt`, readStatus())
+	if (status) writeFileSync(`${journal}.status-before.txt`, readGitStatus())
 	const journalFd = openSync(journal, 'w')
 	const errorsFd = openSync(errors, 'w')
 	rmSync(`${journal}.pid`, { force: true })
@@ -117,9 +260,9 @@ async function main(argv: readonly string[]): Promise<number> {
 		writeFileSync(`${journal}.pid`, `${child.pid}\n`)
 		console.log(JSON.stringify({ pid: child.pid, journal, errors }))
 	}
-	// The signal aborts once the cap elapses, so whether it aborted is whether the cap ended the run.
-	// The timer cannot be cleared, so a cap that elapses after the child exited kills nothing: a
-	// reused pid is not this command's.
+	// The ended controller aborts only when the cap found the command still running, so whether it
+	// aborted is whether the cap ended the run.
+	const ended = new AbortController()
 	const deadline =
 		child === undefined || capMilliseconds === undefined
 			? undefined
@@ -127,14 +270,12 @@ async function main(argv: readonly string[]): Promise<number> {
 	deadline?.addEventListener(
 		'abort',
 		() => {
-			if (child?.pid !== undefined && child.exitCode === null && child.signalCode === null) {
-				killTree(child.pid)
-			}
+			if (child !== undefined) endRunning(child, ended)
 		},
 		{ once: true },
 	)
 	const exit = 'error' in launched ? launched : await waitForExit(launched)
-	const capped = deadline?.aborted === true
+	const capped = ended.signal.aborted
 	closeSync(journalFd)
 	closeSync(errorsFd)
 	const durationMs = Date.now() - started
@@ -142,7 +283,7 @@ async function main(argv: readonly string[]): Promise<number> {
 		errors,
 		`${exit.error === undefined ? '' : `launch: the command could not start: ${exit.error}\n`}\nexit=${exit.error === undefined ? (exit.code ?? 'null') : '127'} signal=${exit.signal ?? 'none'} capped=${capped} duration_ms=${durationMs}\n`,
 	)
-	if (status) writeFileSync(`${journal}.status-after.txt`, readStatus())
+	if (status) writeFileSync(`${journal}.status-after.txt`, readGitStatus())
 	console.log(
 		JSON.stringify({
 			pid: child?.pid,
@@ -159,6 +300,8 @@ async function main(argv: readonly string[]): Promise<number> {
 	return capped ? 124 : (exit.code ?? 1)
 }
 
-main(process.argv.slice(2)).then((code) => {
-	process.exitCode = code
-})
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === import.meta.filename) {
+	main(process.argv.slice(2)).then((code) => {
+		process.exitCode = code
+	})
+}