refactor(command-registry): move CLI flag grammar, text and aliases down (#2543)

docs/agents/cli-flags.md

@@ -3,7 +3,8 @@
 Thread a flag only through the layers that consume it:
 
 1. `packages/contracts/src/cli-flags.ts`: add to `CliFlags`; add the definition to the matching
-   `src/commands/cli-grammar/flag-definitions-*.ts` owner and the relevant group in `flag-groups.ts`
+   `packages/command-registry/src/flag-definitions-*.ts` owner and the relevant group in
+   `packages/command-registry/src/flag-groups.ts`
    (for example `SNAPSHOT_FLAGS`). Then update the command family metadata/schema that exposes the
    flag; find the owner with
    `rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser`. For

packages/command-registry/package.json

@@ -70,6 +70,26 @@
     "./batch-policy": {
       "types": "./src/batch-policy.ts",
       "default": "./src/batch-policy.ts"
+    },
+    "./flag-types": {
+      "types": "./src/flag-types.ts",
+      "default": "./src/flag-types.ts"
+    },
+    "./flag-registry": {
+      "types": "./src/flag-registry.ts",
+      "default": "./src/flag-registry.ts"
+    },
+    "./flag-groups": {
+      "types": "./src/flag-groups.ts",
+      "default": "./src/flag-groups.ts"
+    },
+    "./command-text": {
+      "types": "./src/command-text.ts",
+      "default": "./src/command-text.ts"
+    },
+    "./cli-command-aliases": {
+      "types": "./src/cli-command-aliases.ts",
+      "default": "./src/cli-command-aliases.ts"
     }
   }
 }

src/commands/cli-grammar/flag-registry.test.ts → packages/command-registry/src/__tests__/flag-registry.test.ts

