Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(cli): migrate splits --to=/--url= (graduation read them on master); validator sees multi-line = values; disclose forget purge reason and sources pull path refusals; pin search --json=true and end_of_options agreement

garrytand798be07bc10
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index 34e2c2070b..ee23be4a8f 100644
--- a/scripts/structural-suites.tsv
+++ b/scripts/structural-suites.tsv
@@ -76,7 +76,7 @@ test/claude-cli-recipe.test.ts claude-cli LanguageModel — output cap (#6424) 2
test/claude-cli-recipe.test.ts claude-cli LanguageModel — text-only round trip 4 readFileSync
test/claude-cli-recipe.test.ts claude-cli LanguageModel — tool use 17 readFileSync
test/claude-cli-recipe.test.ts claude-cli recipe registration 2 readFileSync
-test/cli-flag-equals.test.ts #7619 refusals that keep consent, scope and targets right 17 readFileSync,source-surface-helper
+test/cli-flag-equals.test.ts #7619 refusals that keep consent, scope and targets right 20 readFileSync,source-surface-helper
test/cli-flag-equals.test.ts #7619 split rules 21 readFileSync,source-surface-helper
test/cli-force-exit-teardown-arming.test.ts cli.ts — disconnect hard-deadline armed at teardown entry, not before the op body 1 readFileSync,source-surface-helper
test/cli.test.ts BigInt-safe output normalization (#2450) 5 source-surface-helper
diff --git a/src/cli/flag-equals.ts b/src/cli/flag-equals.ts
index 618d5b3fbf..3194f5a5d6 100644
--- a/src/cli/flag-equals.ts
+++ b/src/cli/flag-equals.ts
@@ -116,7 +116,7 @@ export const EQUALS_READERS: Readonly<Record<string, readonly string[]>> = {
lint: ['--exclude'],
// migrate-graduation.ts:97 flagValue (parseGraduationArgs :121-151); graduation-only flags, the legacy copier (migrate-engine.ts) never reads them.
migrate: ['--url-env', '--trigger-bypass', '--drain-timeout', '--batch-size', '--expect'],
- // models.ts:853 doctor mode only (sub selection :817), repeated --skip=<provider>, =-only.
+ // models.ts:853 doctor mode only (sub selection :818), repeated --skip=<provider>, =-only.
'models doctor': ['--skip'],
// core/bounded-listing-cli.ts:15 parseListingFlags via orphans.ts:353.
orphans: ['--limit', '--cursor'],
@@ -210,6 +210,11 @@ export const COMMAND_SWITCHES: Readonly<Record<string, readonly string[]>> = {
embed: ['--stale'],
};
+/** Value flags of a command with no curated help that every path reads as `--flag <value>` (migrate-engine.ts parseArgs, migrate-graduation.ts flagValue and routesToGraduation); their `=` form splits. */
+export const COMMAND_VALUES: Readonly<Record<string, readonly string[]>> = {
+ migrate: ['--to', '--url'],
+};
+
/** Paths (`command sub`) whose handler treats a bare `--` as the end of its options; everywhere else the scan continues past it. */
export const END_OF_OPTIONS: ReadonlySet<string> = new Set(['agent run', 'frontmatter validate']);
@@ -250,7 +255,7 @@ export async function splitFlagEquals(command: string, args: readonly string[]):
const value = m[2]!;
if (flag === '--json' && value === 'true') { out.push(flag); continue; }
types ??= new Map((await loadCuratedHelp(command))?.flags.map(f => [f.name, f.type]));
- const own = types.get(flag) ?? (command === 'sync' ? (SYNC_FLAGS as Record<string, { arity: string }>)[flag]?.arity : undefined);
+ const own = types.get(flag) ?? (command === 'sync' ? (SYNC_FLAGS as Record<string, { arity: string }>)[flag]?.arity : undefined) ?? (COMMAND_VALUES[command]?.includes(flag) ? 'string' : undefined);
const isSwitch = own !== undefined ? own === 'boolean' : flag.startsWith('--no-') || COMMAND_SWITCHES[command]?.includes(flag) || (await knownSwitches()).has(flag);
const refusal = !legal
? [`${where} reads no = form`, `Check the flag in ${where} --help: write a switch on its own (a value never turns it off), or a value as the next argument.`]
@@ -273,7 +278,7 @@ export async function splitFlagEquals(command: string, args: readonly string[]):
export function findUnknownFlag(args: string[], legal: ReadonlySet<string>): string | null {
for (const a of args) {
if (a === '--') break;
- const m = /^--([a-z0-9][a-z0-9-]*)(?:=.*)?$/i.exec(a);
+ const m = /^--([a-z0-9][a-z0-9-]*)(?:=[\s\S]*)?$/i.exec(a);
if (!m) continue;
// Casing typo = unknown flag: every handler in the repo is
// case-sensitive-lowercase, so `--MIGRATE-ONLY` passing validation would
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 64c668f791..5b6021052a 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1308,7 +1308,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.464.0', text: 'Security: `gbrain serve --access=read-only` (the `=` form) now sets the read-only ceiling. It passed flag validation before but started the serve with full write access, because only `--access read-only` was read. A config that used the `=` form now gets the read-only tool set and refused mutations it asked for; a repeated `--access` never widens a read-only value, and an invalid value in either form refuses. `--surface=<v>` likewise now sets the serve surface (it was ignored, leaving the full surface), and a repeated `--surface` takes the narrowest value.' },
{ since: '0.60.464.0', text: 'A managed sync pass whose process was killed or crashed now reads `resumable` / `pass_interrupted` in `gbrain sync status` (with an `interrupted` block naming the pass and the dead holder) instead of `pass_unfinished`, and a second killed pass reads `blocked` / `pass_abandoned` at once. `gbrain doctor` `managed_sync_blocked` lists both (warn, fail after an hour). A live pass still committing is no longer counted abandoned because its row is old.' },
{ since: '0.60.465.0', text: 'On a managed brain, `gbrain trust release h<id>` of a held fact whose entity page exists now writes the fact into that page\'s `## Facts` fence through the page-write door (a `trust_release` page write) and flips the hold in the same publication, so the released fact lives in the page\'s file and a re-import keeps it. Before, the release inserted a database-only row the file never held; a fence-guard hold that names an existing fence row created a database-only twin of it, and now indexes that row and leaves the file unchanged. The row is stamped `user_confirmed` with origin `trust_release` and the page keeps its trust tier. A hold decided after the release was accepted fails `preview_changed` and writes nothing; a remote request, or a deleted or private entity page, refuses and the fact stays held. A hold with no entity page, and unmanaged brains, release database-only as before.' },
- { since: 'TBD', id: 'cli_flag_equals', text: 'A CLI flag value written with `=` that a command used to ignore now exits 2 (`invalid_params`) and names the two-argument spelling the command reads: `gbrain auth create --scopes=read` minted a full-access token. A switch never takes a value (`--yes=n`, `--dry-run=true`, `--apply=false` and `-y=n` exit 2 instead of being ignored). The `=` spellings a command reads on every path keep working; two that only some paths read now exit 2 with the two-argument fix: the source id given that way to `gbrain extract` for stale extraction, and the values given that way to the managed `gbrain sources` lifecycle subcommands (add, remove, archive, restore, purge, set-path, reclone). A value written with `=` on a flag that the help of the command declares used to be ignored and now applies, so check scripts that pass these that way: an all-interfaces bind address given to `gbrain serve` bound loopback and now listens on every interface; a public URL given to `gbrain serve` now sets the OAuth issuer and resource, so clients authorized under the old localhost issuer must reconnect, and admin cookies become Secure on https; the serve port, token lifetime and stdio idle timeout, the sync interval, source and repository, the import worker count and the autopilot install repository and supervisor take effect the same way; a spend cap given to `gbrain onboard` (off included) now applies, and one given to a resumed `gbrain doctor` remediation overrides the cap its checkpoint recorded; and `gbrain apply-migrations` now honors an accepted reviewed inventory and a forced retry of a wedged migration. A script that passes a value with `=` to a command that does not read that form now stops with the fix instead of running without the value.' },
+ { since: 'TBD', id: 'cli_flag_equals', text: 'A CLI flag value written with `=` that a command used to ignore now exits 2 (`invalid_params`) and names the two-argument spelling the command reads: `gbrain auth create --scopes=read` minted a full-access token. A switch never takes a value (`--yes=n`, `--dry-run=true`, `--apply=false` and `-y=n` exit 2 instead of being ignored). The `=` spellings a command reads on every path keep working; four that only some paths read now exit 2 with the two-argument fix: the source id given that way to `gbrain extract` for stale extraction, the reason given that way to a fact purge in `gbrain forget`, the checkout path given that way to the database-free `gbrain sources pull`, and the values given that way to the managed `gbrain sources` lifecycle subcommands (add, remove, archive, restore, purge, set-path, reclone). A value written with `=` on a flag that the help of the command declares used to be ignored and now applies, so check scripts that pass these that way: an all-interfaces bind address given to `gbrain serve` bound loopback and now listens on every interface; a public URL given to `gbrain serve` now sets the OAuth issuer and resource, so clients authorized under the old localhost issuer must reconnect, and admin cookies become Secure on https; the serve port, token lifetime and stdio idle timeout, the sync interval, source and repository, the import worker count, the autopilot install repository and supervisor, and the target engine and URL the legacy `gbrain migrate` copier reads take effect the same way; a spend cap given to `gbrain onboard` (off included) now applies, and one given to a resumed `gbrain doctor` remediation overrides the cap its checkpoint recorded; and `gbrain apply-migrations` now honors an accepted reviewed inventory and a forced retry of a wedged migration. A script that passes a value with `=` to a command that does not read that form now stops with the fix instead of running without the value.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/test/cli-flag-equals.test.ts b/test/cli-flag-equals.test.ts
index 3ca3b205bc..2094f9e245 100644
--- a/test/cli-flag-equals.test.ts
+++ b/test/cli-flag-equals.test.ts
@@ -12,7 +12,8 @@ import { readFileSync } from 'node:fs';
import { Glob } from 'bun';
import { CLI_ONLY, cliOnlyFlagArgs, validateCommandFlags } from '../src/cli/main.ts';
import { CLI_FLAG_REGISTRY } from '../src/core/cli-flag-registry.generated.ts';
-import { END_OF_OPTIONS, EQUALS_READERS, OWN_EQUALS_PARSERS, directEntryArgs, knownSwitches } from '../src/cli/flag-equals.ts';
+import { COMMAND_VALUES, END_OF_OPTIONS, EQUALS_READERS, OWN_EQUALS_PARSERS, directEntryArgs, findUnknownFlag, knownSwitches } from '../src/cli/flag-equals.ts';
+import { CLI_COMMANDS } from '../src/cli/command-table.ts';
import { SEARCH_SUBCOMMANDS } from '../src/cli/subcommands.ts';
import { SYNC_FLAGS } from '../src/core/sync-flags.ts';
import { _resetCliOptionsForTest, getCliOptions } from '../src/core/cli-options.ts';
@@ -27,6 +28,8 @@ import { parseTakesMutation } from '../src/commands/takes-mutation.ts';
import { parseReconcileArgs } from '../src/commands/source-reconcile.ts';
import { parseMigrateEmbeddingsFlags } from '../src/core/embedding-migration-cli.ts';
import { parseGoogleAttachmentsArgs } from '../src/commands/google-attachments.ts';
+import { parseGraduationArgs, routesToGraduation } from '../src/commands/migrate-graduation.ts';
+import type { GBrainConfig } from '../src/core/config.ts';
import { parseAppendArgs } from '../src/cli/commands/append.ts';
import { splitFlagEquals } from '../src/cli/flag-equals.ts';
@@ -46,6 +49,7 @@ async function refusalFor(command: string, args: string[]): Promise<string | nul
async function ownTable(command: string): Promise<Map<string, string>> {
const types = new Map((await loadCuratedHelp(command))?.flags.map(f => [f.name, f.type] as [string, string]));
if (command === 'sync') for (const [flag, spec] of Object.entries(SYNC_FLAGS as Record<string, { arity: string }>)) if (!types.has(flag)) types.set(flag, spec.arity);
+ for (const flag of COMMAND_VALUES[command] ?? []) if (!types.has(flag)) types.set(flag, 'string');
return types;
}
@@ -467,7 +471,7 @@ describe('#7619 refusals that keep consent, scope and targets right', () => {
['reinit-pglite', ['--path=/tmp/brain-example'], '--path'], ['bootstrap', ['interview', '--confirm=abc123'], '--confirm'],
['extract', ['links', '--source', 'db', '--source-id=source-a'], '--source-id'], ['extract', ['--stale', '--source-id=source-a'], '--source-id'],
['trust', ['explain', 'ref-example', '--source=source-a'], '--source'], ['jobs', ['work', '--concurrency=4'], '--concurrency'],
- ['forget', ['34', '--reason=stale-example'], '--reason'], ['migrate', ['--to=pglite'], '--to'],
+ ['forget', ['34', '--reason=stale-example'], '--reason'], ['migrate', ['--to', 'pglite', '--path=/tmp/brain-example'], '--path'],
['jobs', ['submit', 'shell', '--params={"a":1}'], '--params'], ['jobs', ['submit', 'sync', '--max-usd=5'], '--max-usd'],
] as const) {
const r = await cliOnlyFlagArgs(command, [...args]);
@@ -477,6 +481,14 @@ describe('#7619 refusals that keep consent, scope and targets right', () => {
});
// Value: protects=a split value never becomes the first numeric/slug target (forget --purge --reason=3 34 must not hit fact 3); fails_when=a refusal turns into a split or keep; why_new=rows only asserted not-null; seam=none; no_claim=handler behavior after a split (argv-level only)
+ test('migrate splits the target engine and URL, which every migrate path reads as two arguments', async () => {
+ expect(await argvFor('migrate', ['--to=postgres', '--url-env', 'TARGET_URL', '--plan'])).toEqual(['--to', 'postgres', '--url-env', 'TARGET_URL', '--plan']);
+ expect(await argvFor('migrate', ['--to=pglite', '--path', '/tmp/brain-example'])).toEqual(['--to', 'pglite', '--path', '/tmp/brain-example']);
+ expect(await argvFor('migrate', ['--to=postgres', '--url=-', '--plan'])).toEqual(['--to', 'postgres', '--url', '-', '--plan']);
+ expect(parseGraduationArgs(['--to', 'postgres', '--url', '-', '--plan'])).toMatchObject({ mode: 'plan', to: 'postgres', urlFromStdin: true });
+ expect(routesToGraduation(['--to', 'postgres'], { engine: 'pglite' } as GBrainConfig, 'linux')).toBe(true);
+ });
+
test('a flag value never becomes the numeric or slug target of a mutating subcommand', async () => {
for (const [command, args] of [
['forget', ['--purge', '--reason=3', '34', '--dry-run']],
@@ -618,6 +630,23 @@ describe('#7619 refusals that keep consent, scope and targets right', () => {
expect(await argvFor('doctor', ['--json=true'])).toEqual(['--json']);
expect(await argvFor('sync', ['--json=true'])).toEqual(['--json']);
expect(await refusalFor('sync', ['--json=false'])).toContain('--json is a switch');
+ for (const sub of SEARCH_SUBCOMMANDS) {
+ expect(await argvFor('search', [sub, '--json=true'])).toEqual([sub, '--json']);
+ expect(await refusalFor('search', [sub, '--json=false'])).toContain('--json=…');
+ }
+ });
+
+ test('an unknown or miscased flag with a multi-line = value is still unknown', () => {
+ const legal = new Set(CLI_FLAG_REGISTRY.auth);
+ expect(findUnknownFlag(['create', 'bot', '--scope=read\nwrite'], legal)).toBe('--scope');
+ expect(findUnknownFlag(['create', 'bot', '--Scopes=read\nwrite'], legal)).toBe('--Scopes');
+ });
+
+ test('every command-table end_of_options command has an END_OF_OPTIONS path', () => {
+ for (const c of CLI_COMMANDS) {
+ if (!(c as { end_of_options?: true }).end_of_options) continue;
+ expect([...END_OF_OPTIONS].some(k => k.split(' ')[0] === c.name)).toBe(true);
+ }
});
test('a refused credential value is never echoed', async () => {