@orkestrel/scaffold 0.0.76 → 0.0.78

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

@@ -0,0 +1,300 @@
+// 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
+// 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. Exit 0, or 64 when no mode is
+// given or --refs names no path.
+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) {
+    return !BINARY.test(path) && basename(path) !== 'host.json';
+}
+function expandPaths(paths) {
+    return paths.flatMap((path) => {
+        if (!existsSync(path))
+            return [];
+        if (statSync(path).isDirectory())
+            return listFiles(path).map((file) => file.path);
+        return [normalizeSlashes(path)];
+    });
+}
+function readLines(path) {
+    return readFileSync(path, 'utf8').split(/\r\n|\n/);
+}
+function mapTree(paths) {
+    return expandPaths(paths)
+        .filter(isText)
+        .map((path) => {
+        const text = readFileSync(path, 'utf8');
+        return {
+            path,
+            lines: text === '' ? 0 : text.split(/\r\n|\n/).length,
+            bytes: Buffer.byteLength(text),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+function mapHeadings(paths) {
+    const rows = [];
+    for (const path of expandPaths(paths).filter((candidate) => candidate.endsWith('.md'))) {
+        let fenced = false;
+        readLines(path).forEach((text, index) => {
+            if (text.startsWith('```'))
+                fenced = !fenced;
+            if (fenced)
+                return;
+            const match = text.match(HEADING);
+            if (match?.[1] !== undefined && match[2] !== undefined) {
+                rows.push({ path, line: index + 1, text: `${match[1]} ${match[2]}` });
+            }
+        });
+    }
+    return rows;
+}
+function mapExports(paths) {
+    const rows = [];
+    for (const path of expandPaths(paths).filter((candidate) => /\.[cm]?ts$/u.test(candidate))) {
+        readLines(path).forEach((text, index) => {
+            const match = text.match(EXPORT);
+            if (match?.[1] !== undefined && match[2] !== undefined) {
+                rows.push({ path, line: index + 1, text: `${match[1]} ${match[2]}` });
+            }
+            else if (/^export\s+\*\s+from\s+/u.test(text)) {
+                rows.push({ path, line: index + 1, text: text.trim() });
+            }
+        });
+    }
+    return rows;
+}
+function buildMatcher(term, ignoreCase) {
+    const needle = ignoreCase ? term.toLowerCase() : term;
+    return (text) => (ignoreCase ? text.toLowerCase() : text).includes(needle);
+}
+function mapCensus(terms, roots, ignoreCase) {
+    const files = expandPaths(roots).filter(isText);
+    return terms.map((term) => {
+        const matches = buildMatcher(term, ignoreCase);
+        const rows = [];
+        for (const path of files) {
+            readLines(path).forEach((text, index) => {
+                if (matches(text))
+                    rows.push({ path, line: index + 1, text: text.trim().slice(0, 160) });
+            });
+        }
+        return { term, rows };
+    });
+}
+function mapRefs(target, roots) {
+    const needle = normalizeSlashes(target);
+    const name = basename(needle);
+    const rows = [];
+    for (const path of expandPaths(roots).filter(isText)) {
+        if (path === needle)
+            continue;
+        readLines(path).forEach((text, index) => {
+            if (text.includes(needle) || text.includes(name)) {
+                rows.push({ path, line: index + 1, text: text.trim().slice(0, 160) });
+            }
+        });
+    }
+    return rows;
+}
+function readYamlKeys(path, lines, offset) {
+    const rows = [];
+    const stack = [];
+    lines.forEach((text, index) => {
+        const content = text.trimStart();
+        if (content === '' || content.startsWith('#'))
+            return;
+        const indent = text.length - content.length;
+        const match = content.match(/^([A-Za-z_][\w-]*)\s*:(?:\s+(.*))?$/u);
+        if (match?.[1] === undefined) {
+            // A list item, a block scalar line, or a wrapped value extends the key before it.
+            const last = rows.at(-1);
+            if (last !== undefined && indent >= (stack.at(-1)?.indent ?? 0)) {
+                rows[rows.length - 1] = { ...last, text: `${last.text} ${content.trim()}`.trimEnd() };
+            }
+            return;
+        }
+        while (stack.length > 0 && (stack.at(-1)?.indent ?? 0) >= indent)
+            stack.pop();
+        const key = [...stack.map((entry) => entry.key), match[1]].join('.');
+        stack.push({ indent, key: match[1] });
+        rows.push({ path, line: index + offset, text: `${key}: ${(match[2] ?? '').trim()}`.trimEnd() });
+    });
+    return rows;
+}
+function readTomlKeys(path, lines, offset) {
+    const rows = [];
+    let table = '';
+    let fence;
+    lines.forEach((text, index) => {
+        if (fence !== undefined) {
+            // The body of a multi-line string carries no key.
+            if (text.includes(fence))
+                fence = undefined;
+            return;
+        }
+        const header = text.match(/^\s*\[\[?([^\]]+)\]\]?\s*$/u);
+        if (header?.[1] !== undefined) {
+            table = header[1].trim();
+            return;
+        }
+        const match = text.match(/^\s*([A-Za-z0-9_.-]+|"[^"]+")\s*=\s*(.*)$/u);
+        if (match?.[1] === undefined)
+            return;
+        const value = (match[2] ?? '').trim();
+        const opening = value.match(/^("""|''')/u)?.[1];
+        if (opening !== undefined && value.indexOf(opening, 3) === -1)
+            fence = opening;
+        rows.push({
+            path,
+            line: index + offset,
+            text: `${table === '' ? '' : `${table}.`}${match[1]}: ${value}`.trimEnd(),
+        });
+    });
+    return rows;
+}
+function mapFrontmatter(paths) {
+    const rows = [];
+    for (const path of expandPaths(paths).filter((candidate) => /\.(md|mdc|toml|ya?ml)$/u.test(candidate))) {
+        const lines = readLines(path);
+        const markdown = /\.mdc?$/u.test(path);
+        const end = markdown ? lines.indexOf('---', 1) : lines.length;
+        if (markdown && (lines[0] !== '---' || end === -1))
+            continue;
+        const body = lines.slice(markdown ? 1 : 0, end);
+        const offset = markdown ? 2 : 1;
+        rows.push(...(path.endsWith('.toml')
+            ? readTomlKeys(path, body, offset)
+            : readYamlKeys(path, body, offset)));
+    }
+    return rows;
+}
+function readHeadingTexts(path) {
+    return new Set(mapHeadings([path]).map((row) => row.text.replace(/^#+\s+/u, '').toLowerCase()));
+}
+function mapAnchors(paths) {
+    const headings = new Map();
+    const rows = [];
+    for (const path of expandPaths(paths).filter((candidate) => candidate.endsWith('.md'))) {
+        readLines(path).forEach((text, index) => {
+            for (const match of text.matchAll(ANCHOR)) {
+                const target = match[1] === undefined ? path : normalizeSlashes(match[1]);
+                const heading = (match[2] ?? '').trim();
+                if (heading === '')
+                    continue;
+                if (!existsSync(target)) {
+                    rows.push({ path, line: index + 1, target, heading });
+                    continue;
+                }
+                const known = headings.get(target) ?? readHeadingTexts(target);
+                headings.set(target, known);
+                if (!known.has(heading.toLowerCase()))
+                    rows.push({ path, line: index + 1, target, heading });
+            }
+        });
+    }
+    return rows;
+}
+function renderReport(report) {
+    const lines = [];
+    if (report.tree !== undefined) {
+        lines.push('## Tree');
+        for (const row of report.tree)
+            lines.push(`${row.path}\t${row.lines} lines\t${row.bytes} bytes`);
+        lines.push(`total\t${report.tree.length} files\t${report.tree.reduce((sum, row) => sum + row.lines, 0)} lines`);
+    }
+    if (report.headings !== undefined) {
+        lines.push('## Headings');
+        for (const row of report.headings)
+            lines.push(`${row.path}:${row.line}\t${row.text}`);
+    }
+    if (report.frontmatter !== undefined) {
+        lines.push('## Frontmatter');
+        for (const row of report.frontmatter)
+            lines.push(`${row.path}:${row.line}	${row.text}`);
+    }
+    if (report.exports !== undefined) {
+        lines.push('## Exports (text reading)');
+        for (const row of report.exports)
+            lines.push(`${row.path}:${row.line}\t${row.text}`);
+    }
+    if (report.census !== undefined) {
+        for (const entry of report.census) {
+            lines.push(`## Census: ${entry.term} (${entry.rows.length})`);
+            for (const row of entry.rows)
+                lines.push(`${row.path}:${row.line}\t${row.text}`);
+        }
+    }
+    if (report.refs !== undefined) {
+        lines.push(`## Refs (${report.refs.length})`);
+        for (const row of report.refs)
+            lines.push(`${row.path}:${row.line}\t${row.text}`);
+    }
+    if (report.anchors !== undefined) {
+        lines.push(`## Unresolved anchors (${report.anchors.length})`);
+        for (const row of report.anchors)
+            lines.push(`${row.path}:${row.line}\t${row.target} § ${row.heading}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--refs', '--paths', '--out']);
+    if (missing.length > 0) {
+        console.error(`map: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const roots = (readOption(argv, '--paths') ?? '.').split(',');
+    const ignoreCase = argv.includes('--ignore-case');
+    const tree = readList(argv, '--tree');
+    const headings = readList(argv, '--headings');
+    const frontmatter = readList(argv, '--frontmatter');
+    const exports = readList(argv, '--exports');
+    const census = readList(argv, '--census');
+    const refs = readOption(argv, '--refs');
+    const anchors = readList(argv, '--anchors');
+    if (tree.length +
+        headings.length +
+        frontmatter.length +
+        exports.length +
+        census.length +
+        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]');
+        return 64;
+    }
+    const report = {
+        ...(tree.length > 0 ? { tree: mapTree(tree) } : {}),
+        ...(headings.length > 0 ? { headings: mapHeadings(headings) } : {}),
+        ...(frontmatter.length > 0 ? { frontmatter: mapFrontmatter(frontmatter) } : {}),
+        ...(exports.length > 0 ? { exports: mapExports(exports) } : {}),
+        ...(census.length > 0 ? { census: mapCensus(census, roots, ignoreCase) } : {}),
+        ...(refs === undefined ? {} : { refs: mapRefs(refs, roots) }),
+        ...(anchors.length > 0 ? { anchors: mapAnchors(anchors) } : {}),
+    };
+    const output = argv.includes('--json') ? `${JSON.stringify(report)}\n` : renderReport(report);
+    const out = readOption(argv, '--out');
+    if (out === undefined)
+        process.stdout.write(output);
+    else {
+        mkdirSync(dirname(out), { recursive: true });
+        writeFileSync(out, output);
+        console.log(`map: wrote ${out}`);
+    }
+    return 0;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/agents/templates/brief.md

@@ -0,0 +1,55 @@
+# Unit UNIT_ID — SHORT_SUBJECT
+
+Fill every section. Write `none` in an empty one. Replace each `UPPER_SNAKE_CASE` placeholder.
+
+## Role and engine
+
+ROLE on ENGINE, reached as TRANSPORT. Executor: NATIVE_SUBAGENT | BENCH_ENGINE | BRIDGE_DRIVER.
+
+## Objective
+
+ONE_OUTCOME.
+
+## Context
+
+- **Evidence.** COMMANDS_AND_OUTPUT behind every fact.
+- **Law.** `AGENTS.md`; RULE_FILES; SKILL and the references it names; GUIDE_OR_SPEC.
+- **Installed primitives.** ORKESTREL_PACKAGES with the surface each unit reads first. A local helper whose job an installed export does is a defect.
+- **Host.** SHELL, WORKING_PATH, SANDBOX_NETWORK_APPROVAL_LIMITS.
+- **Standing conditions.** DIRTY_FILES, KNOWN_FAILING_COMMANDS, BLOCKED_TOOLS, and who repairs each.
+
+## Unknowns
+
+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.
+- **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 mutating command.
+
+## Execution
+
+Perform the assignment yourself and spawn nothing. (Bridge driver: carry this brief unaltered, launch ENGINE through its CLI, and return the journal path and session id with the result.)
+
+## Output
+
+RETURN_SHAPE through OUTPUT_MECHANISM. No process diary.
+
+## Deviation contract
+
+Stop and report (expected, found, evidence, done or not done, one hypothesis) on OBJECTIVE_CONFLICT. Settle ANCILLARY_CHOICES yourself and record them.
+
+## Acceptance criteria
+
+1. CHEAPEST_GATE (regeneration, typecheck, or lint over owned files)
+2. SCOPED_TEST
+3. ARTIFACT_CRITERION
+
+**Observations, not criteria.** TIMING_SENSITIVE_OR_TREE_WIDE_GATES the unit reports and the Orchestrator re-runs.
+
+## Review evidence
+
+The actual diff and `git status --porcelain` for a code change; the capture portfolio for a rendered surface; the proposal, the canon it must satisfy, and its motivation for a process proposal.

package/dist/bin/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
 import { attempt, isArray, isError, isInstance, isRecord, isString, parseJSON } from "@orkestrel/contract";
-import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
+import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, SKILLS_CONFIG_PATH, ScaffoldError, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
 import { MAX_INVENTORY_PATHS, Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readHostManifest, readSnapshot, resolveContainedPath } from "../src/server/index.js";
 import { createMarkdown, flattenText, isTableNode } from "@orkestrel/markdown";
 import { createSession } from "@orkestrel/process/server";
@@ -1853,6 +1853,7 @@ var CLI = class {
 		const global = resolveContainedPath(target, GLOBAL_SETUP_PATH);
 		const showcase = resolveContainedPath(target, SHOWCASE_CONFIG_PATH);
 		const journey = resolveContainedPath(target, JOURNEY_CONFIG_PATH);
+		const skills = resolveContainedPath(target, SKILLS_CONFIG_PATH);
 		const setup = /* @__PURE__ */ new Set();
 		if (tests !== void 0) for (const path of listFiles(tests)) {
 			if (path.includes("/") || !path.startsWith("setup") || !path.endsWith(".test.ts")) continue;
@@ -1871,7 +1872,8 @@ var CLI = class {
 			service: service !== void 0 && isExactCaseFile(service),
 			global: global !== void 0 && isExactCaseFile(global),
 			showcase: showcase !== void 0 && isExactCaseFile(showcase),
-			journey: journey !== void 0 && isExactCaseFile(journey)
+			journey: journey !== void 0 && isExactCaseFile(journey),
+			skills: skills !== void 0 && isExactCaseFile(skills)
 		});
 	}
 	#projectQuestion(target, blueprint, writing = false) {