@orkestrel/scaffold 0.0.108 → 0.0.109

package/dist/agents/skills/orkestrel-scout/scripts/map.js

@@ -1,28 +1,172 @@
 // Map terrain before a brief, an absorption lane, or a rename. Run from the checkout root:
 //   node .agents/skills/orkestrel-scout/scripts/map.ts --tree PATH... [--headings PATH...] [--frontmatter PATH...] [--exports PATH...] [--census TERM...] [--refs PATH] [--anchors PATH...] [--paths a,b] [--ignore-case] [--json] [--out FILE]
 // --tree lists every file under each path with its line count and size. --headings lists every
-// Markdown heading with its line. --frontmatter lists every key of a Markdown frontmatter block, a
-// TOML file, or a YAML file with its whole value, a nested key dotted under its parents
-// (`interface.default_prompt`) and a TOML key under its table. --exports lists every `export`
-// declaration line in a TypeScript file (a text reading, not the compiler's). --census lists every line carrying a term. --refs lists
+// Markdown heading with its line; a heading inside a fenced block is no heading, where a fence
+// opens with a run of three or more backticks or tildes indented up to three spaces and closes with
+// a run of the same character at least as long. --frontmatter lists every key of a Markdown
+// frontmatter block, a TOML file, or a YAML file with its whole value, a nested key dotted under its
+// parents (`interface.default_prompt`) and a TOML key under its table. --exports lists every
+// `export` declaration line in a TypeScript file (a text reading, not the compiler's). --census
+// lists every line carrying a term. --refs lists
 // every line naming a path or its basename. --anchors lists every `§ Heading` reference whose
 // heading the named file, or the same file, does not carry. Walks skip node_modules, .git, dist,
 // tmp, .orkestrel, .idea, and host.json; --paths narrows a census or refs walk. Modes combine, each
 // printing its section; --json prints one object; --out writes the output to FILE instead of the
 // terminal. Give each flag once; a later duplicate is not read. A value that opens with `--` is a
