@maple-kit/cli

@maple-kit/cli

The maple binary for Maple — visual review comments on deployed previews, written for people and read by agents.

Pre-release. Every package here is 0.x and makes no compatibility promise.

Every command that prints a table also takes --json, so an agent drives it from a terminal as easily as a person does. A flag's value can follow it (--owner acme) or be joined to it (--owner=acme), and a flag the command does not take is an error that lists the ones it does.

Install

npm install -g @maple-kit/cli

Commands

Command	What it does
maple review	Put the overlay on your running app through a proxy, with nothing wired in
maple connectors	Show the connector kinds and the methods each one may implement
maple mock schema	Write an OpenAPI document of a tRPC router's response types
maple mock plan	Print the recipe a preview's route plans for a sentence
maple setup app	Print the prefilled GitHub App registration URL and the steps after it
maple setup verify	Check that a comment App's Device Flow is on
maple setup ci	Print or write the gate workflow, and the ruleset that requires it
maple setup preview mirrord	Add the env override and steal mode to a mirrord config
maple lint	Run the design-system lint against a preview, locally
maple ci lint	Run the design lint as CI does: SARIF and the maple/design-lint check
maple solo	Keep a preview's comments on this machine: start the bridge, print the link

maple setup

Registering Maple's GitHub Apps, and gating a merge on the review. The permissions each App is registered with are one constant in this package, GITHUB_APP_PERMISSIONS, so this is where they are read from rather than copied.

maple setup app --owner=acme            # the comment App: pull_requests=write
maple setup app --owner=acme --gate     # the gate App: checks=write
maple setup verify --client-id=<Iv…>     # exits 1 if Device Flow is off
maple setup ci --require-approval --write

setup app prints a URL that opens GitHub's New GitHub App form already filled in, then the steps no URL parameter can set: Device Flow, token expiry, the logo, the installation and where the Client ID goes. --personal registers under a personal account instead of an organisation, and --json prints the URL, permissions and steps as one object.

setup verify asks GitHub for a device code the way a reviewer's first sign-in will, and prints neither code it receives.

setup ci writes .github/workflows/maple.yml on maple-kit/maple-action@v0, refusing to overwrite one that is there, and prints the gh api command that makes maple/visual-review a required check pinned to GitHub Actions.

setup preview mirrord adds feature.env.override to each preview config in .mirrord/*.json (a file name containing preview, a top-level key or a feature.preview section; the others are listed and left alone, and --config <file> names one explicitly) so a mirrord preview pod knows its key, pull request, branch and commit. The values are Tera templates over -k and GitHub Actions' own variables, so on GitHub Actions no workflow step is needed; on other CI, export MAPLE_PULL_REQUEST or MAPLE_BRANCH before mirrord preview start. It sets feature.network.incoming.mode to steal when no mode is set. Without --write it prints the change; it never overwrites a value that is set, warns on mirrord's mirror, and refuses a file with comments. After --write it runs mirrord verify-config --resolved when mirrord is installed, on a temp copy with a literal key when the file's own is missing or a template, which mirrord cannot render.

maple mock plan

Asks a deployed Maple route to read a sentence as a mock, and prints the recipe Maple Mock's box would apply. It asks the route rather than a model, so CI holds no key and gets exactly the box's own plan.

maple mock plan "the reviews list is empty" \
  --url=https://preview.example.com/api/maple \
  --route=/reviews \
  --calls="rest:GET /api/reviews,rest:GET /api/audit" \
  --json

{
  "version": 2,
  "calls": [{ "key": "rest:GET /api/reviews", "state": "empty" }],
  "route": "/reviews",
  "request": "the reviews list is empty"
}

Flag	What it is
--url	Where Maple's route is mounted on the preview.
--route	The page's route pattern the recipe applies on, such as /projects/:id.
--calls	The calls the page makes, comma-separated, named as the box names them.

It exits 1, saying why, when the sentence names no state or the plan is not sure enough to mock anything: the same gate the box applies.

maple mock schema

maple mock schema server/router.ts --out=.maple/schema.json [--export=AppRouter] [--superjson]

Reads the router's TypeScript types statically, runs none of its code, and writes the document Maple's route serves as each call's shape. It needs @trpc/openapi, an optional peer loaded only by this command.

maple connectors

Connector kinds
  store         required: list, append
                optional: appendMany, setStatus, head, watch, approvals, approve, unapprove
  media         required: putBlob, getUrl
                optional: remove
  observability required: getReplayLink
                optional: fetchEvents
  identity      required: resolveUser
                optional: none
  gate          required: publish
                optional: read
  classifier    required: none
                optional: score, classify, plan

Built from core's own tables, so it cannot drift from the code. A connector's capabilities are exactly the methods it defines.

Reading comments from a terminal

Listing, reading and resolving review comments is the agent's job, over @maple-kit/mcp.

Licence

Apache-2.0. See LICENSE and NOTICE.