@@ -1,6 +1,6 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
-import { getFlagDefinition } from './flag-registry.ts';
+import { getFlagDefinition } from '../flag-registry.ts';
 import { PLATFORM_SELECTORS } from '@agent-device/kernel/device';
 
 test('--platform enumValues are derived from the canonical PLATFORM_SELECTORS tuple', () => {

scripts/integration-progress-model.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
 import { listCommandMetadata } from '../src/commands/command-metadata.ts';
-import { getFlagDefinitions } from '../src/commands/cli-grammar/flag-registry.ts';
+import { getFlagDefinitions } from '@agent-device/command-registry/flag-registry';
 import { walkFiles } from './lib/walk-files.ts';
 
 const EMPTY_COVERAGE_METRIC = { pct: 0 };

src/__tests__/command-doc-coverage.test.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import assert from 'node:assert/strict';
 import { describe, test } from 'vitest';
 import { PUBLIC_COMMANDS, isKnownCliCommandName } from '@agent-device/command-registry/catalog';
-import { cliCommandAlias } from '../commands/cli-command-aliases.ts';
+import { cliCommandAlias } from '@agent-device/command-registry/cli-command-aliases';
 import { getCliCommandSchema } from '../cli-schema/command-schema.ts';
 import { buildCommandUsage } from '../cli-schema/usage.ts';
 

src/cli-schema/cli-config.ts

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { AppError } from '@agent-device/kernel/errors';
 import { mergeDefinedFlags } from './merge-flags.ts';
-import { type FlagKey } from '../commands/cli-grammar/flag-types.ts';
+import { type FlagKey } from '@agent-device/command-registry/flag-types';
 import { projectConfigFlagKeys } from './command-schema.ts';
 import { expandUserHomePath, resolveUserPath } from '@agent-device/host-kit/file';
 import {

src/cli-schema/cli-help-alias-fast-path.test.ts

@@ -1,7 +1,7 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import { buildCommandUsageText, resolveHelpTargetUsageText } from './cli-help.ts';
-import { cliAliasesForCommand } from '../commands/cli-command-aliases.ts';
+import { cliAliasesForCommand } from '@agent-device/command-registry/cli-command-aliases';
 import { listCliCommandNames } from '@agent-device/command-registry/catalog';
 
 const ALIASES = listCliCommandNames().flatMap((command) =>

src/cli-schema/cli-help.ts

@@ -4,8 +4,8 @@ import {
   MAESTRO_COMPATIBILITY_ADR_URL,
   MAESTRO_COMPATIBILITY_ISSUE_URL,
 } from '@agent-device/maestro';
-import { normalizeCliCommandAlias } from '../commands/cli-command-aliases.ts';
-import { helpBody } from '../commands/command-text.ts';
+import { normalizeCliCommandAlias } from '@agent-device/command-registry/cli-command-aliases';
+import { helpBody } from '@agent-device/command-registry/command-text';
 import {
   DEVICE_SELECTION_FLAG_KEYS,
   getCliCommandSchema,

src/cli-schema/command-overrides.ts

@@ -5,7 +5,7 @@ import type { CommandSchema } from './types.ts';
 import {
   COMMON_COMMAND_SUPPORTED_FLAG_KEYS,
   METRO_PREPARE_FLAGS,
-} from '../commands/cli-grammar/flag-groups.ts';
+} from '@agent-device/command-registry/flag-groups';
 
 type SchemaOnlyCliCommandName = Exclude<LocalCliCommandName, CommandName>;
 

src/cli-schema/command-schema.ts

@@ -7,13 +7,13 @@ import {
   getFlagDefinitions,
   projectConfigFlagKeys,
   recordedFlagKeys,
-} from '../commands/cli-grammar/flag-registry.ts';
+} from '@agent-device/command-registry/flag-registry';
 import {
   COMMON_COMMAND_SUPPORTED_FLAG_KEYS,
   DEVICE_SELECTION_FLAG_KEYS,
   GLOBAL_FLAG_KEYS,
-} from '../commands/cli-grammar/flag-groups.ts';
-import { type FlagDefinition, type FlagKey } from '../commands/cli-grammar/flag-types.ts';
+} from '@agent-device/command-registry/flag-groups';
+import { type FlagDefinition, type FlagKey } from '@agent-device/command-registry/flag-types';
 import { AppError } from '@agent-device/kernel/errors';
 
 export type { FlagDefinition, FlagKey };

src/cli-schema/types.ts

@@ -1,6 +1,6 @@
-import type { FlagKey } from '../commands/cli-grammar/flag-types.ts';
+import type { FlagKey } from '@agent-device/command-registry/flag-types';
 import type { CliFlags } from '@agent-device/contracts/command';
-import type { CommandText } from '../commands/command-text.ts';
+import type { CommandText } from '@agent-device/command-registry/command-text';
 
 /**
  * Command grammar plus its resolved text. Prose lives entirely in `text`; everything else here

src/cli-schema/usage.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import { listCliCommandNames } from '@agent-device/command-registry/catalog';
-import type { CommandText } from '../commands/command-text.ts';
+import type { CommandText } from '@agent-device/command-registry/command-text';
 import {
   getCliCommandSchema,
   getFlagDefinitions,

src/cli.ts

@@ -47,7 +47,7 @@ import {
   type RemoteConnectionRequestMetadata,
 } from './remote/remote-connection-state.ts';
 import { resolveRemoteAuthForCli } from './cli/auth-session.ts';
-import type { FlagKey } from './commands/cli-grammar/flag-types.ts';
+import type { FlagKey } from '@agent-device/command-registry/flag-types';
 import type { CliFlags } from '@agent-device/contracts/command';
 import type { SessionRuntimeHints } from '@agent-device/kernel/contracts';
 import { INTERNAL_COMMANDS, isKnownCliCommandName } from '@agent-device/command-registry/catalog';

src/cli/entry.test.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert/strict';
 import { test } from 'vitest';
 import * as cliHelp from '../cli-schema/cli-help.ts';
 import { listCliCommandNames } from '@agent-device/command-registry/catalog';
-import { cliAliasesForCommand } from '../commands/cli-command-aliases.ts';
+import { cliAliasesForCommand } from '@agent-device/command-registry/cli-command-aliases';
 import { runEntry, type EntryModules } from './entry.ts';
 
 const ALIASES = listCliCommandNames().flatMap((command) =>

src/cli/parser/__tests__/maestro-support-matrix.test.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { expect, test } from 'vitest';
 import { usageForCommand } from '../args.ts';
-import { getFlagDefinitions } from '../../../commands/cli-grammar/flag-registry.ts';
+import { getFlagDefinitions } from '@agent-device/command-registry/flag-registry';
 import {
   MAESTRO_COMPATIBILITY_ADR_URL,
   MAESTRO_COMPATIBILITY_ISSUE_URL,

src/cli/parser/args.ts

@@ -16,7 +16,7 @@ import {
   cliCommandAlias,
   normalizeCliCommandAlias,
   retiredCliCommandMessage,
-} from '../../commands/cli-command-aliases.ts';
+} from '@agent-device/command-registry/cli-command-aliases';
 import { formatUnknownFlagMessage, suggestCommandFor } from './command-suggestions.ts';
 
 type ParsedArgs = {

src/commands/__tests__/command-surface-metadata.test.ts

@@ -20,7 +20,7 @@ import {
   listCommandFamilyMetadata,
 } from '../family/registry.ts';
 import { listExecutableCommandNames } from '../command-surface.ts';
-import { helpBody, mcpBody } from '../command-text.ts';
+import { helpBody, mcpBody } from '@agent-device/command-registry/command-text';
 import { explainCommand } from '../command-explain.ts';
 import { getDaemonRouteOwnerFiles } from '../../daemon/route-owner-files.ts';
 

src/commands/capture/diff.ts

@@ -1,5 +1,5 @@
 import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
-import { SNAPSHOT_FLAGS } from '../cli-grammar/flag-groups.ts';
+import { SNAPSHOT_FLAGS } from '@agent-device/command-registry/flag-groups';
 import { AppError } from '@agent-device/kernel/errors';
 import {
   booleanField,

src/commands/capture/snapshot.ts

@@ -4,7 +4,7 @@ import {
   SNAPSHOT_COMMAND_OPTION_KEYS,
   snapshotOptionsFromFlags,
 } from '@agent-device/kernel/snapshot';
-import { SNAPSHOT_FLAGS } from '../cli-grammar/flag-groups.ts';
+import { SNAPSHOT_FLAGS } from '@agent-device/command-registry/flag-groups';
 import { booleanField, integerField, optionField, stringField } from '../command-input.ts';
 import {
   commonInputFromFlags,

src/commands/capture/wait.ts

@@ -3,7 +3,7 @@ import { PUBLIC_COMMANDS } from '@agent-device/command-registry/catalog';
 import type { WaitCommandOptions } from '@agent-device/contracts/client';
 import { parseWaitPositionals } from '@agent-device/command-registry/wait-positionals';
 import type { WaitParsed } from '@agent-device/command-registry/wait-positionals';
-import { SELECTOR_SNAPSHOT_FLAGS } from '../cli-grammar/flag-groups.ts';
+import { SELECTOR_SNAPSHOT_FLAGS } from '@agent-device/command-registry/flag-groups';
 import { AppError } from '@agent-device/kernel/errors';
 import { isValidSelectorExpression } from '@agent-device/selectors';
 import { booleanField, enumField, integerField, stringField } from '../command-input.ts';

src/commands/cli-grammar/flag-declaration-admission.test.ts

@@ -3,8 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { test, vi } from 'vitest';
 import type { CliFlags } from '@agent-device/contracts/command';
-import { getFlagDefinitionsForKey } from './flag-registry.ts';
-import type { FlagDefinition } from './flag-types.ts';
+import { getFlagDefinitionsForKey } from '@agent-device/command-registry/flag-registry';
+import type { FlagDefinition } from '@agent-device/command-registry/flag-types';
 import { resolveConfigBackedFlagDefaults } from '../../cli-schema/cli-config.ts';
 import { recordActionEntry } from '../../daemon/session-action-recorder.ts';
 import { makeIosSession } from '../../__tests__/test-utils/session-factories.ts';
@@ -59,7 +59,7 @@ test('project-config admission follows the declaration: an undeclared key is ref
   // Planted: flip the declaration before `cli-config` builds, and the identical file is
   // admitted. A hand-maintained allowlist in `cli-config.ts` could not follow this.
   vi.resetModules();
-  const registry = await import('./flag-registry.ts');
+  const registry = await import('@agent-device/command-registry/flag-registry');
   const planted = getInRegistry(registry, 'daemonBaseUrl');
   Object.assign(planted, { projectConfig: true });
   const { resolveConfigBackedFlagDefaults: derivePlanted } =
@@ -95,7 +95,7 @@ test('recorder sanitization follows the declaration: an undeclared key is droppe
   // Planted: flip the declaration before the recorder builds, and the production
   // `sanitizeFlags` now copies the same value.
   vi.resetModules();
-  const registry = await import('./flag-registry.ts');
+  const registry = await import('@agent-device/command-registry/flag-registry');
   const planted = getInRegistry(registry, 'overlayRefs');
   Object.assign(planted, { recorded: true });
   const { recordActionEntry: recordPlanted } =
@@ -130,7 +130,7 @@ test('a CLI-only key cannot opt into recording', () => {
 });
 
 function getInRegistry(
-  registry: typeof import('./flag-registry.ts'),
+  registry: typeof import('@agent-device/command-registry/flag-registry'),
   key: 'daemonBaseUrl' | 'overlayRefs',
 ): FlagDefinition {
   const declaration = registry.getFlagDefinitionsForKey(key)[0];

src/commands/command-explain.ts

@@ -1,5 +1,8 @@
 import { listCliCommandNames } from '@agent-device/command-registry/catalog';
-import { cliAliasesForCommand, normalizeCliCommandAlias } from './cli-command-aliases.ts';
+import {
+  cliAliasesForCommand,
+  normalizeCliCommandAlias,
+} from '@agent-device/command-registry/cli-command-aliases';
 import { buildCommandUsage } from '../cli-schema/usage.ts';
 import type { DaemonCommandRoute } from '../daemon/daemon-command-registry.ts';
 import { commandDescriptors, type Command } from '@agent-device/command-registry/registry';

src/commands/command-flags.ts

@@ -9,7 +9,7 @@ import {
   SNAPSHOT_COMMAND_OPTION_KEYS,
   snapshotFlagsFromOptions,
 } from '@agent-device/kernel/snapshot';
-import { getFlagDefinitions } from './cli-grammar/flag-registry.ts';
+import { getFlagDefinitions } from '@agent-device/command-registry/flag-registry';
 import type { InternalRequestOptions } from '@agent-device/contracts/client';
 import type { CommandMetadata } from './command-contract.ts';
 

src/commands/command-input-option-field.test.ts

@@ -1,8 +1,11 @@
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { test, vi } from 'vitest';
-import { getFlagDefinitions, getFlagDefinitionsForKey } from './cli-grammar/flag-registry.ts';
-import type { FlagDefinition, FlagKey } from './cli-grammar/flag-types.ts';
+import {
+  getFlagDefinitions,
+  getFlagDefinitionsForKey,
+} from '@agent-device/command-registry/flag-registry';
+import type { FlagDefinition, FlagKey } from '@agent-device/command-registry/flag-types';
 import { listCommandMetadata } from './command-metadata.ts';
 import type { JsonSchema } from './command-contract.ts';
 import { optionField } from './command-input.ts';
@@ -57,7 +60,7 @@ async function buildWithPlantedOption(
   vi.resetModules();
 
   // Plant first: nothing in this module graph has built a command yet.
-  const registry = await import('./cli-grammar/flag-registry.ts');
+  const registry = await import('@agent-device/command-registry/flag-registry');
   const declaration = registry
     .getFlagDefinitionsForKey(key)
     .find((candidate) => candidate.inputDescription !== undefined);

src/commands/command-input.ts

@@ -9,8 +9,8 @@ import {
   readOptionalNumber as optionalNumberValue,
   type CliFlags,
 } from '@agent-device/contracts/command';
-import { getFlagDefinitionsForKey } from './cli-grammar/flag-registry.ts';
-import type { FlagDefinition, FlagKey } from './cli-grammar/flag-types.ts';
+import { getFlagDefinitionsForKey } from '@agent-device/command-registry/flag-registry';
+import type { FlagDefinition, FlagKey } from '@agent-device/command-registry/flag-types';
 import { AppError } from '@agent-device/kernel/errors';
 import type { RepeatedInput } from '@agent-device/contracts/interaction';
 import type { JsonSchema } from './command-contract.ts';

src/commands/family/types.ts

@@ -3,7 +3,10 @@ import type { CommandSchema, CommandSchemaOverride } from '../../cli-schema/type
 import type { AnyDaemonWriter, CliReader } from '../cli-grammar/types.ts';
 import type { CommandMetadata, JsonSchema } from '../command-contract.ts';
 import type { CliOutputFormatter } from '../output-common.ts';
-import { resolveFacetText, type FacetCommandText } from '../command-text.ts';
+import {
+  resolveFacetText,
+  type FacetCommandText,
+} from '@agent-device/command-registry/command-text';
 
 export type AnyCommandMetadata<Name extends string = string> = CommandMetadata<Name, unknown>;
 

src/commands/interaction/index.ts

@@ -20,7 +20,10 @@ import type {
   TypeTextOptions,
 } from '@agent-device/contracts/client';
 import type { CommandSchemaOverride } from '../../cli-schema/types.ts';
-import { REPEATED_TOUCH_FLAGS, SELECTOR_SNAPSHOT_FLAGS } from '../cli-grammar/flag-groups.ts';
+import {
+  REPEATED_TOUCH_FLAGS,
+  SELECTOR_SNAPSHOT_FLAGS,
+} from '@agent-device/command-registry/flag-groups';
 import { postActionObservationCliFlags } from '../post-action-observation-grammar.ts';
 import {
   toClientElementTarget,

src/commands/management/app.ts

@@ -17,7 +17,7 @@ import {
 } from '../command-input.ts';
 import { commonInputFromFlags, direct, optionalString } from '../cli-grammar/common.ts';
 import type { CliReader, CommandInput, DaemonWriter } from '../cli-grammar/types.ts';
-import { METRO_RELOAD_FLAGS } from '../cli-grammar/flag-groups.ts';
+import { METRO_RELOAD_FLAGS } from '@agent-device/command-registry/flag-groups';
 import { defineCommandFacet } from '../family/types.ts';
 import { defineFieldCommandMetadata } from '../field-command-contract.ts';
 import { withCommandRuntimeHints } from '../runtime-hints.ts';

src/commands/metro/index.ts

@@ -19,7 +19,10 @@ import {
 import { defineCommandFacet, defineCommandFamilyFromFacets } from '../family/types.ts';
 import { defineFieldCommandMetadata } from '../field-command-contract.ts';
 import type { CliReader } from '../cli-grammar/types.ts';
-import { METRO_PREPARE_FLAGS, METRO_RELOAD_FLAGS } from '../cli-grammar/flag-groups.ts';
+import {
+  METRO_PREPARE_FLAGS,
+  METRO_RELOAD_FLAGS,
+} from '@agent-device/command-registry/flag-groups';
 import { metroCliOutputFormatters } from './output.ts';
 import { readMetroPrepareKind } from './prepare-kind.ts';
 

src/commands/post-action-observation-grammar.ts

@@ -5,8 +5,8 @@ import {
   commandSupportsVerifyEvidence,
 } from '@agent-device/command-registry/registry';
 import { settleInputFromFlags } from './cli-grammar/common.ts';
-import { SETTLE_FLAGS } from './cli-grammar/flag-groups.ts';
-import type { FlagKey } from './cli-grammar/flag-types.ts';
+import { SETTLE_FLAGS } from '@agent-device/command-registry/flag-groups';
+import type { FlagKey } from '@agent-device/command-registry/flag-types';
 import { booleanField, integerField } from './command-input.ts';
 
 /**

src/commands/replay/index.ts

@@ -18,7 +18,7 @@ import {
   requiredString,
 } from '../cli-grammar/common.ts';
 import type { AsyncDaemonWriter, CliReader, CommandInput } from '../cli-grammar/types.ts';
-import { METRO_RELOAD_FLAGS, REPLAY_FLAGS } from '../cli-grammar/flag-groups.ts';
+import { METRO_RELOAD_FLAGS, REPLAY_FLAGS } from '@agent-device/command-registry/flag-groups';
 import { withCommandRuntimeHints } from '../runtime-hints.ts';
 import {
   collectReplayShellEnv,

src/mcp/command-tools.ts

@@ -11,7 +11,7 @@ import {
   listMcpCommandMetadata,
   type CommandName,
 } from '../commands/command-metadata.ts';
-import { mcpBody } from '../commands/command-text.ts';
+import { mcpBody } from '@agent-device/command-registry/command-text';
 import { resolveStructuredBatchCommandName } from '@agent-device/command-registry/batch-policy';
 import {
   resolveCommandRecordsSessionAction,

src/mcp/tool-input-config.ts

@@ -1,5 +1,5 @@
 import { isFlagSupportedForCommand } from '../cli-schema/option-schema.ts';
-import type { FlagKey } from '../commands/cli-grammar/flag-types.ts';
+import type { FlagKey } from '@agent-device/command-registry/flag-types';
 import type { CliFlags } from '@agent-device/contracts/command';
 import type { JsonSchema } from '../commands/command-contract.ts';
 import type { CommandName } from '../commands/command-metadata.ts';

test/integration/smoke-cli.test.ts

@@ -1,7 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { runCmdSync } from '@agent-device/host-kit/command';
-import { cliAliasesForCommand } from '../../src/commands/cli-command-aliases.ts';
+import { cliAliasesForCommand } from '@agent-device/command-registry/cli-command-aliases';
 import { listCliCommandNames } from '@agent-device/command-registry/catalog';
 
 function runCli(args: string[]): { status: number; stdout: string; stderr: string } {