@agentwhy/cli 0.0.0-dev

package/dist/adapter/codex/events/turn-permissions.js

@@ -0,0 +1,60 @@
+import { isJsonObject } from '../../../shared/json.js';
+import { APPROVAL_POLICIES, APPROVERS, PERMISSIONS, SANDBOX_TYPES, SCOPE_ACCESS, SCOPE_TARGETS } from '../contract/permissions.js';
+/**
+ * The permissions a `turn_context` recorded (X22): kept as recorded settings, apart from agentwhy's policy. A value the
+ * contract does not list is not copied into the model - it is said as unrecognised, and the record as incomplete.
+ */
+export function permissionsOf(context) {
+    let complete = true;
+    const known = (value, list) => {
+        if (value === undefined)
+            return undefined;
+        const found = list.find((each) => each === value);
+        if (found === undefined)
+            complete = false;
+        return found;
+    };
+    const approval = known(context[PERMISSIONS.approval], APPROVAL_POLICIES);
+    const approverValue = context[PERMISSIONS.approver];
+    const approver = approverValue === undefined
+        ? 'unrecorded'
+        : typeof approverValue === 'string' && Object.hasOwn(APPROVERS, approverValue)
+            ? APPROVERS[approverValue]
+            : 'unrecognised';
+    if (approver === 'unrecognised')
+        complete = false;
+    const sandboxPolicy = context[PERMISSIONS.sandbox];
+    const sandbox = isJsonObject(sandboxPolicy) ? known(sandboxPolicy[PERMISSIONS.sandboxType], SANDBOX_TYPES) : undefined;
+    const networkValue = isJsonObject(sandboxPolicy) ? sandboxPolicy[PERMISSIONS.network] : undefined;
+    const network = networkValue === undefined ? 'unrecorded' : networkValue === true ? 'allowed' : networkValue === false ? 'restricted' : 'unrecognised';
+    if (network === 'unrecognised')
+        complete = false;
+    const fileSystem = context[PERMISSIONS.fileSystem];
+    const entries = isJsonObject(fileSystem) ? fileSystem[PERMISSIONS.entries] : undefined;
+    const scopes = Array.isArray(entries) ? entries.map((entry) => scopeOf(entry, () => { complete = false; })) : [];
+    if (fileSystem !== undefined && !Array.isArray(entries))
+        complete = false;
+    return {
+        ...(approval === undefined ? {} : { approval }),
+        approver,
+        ...(sandbox === undefined ? {} : { sandbox }),
+        network,
+        scopes,
+        complete,
+    };
+}
+function scopeOf(entry, unknownPart) {
+    const access = isJsonObject(entry) ? SCOPE_ACCESS.find((each) => each === entry[PERMISSIONS.access]) : undefined;
+    const target = isJsonObject(entry) ? entry[PERMISSIONS.target] : undefined;
+    const type = isJsonObject(target) ? target[PERMISSIONS.targetType] : undefined;
+    const path = isJsonObject(target) ? target[PERMISSIONS.targetPath] : undefined;
+    const scope = {
+        access: access ?? 'unrecognised',
+        target: type === SCOPE_TARGETS.path && typeof path === 'string'
+            ? { kind: 'path', path }
+            : type === SCOPE_TARGETS.special ? { kind: 'special' } : { kind: 'unrecognised' },
+    };
+    if (scope.access === 'unrecognised' || scope.target.kind === 'unrecognised')
+        unknownPart();
+    return scope;
+}

package/dist/adapter/codex/hooks/pre-tool-use-input.js