-// missing value, so census a custom property without its leading dashes. Exit 0, or 64 when no
-// mode is given or a flag is given with no value.
-import { existsSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
-import { basename, dirname } from 'node:path';
-import { listFiles, normalizeSlashes, readList, readMissingFlags, readOption, } from "../../orkestrel-dispatch/scripts/helpers.js";
-const EXPORT = /^export\s+(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(function\*?|const|let|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/u;
-const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/u;
-const ANCHOR = /(?:`([^`\n]+\.md)`\s*)?§\s*"?([^"`\n|;,.)]+?)"?(?=\s*(?:[,.;)|]|\s(?:and|or|names|fixes|owns|states|binds|governs|decides|before|after)\b|$))/gu;
-const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
-function isText(path) {
+// missing value, so census a custom property without its leading dashes. The script refuses a flag
+// it does not read, the `--flag=value` form included, and names every unknown flag and every flag
+// given with no value in one refusal. Exit 0, or 64 when no mode is given, a flag is given with no
+// value, or a flag is unknown.
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/** Matches an `export` declaration line and captures its kind and name. */
+export const EXPORT = /^export\s+(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(function\*?|const|let|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/u;
+/** Matches a Markdown heading line and captures its marker and text. */
+export const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/u;
+/** Matches a `§ Heading` reference, with the backticked Markdown path that may precede it. */
+export const ANCHOR = /(?:`([^`\n]+\.md)`\s*)?§\s*"?([^"`\n|;,.)]+?)"?(?=\s*(?:[,.;)|]|\s(?:and|or|names|fixes|owns|states|binds|governs|decides|before|after)\b|$))/gu;
+/** Matches the extensions of the binary files a walk reads as no text. */
+export const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
+/** Matches a line that can open or close a code fence and captures its run of backticks or tildes. */
+export const FENCE = /^ {0,3}(`{3,}|~{3,})/u;
+/** 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 = [
+    '--tree',
+    '--headings',
+    '--frontmatter',
+    '--exports',
+    '--census',
+    '--refs',
+    '--anchors',
+    '--paths',
+    '--out',
+];
+/** Lists every flag the script reads, value flags and switches alike. */
+export const FLAGS = [...VALUE_FLAGS, '--ignore-case', '--json'];
+/** Holds the usage line printed when a call names no mode. */
+export const USAGE = 'usage: map.ts [--tree PATH...] [--headings PATH...] [--frontmatter PATH...] [--exports PATH...] [--census TERM...] [--refs PATH] [--anchors PATH...] [--paths a,b] [--ignore-case] [--json] [--out FILE]';
+/**
+ * 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 `--paths`.
+ * @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));
+}
+/**
+ * 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 rest = argv.slice(index + 1);
+    const end = rest.findIndex((argument) => argument.startsWith('--'));
+    return end === -1 ? rest : rest.slice(0, end);
+}
+/**
+ * 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;
+}
+/**
+ * Checks whether a walk reads a file as text.
+ *
+ * @param path - The file path.
+ * @returns True if the path carries no binary extension and is not `host.json`; false otherwise.
+ */
+export function isText(path) {
     return !BINARY.test(path) && basename(path) !== 'host.json';
 }
-function expandPaths(paths) {
+/**
+ * Expands paths into the files they name.
+ *
+ * @param paths - Files and directories; an absent path names nothing.
+ * @returns Each file, a directory expanded to the files beneath it.
+ */
+export function expandPaths(paths) {
     return paths.flatMap((path) => {
         if (!existsSync(path))
             return [];
@@ -31,10 +175,22 @@ function expandPaths(paths) {
         return [normalizeSlashes(path)];
     });
 }
-function readLines(path) {
+/**
+ * Reads a file as lines.
+ *
+ * @param path - The file to read.
+ * @returns The lines, split on either line ending.
+ */
+export function readLines(path) {
     return readFileSync(path, 'utf8').split(/\r\n|\n/);
 }
-function mapTree(paths) {
+/**
+ * Maps the files beneath paths with their line counts and sizes.
+ *
+ * @param paths - Files and directories.
+ * @returns A row per text file, sorted by path.
+ */
+export function mapTree(paths) {
     return expandPaths(paths)
         .filter(isText)
         .map((path) => {
@@ -47,13 +203,48 @@ function mapTree(paths) {
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-function scanFences(lines) {
-    const fenced = [];
-    for (const text of lines)
-        fenced.push((fenced.at(-1) ?? false) !== text.startsWith('```'));
-    return fenced;
+/**
+ * Finds the lines that can open or close a code fence.
+ *
+ * @param lines - The lines of a Markdown file.
+ * @returns Each line that opens with up to three spaces and a run of three or more backticks or tildes.
+ */
+export function findFenceLines(lines) {
+    return lines.flatMap((text, index) => {
+        const run = text.match(FENCE)?.[1];
+        return run === undefined ? [] : [{ index, run }];
+    });
+}
+/**
+ * Marks the lines that sit inside a code fence.
+ *
+ * @remarks
+ * A fence opens on a run of three or more backticks or tildes, indented up to three spaces, and
+ * closes on a run of the same character at least as long; a fence-like line inside an open fence
+ * that does not close it is content, and a fence the file never closes runs to its end.
+ *
+ * @param lines - The lines of a Markdown file.
+ * @returns One flag per line: true for the fence lines and the lines between them.
+ */
+export function scanFences(lines) {
+    const { open, spans } = findFenceLines(lines).reduce((state, fence) => {
+        if (state.open === undefined)
+            return { open: fence, spans: state.spans };
+        const closes = fence.run.startsWith(state.open.run.charAt(0)) && fence.run.length >= state.open.run.length;
+        return closes
+            ? { open: undefined, spans: [...state.spans, [state.open.index, fence.index]] }
+            : state;
+    }, { open: undefined, spans: [] });
+    const all = open === undefined ? spans : [...spans, [open.index, lines.length - 1]];
+    return [...lines.keys()].map((index) => all.some(([first, last]) => index >= first && index <= last));
 }
-function mapHeadings(paths) {
+/**
+ * Maps the Markdown headings outside code fences.
+ *
+ * @param paths - Files and directories; only Markdown files are read.
+ * @returns A row per heading, its text the marker and the heading text.
+ */
+export function mapHeadings(paths) {
     return expandPaths(paths)
         .filter((candidate) => candidate.endsWith('.md'))
         .flatMap((path) => {
@@ -69,7 +260,13 @@ function mapHeadings(paths) {
         });
     });
 }
-function mapExports(paths) {
+/**
+ * Maps the `export` declaration lines of TypeScript files.
+ *
+ * @param paths - Files and directories; only TypeScript files are read.
+ * @returns A row per declaration, its text the kind and name, or the whole `export * from` line.
+ */
+export function mapExports(paths) {
     return expandPaths(paths)
         .filter((candidate) => /\.[cm]?ts$/u.test(candidate))
         .flatMap((path) => readLines(path).flatMap((text, index) => {
@@ -82,11 +279,26 @@ function mapExports(paths) {
             : [];
     }));
 }
-function buildMatcher(term, ignoreCase) {
+/**
+ * Builds the predicate a census applies to a line.
+ *
+ * @param term - The term to find.
+ * @param ignoreCase - If true, compares without regard to letter case; if false, compares exactly.
+ * @returns A predicate that is true for a line carrying the term.
+ */
+export function buildMatcher(term, ignoreCase) {
     const needle = ignoreCase ? term.toLowerCase() : term;
     return (text) => (ignoreCase ? text.toLowerCase() : text).includes(needle);
 }
-function mapCensus(terms, roots, ignoreCase) {
+/**
+ * Maps the lines that carry each census term.
+ *
+ * @param terms - The terms to find.
+ * @param roots - The files and directories to read.
+ * @param ignoreCase - If true, compares without regard to letter case; if false, compares exactly.
+ * @returns The matching lines per term, each line's text trimmed and cut to its first 160 characters.
+ */
+export function mapCensus(terms, roots, ignoreCase) {
     const files = expandPaths(roots).filter(isText);
     return terms.map((term) => {
         const matches = buildMatcher(term, ignoreCase);
@@ -96,7 +308,14 @@ function mapCensus(terms, roots, ignoreCase) {
         };
     });
 }
-function mapRefs(target, roots) {
+/**
+ * Maps the lines that name a path or its basename.
+ *
+ * @param target - The path to find.
+ * @param roots - The files and directories to read; the target file itself is left out.
+ * @returns The lines that carry the path or its basename.
+ */
+export function mapRefs(target, roots) {
     const needle = normalizeSlashes(target);
     const name = basename(needle);
     return expandPaths(roots)
@@ -106,7 +325,14 @@ function mapRefs(target, roots) {
         ? [{ path, line: index + 1, text: text.trim().slice(0, 160) }]
         : []));
 }
-function classifyYamlLines(lines, offset) {
+/**
+ * Classifies the lines of a YAML body.
+ *
+ * @param lines - The body lines.
+ * @param offset - The line number of the first body line.
+ * @returns Each non-blank, non-comment line with its indent, content, key, and inline value.
+ */
+export function classifyYamlLines(lines, offset) {
     return lines.flatMap((text, index) => {
         const content = text.trimStart();
         if (content === '' || content.startsWith('#'))
@@ -123,7 +349,15 @@ function classifyYamlLines(lines, offset) {
         ];
     });
 }
-function stepYamlState(state, line, position) {
+/**
+ * Steps the YAML reader over one classified line.
+ *
+ * @param state - The reader's state before the line.
+ * @param line - The classified line.
+ * @param position - The line's position among the classified lines.
+ * @returns The state after the line; a line with no key leaves it unchanged.
+ */
+export function stepYamlState(state, line, position) {
     if (line.key === undefined)
         return state;
     // Indents strictly increase along the stack, so the entries at or past this indent are the tail.
@@ -134,7 +368,16 @@ function stepYamlState(state, line, position) {
         heads: [...state.heads, { position, line, key }],
     };
 }
-function readYamlKeys(path, lines, offset) {
+/**
+ * Reads every key of a YAML body with its whole value.
+ *
+ * @param path - The file the body came from.
+ * @param lines - The body lines.
+ * @param offset - The line number of the first body line.
+ * @returns A row per key, a nested key dotted under its parents and its value extended by the
+ * list items and wrapped lines indented under it.
+ */
+export function readYamlKeys(path, lines, offset) {
     const classified = classifyYamlLines(lines, offset);
     const { heads } = classified.reduce((state, line, position) => stepYamlState(state, line, position), { stack: [], heads: [] });
     // A list item, a block scalar line, or a wrapped value extends the key line before it when it is
@@ -153,7 +396,16 @@ function readYamlKeys(path, lines, offset) {
             .trimEnd(),
     }));
 }
-function stepTomlState(state, text, path, line) {
+/**
+ * Steps the TOML reader over one line.
+ *
+ * @param state - The reader's state before the line.
+ * @param text - The line.
+ * @param path - The file the line came from.
+ * @param line - The line's number.
+ * @returns The state after the line, with a row added for a key and the table set for a header.
+ */
+export function stepTomlState(state, text, path, line) {
     if (state.fence !== undefined) {
         // The body of a multi-line string carries no key.
         return text.includes(state.fence) ? { ...state, fence: undefined } : state;
@@ -165,10 +417,10 @@ function stepTomlState(state, text, path, line) {
     if (match?.[1] === undefined)
         return state;
     const value = (match[2] ?? '').trim();
-    const opening = value.match(/^("""|''')/u)?.[1];
+    const marker = value.match(/^("""|''')/u)?.[1];
     return {
         table: state.table,
-        fence: opening !== undefined && value.indexOf(opening, 3) === -1 ? opening : undefined,
+        fence: marker !== undefined && value.indexOf(marker, 3) === -1 ? marker : undefined,
         rows: [
             ...state.rows,
             {
@@ -179,10 +431,24 @@ function stepTomlState(state, text, path, line) {
         ],
     };
 }
-function readTomlKeys(path, lines, offset) {
+/**
+ * Reads every key of a TOML body with its value.
+ *
+ * @param path - The file the body came from.
+ * @param lines - The body lines.
+ * @param offset - The line number of the first body line.
+ * @returns A row per key, a key under a table dotted beneath it; a multi-line string's body is no key.
+ */
+export function readTomlKeys(path, lines, offset) {
     return lines.reduce((state, text, index) => stepTomlState(state, text, path, index + offset), { table: '', fence: undefined, rows: [] }).rows;
 }
-function mapFrontmatter(paths) {
+/**
+ * Maps the keys of Markdown frontmatter, TOML, and YAML files.
+ *
+ * @param paths - Files and directories; only Markdown, MDC, TOML, and YAML files are read.
+ * @returns A row per key; a Markdown file without a closed frontmatter block gives none.
+ */
+export function mapFrontmatter(paths) {
     return expandPaths(paths)
         .filter((candidate) => /\.(md|mdc|toml|ya?ml)$/u.test(candidate))
         .flatMap((path) => {
@@ -198,10 +464,23 @@ function mapFrontmatter(paths) {
             : readYamlKeys(path, body, offset);
     });
 }
-function readHeadingTexts(path) {
+/**
+ * Reads the heading texts of a Markdown file.
+ *
+ * @param path - The Markdown file.
+ * @returns Each heading's text without its marker, lowercased.
+ */
+export function readHeadingTexts(path) {
     return new Set(mapHeadings([path]).map((row) => row.text.replace(/^#+\s+/u, '').toLowerCase()));
 }
-function mapAnchors(paths) {
+/**
+ * Maps the `§ Heading` references whose heading their target does not carry.
+ *
+ * @param paths - Files and directories; only Markdown files are read.
+ * @returns A row per unresolved reference. A reference with no backticked path before it targets
+ * the file that carries it, and a reference whose target file is absent is unresolved.
+ */
+export function mapAnchors(paths) {
     const citations = expandPaths(paths)
         .filter((candidate) => candidate.endsWith('.md'))
         .flatMap((path) => readLines(path).flatMap((text, index) => [...text.matchAll(ANCHOR)].flatMap((match) => {
@@ -213,7 +492,13 @@ function mapAnchors(paths) {
     const headings = new Map([...new Set(citations.map(({ target }) => target).filter((target) => existsSync(target)))].map((target) => [target, readHeadingTexts(target)]));
     return citations.filter(({ target, heading }) => headings.get(target)?.has(heading.toLowerCase()) !== true);
 }
-function renderReport(report) {
+/**
+ * Renders a map as text.
+ *
+ * @param report - The map.
+ * @returns One section per mode the map carries, each opened by a `##` heading, ending in a line feed.
+ */
+export function renderReport(report) {
     const { tree, headings, frontmatter, exports, census, refs, anchors } = report;
     const lines = [
         ...(tree === undefined
@@ -251,20 +536,20 @@ function renderReport(report) {
     ];
     return `${lines.join('\n')}\n`;
 }
-function main(argv) {
-    const missing = readMissingFlags(argv, [
-        '--tree',
-        '--headings',
-        '--frontmatter',
-        '--exports',
-        '--census',
-        '--refs',
-        '--anchors',
-        '--paths',
-        '--out',
-    ]);
-    if (missing.length > 0) {
-        console.error(`map: ${missing.join(', ')} given with no value`);
+/**
+ * Runs the script on its arguments.
+ *
+ * @param argv - The arguments after the script path.
+ * @returns The exit code: 0 on success, 64 on usage.
+ */
+export function main(argv) {
+    const unknown = readUnknownFlags(argv, FLAGS);
+    const missing = readMissingFlags(argv, VALUE_FLAGS);
+    if (unknown.length > 0 || missing.length > 0) {
+        console.error(`map: ${[
+            ...(unknown.length > 0 ? [`${unknown.join(', ')} is not a flag this script reads`] : []),
+            ...(missing.length > 0 ? [`${missing.join(', ')} given with no value`] : []),
+        ].join('; ')}; ${USAGE}`);
         return 64;
     }
     const roots = (readOption(argv, '--paths') ?? '.').split(',');
@@ -284,7 +569,7 @@ function main(argv) {
         anchors.length ===
         0 &&
         refs === undefined) {
-        console.error('usage: map.ts [--tree PATH...] [--headings PATH...] [--frontmatter PATH...] [--exports PATH...] [--census TERM...] [--refs PATH] [--anchors PATH...] [--paths a,b] [--ignore-case] [--json] [--out FILE]');
+        console.error(USAGE);
         return 64;
     }
     const report = {
@@ -307,4 +592,6 @@ function main(argv) {
     }
     return 0;
 }
-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/agents/templates/brief.md

@@ -27,7 +27,7 @@ UNKNOWN and how the unit reports it.
 ## Scope
 
 - **Owned.** FILES, including the tests that pin the behavior, the fixtures derived from a constant, and the materialized copy of a template.
-- **Shared (report-only).** FILES; return an exact patch.
+- **Shared (report-only).** FILES; return an exact patch as an edit file: one `### <path>` block per edit, each with a `reason:` line and fenced `old:` and `new:` texts, that `.agents/skills/orkestrel-dispatch/scripts/patch.ts` applies.
 - **Off-limits.** FILES. Never list `tmp/probes/` here.
 - **Made false by this change.** FILES, derived by running the suite or by a named search bound.
 - **Tools and limits.** ALLOWED_TOOLS; scoped validation only; no tree-wide source-mutating command. For a verifier, declare each permitted output path per `.agents/orchestration.md` § Permission floor.