Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

refactor(cli): discovery and selection agree on file names [C7,V4]

Corey Olsonfcd1ad062a36
diff --cc src/affected-tests.js
index b6875194,bc221485..4bd9c380
--- a/src/affected-tests.js
+++ b/src/affected-tests.js
@@@ -4,6 -4,6 +4,10 @@@ import { posix } from 'node:path'
import { fileURLToPath } from 'node:url';
import { pathToFileURL } from 'node:url';
import { cleanGitEnvironment } from './git.js';
++import {
++ COMMAND_CANDIDATE,
++ ENGINE_CANDIDATE,
++} from './discovery.js';
import {
commonJsIn,
importsIn,
@@@ -18,9 -18,6 +22,7 @@@ const SOURCE_TREE_INPUT = '/** @pullboa
const DOCS_TREE_INPUT = '/** @pullboard-test-input docs-tree */';
// A computed-import test may declare the repository modules it can load, in its leading comment header only.
const LOADS = /^\/\*\* @pullboard-test-loads (.+?) \*\/$/u;
+const COMMAND_REGISTRY = 'src/commands/index.js';
- const COMMAND_MODULE = /^src\/commands\/(?!index\.js$)[\w-]+\.js$/u;
- const ENGINE_LEAF = /^src\/[\w-]+-engine\.js$/u;
const GLOBAL = new Set(['bin/run-tests.js', 'package.json', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'src/gate.js', 'src/cli.js', 'src/hooks.js', 'src/trusted-policy.js', 'src/affected-tests.js', 'src/module-imports.js']);
/**
@@@ -302,14 -297,6 +304,15 @@@ function graphAt(root, commit, changedD
reverse.get('bin/pullboard.js').add(path);
}
});
+ // Discovery is not an import: the command registry loads each src/commands module, and machine.js reads each
+ // src/*-engine.js leaf as text. A change to one reaches the reader, so everything that imports the reader is selected.
+ for (const module of paths) {
- const reader = COMMAND_MODULE.test(module) ? COMMAND_REGISTRY : ENGINE_LEAF.test(module) ? 'src/machine.js' : null;
++ const reader = module.startsWith('src/commands/') && COMMAND_CANDIDATE.test(module.slice('src/commands/'.length)) ? COMMAND_REGISTRY
++ : module.startsWith('src/') && ENGINE_CANDIDATE.test(module.slice('src/'.length)) ? 'src/machine.js' : null;
+ if (!reader) continue;
+ if (!reverse.has(module)) reverse.set(module, new Set());
+ reverse.get(module).add(reader);
+ }
return { paths, reverse, unknown, undeclared, testTreeReaders, sourceTreeReaders, docInputs };
}
diff --cc src/commands/index.js
index 4969eb15,00000000..f41c0399
mode 100644,000000..100644
--- a/src/commands/index.js
+++ b/src/commands/index.js
@@@ -1,21 -1,0 +1,24 @@@
+/**
+ * Every command, discovered: each src/commands/<name>.js is the pullboard <name> command and exports run. An item
+ * adding a command adds its own new file and no line of any shared one, so two items adding different commands never
+ * conflict, even at the same sorted spot [C7,V4]. Modules load on first use, so a command that is not run costs nothing.
+ */
++import {
++ COMMAND_CANDIDATE,
++ COMMAND_FILE,
++ discovered,
++} from '../discovery.js';
+import { readdirSync } from 'node:fs';
+
+const FOLDER = new URL('./', import.meta.url);
+
+/** Load one command module by its file name under src/commands/. */
+function loader(file) {
+ return () => import(new URL(file, FOLDER).href);
+}
+
- export const COMMANDS = Object.fromEntries(readdirSync(FOLDER)
- .filter((file) => file.endsWith('.js') && file !== 'index.js')
- .sort()
++export const COMMANDS = Object.fromEntries(discovered(readdirSync(FOLDER), COMMAND_CANDIDATE, COMMAND_FILE, 'command')
+ .map((file) => [file.slice(0, -'.js'.length), loader(file)]));
+
+/** Commands that run but stay out of help and the result-command list. */
+export const UNLISTED_COMMANDS = ['mcp'];
diff --cc src/commands/publish.js
index 00000000,00000000..03104295
new file mode 100644
--- /dev/null
+++ b/src/commands/publish.js
@@@ -1,0 -1,0 +1,20 @@@
++/** The pullboard publish command, in its own module so an item adding another command never edits these lines. */
++import { publishTrunk } from '../publish.js';
++import { COORDINATOR } from '../config.js';
++import { mainPolicy } from '../trusted-policy.js';
++import { Refused } from '../refused.js';
++import {
++ actOn,
++ gateWaitReporter,
++} from '../cli.js';
++
++/** Run `pullboard publish` and return its exit code. */
++export async function run(io, { first, second, rest }) {
++ return actOn(io, async (ctx, board, me) => {
++ if (me.id !== COORDINATOR || !ctx.info.isMain) throw new Refused('COORDINATOR_ONLY', 'only the coordinator publishes the trunk; ask your coordinator to run pullboard publish');
++ if (first || second || rest.length) throw new Refused('USAGE', 'pullboard publish');
++ const result = await publishTrunk({ root: ctx.info.root, board, config: mainPolicy(ctx.info.root).config, say: io.say, onWait: gateWaitReporter(io) });
++ io.result?.(result);
++ return result.published || result.waiting ? 0 : 1;
++ });
++}
diff --cc src/discovery.js
index 00000000,00000000..955eba92
new file mode 100644
--- /dev/null
+++ b/src/discovery.js
@@@ -1,0 -1,0 +1,34 @@@
++/**
++ * Which files are commands and which are engines, in one place [C7,V4]. The runtime discovery in src/commands/index.js and
++ * src/machine.js and the affected-test selector in src/affected-tests.js all read these, so no name is accepted by one and
++ * missed by another. A candidate is any file that looks like one; a name with a character outside the strict set is refused
++ * at discovery with a clear error, and the selector still treats it as reaching its reader.
++ */
++
++/** Every file in src/commands/ other than the registry is a command candidate. */
++export const COMMAND_CANDIDATE = /^(?!index\.js$)[^/]+\.js$/u;
++
++/** A command file name the registry accepts: letters, digits, underscores and hyphens. */
++export const COMMAND_FILE = /^[\w-]+\.js$/u;
++
++/** Every file in src/ ending in -engine.js is an engine candidate. */
++export const ENGINE_CANDIDATE = /^[^/]*-engine\.js$/u;
++
++/** An engine file name machine.js accepts: letters, digits, underscores and hyphens before -engine.js. */
++export const ENGINE_FILE = /^[\w-]+-engine\.js$/u;
++
++/**
++ * Keep the candidates of a folder that the strict pattern accepts, refusing the rest by name.
++ *
++ * @param {string[]} names file names in the folder
++ * @param {RegExp} candidate what looks like a member
++ * @param {RegExp} strict what a member may be called
++ * @param {string} what what the members are, for the error
++ * @returns {string[]} the accepted names, sorted
++ */
++export function discovered(names, candidate, strict, what) {
++ const found = names.filter((name) => candidate.test(name)).sort();
++ const refused = found.filter((name) => !strict.test(name));
++ if (refused.length) throw new Error(`${refused.join(', ')} cannot be a ${what}: use only letters, digits, underscores and hyphens in the file name`);
++ return found;
++}
diff --cc src/machine.js
index 561f1c8d,c0fb3b3c..de81f194
--- a/src/machine.js
+++ b/src/machine.js
@@@ -9,41 -9,45 +9,46 @@@
* broken copy, and checks the declaration against the refusals board.js and cli.js raise today.
*/
-import { RIGOR_NOTICE_ENGINE } from './rigor-source.js';
-import { HEALTH_CAP_ENGINE } from './health-receipts.js';
-import { NATIVE_FLAKE_ENGINE } from './flake-engine.js';
-import { RECURRING_JOB_ENGINE } from './job-engine.js';
-import { LOCAL_LANDING_ENGINE } from './land-engine.js';
++import {
++ ENGINE_CANDIDATE,
++ ENGINE_FILE,
++ discovered,
++} from './discovery.js';
+import {
+ readdirSync,
+ readFileSync,
+} from 'node:fs';
+
+export { AUTO_ESCALATE_ENGINE } from './auto-escalate-engine.js';
+export { ROW_DRAFT_ENGINE } from './row-draft-engine.js';
+export { STRONG_REJECTION_NOTICE_ENGINE } from './strong-rejection-notice-engine.js';
+export { SUBMITTED_CONFLICT_ENGINE } from './submitted-conflict-engine.js';
+export { WITHDRAW_MILESTONE_ENGINE } from './withdraw-milestone-engine.js';
-/** First writer for withdraw-and-remove milestone behavior; shipment remains engine 45. */
-export const WITHDRAW_MILESTONE_ENGINE = 51;
-
-/** First engine that automatically escalates an item's second rejection at its current route [B15]. */
-export const AUTO_ESCALATE_ENGINE = 50;
-
-/** The first engine that records a spec row a lane agent drafts on the board, not in SPEC.md (#878). */
-export const ROW_DRAFT_ENGINE = 55;
-
-/** First engine replacing an automatic ceiling escalation with a paired notice [B15,H16]. */
-export const STRONG_REJECTION_NOTICE_ENGINE = 54;
-
-/** Executable move semantics, carried by every sealed move and retained during replay [H16]. */
/**
- * The engine at which a conflict reopen may return a submitted head, not only an accepted one, and any joined
- * seat may record it (#807; allocated by the coordinator, 19 Oct).
+ * Find every feature engine: each src/*-engine.js leaf declares exactly one `export const NAME_ENGINE = n;` line.
+ * A feature that raises the engine adds its own new file and no line of any shared one, so two items adding
+ * different engines never conflict [C7,V4]. The value is read as text because machine.js needs it synchronously.
+ *
+ * @param {URL} directory the folder holding the *-engine.js leaves
+ * @returns {Record<string, number>} engine number by file name, in name order
*/
-export const SUBMITTED_CONFLICT_ENGINE = 60;
-
-export const ENGINE_VERSION = Math.max(
- LOCAL_LANDING_ENGINE,
- HEALTH_CAP_ENGINE,
- SUBMITTED_CONFLICT_ENGINE,
- NATIVE_FLAKE_ENGINE,
- ROW_DRAFT_ENGINE,
- AUTO_ESCALATE_ENGINE,
- RIGOR_NOTICE_ENGINE,
- WITHDRAW_MILESTONE_ENGINE,
- STRONG_REJECTION_NOTICE_ENGINE,
- 52,
- 56,
- RECURRING_JOB_ENGINE,
-);
+export function discoverEngines(directory = new URL('./', import.meta.url)) {
+ const found = {};
- for (const file of readdirSync(directory).filter((name) => /-engine\.js$/u.test(name)).sort()) {
++ for (const file of discovered(readdirSync(directory), ENGINE_CANDIDATE, ENGINE_FILE, 'feature engine')) {
+ const lines = readFileSync(new URL(file, directory), 'utf8').split('\n').filter((line) => /^export const /u.test(line));
+ const match = lines.length === 1 ? /^export const [A-Z][A-Z0-9_]*_ENGINE = (\d+);$/u.exec(lines[0]) : null;
+ if (!match) throw new Error(`${file} must declare exactly one line \`export const NAME_ENGINE = <number>;\` so ENGINE_VERSION can read it`);
+ found[file.slice(0, -'-engine.js'.length)] = Number(match[1]);
+ }
+ return found;
+}
+
+/** Every feature engine by name, discovered from the *-engine.js files beside this one. */
+export const ENGINE_REGISTRY = discoverEngines();
+
+/** The highest engine number any feature declares. */
+export const ENGINE_VERSION = Math.max(...Object.values(ENGINE_REGISTRY));
/**
* The engine whose relay moves carry seat provenance and verifier standing (#579). It is its own
diff --cc test/affected-tests.test.js
index b0130f9c,b5269d1a..f65512a4
--- a/test/affected-tests.test.js
+++ b/test/affected-tests.test.js
@@@ -311,32 -311,3 +311,50 @@@ test('a declaration counts only in the
const braces = box.commit();
assert.equal(selectAffectedTests(box.root, { base: after, commit: braces, changed: ['src/actual.js'] }).full, true, 'an unexpandable glob falls back');
});
+
+test('a discovered command module or engine leaf selects what reads its registry [C7,V4]', (t) => {
+ const box = graph(t);
+ box.put('bin/pullboard.js', "import '../src/cli.js';\n");
+ box.put('src/cli.js', "import './commands/index.js';\nimport './machine.js';\n");
+ box.put('src/commands/index.js', "const modules = (file) => import(new URL(file, import.meta.url).href);\nexport const COMMANDS = { alpha: () => modules('./alpha.js') };\n");
+ box.put('src/commands/alpha.js', 'export function run() { return 0; }\n');
+ box.put('src/machine.js', "import { readFileSync } from 'node:fs';\nexport const ENGINE_VERSION = readFileSync('x-engine.js', 'utf8').length;\n");
+ box.put('src/x-engine.js', 'export const X_ENGINE = 1;\n');
+ box.put('src/unrelated.js', 'export const value = 1;\n');
+ box.put('test/direct-cli.test.js', "const BIN = '../bin/pullboard.js';\n");
+ box.put('test/machine-reader.test.js', "import '../src/machine.js';\n");
+ box.put('test/unrelated.test.js', "import '../src/unrelated.js';\n");
+ const base = box.commit();
+
+ box.put('src/commands/alpha.js', 'export function run() { return 1; }\n');
+ const commandCommit = box.commit();
+ const command = selectAffectedTests(box.root, { base, commit: commandCommit });
+ assert.equal(command.full, false, command.reason);
+ assert.ok(command.files.includes('test/direct-cli.test.js'), 'a changed command module selects the tests that run the CLI');
+ assert.ok(!command.files.includes('test/unrelated.test.js'), 'and nothing unrelated');
+
+ box.put('src/x-engine.js', 'export const X_ENGINE = 2;\n');
+ const engineCommit = box.commit();
+ const engine = selectAffectedTests(box.root, { base: commandCommit, commit: engineCommit });
+ assert.equal(engine.full, false, engine.reason);
+ assert.ok(engine.files.includes('test/machine-reader.test.js'), 'a changed engine leaf selects the tests that import machine.js');
+ assert.ok(!engine.files.includes('test/unrelated.test.js'), 'and nothing unrelated');
+});
++
++test('runtime discovery and the selector agree on which files are engines and commands [C7,V4]', (t) => {
++ const box = graph(t);
++ box.put('src/machine.js', "import { readFileSync } from 'node:fs';\nexport const ENGINE_VERSION = readFileSync('x-engine.js', 'utf8').length;\n");
++ box.put('src/commands/index.js', "const modules = (file) => import(new URL(file, import.meta.url).href);\nexport const COMMANDS = { alpha: () => modules('./alpha.js') };\n");
++ box.put('test/reader.test.js', "import '../src/machine.js';\n");
++ box.put('test/commands.test.js', "import '../src/commands/index.js';\n");
++ box.put('test/unrelated.test.js', 'export const value = 1;\n');
++ let base = box.commit();
++ for (const [file, reader] of [['src/check-alpha-engine.js', 'test/reader.test.js'], ['src/check.alpha-engine.js', 'test/reader.test.js'],
++ ['src/commands/beta.js', 'test/commands.test.js'], ['src/commands/gamma.delta.js', 'test/commands.test.js']]) {
++ box.put(file, 'export const ENGINE = 1;\n');
++ const commit = box.commit();
++ const selected = selectAffectedTests(box.root, { base, commit });
++ assert.ok(selected.full || selected.files.includes(reader), `${file} reaches ${reader} or falls back to the full suite, never selects nothing`);
++ base = commit;
++ }
++});
diff --cc test/engine.test.js
index bcce4c60,fab5aa34..de315001
--- a/test/engine.test.js
+++ b/test/engine.test.js
@@@ -2,7 -1,7 +2,7 @@@
/** @pullboard-test-loads src/engine.js src/machine.js */
/** Real-SQLite tests for the deterministic, sequence-ordered move engine [H3,H16]. */
import assert from 'node:assert/strict';
- import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
-import { mkdtempSync, rmSync } from 'node:fs';
++import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
@@@ -10,7 -9,7 +10,8 @@@ import { test } from 'node:test'
import * as store from '../src/board.js';
import { exportBoard, importBoard, restoreRelaySnapshot } from '../src/exchange.js';
import { applyEngineMove, applyRelayMove, prepareEngineMove, appliedSequence, engineReceipt, refuseRelayMove, startRelayEpoch, checkpointSequence, ENGINE_OPERATIONS } from '../src/engine.js';
- import { ENGINE_REGISTRY, ENGINE_VERSION } from '../src/machine.js';
-import { ENGINE_VERSION } from '../src/machine.js';
++import { COMMAND_CANDIDATE, COMMAND_FILE, discovered } from '../src/discovery.js';
++import { ENGINE_REGISTRY, ENGINE_VERSION, discoverEngines } from '../src/machine.js';
import { Refused } from '../src/refused.js';
import { unpackRelease } from './release-archive.js';
@@@ -624,15 -623,3 +625,27 @@@ test('a failed durable receipt rolls ba
assert.deepEqual(exportBoard(board), before, 'receipt failure cannot leave a committed claim without its replay position');
assert.equal(replayCursor(board), 0);
});
+
+test('the engine version is the highest feature engine [C7,V4]', () => {
+ const entries = Object.entries(ENGINE_REGISTRY);
+ assert.ok(entries.length > 0, 'the registry names at least one feature engine');
+ for (const [name, engine] of entries) assert.ok(Number.isSafeInteger(engine) && engine > 0, `feature ${name} declares a positive whole engine number`);
+ assert.equal(ENGINE_VERSION, Math.max(...entries.map(([, engine]) => engine)), 'the engine version is the highest number any feature declares');
+ const source = new URL('../src/', import.meta.url);
+ const files = readdirSync(source).filter((file) => /-engine\.js$/u.test(file));
+ assert.deepEqual(Object.keys(ENGINE_REGISTRY), files.map((file) => file.slice(0, -'-engine.js'.length)).sort(), 'every src/*-engine.js leaf is a feature engine, discovered by its file name');
+ for (const file of files) assert.match(readFileSync(new URL(file, source), 'utf8'), /^export const [A-Z][A-Z0-9_]*_ENGINE = \d+;$/mu, `${file} declares its one engine constant`);
+ assert.doesNotMatch(readFileSync(new URL('machine.js', source), 'utf8'), /Math\.max\([A-Z_]+ENGINE,/u, 'src/machine.js lists no engine by name');
+});
++
++test('a feature engine or command file name outside letters, digits, underscore and hyphen is refused by discovery [C7,V4]', () => {
++ const directory = mkdtempSync(join(tmpdir(), 'pullboard-discovery-'));
++ try {
++ writeFileSync(join(directory, 'check-alpha-engine.js'), 'export const CHECK_ALPHA_ENGINE = 70;\n');
++ assert.deepEqual(discoverEngines(pathToFileURL(directory + '/')), { 'check-alpha': 70 }, 'a hyphenated engine file is discovered');
++ writeFileSync(join(directory, 'check.beta-engine.js'), 'export const CHECK_BETA_ENGINE = 71;\n');
++ assert.throws(() => discoverEngines(pathToFileURL(directory + '/')), /check\.beta-engine\.js cannot be a feature engine/u, 'a dotted engine file is refused by name');
++ } finally { rmSync(directory, { recursive: true, force: true }); }
++ assert.deepEqual(discovered(['index.js', 'add.js', 'two-words.js'], COMMAND_CANDIDATE, COMMAND_FILE, 'command'), ['add.js', 'two-words.js']);
++ assert.throws(() => discovered(['index.js', 'add.js', 'a.b.js'], COMMAND_CANDIDATE, COMMAND_FILE, 'command'), /a\.b\.js cannot be a command/u, 'a dotted command file is refused by name');
++});