@@ -0,0 +1,24 @@
+import { PRE_TOOL_USE } from '../contract/hooks.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+/**
+ * Reads the text a Codex `PreToolUse` hook was given (`codex-blocks-too` CK4): the command line of a shell call, and the
+ * session's folder, which `refuse --codex` looks for the project from (CK3). A call to any tool but the shell is
+ * `another-tool`, and passes. Never throws. The fields are Codex's own, measured (CKB2); that they are named as Claude
+ * Code's are is an observation, not a shared definition.
+ */
+export function parseCodexPreToolUseInput(text) {
+    const input = parseJsonObject(text);
+    if (input === undefined)
+        return { unusable: 'not-json' };
+    const { fields } = PRE_TOOL_USE;
+    if (input[fields.event] !== PRE_TOOL_USE.event)
+        return { unusable: 'another-event' };
+    if (input[fields.toolName] !== PRE_TOOL_USE.shellTool)
+        return { anotherTool: true };
+    const toolInput = input[fields.toolInput];
+    const command = isJsonObject(toolInput) ? toolInput[fields.command] : undefined;
+    if (typeof command !== 'string')
+        return { unusable: 'field-missing' };
+    const cwd = input[fields.cwd];
+    return typeof cwd === 'string' && cwd !== '' ? { command, cwd } : { command };
+}

package/dist/adapter/codex/hooks/stop-refusals.js

@@ -0,0 +1,57 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { CODE_CELL } from '../contract/deliveries.js';
+import { ENVELOPE, LINE_TYPES } from '../contract/envelope.js';
+import { STOP } from '../contract/hooks.js';
+import { RESPONSE_ITEMS } from '../contract/messages.js';
+import { RESPONSE_TURN } from '../contract/turns.js';
+import { hookRefusalsIn } from '../events/hook-refusals.js';
+/**
+ * `Stop` has a session id, a turn id and (outside ephemeral runs) a transcript path. The rollout reader already
+ * recognizes agentwhy's own refusal text in a code cell's output; this narrow reader applies that recognizer only to
+ * outputs with the Stop input's turn id. It never returns any other transcript content.
+ */
+export class CodexTurnRefusals {
+    #input;
+    #files;
+    constructor(input, files) {
+        this.#input = input;
+        this.#files = files;
+    }
+    async find() {
+        const text = await this.#input.readAll(1024 * 1024);
+        const input = text === undefined ? undefined : parseJsonObject(text);
+        if (input === undefined || input[STOP.fields.event] !== STOP.event || input[STOP.fields.active] === true)
+            return [];
+        const turnId = input[STOP.fields.turnId];
+        const path = input[STOP.fields.transcriptPath];
+        if (typeof turnId !== 'string' || turnId === '' || typeof path !== 'string' || path === '')
+            return [];
+        const found = [];
+        try {
+            for await (const raw of this.#files.readLines(path)) {
+                const line = parseJsonObject(raw);
+                if (line?.[ENVELOPE.type] !== LINE_TYPES.responseItem)
+                    continue;
+                const payload = line[ENVELOPE.payload];
+                if (!isJsonObject(payload) || payload[ENVELOPE.payloadType] !== RESPONSE_ITEMS.codeCellOutput)
+                    continue;
+                const metadata = payload[RESPONSE_TURN.metadata];
+                if (!isJsonObject(metadata) || metadata[RESPONSE_TURN.turnId] !== turnId)
+                    continue;
+                const output = payload[CODE_CELL.output];
+                const parts = typeof output === 'string' ? [output] : Array.isArray(output)
+                    ? output.flatMap((part) => isJsonObject(part) && part[CODE_CELL.partType] === CODE_CELL.textPart &&
+                        typeof part[CODE_CELL.partText] === 'string' ? [part[CODE_CELL.partText]] : [])
+                    : [];
+                found.push(...hookRefusalsIn(parts.join('\n')));
+            }
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return [];
+        }
+        return found;
+    }
+}

package/dist/adapter/codex/probe/codex-doctor-report.js

@@ -0,0 +1 @@
+export {};

package/dist/adapter/codex/probe/codex-probe.js

