chore: tighten command surface cleanup

Author: thymikee

src/cli/batch-steps.ts

@@ -1,10 +1,11 @@
 import type { BatchStep } from '../client-types.ts';
 import { readInputFromCli } from '../commands/cli-grammar.ts';
+import { isCommandName, type CommandName } from '../commands/command-surface.ts';
 import type { CliFlags } from '../utils/command-schema.ts';
 import { AppError } from '../utils/errors.ts';
 
 type LegacyCliBatchStep = {
-  command: string;
+  command: CommandName;
   positionals?: string[];
   flags?: Record<string, unknown>;
   runtime?: unknown;
@@ -69,8 +70,7 @@ function readLegacyCliBatchStep(step: unknown, stepNumber: number): LegacyCliBat
   }
   const record = step as Record<string, unknown>;
   assertLegacyBatchStepKeys(record, stepNumber);
-  const command = typeof record.command === 'string' ? record.command.trim().toLowerCase() : '';
-  if (!command) throw new AppError('INVALID_ARGS', `Batch step ${stepNumber} requires command.`);
+  const command = readLegacyCommand(record.command, stepNumber);
   const positionals = readLegacyPositionals(record.positionals, stepNumber);
   const flags = readLegacyFlags(record.flags, stepNumber);
   return {
@@ -81,6 +81,16 @@ function readLegacyCliBatchStep(step: unknown, stepNumber: number): LegacyCliBat
   };
 }
 
+function readLegacyCommand(value: unknown, stepNumber: number): CommandName {
+  const command = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!command) throw new AppError('INVALID_ARGS', `Batch step ${stepNumber} requires command.`);
+  if (isCommandName(command)) return command;
+  throw new AppError(
+    'INVALID_ARGS',
+    `Batch step ${stepNumber} command is not available through command batch: ${String(value)}`,
+  );
+}
+
 function assertLegacyBatchStepKeys(record: Record<string, unknown>, stepNumber: number): void {
   const unknownKeys = Object.keys(record).filter(
     (key) => !['command', 'positionals', 'flags', 'runtime'].includes(key),

src/cli/commands/generic.ts

@@ -2,7 +2,7 @@ import type { AgentDeviceClient, CommandRequestResult } from '../../client.ts';
 import { announceReplayTestRun, renderReplayTestResponse } from '../../cli-test.ts';
 import { listCliOutputCommandNames } from '../../commands/cli-output.ts';
 import { runCliCommand, runCliCommandWithOutput } from '../../commands/cli-runner.ts';
-import { listCommandNames, type CliCommand } from '../../commands/command-surface.ts';
+import { listCommandNames, type CommandName } from '../../commands/command-surface.ts';
 import type { CliOutput } from '../../commands/command-contract.ts';
 import type { ReplaySuiteResult } from '../../daemon/types.ts';
 import type { CliFlags } from '../../utils/command-schema.ts';
@@ -19,7 +19,7 @@ type GenericClientCommandRunner = (params: {
 
 const formattedCommandHandlers = Object.fromEntries(
   listCliOutputCommandNames().map((command) => [command, createFormattedHandler(command)]),
-) as Partial<Record<CliCommand, ClientCommandHandler>>;
+) as Partial<Record<CommandName, ClientCommandHandler>>;
 
 export const dedicatedCommandHandlers = formattedCommandHandlers;
 
@@ -80,7 +80,7 @@ function writeGenericCliOutput(
   return 0;
 }
 
-function createFormattedHandler(command: CliCommand): ClientCommandHandler {
+function createFormattedHandler(command: CommandName): ClientCommandHandler {
   return async ({ positionals, flags, client }) => {
     const { cliOutput } = await runCliCommandWithOutput({
       client,
@@ -107,6 +107,6 @@ function writeCliOutput(flags: CliFlags, output: CliOutput): void {
   );
 }
 
-function isGenericCliCommand(command: CliCommand): boolean {
+function isGenericCliCommand(command: CommandName): boolean {
   return !(command in formattedCommandHandlers) && command !== 'screenshot' && command !== 'diff';
 }

src/commands/cli-grammar/registry.ts

@@ -1,5 +1,4 @@
 import type { CliFlags } from '../../utils/command-schema.ts';
-import { AppError } from '../../utils/errors.ts';
 import { appCliReaders } from './apps.ts';
 import { captureCliReaders } from './capture.ts';
 import { commonInputFromFlags } from './common.ts';
@@ -11,6 +10,7 @@ import { replayCliReaders } from './replay.ts';
 import { selectorCliReaders } from './selectors.ts';
 import { systemCliReaders } from './system.ts';
 import type { CliReader } from './types.ts';
+import type { CommandName } from '../command-surface.ts';
 
 const cliReaders = {
   ...appCliReaders,
@@ -29,14 +29,12 @@ const cliReaders = {
     maxSteps: flags.batchMaxSteps,
     out: flags.out,
   }),
-} satisfies Record<string, CliReader>;
+} satisfies Record<CommandName, CliReader>;
 
 export function readInputFromCli(
-  command: string,
+  command: CommandName,
   positionals: string[],
   flags: CliFlags,
 ): Record<string, unknown> {
-  const reader = (cliReaders as Record<string, CliReader>)[command];
-  if (!reader) throw new AppError('INVALID_ARGS', `Unknown CLI command: ${command}`);
-  return reader(positionals, flags);
+  return cliReaders[command](positionals, flags);
 }

src/commands/cli-runner.ts

@@ -1,13 +1,13 @@
 import type { AgentDeviceClient, CommandRequestResult } from '../client.ts';
 import { formatCliOutput } from './cli-output.ts';
 import { readInputFromCli } from './cli-grammar.ts';
-import { runCommand, type CliCommand } from './command-surface.ts';
+import { runCommand, type CommandName } from './command-surface.ts';
 import type { CliOutput } from './command-contract.ts';
 import type { CliFlags } from '../utils/command-schema.ts';
 
 type CliRunOptions = {
   client: AgentDeviceClient;
-  command: CliCommand;
+  command: CommandName;
   positionals: string[];
   flags: CliFlags;
 };

src/commands/command-surface.ts

@@ -22,7 +22,6 @@ const commandSurface = [
 ] as const;
 
 export type CommandName = (typeof commandSurface)[number]['name'];
-export type CliCommand = CommandName;
 export type { BatchCommandName };
 
 const commandMap: ReadonlyMap<CommandName, AnyExecutableCommand> = new Map(

src/utils/cli-command-overrides.ts

@@ -324,7 +324,7 @@ const CLI_COMMAND_OVERRIDES = {
     usageOverride: 'session list',
     positionalArgs: ['list?'],
   },
-} as const satisfies Record<string, CommandSchemaOverride>;
+} as const satisfies Partial<Record<CommandName, CommandSchemaOverride>>;
 
 export function getSchemaOnlyCliCommandSchema(command: string): CommandSchema | undefined {
   return Object.hasOwn(SCHEMA_ONLY_CLI_COMMAND_SCHEMAS, command)