Skip to content

Deepen command grammar modules #594

@thymikee

Description

@thymikee

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions