Problem
Command grammar is still shallow and split across several Modules:
src/commands/semantic-cli.ts maps CLI positionals + flags into semantic input.
src/commands/semantic-request.ts maps semantic input back into daemon command + positionals + flags.
src/command-codecs/* contains partial decode-only grammar for targets, wait, find, is, settings, and type.
This makes CLI, Node client, batch, and MCP share semantic contracts, but not all of the command grammar. Target grammar is the clearest example: decode logic lives in command-codecs/targets.ts, semantic input shaping lives in semantic-cli.ts, and daemon positional encoding lives in semantic-request.ts.
Goal
Deepen command grammar into a dedicated Module with a small Interface for interface-specific projection, while keeping semantic command definitions focused on semantic inputs and outputs.
Candidate Interface shape:
readCliSemanticInput(command, positionals, flags)
writeDaemonRequest(command, input)
writeBatchStep(command, input)
The Implementation can stay grouped by command family, for example:
- interactions and target grammar
- wait, find, is, and settings
- gestures
- lifecycle, apps, and session
- observability and replay
Suggested First Slice
Start with interaction target grammar: click, press, longpress, fill, and get.
This has the best signal because it currently duplicates grammar across semantic-cli.ts, semantic-request.ts, command-codecs/targets.ts, and daemon interaction target parsing.
Acceptance Criteria
- CLI, Node client, batch, and MCP continue to use the same semantic command contracts.
- CLI grammar remains an Adapter, not part of command definitions.
- Interaction target grammar has one source of truth for CLI decode and daemon positional encode.
- Existing command behavior stays compatible.
- Net code should shrink or stay close to neutral by deleting duplicated codec/request helpers.
- Tests cover the grammar Interface behavior rather than asserting shallow codec objects exist.
Notes
This was intentionally deferred from PR #593 to keep the semantic MCP refactor scoped.
Problem
Command grammar is still shallow and split across several Modules:
src/commands/semantic-cli.tsmaps CLIpositionals + flagsinto semantic input.src/commands/semantic-request.tsmaps semantic input back into daemoncommand + positionals + flags.src/command-codecs/*contains partial decode-only grammar for targets, wait, find, is, settings, and type.This makes CLI, Node client, batch, and MCP share semantic contracts, but not all of the command grammar. Target grammar is the clearest example: decode logic lives in
command-codecs/targets.ts, semantic input shaping lives insemantic-cli.ts, and daemon positional encoding lives insemantic-request.ts.Goal
Deepen command grammar into a dedicated Module with a small Interface for interface-specific projection, while keeping semantic command definitions focused on semantic inputs and outputs.
Candidate Interface shape:
The Implementation can stay grouped by command family, for example:
Suggested First Slice
Start with interaction target grammar:
click,press,longpress,fill, andget.This has the best signal because it currently duplicates grammar across
semantic-cli.ts,semantic-request.ts,command-codecs/targets.ts, and daemon interaction target parsing.Acceptance Criteria
Notes
This was intentionally deferred from PR #593 to keep the semantic MCP refactor scoped.