@orkestrel/scaffold 0.0.77 → 0.0.78

package/dist/agents/skills/orkestrel-harden/scripts/discovery.js

@@ -0,0 +1,196 @@
+// Census of test discovery: which projects the gates reach, what each collects, and where a suite
+// skips. Run from the checkout root:
+//   node .agents/skills/orkestrel-harden/scripts/discovery.ts [--config vite.config.ts] [--projects a,b] [--json]
+// The script follows every root script chain in package.json (a script no other script invokes) to
+// the `--project` names its Vitest scripts gate and the test files its `node` scripts run, runs
+// `vitest list --json` once through the local vitest entry to read what each project collects, and
+// reads every collected file for `.skip(`, `.todo(`, `.skipIf(`, `.runIf(`, `retry:`, and
+// `timeout:`. It flags a collected project no root chain reaches, a named project that collects
+// nothing, and a test file under tests/ that no project collects and no root script runs directly.
+// A project with no test file and no gate is outside the census. Exit 0 with no flag, 3 with one, 2 when Vitest cannot list, 64 on
+// usage.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { listFiles, readMissingFlags, readOption, } from "../../orkestrel-dispatch/scripts/helpers.js";
+const VITEST = 'node_modules/vitest/vitest.mjs';
+const MARKERS = ['.skip(', '.todo(', '.skipIf(', '.runIf(', 'retry:', 'timeout:'];
+function readScripts() {
+    const parsed = JSON.parse(readFileSync('package.json', 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null)
+        return {};
+    const scripts = Object.fromEntries(Object.entries(parsed)).scripts;
+    if (typeof scripts !== 'object' || scripts === null)
+        return {};
+    const record = {};
+    for (const [key, value] of Object.entries(scripts))
+        if (typeof value === 'string')
+            record[key] = value;
+    return record;
+}
+function listInvocations(text) {
+    return [...text.matchAll(/npm run ([A-Za-z0-9:_-]+)/gu)].flatMap((match) => match[1] === undefined ? [] : [match[1]]);
+}
+function readGates(scripts) {
+    const invoked = new Set(Object.values(scripts).flatMap(listInvocations));
+    const projects = new Map();
+    const files = new Map();
+    for (const root of Object.keys(scripts).filter((name) => !invoked.has(name))) {
+        const visited = new Set();
+        const pending = [root];
+        while (pending.length > 0) {
+            const name = pending.pop();
+            if (name === undefined || visited.has(name))
+                continue;
+            visited.add(name);
+            const text = scripts[name];
+            if (text === undefined)
+                continue;
+            pending.push(...listInvocations(text));
+            const gate = root === name ? name : `${root} > ${name}`;
+            if (/\bvitest\b/u.test(text)) {
+                for (const match of text.matchAll(/--project[= ]([A-Za-z0-9:_-]+)/gu)) {
+                    if (match[1] !== undefined && !projects.has(match[1]))
+                        projects.set(match[1], gate);
+                }
+            }
+            for (const match of text.matchAll(/(?:^|\s)((?:tests|src|app)\/[A-Za-z0-9_./-]+\.test\.[cm]?ts)\b/gu)) {
+                if (match[1] !== undefined && !files.has(match[1]))
+                    files.set(match[1], gate);
+            }
+        }
+    }
+    return { projects, files };
+}
+function listCollected(config) {
+    const result = spawnSync(process.execPath, [VITEST, 'list', '--config', config, '--json'], {
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        windowsHide: true,
+    });
+    if (result.status !== 0)
+        return undefined;
+    const start = result.stdout.indexOf('[');
+    if (start === -1)
+        return undefined;
+    const parsed = JSON.parse(result.stdout.slice(start));
+    if (!Array.isArray(parsed))
+        return undefined;
+    const collected = [];
+    for (const entry of parsed) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = Object.fromEntries(Object.entries(entry));
+        if (typeof record.file === 'string' && typeof record.projectName === 'string') {
+            collected.push({
+                file: relative(process.cwd(), record.file).split('\\').join('/'),
+                projectName: record.projectName,
+            });
+        }
+    }
+    return collected;
+}
+function listTestFiles(directory) {
+    if (!existsSync(directory))
+        return [];
+    return listFiles(directory)
+        .map((file) => file.path)
+        .filter((path) => /\.test\.[cm]?ts$/u.test(path));
+}
+function countMarkers(file) {
+    const text = readFileSync(file, 'utf8');
+    const counts = {};
+    for (const marker of MARKERS) {
+        const count = text.split(marker).length - 1;
+        if (count > 0)
+            counts[marker] = count;
+    }
+    return counts;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--config', '--projects']);
+    if (missing.length > 0) {
+        console.error(`discovery: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const config = readOption(argv, '--config') ?? 'vite.config.ts';
+    if (!existsSync(config) || !existsSync('package.json')) {
+        console.error('usage: discovery.ts [--config vite.config.ts] [--projects a,b] [--json]');
+        return 64;
+    }
+    if (!existsSync(VITEST)) {
+        console.error(`discovery: ${VITEST} is missing; run npm ci first`);
+        return 2;
+    }
+    const gates = readGates(readScripts());
+    const collected = listCollected(config);
+    if (collected === undefined) {
+        console.error('discovery: vitest list failed; run it bare to read the diagnostic');
+        return 2;
+    }
+    const named = (readOption(argv, '--projects') ?? '').split(',').filter((name) => name !== '');
+    const names = new Set([
+        ...gates.projects.keys(),
+        ...collected.map((entry) => entry.projectName),
+        ...named,
+    ]);
+    const projects = [...names].sort().map((name) => {
+        const mine = collected.filter((entry) => entry.projectName === name);
+        const fileGate = mine
+            .map((entry) => gates.files.get(entry.file))
+            .find((gate) => gate !== undefined);
+        return {
+            name,
+            gate: gates.projects.get(name) ?? fileGate,
+            files: new Set(mine.map((entry) => entry.file)).size,
+            tests: mine.length,
+        };
+    });
+    const collectedFiles = new Set(collected.map((entry) => entry.file));
+    const undiscovered = listTestFiles('tests')
+        .filter((file) => !collectedFiles.has(file) && !gates.files.has(file))
+        .sort();
+    const ungated = projects
+        .filter((project) => project.gate === undefined && project.tests > 0)
+        .map((project) => project.name);
+    // A project no chain reaches is a workbench (the `probe` project collects `tmp/probes/**`), so an
+    // empty one is reported, never flagged.
+    const empty = projects
+        .filter((project) => project.tests === 0 && project.gate?.includes(' > ') === true)
+        .map((project) => project.name);
+    const workbenches = projects
+        .filter((project) => project.tests === 0 && project.gate?.includes(' > ') !== true)
+        .map((project) => project.name);
+    const census = [...collectedFiles].sort().map((file) => ({
+        file,
+        projects: [
+            ...new Set(collected.filter((entry) => entry.file === file).map((entry) => entry.projectName)),
+        ],
+        markers: countMarkers(resolve(file)),
+    }));
+    const flagged = undiscovered.length + ungated.length + empty.length > 0;
+    if (argv.includes('--json')) {
+        console.log(JSON.stringify({ config, projects, ungated, empty, workbenches, undiscovered, census }));
+    }
+    else {
+        for (const project of projects) {
+            console.log(`discovery: ${project.name.padEnd(14)} ${String(project.files).padStart(3)} file(s) ${String(project.tests).padStart(5)} test(s) gate=${project.gate ?? 'none'}`);
+        }
+        for (const name of ungated)
+            console.log(`discovery: ${name} collects tests but no root script chain reaches it`);
+        for (const name of empty)
+            console.log(`discovery: ${name} collects nothing`);
+        for (const name of workbenches)
+            console.log(`discovery: ${name} is a workbench no chain runs; it collects nothing`);
+        for (const file of undiscovered)
+            console.log(`discovery: ${file} is collected by no project`);
+        for (const entry of census) {
+            const marks = Object.entries(entry.markers);
+            if (marks.length > 0) {
+                console.log(`discovery: ${entry.file} ${marks.map(([marker, count]) => `${marker}×${count}`).join(' ')}`);
+            }
+        }
+    }
+    return flagged ? 3 : 0;
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/agents/skills/orkestrel-publish/scripts/compare.js

@@ -0,0 +1,206 @@
+// Compare the rebuilt dist/ against the published tarball on material content. Run from the
+// publishing package's root after its build:
+//   node .agents/skills/orkestrel-publish/scripts/compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]
+// The package defaults to the manifest's name and the version to what the registry serves; --tarball
+// compares against a local .tgz instead of fetching. Sourcemaps are excluded, a text file differs
+// only when it differs with all whitespace removed, and a binary file differs on any byte. The
+// summary lists the paths added, removed, and changed. Exit 0 when nothing material differs, 3 when
+// something does, 2 when the tarball cannot be read, 64 on usage.
+import { existsSync, readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { listFiles, readMissingFlags, readOption, runNpm, } from "../../orkestrel-dispatch/scripts/helpers.js";
+const BLOCK = 512;
+const PACKAGE_PREFIX = 'package/';
+function readManifest() {
+    if (!existsSync('package.json'))
+        return { name: undefined, version: undefined };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync('package.json', 'utf8'));
+    }
+    catch {
+        return { name: undefined, version: undefined };
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return { name: undefined, version: undefined };
+    const record = Object.fromEntries(Object.entries(parsed));
+    return {
+        name: typeof record.name === 'string' ? record.name : undefined,
+        version: typeof record.version === 'string' ? record.version : undefined,
+    };
+}
+function readField(text) {
+    const stripped = text.replace(/^"|"$/gu, '');
+    return stripped === '' ? undefined : stripped;
+}
+function readHeaderText(header, start, length) {
+    const slice = header.subarray(start, start + length);
+    const end = slice.indexOf(0);
+    return slice.subarray(0, end === -1 ? slice.length : end).toString('utf8');
+}
+function readPaxPath(data) {
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(0x20, offset);
+        if (space === -1)
+            return undefined;
+        const length = Number(data.subarray(offset, space).toString('utf8'));
+        if (!Number.isFinite(length) || length <= 0)
+            return undefined;
+        const record = data.subarray(space + 1, offset + length - 1).toString('utf8');
+        if (record.startsWith('path='))
+            return record.slice('path='.length);
+        offset += length;
+    }
+    return undefined;
+}
+function readTar(archive) {
+    const files = new Map();
+    let offset = 0;
+    let overrideName;
+    while (offset + BLOCK <= archive.length) {
+        const header = archive.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = Number.parseInt(readHeaderText(header, 124, 12).trim() || '0', 8);
+        const type = String.fromCharCode(header[156] ?? 0);
+        const magic = readHeaderText(header, 257, 6);
+        const prefix = magic.startsWith('ustar') ? readHeaderText(header, 345, 155) : '';
+        const shortName = readHeaderText(header, 0, 100);
+        const name = overrideName ?? (prefix === '' ? shortName : `${prefix}/${shortName}`);
+        const data = archive.subarray(offset + BLOCK, offset + BLOCK + size);
+        overrideName = undefined;
+        if (type === 'x')
+            overrideName = readPaxPath(data);
+        else if (type === 'L')
+            overrideName = readHeaderText(data, 0, data.length);
+        else if (type === '0' || type === '\0')
+            files.set(name, Buffer.from(data));
+        offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+    }
+    return files;
+}
+// A dist tree holds nothing a walk skips, so every emitted file counts.
+const NOTHING_SKIPPED = new Set();
+function readNpmValue(args) {
+    const result = runNpm(args);
+    return result.status === 0 ? readField(result.stdout.trim()) : undefined;
+}
+function isMaterial(path) {
+    return !path.endsWith('.map');
+}
+function differs(left, right) {
+    if (left.includes(0) || right.includes(0))
+        return !left.equals(right);
+    return left.toString('utf8').replace(/\s+/gu, '') !== right.toString('utf8').replace(/\s+/gu, '');
+}
+async function main(argv) {
+    const missing = readMissingFlags(argv, ['--package', '--version', '--tarball', '--dist']);
+    if (missing.length > 0) {
+        console.error(`compare: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const manifest = readManifest();
+    const name = readOption(argv, '--package') ?? manifest.name;
+    const dist = readOption(argv, '--dist') ?? 'dist';
+    const tarball = readOption(argv, '--tarball');
+    if (name === undefined ||
+        !existsSync(dist) ||
+        (argv.includes('--tarball') && tarball === undefined)) {
+        console.error('usage: compare.ts [--package NAME] [--version V] [--tarball PATH] [--dist dist] [--json]');
+        return 64;
+    }
+    let version = readOption(argv, '--version');
+    let archive;
+    if (tarball !== undefined) {
+        if (!existsSync(tarball)) {
+            console.error(`compare: ${tarball} does not exist`);
+            return 2;
+        }
+        archive = readFileSync(tarball);
+    }
+    else {
+        version ??= readNpmValue(['view', name, 'version', '--json']);
+        const url = version === undefined
+            ? undefined
+            : readNpmValue(['view', `${name}@${version}`, 'dist.tarball', '--json']);
+        if (version === undefined || url === undefined) {
+            console.error(`compare: the registry served no tarball for ${name}${version === undefined ? '' : `@${version}`}`);
+            return 2;
+        }
+        const fetched = await fetchTarball(url);
+        if (fetched === undefined) {
+            console.error(`compare: fetching ${url} failed`);
+            return 2;
+        }
+        archive = fetched;
+    }
+    const published = new Map();
+    let entries;
+    try {
+        entries = readTar(gunzipSync(archive));
+    }
+    catch (error) {
+        console.error(`compare: the tarball could not be read: ${error instanceof Error ? error.message : String(error)}`);
+        return 2;
+    }
+    for (const [path, content] of entries) {
+        const prefixed = `${PACKAGE_PREFIX}${dist}/`;
+        if (path.startsWith(prefixed) && isMaterial(path))
+            published.set(path.slice(prefixed.length), content);
+    }
+    const local = new Map();
+    for (const { path } of listFiles(dist, NOTHING_SKIPPED)) {
+        const key = relative(dist, path).split('\\').join('/');
+        if (isMaterial(key))
+            local.set(key, readFileSync(path));
+    }
+    const added = [...local.keys()].filter((key) => !published.has(key)).sort();
+    const removed = [...published.keys()].filter((key) => !local.has(key)).sort();
+    const changed = [...local.keys()]
+        .filter((key) => {
+        const other = published.get(key);
+        const mine = local.get(key);
+        return other !== undefined && mine !== undefined && differs(mine, other);
+    })
+        .sort();
+    const material = added.length + removed.length + changed.length > 0;
+    const summary = {
+        package: name,
+        version,
+        tarball,
+        dist,
+        compared: published.size,
+        added,
+        removed,
+        changed,
+        material,
+    };
+    if (argv.includes('--json'))
+        console.log(JSON.stringify(summary));
+    else {
+        console.log(`compare: ${name}${version === undefined ? '' : `@${version}`} — ${published.size} published file(s), ${added.length} added, ${removed.length} removed, ${changed.length} changed`);
+        for (const path of added)
+            console.log(`compare: added ${path}`);
+        for (const path of removed)
+            console.log(`compare: removed ${path}`);
+        for (const path of changed)
+            console.log(`compare: changed ${path}`);
+    }
+    return material ? 3 : 0;
+}
+async function fetchTarball(url) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok)
+            return undefined;
+        return Buffer.from(await response.arrayBuffer());
+    }
+    catch {
+        return undefined;
+    }
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/agents/skills/orkestrel-publish/scripts/pins.js

@@ -0,0 +1,93 @@
+// Sweep source and tests for a prior version or range literal after a bump or a re-pin. Run from
+// the publishing package's root:
+//   node .agents/skills/orkestrel-publish/scripts/pins.ts --version 0.0.76 [--range ^0.0.16 ...] [--paths src,tests] [--json]
+// `--range` repeats. A version hit is the literal bounded by characters other than digits and dots,
+// so `~0.0.76` and `"0.0.76"` both hit and `0.0.760` does not. A range that is one comparator over
+// one version (`^8.3.0`, `~8.3.0`, `>=8.3.0`, `v8.3.0`) hits its bare version in any form, bounded the
+// same way, so `--range ^8.3.0` hits `~8.3.0` and `serves 8.3.0` and misses `^8.3.1`; any other
+// range (`>=1.2.0 <2.0.0`, `8.x`) hits its literal bounded the same way and not preceded by another
+// range operator. Each matching line prints once as path:line: text, naming the first requested
+// literal that matched in the order --version then each --range, so the operator rules on it.
+// Exit 0 with no hits, 3 with hits, 64 on usage.
+import { readFileSync, statSync } from 'node:fs';
+import { listFiles, readMissingFlags, readOptions, } from "../../orkestrel-dispatch/scripts/helpers.js";
+const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u;
+const COMPARATOR = /^(?:\^|~|>=|>|<=|<|=)?v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)$/u;
+function escapePattern(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+function buildVersionPattern(version) {
+    return new RegExp(`(?<![0-9.])${escapePattern(version)}(?![0-9.])`, 'u');
+}
+function buildVersionLiteral(literal) {
+    return { literal, pattern: buildVersionPattern(literal) };
+}
+function buildRangeLiteral(literal) {
+    const version = COMPARATOR.exec(literal)?.[1];
+    if (version !== undefined)
+        return { literal, pattern: buildVersionPattern(version) };
+    return {
+        literal,
+        pattern: new RegExp(`(?<![0-9.^~<>=])${escapePattern(literal)}(?![0-9.])`, 'u'),
+    };
+}
+function sweepFile(path, literals) {
+    const content = readFileSync(path);
+    if (content.includes(0))
+        return [];
+    const hits = [];
+    content
+        .toString('utf8')
+        .split(/\r\n|\n/)
+        .forEach((text, index) => {
+        const match = literals.find((entry) => entry.pattern.test(text));
+        if (match !== undefined) {
+            hits.push({ path, line: index + 1, literal: match.literal, text: text.trim() });
+        }
+    });
+    return hits;
+}
+function main(argv) {
+    const missing = readMissingFlags(argv, ['--version', '--range', '--paths']);
+    if (missing.length > 0) {
+        console.error(`pins: ${missing.join(', ')} given with no value`);
+        return 64;
+    }
+    const version = readOptions(argv, '--version')[0];
+    const ranges = readOptions(argv, '--range');
+    const paths = (readOptions(argv, '--paths')[0] ?? 'src,tests').split(',');
+    if (version === undefined && ranges.length === 0) {
+        console.error('usage: pins.ts --version PRIOR [--range PRIOR_RANGE ...] [--paths src,tests] [--json]');
+        return 64;
+    }
+    const literals = [
+        ...(version === undefined ? [] : [buildVersionLiteral(version)]),
+        ...ranges.map(buildRangeLiteral),
+    ];
+    const present = paths.filter((path) => {
+        try {
+            return statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+    const skipped = paths.filter((path) => !present.includes(path));
+    for (const path of skipped)
+        console.error(`pins: ${path} is not a directory; skipped`);
+    const hits = present
+        .flatMap((directory) => listFiles(directory).map((file) => file.path))
+        .filter((file) => !BINARY.test(file))
+        .flatMap((file) => sweepFile(file, literals));
+    const names = literals.map((entry) => entry.literal);
+    if (argv.includes('--json')) {
+        console.log(JSON.stringify({ literals: names, paths: present, skipped, hits }));
+    }
+    else {
+        for (const hit of hits)
+            console.log(`${hit.path}:${hit.line}: ${hit.text}`);
+        console.log(`pins: ${hits.length} hit(s) for ${names.join(', ')} under ${present.join(', ')}`);
+    }
+    return hits.length === 0 ? 0 : 3;
+}
+process.exitCode = main(process.argv.slice(2));