@@ -0,0 +1,268 @@
+import { basename } from 'node:path';
+import { Counter } from '../../../shared/counter.js';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { agentSource } from '../../../core/evidence.js';
+import { ACTION_ITEMS, COMMAND, ITEM, ITEM_EVENT, ITEM_STATUSES, SHELL_FLAGS, SHELLS } from '../contract/actions.js';
+import { ACTIVITY } from '../contract/delegations.js';
+import { ENVELOPE, LEGACY_EVENTS, LINE_TYPES, PASSIVE_EVENTS } from '../contract/envelope.js';
+import { EVENT_MESSAGES, MESSAGE_ITEMS, REASONING, RESPONSE_ITEMS } from '../contract/messages.js';
+import { SESSION } from '../contract/session.js';
+import { TURN_CONTEXT, TURN_EVENTS } from '../contract/turns.js';
+import { CONTRACT_VERSION, VERIFIED_AGAINST } from '../contract/version.js';
+import { sessionOwners, AMBIGUOUS } from '../discovery/session-owners.js';
+import { sessionRoots } from '../discovery/session-roots.js';
+import { capabilitiesOf } from '../events/capability-records.js';
+import { permissionsOf } from '../events/turn-permissions.js';
+const UNKNOWN = '<unknown>';
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const KNOWN_LINES = Object.values(LINE_TYPES);
+const KNOWN_RESPONSES = Object.values(RESPONSE_ITEMS);
+const KNOWN_EVENTS = [
+    ITEM_EVENT.type, TURN_EVENTS.started, TURN_EVENTS.complete, TURN_EVENTS.aborted, EVENT_MESSAGES.user, EVENT_MESSAGES.agent,
+    ...PASSIVE_EVENTS, ...LEGACY_EVENTS,
+];
+const KNOWN_ITEMS = [...Object.values(ACTION_ITEMS), ...Object.values(MESSAGE_ITEMS), ACTIVITY.type];
+const ACTIONS = Object.values(ACTION_ITEMS);
+const LEGACY = LEGACY_EVENTS;
+/** A label from a fixed vocabulary, or `<unknown>`: an unknown spelling is counted and never printed (X24). */
+function known(value, vocabulary) {
+    return typeof value === 'string' && vocabulary.includes(value) ? value : UNKNOWN;
+}
+/**
+ * Measures Codex rollouts for `doctor` (X26): a file given by name, or every rollout under a folder. It shares the
+ * ownership rule with discovery and the reconnaissance probe (`sessionOwners`), and reads the contract's vocabularies
+ * rather than the probe script, which stays a tool of its own (spec §8).
+ */
+export class CodexProbe {
+    #discovery;
+    #directories;
+    #files;
+    constructor(dependencies) {
+        this.#discovery = dependencies.discovery;
+        this.#directories = dependencies.directories;
+        this.#files = dependencies.files;
+    }
+    async probe(input) {
+        const tally = new Tally();
+        const sources = await this.#sources(input, tally);
+        const owners = sessionOwners(sources.map((source) => (source.header.id === '' ? undefined : source.header.id)));
+        for (const [id, owner] of owners) {
+            if (owner === AMBIGUOUS) {
+                tally.sharedIds += 1;
+                tally.filesSharingIds += sources.filter((source) => source.header.id === id).length;
+            }
+            else
+                tally.uniqueIds += 1;
+        }
+        for (const source of sources) {
+            const { header } = source;
+            tally.versions.add(known(header.version, VERIFIED_AGAINST.codex));
+            tally.historyModes.add(header.historyMode === 'unknown' ? UNKNOWN : header.historyMode);
+            tally.origins.add(header.origin.kind);
+            const named = UUID.exec(basename(source.path))?.[0];
+            if (named !== undefined && named.toLowerCase() !== header.id.toLowerCase())
+                tally.fileNameDisagrees += 1;
+            if (source.relation.kind === 'resolved') {
+                if (sources[source.relation.root] === source)
+                    tally.roots += 1;
+                else
+                    tally.descendants += 1;
+            }
+            else
+                tally.unresolved.add(source.relation.reason);
+            await this.#file(source, tally);
+        }
+        return tally.report();
+    }
+    /** The rollouts to measure: the file given, or the recognised rollouts under a folder, each with its tree relation. */
+    async #sources(input, tally) {
+        let kind;
+        try {
+            kind = await this.#directories.kindOf(input);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            tally.unreadable += 1;
+            return [];
+        }
+        if (kind === 'directory') {
+            const listing = await this.#discovery.list(input);
+            const unknownFormat = listing.gaps.filter((gap) => gap.reason === 'unknown-format').length;
+            tally.found += listing.sources.length + unknownFormat;
+            tally.unknownFormat += unknownFormat;
+            tally.unreadable += listing.gaps.length - unknownFormat;
+            return listing.sources;
+        }
+        tally.found += 1;
+        const head = await this.#discovery.readHeader(input);
+        if (head.kind === 'unknown')
+            tally.unknownFormat += 1;
+        if (head.kind === 'unavailable')
+            tally.unreadable += 1;
+        if (head.kind !== 'recognised')
+            return [];
+        return [{ path: input, header: head.header, relation: sessionRoots([head.header])[0] ?? { kind: 'unresolved', reason: 'invalid-identity' } }];
+    }
+    async #file(source, tally) {
+        tally.recognised += 1;
+        const directories = new Set();
+        let lastOrdinal;
+        let metadata = 0;
+        const facts = { unrecognised: false, interrupted: false, hiddenReasoning: false, permissionsIncomplete: false, permissionsRecorded: false };
+        try {
+            for await (const raw of this.#files.readLines(source.path)) {
+                if (raw.trim() === '')
+                    continue;
+                tally.lines += 1;
+                const line = parseJsonObject(raw);
+                if (line === undefined) {
+                    tally.unparsable += 1;
+                    continue;
+                }
+                const ordinal = line[ENVELOPE.ordinal];
+                if (typeof ordinal === 'number') {
+                    if (lastOrdinal !== undefined && ordinal < lastOrdinal)
+                        tally.ordinalBackwards += 1;
+                    if (lastOrdinal !== undefined && ordinal === lastOrdinal)
+                        tally.ordinalRepeats += 1;
+                    lastOrdinal = ordinal;
+                }
+                const type = known(line[ENVELOPE.type], KNOWN_LINES);
+                tally.lineTypes.add(type);
+                if (type === UNKNOWN)
+                    facts.unrecognised = true;
+                const payload = line[ENVELOPE.payload];
+                if (!isJsonObject(payload))
+                    continue;
+                if (type === LINE_TYPES.sessionMeta) {
+                    metadata += 1;
+                    const directory = payload[SESSION.workingDirectory];
+                    if (typeof directory === 'string')
+                        directories.add(directory);
+                }
+                if (type === LINE_TYPES.turnContext) {
+                    const directory = payload[TURN_CONTEXT.workingDirectory];
+                    if (typeof directory === 'string')
+                        directories.add(directory);
+                    facts.permissionsRecorded = true;
+                    if (!permissionsOf(payload).complete)
+                        facts.permissionsIncomplete = true;
+                }
+                if (type === LINE_TYPES.responseItem) {
+                    const kind = known(payload[ENVELOPE.payloadType], KNOWN_RESPONSES);
+                    tally.responseItems.add(kind);
+                    if (kind === UNKNOWN)
+                        facts.unrecognised = true;
+                    if (kind === RESPONSE_ITEMS.reasoning && !readableSummary(payload[REASONING.summary]))
+                        facts.hiddenReasoning = true;
+                }
+                if (type === LINE_TYPES.event) {
+                    const kind = known(payload[ENVELOPE.payloadType], KNOWN_EVENTS);
+                    tally.events.add(kind);
+                    // A legacy event is a label the contract knows and a record the reader cannot map, and so is an item event with
+                    // no item: both are unrecognised to the reader (`rollout-scan.ts`), so what the file can answer is said alike.
+                    if (kind === UNKNOWN || LEGACY.includes(kind))
+                        facts.unrecognised = true;
+                    if (kind === TURN_EVENTS.aborted)
+                        facts.interrupted = true;
+                    const item = payload[ITEM_EVENT.item];
+                    if (kind === ITEM_EVENT.type && !isJsonObject(item))
+                        facts.unrecognised = true;
+                    if (kind === ITEM_EVENT.type && isJsonObject(item)) {
+                        const itemType = known(item[ITEM.type], KNOWN_ITEMS);
+                        tally.items.add(itemType);
+                        if (itemType === UNKNOWN)
+                            facts.unrecognised = true;
+                        if (itemType === UNKNOWN || ACTIONS.includes(itemType)) {
+                            tally.itemStatuses.add(`${itemType} ${item[ITEM.status] === undefined ? '(none)' : known(item[ITEM.status], Object.values(ITEM_STATUSES))}`);
+                        }
+                        if (itemType === ACTION_ITEMS.command)
+                            tally.commandShapes.add(commandShape(item[COMMAND.command]));
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            tally.unreadable += 1;
+        }
+        if (metadata > 1)
+            tally.laterMetadata += metadata - 1;
+        if (directories.size > 1)
+            tally.filesWithSeveral += 1;
+        if (directories.size === 0)
+            tally.filesWithNone += 1;
+        for (const record of capabilitiesOf(source.header, agentSource(source.header.id), source.header.id, facts)) {
+            tally.capabilities.add(`${record.question} ${record.state}`);
+        }
+    }
+}
+/** X7: a command read as a line, or kept whole. */
+function commandShape(command) {
+    return Array.isArray(command) && command.length === 3 && typeof command[0] === 'string' && SHELLS.some((shell) => shell === basename(command[0]))
+        && SHELL_FLAGS.some((flag) => flag === command[1]) && typeof command[2] === 'string' ? 'recognised' : 'other';
+}
+function readableSummary(summary) {
+    return Array.isArray(summary) && summary.some((part) => isJsonObject(part) && typeof part[REASONING.summaryText] === 'string' && part[REASONING.summaryText] !== '');
+}
+/** What a run counts, turned into the closed report. */
+class Tally {
+    found = 0;
+    recognised = 0;
+    unknownFormat = 0;
+    unreadable = 0;
+    lines = 0;
+    unparsable = 0;
+    uniqueIds = 0;
+    sharedIds = 0;
+    filesSharingIds = 0;
+    fileNameDisagrees = 0;
+    laterMetadata = 0;
+    roots = 0;
+    descendants = 0;
+    filesWithSeveral = 0;
+    filesWithNone = 0;
+    ordinalBackwards = 0;
+    ordinalRepeats = 0;
+    versions = new Counter();
+    historyModes = new Counter();
+    origins = new Counter();
+    unresolved = new Counter();
+    lineTypes = new Counter();
+    responseItems = new Counter();
+    events = new Counter();
+    items = new Counter();
+    itemStatuses = new Counter();
+    commandShapes = new Counter();
+    capabilities = new Counter();
+    report() {
+        return {
+            schemaVersion: 1,
+            provider: 'codex',
+            contractVersion: CONTRACT_VERSION,
+            verifiedAgainst: VERIFIED_AGAINST.codex,
+            files: { found: this.found, recognised: this.recognised, unknownFormat: this.unknownFormat, unreadable: this.unreadable },
+            lines: { total: this.lines, unparsable: this.unparsable },
+            versions: this.versions.toCounts(),
+            historyModes: this.historyModes.toCounts(),
+            origins: this.origins.toCounts(),
+            identity: {
+                uniqueIds: this.uniqueIds, sharedIds: this.sharedIds, filesSharingIds: this.filesSharingIds,
+                fileNameDisagrees: this.fileNameDisagrees, laterMetadata: this.laterMetadata,
+            },
+            tree: { roots: this.roots, descendants: this.descendants, unresolved: this.unresolved.toCounts() },
+            workingDirectories: { filesWithSeveral: this.filesWithSeveral, filesWithNone: this.filesWithNone },
+            order: { ordinalBackwards: this.ordinalBackwards, ordinalRepeats: this.ordinalRepeats },
+            lineTypes: this.lineTypes.toCounts(),
+            responseItems: this.responseItems.toCounts(),
+            events: this.events.toCounts(),
+            items: this.items.toCounts(),
+            itemStatuses: this.itemStatuses.toCounts(),
+            commandShapes: this.commandShapes.toCounts(),
+            capabilities: this.capabilities.toCounts(),
+        };
+    }
+}

package/dist/adapter/codex/settings/codex-hooks.js

@@ -0,0 +1,83 @@
+import { isJsonObject } from '../../../shared/json.js';
+import { PRE_TOOL_USE, PROJECT_HOOKS } from '../contract/hooks.js';
+/**
+ * agentwhy's Codex hook, and no one else's: `refuse` with `--codex` straight after it. Nothing but agentwhy writes that
+ * flag, so a command with it is taken out and replaced, and every other command in the file is left as it was (K13).
+ */
+const RUNS_CODEX_REFUSE = /(?:^|\s)refuse\s+--codex(?:\s|$)/;
+const RUNS_CODEX_STOP = /(?:^|\s)codex-stop\s+--codex(?:\s|$)/;
+/**
+ * The command agentwhy's Codex hook runs (`codex-blocks-too` CK3): the invocation, `refuse --codex`, and the settings
+ * file Claude Code's `refuse` reads, relative to the project, where it reads one. `refuse --codex` finds the project
+ * from the folder Codex runs it in, so no absolute path is written and the file works in a clone.
+ */
+export function codexRefuseCommand(invoke, settings) {
+    return `${invoke} refuse --codex${settings === undefined ? '' : ` --settings "${settings}"`}`;
+}
+/** The companion Stop hook asks Codex to credit agentwhy for a blocked command in its reply. */
+export function codexStopCommand(invoke) {
+    return `${invoke} codex-stop --codex`;
+}
+/** The command agentwhy's Codex hook runs in this file, where it runs one. */
+export function codexRefuseIn(file) {
+    return commandsOf(file, PRE_TOOL_USE.event).find((command) => RUNS_CODEX_REFUSE.test(command));
+}
+export function codexStopIn(file) {
+    return commandsOf(file, 'Stop').find((command) => RUNS_CODEX_STOP.test(command));
+}
+/** The file with agentwhy's Codex hook running `command`, on the shell's `PreToolUse`, in place of any it had (CK5). */
+export function withCodexRefuse(file, command, stopCommand) {
+    const { file: without } = withoutCodexRefuse(file);
+    const hooks = isJsonObject(without[PROJECT_HOOKS.hooks]) ? { ...without[PROJECT_HOOKS.hooks] } : {};
+    const list = Array.isArray(hooks[PRE_TOOL_USE.event]) ? [...hooks[PRE_TOOL_USE.event]] : [];
+    const stops = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
+    list.push({
+        [PROJECT_HOOKS.matcher]: PRE_TOOL_USE.shellTool,
+        [PROJECT_HOOKS.commands]: [{ [PROJECT_HOOKS.type]: PROJECT_HOOKS.commandType, [PROJECT_HOOKS.command]: command }],
+    });
+    stops.push({ [PROJECT_HOOKS.commands]: [{ [PROJECT_HOOKS.type]: PROJECT_HOOKS.commandType, [PROJECT_HOOKS.command]: stopCommand }] });
+    return { ...without, [PROJECT_HOOKS.hooks]: { ...hooks, [PRE_TOOL_USE.event]: list, Stop: stops } };
+}
+/**
+ * The file without agentwhy's Codex hook. An entry left with no command is dropped, and an event left with no entry;
+ * the `hooks` object itself stays, empty or not, and so does every other key and hook.
+ */
+export function withoutCodexRefuse(file) {
+    const hooks = file[PROJECT_HOOKS.hooks];
+    if (!isJsonObject(hooks))
+        return { file, removed: 0 };
+    let removed = 0;
+    const kept = {};
+    for (const [event, list] of Object.entries(hooks)) {
+        if (!Array.isArray(list)) {
+            kept[event] = list;
+            continue;
+        }
+        const entries = list.flatMap((entry) => {
+            if (!isJsonObject(entry) || !Array.isArray(entry[PROJECT_HOOKS.commands]))
+                return [entry];
+            const commands = entry[PROJECT_HOOKS.commands].filter((item) => {
+                const ours = isJsonObject(item) && typeof item[PROJECT_HOOKS.command] === 'string' &&
+                    (event === PRE_TOOL_USE.event ? RUNS_CODEX_REFUSE.test(item[PROJECT_HOOKS.command]) :
+                        event === 'Stop' && RUNS_CODEX_STOP.test(item[PROJECT_HOOKS.command]));
+                if (ours)
+                    removed += 1;
+                return !ours;
+            });
+            return commands.length === 0 ? [] : [{ ...entry, [PROJECT_HOOKS.commands]: commands }];
+        });
+        if (entries.length > 0)
+            kept[event] = entries;
+    }
+    return { file: removed === 0 ? file : { ...file, [PROJECT_HOOKS.hooks]: kept }, removed };
+}
+function commandsOf(file, event) {
+    const hooks = file[PROJECT_HOOKS.hooks];
+    if (!isJsonObject(hooks))
+        return [];
+    return [hooks[event]].flatMap((list) => Array.isArray(list)
+        ? list.flatMap((entry) => isJsonObject(entry) && Array.isArray(entry[PROJECT_HOOKS.commands])
+            ? entry[PROJECT_HOOKS.commands].flatMap((item) => isJsonObject(item) && typeof item[PROJECT_HOOKS.command] === 'string' ? [item[PROJECT_HOOKS.command]] : [])
+            : [])
+        : []);
+}

package/dist/cli/cli-command.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/command-router.js

@@ -0,0 +1,42 @@
+const HELP_FLAGS = ['--help', '-h'];
+/** Dispatches argv to the registered command of that name. Adding a command never changes the router. */
+export class CommandRouter {
+    #commands;
+    #withoutACommand;
+    /**
+     * `withoutACommand` answers `agentwhy` with nothing after it, and with arguments that begin with `-` (they are its
+     * flags); without one, that stays a usage error. It may also be registered under its own name.
+     */
+    constructor(commands, withoutACommand) {
+        this.#withoutACommand = withoutACommand;
+        const byName = new Map();
+        for (const command of commands) {
+            if (byName.has(command.name))
+                throw new Error(`duplicate command: ${command.name}`);
+            byName.set(command.name, command);
+        }
+        this.#commands = byName;
+    }
+    /** The usage of every command, in registration order, after the one a bare `agentwhy` runs, and never twice. */
+    get usage() {
+        const commands = new Set([...(this.#withoutACommand === undefined ? [] : [this.#withoutACommand]), ...this.#commands.values()]);
+        return [...commands].map((command) => command.usage).join('\n');
+    }
+    async route(argv) {
+        const [name, ...args] = argv;
+        if (name !== undefined && HELP_FLAGS.includes(name))
+            return { kind: 'help', usage: this.usage };
+        if (name === undefined) {
+            return this.#withoutACommand === undefined ? this.#usageError('missing command') : this.#withoutACommand.execute([]);
+        }
+        if (name.startsWith('-') && this.#withoutACommand !== undefined)
+            return this.#withoutACommand.execute(argv);
+        const command = this.#commands.get(name);
+        if (command === undefined)
+            return this.#usageError(`unknown command: ${name}`);
+        return command.execute(args);
+    }
+    #usageError(message) {
+        return { kind: 'usage-error', message, usage: this.usage };
+    }
+}