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.

fix(help): settings forms and every printed subcommand have help [N2]

Corey Olson19cedc9cf297
diff --git a/src/cli.js b/src/cli.js
index bf20e2d4..860e236b 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -167,6 +167,7 @@ import {
import { lifecycleMarkdown } from './machine.js';
import {
buildHelp,
+ SETTING_FORMS,
VERSION,
} from './help.js';
import {
@@ -3855,7 +3856,7 @@ function settingsCommand(io, { first, second, rest }) {
io.say(`gate.shortSlots: ${shortSlots}${shortSlots ? '' : ' (off; runs that name their test files wait for a gate slot)'}`);
return 0;
}
- if (!['gateSlots', 'browserSlots', 'gate.shortSlots'].includes(first) || !second || rest.length) {
+ if (!SETTING_FORMS.includes(first) || !second || rest.length) {
throw new Refused('USAGE', 'pullboard settings gateSlots <n> | browserSlots <n> | gate.shortSlots <n>');
}
if (first === 'gate.shortSlots') {
diff --git a/src/help.js b/src/help.js
index d24bd785..8dea26be 100644
--- a/src/help.js
+++ b/src/help.js
@@ -360,7 +360,7 @@ function commandHelpRows(fullHelp, commandNames) {
// Every printed subcommand phrase (milestone items, relay devices) is a name too, so its help exists [N2].
...lines.filter((line) => line.startsWith(' pullboard ')).flatMap((line) => usagePhrases(line.trim())).filter((phrase) => phrase.includes(' ')),
])];
- return Object.fromEntries(names.map((name) => {
+ const entries = Object.fromEntries(names.map((name) => {
const parts = name.split(' ');
const alias = HELP_ALIASES[name];
const matches = alias?.source ? rows.filter((row) => row.usage === alias.source || row.usage.startsWith(`${alias.source} `)) : alias ? [] : rows.filter((row) => {
@@ -384,6 +384,7 @@ function commandHelpRows(fullHelp, commandNames) {
const example = exampleFor(name, usages[0]);
return [name, Object.freeze({ usages, flags, example, notes: HELP_NOTES[name] ?? [] })];
}));
+ return { ...entries, ...settingFormHelp(entries) };
}
/** Render the short first-run overview, with command names grouped by when a person needs them. */
@@ -399,7 +400,22 @@ function overviewHelp(groups, firstRun = false) {
return lines.join('\n');
}
-/** Build help from the actual command declarations, preserving the printed overview and full list. */
+/** The settings forms settingsCommand dispatches with a value; each gets its own help, from this list (N2). */
+export const SETTING_FORMS = Object.freeze(['gateSlots', 'browserSlots', 'gate.shortSlots']);
+
+/** Help for each settings form the printed usage did not already name, so each form is covered (N2). */
+function settingFormHelp(commands) {
+ return Object.fromEntries(SETTING_FORMS.filter((form) => !commands[`settings ${form}`]).map((form) => [`settings ${form}`, Object.freeze({
+ usages: [`pullboard settings ${form} <n>`], flags: [], example: `pullboard settings ${form} 2`, notes: [],
+ })]));
+}
+
+/**
+ * Build help from the actual command declarations, preserving the printed overview and full list.
+ *
+ * @param {string[]} [commandNames]
+ * @returns {Readonly<object>}
+ */
export function buildHelp(commandNames = []) {
return Object.freeze({
overview: overviewHelp(HELP_GROUPS),
@@ -472,6 +488,7 @@ export function commandPhrases(help = HELP) {
for (const line of help.all.split('\n')) {
if (line.startsWith(' pullboard ')) for (const phrase of usagePhrases(line.trim())) phrases.add(phrase);
}
+ for (const form of SETTING_FORMS) phrases.add(`settings ${form}`);
for (const [name, declaration] of Object.entries(help.commands)) {
if (/^[a-z][a-z0-9-]*(?: [a-z][a-z0-9-]*)*$/u.test(name)) phrases.add(name);
for (const usage of declaration.usages) for (const phrase of usagePhrases(usage)) phrases.add(phrase);
diff --git a/test/cli-help.test.js b/test/cli-help.test.js
index 5408ee59..12aabb1d 100644
--- a/test/cli-help.test.js
+++ b/test/cli-help.test.js
@@ -231,7 +231,7 @@ test('help add example runs on a fresh board [I1,L3]', (t) => {
test('help covers every dispatched subcommand [N2]', () => {
// Every printed subcommand phrase is one the CLI dispatches; each must have help, and an unknown name still refuses.
- const subcommands = helpDeclaration.commandPhrases(HELP).filter((phrase) => phrase.includes(' '));
+ const subcommands = [...new Set([...helpDeclaration.commandPhrases(HELP).filter((phrase) => phrase.includes(' ')), ...helpDeclaration.SETTING_FORMS.map((form) => `settings ${form}`)])];
assert.ok(subcommands.includes('milestone items') && subcommands.includes('relay devices') && subcommands.includes('spec approve'),
'the walk covers the subcommands that were refused before');
for (const phrase of subcommands) {
@@ -243,3 +243,21 @@ test('help covers every dispatched subcommand [N2]', () => {
assert.equal(unknown.status, 2, 'an unknown subcommand still exits 2');
assert.equal(unknown.stdout, '');
});
+
+test('the settings forms the CLI dispatches have help and reach their own refusal [N2]', () => {
+ // The expected forms are written out here, not read from the parser: each one must have help, and
+ // each must reach its own value check in settingsCommand, which proves the dispatcher knows it (#824).
+ assert.deepEqual([...helpDeclaration.SETTING_FORMS], ['gateSlots', 'browserSlots', 'gate.shortSlots']);
+ const folder = mkdtempSync(join(tmpdir(), 'pullboard-settings-'));
+ sandboxes.push(folder);
+ runFixtureGit(['init', '-q'], { cwd: folder });
+ const refusals = { gateSlots: '[USAGE]', browserSlots: '[BAD_BROWSER_SLOTS]', 'gate.shortSlots': '[BAD_SHORT_SLOTS]' };
+ for (const [form, code] of Object.entries(refusals)) {
+ const help = run('help', 'settings', form);
+ assert.equal(help.status, 0, `help settings ${form} exits 0: ${help.stderr}`);
+ assert.match(help.stdout, new RegExp(`^Usage: pullboard settings ${form.replace('.', '\\.')} `, 'u'), `help settings ${form} names its usage`);
+ const refused = runFixtureChild(process.execPath, [BIN, 'settings', form, 'abc'], { cwd: folder, encoding: 'utf8' });
+ assert.equal(refused.status, 1, `settings ${form} abc is refused: ${refused.stdout}`);
+ assert.ok(refused.stderr.includes(code), `settings ${form} reaches its own check ${code}: ${refused.stderr}`);
+ }
+});