@deckco/cli 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,309 @@
1
- # Temporary Holding Version
1
+ # `@deckco/cli` — command table
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The data table every Deck command and MCP tool is generated from. One row per API
4
+ operation; one handler (V2-4689 → 2a) runs all of them, and the local and hosted
5
+ MCP servers expose the same rows as tools.
6
+
7
+ It sits beside the servers that read it, under `external-components/`: this
8
+ package, `../mcp/server` (hosted, mcp.deck.co) and the local server when it
9
+ lands. The table stays here rather than in a package of its own, decided
10
+ 2026-11-02 — a third workspace buys nothing while one package owns both the
11
+ builder and the classification that the build fails without.
12
+
13
+ One consequence worth knowing before 3c wires the hosted server to real tools:
14
+ its image builds with `external-components/mcp/server` as the Docker context, so
15
+ it cannot `COPY` `spec/table.json` from here. Widen that context to
16
+ `external-components/` (`build-mcp-server.yaml`, and the Dockerfile's paths with
17
+ it) when the table is first needed there. Do not vendor a second copy: two
18
+ tables that can disagree is precisely what one table exists to prevent.
19
+
20
+ ## Installing it
21
+
22
+ ```bash
23
+ npm i -g @deckco/cli
24
+ deck tasks list --json
25
+ ```
26
+
27
+ ## Running it from the repo
28
+
29
+ ```bash
30
+ npx tsx bin/deck.ts tasks list --help --json
31
+ ```
32
+
33
+ `bin/deck.ts` is the entry point and `tsx` runs it in place, because it imports
34
+ `../src/run.js` — a specifier only a bundler or a transpiling runner resolves.
35
+
36
+ The published package resolves it ahead of time: `npm run build` bundles the
37
+ entry point into `dist/deck.js` with esbuild, and `bin` points there. A bundle
38
+ rather than a `tsc` emit because it solves a second problem at the same time —
39
+ `@deck/command-table` is `private` and unpublishable, so it has to be inlined;
40
+ declared as a dependency it would install fine in this workspace and 404 for
41
+ every customer. `jq-wasm` stays external, being a real runtime dependency with
42
+ a `.wasm` asset no bundler can inline.
43
+
44
+ **The bundle must stay one level below the package root.** `src/version.ts`
45
+ reads `../package.json` and `src/run.ts` reads `../spec/table.json`, both
46
+ relative to `import.meta.dirname`; `dist/deck.js` keeps those resolving and a
47
+ nested `dist/src/deck.js` would break both at once. `tests/package.test.ts`
48
+ packs the real tarball, installs it into an empty directory and runs the
49
+ binary, so that constraint fails a PR instead of a release.
50
+
51
+ ## Commands
52
+
53
+ Table commands (one per API operation) are listed by `deck api ls`; `deck help` lists everything.
54
+ The hand-written ones, none of which is a table row:
55
+
56
+ | Command | What it does |
57
+ |---|---|
58
+ | `init`, `login`, `logout`, `whoami` | Create an org, sign in (Clerk OAuth, then `POST /v2/bot/token`), sign out, say who you are |
59
+ | `orgs list`, `orgs switch` | List and switch the org the session is scoped to |
60
+ | `link`, `unlink`, `doctor` | Bind a directory to an org, unbind, diagnose state |
61
+ | `keys list/retrieve/create/delete` | API keys (`/v2/api-keys`, unpublished, so not table rows and not MCP tools) |
62
+ | `retrieve <id>` | GET any resource by its id prefix |
63
+ | `api`, `api ls` | Raw request, and the table's command listing |
64
+ | `agent setup`, `agent-guide` | Set up an agent's client; print the one-call orientation |
65
+ | `mcp serve/install/list/uninstall` | The local MCP server and its client entries |
66
+ | `open`, `completion`, `upgrade`, `changelog` | Open a resource in the Console, shell completion, self-update, release notes |
67
+ | `telemetry`, `feedback` | Telemetry status/enable/disable; send feedback |
68
+ | `version`, `help` | |
69
+
70
+ `task-runs watch` and the other `watch` commands come from the table's follow descriptors.
71
+
72
+ `events tail` is a **one-shot** `GET /v2/events`: it fetches once and exits. It does not poll, move `created_after`, dedupe by event id or stream lines, which the name suggests and the PRD's composite would do. The table names that operation `events tail`; `events list` does not exist yet (renaming would break the `follow`/`stream` aliases, which resolve only at an existing `tail`).
73
+
74
+ Not built yet, and listed with the reason in `tests/native.test.ts` (`ABSENT`):
75
+ `routines build/test`, `routine-builds *`, `sessions browser-access *`, `events verify`,
76
+ `docs search/read`, and `events list` (the table names `GET /v2/events` `events tail`).
77
+ That test fails when one of them starts resolving, so the entry must be deleted then.
78
+
79
+ ### `open` and `changelog` need `DECK_CONSOLE_URL` off production
80
+
81
+ Both refuse, deliberately, unless the API is production (`api.deck.co`) or
82
+ `DECK_CONSOLE_URL` is set: a local or ephemeral stack has no way to know which Console
83
+ belongs to it, and guessing would open the wrong environment. On such a stack:
84
+
85
+ ```bash
86
+ export DECK_CONSOLE_URL=https://<your-console-host>
87
+ ```
88
+
89
+ ## Before the first release: two values must be supplied
90
+
91
+ - **Clerk CLI client ids** — `src/oauth-clients.ts` (`ENVIRONMENTS`). Empty today, so
92
+ `deck login` refuses by name on every environment. (V2-4680.)
93
+ - **PostHog project key** — `src/telemetry-project.ts`. An empty placeholder, so the
94
+ client is a no-op and `deck feedback` cannot succeed. See the file for the two
95
+ candidate keys and why they are not interchangeable.
96
+
97
+ Neither has a fallback; shipping without them ships a CLI that cannot sign in and cannot
98
+ send feedback.
99
+
100
+ ## Telemetry, and the key that is not set
101
+
102
+ `posthog-node` is bundled like the MCP SDK, so it is a devDependency and
103
+ customers never install it. Its own `engines.node` is `>=20`. The package
104
+ declares `>=20.11`; neither that nor any other lower bound has been exercised,
105
+ because the bundle has only ever been run on Node 22.
106
+
107
+ **The PostHog project key is a placeholder (`src/telemetry-project.ts`, empty),
108
+ and the client sends nothing until it is set.** It must be chosen before
109
+ release; the file lists the two committed candidates and why they are not
110
+ interchangeable. `DECK_POSTHOG_KEY`, `DECK_POSTHOG_HOST` and
111
+ `DECK_POSTHOG_FEEDBACK_SURVEY_ID` override it for local testing, and no test
112
+ uses a real key.
113
+
114
+ Telemetry must never change what the CLI does: no exit code, no output, and at
115
+ most `FLUSH_TIMEOUT_MS` of delay. `tests/telemetry.test.ts` holds the failure
116
+ modes against the same command run with telemetry off, and
117
+ `tests/package.test.ts` holds the installed binary against an endpoint that
118
+ never answers.
119
+
120
+ ## Releasing it
121
+
122
+ Push a tag:
123
+
124
+ ```bash
125
+ # from external-components/ — the lockfile records the member's version too,
126
+ # so `npm pkg set` alone leaves it stale.
127
+ npm pkg set version=0.2.0 --workspace @deckco/cli
128
+ npm install --package-lock-only
129
+ # ...open that as a PR, merge it, then tag the merge commit ON MAIN:
130
+ git tag cli-v0.2.0 && git push origin cli-v0.2.0
131
+ ```
132
+
133
+ `npm version` is deliberately not used: in a workspace it does not create the
134
+ `cli-v*` tag this release is keyed on.
135
+
136
+ `release-cli.yaml` publishes on a `cli-v*` tag — never on a merge, since an npm
137
+ version cannot be republished. It refuses a tag that is not reachable from
138
+ `main`, refuses one whose number disagrees with `package.json`, and runs the
139
+ packaging test before uploading.
140
+
141
+ No `provenance`: npm will not sign a package whose source repo is private, and
142
+ this one is. Turning it on fails the publish with
143
+ `Unsupported ... repository visibility: private`. Revisit if the repo ever goes
144
+ public.
145
+
146
+ ## Layout
147
+
148
+ | Path | What it is |
149
+ |---|---|
150
+ | `spec/openapi.json` | The pinned spec snapshot. Committed, never fetched at build time. |
151
+ | `spec/SOURCE.json` | Where that snapshot came from — URL, `info.version`, fetch date. |
152
+ | `spec/overlay.json` | The per-operation facts no spec carries, plus aliases for operations the API shipped unnamed. |
153
+ | `spec/table.json` | The emitted table. Committed so an API change shows up as a diff. |
154
+ | `src/build-table.ts` | The builder. Pure — spec in, rows out, no I/O. |
155
+
156
+ `npm run refresh:spec` validates the fetched document before it overwrites
157
+ anything: a 200 carrying valid JSON that is not this spec leaves the pin intact,
158
+ because the pin is what every review of an API change is diffed against.
159
+
160
+ ## Which spec, and why it is pinned
161
+
162
+ The snapshot is the spec **the API generates from its own controllers**
163
+ (`api.deck.co/openapi/v1.json`), not the copy Mintlify serves at
164
+ `docs.deck.co/api-reference/v2.json`. The two are not the same document: as of
165
+ build `2.0.0.522` the generated one has 85 operations and the docs copy has 65,
166
+ because the docs copy is maintained by hand. Reading the docs copy would ship a
167
+ CLI missing a fifth of the API.
168
+
169
+ It is committed rather than fetched because `destructive`, `sensitive` and
170
+ `core` exist in no spec — the generator emits no `x-` extensions. Each is a
171
+ human call per operation,
172
+ and a committed snapshot is what makes an API change arrive as a reviewable PR
173
+ where that call gets made. Fetch live instead and a new endpoint reaches the CLI
174
+ and the hosted MCP's tool list with whatever the default is — a new delete
175
+ without `--yes`, or a secret-adjacent endpoint visible to a token that should
176
+ not see it.
177
+
178
+ ## Refreshing after an API change
179
+
180
+ ```bash
181
+ npm run refresh:spec # re-fetch the snapshot (writes spec/openapi.json + SOURCE.json)
182
+ npm run build:table # re-emit spec/table.json
183
+ npm test # fails until every new operation is classified
184
+ ```
185
+
186
+ The build refuses rather than guesses. Each refusal names what to do:
187
+
188
+ - **no `operationId`** — the controller action is missing `[EndpointName("...")]`.
189
+ Fix it in the API; until then, name it in `unnamed_operations` so the command
190
+ name is reviewed rather than invented.
191
+ - **no tag** — no command group can be derived.
192
+ - **no overlay entry** — classify the operation in `spec/overlay.json`.
193
+ - **malformed overlay entry** — `command` must be a non-empty string and the
194
+ three flags booleans. Not trusted, because a missing `destructive` would read
195
+ as falsy and ship a delete with no `--yes`.
196
+ - **overlay entry the spec no longer has** — delete the line.
197
+ - **alias the spec no longer needs** — the API now supplies the `operationId`
198
+ itself, so delete the `unnamed_operations` entry.
199
+ - **two operations deriving the same command or tool name** — `deriveCommand`
200
+ drops the tag's nouns, so a collision is possible; renaming a published command
201
+ later is not.
202
+
203
+ ## What the MCP servers take from a row
204
+
205
+ The CLI and both MCP servers run off the same row — that is what keeps them on
206
+ one set of operations. The MCP side needs three things the CLI does not care
207
+ about, so they are columns here rather than something the server re-derives:
208
+
209
+ | Column | Why MCP needs it |
210
+ |---|---|
211
+ | `description` | What a model reads when choosing a tool. Taken from the operation's `summary`. |
212
+ | `body_schema` | Handed straight to the tool's `inputSchema`, so it stays real JSON Schema — `required` and `enum` intact. A flattened name→type map would drop both and leave the model guessing. |
213
+ | `path_params` / `query_params` | Each carries its own schema and whether it is required, so the server can merge them into one `inputSchema` and the CLI can type-check a flag. |
214
+
215
+ `mcp` is whether the operation may be an MCP tool **at all** — not registered,
216
+ and not reachable through `execute`. False on the three whose response carries a
217
+ secret: `credentials create` and `token create`, which the PRD names ("would put
218
+ a secret into model context and client transcripts"), and `init`
219
+ (`POST /v2/organizations`), which it does not — that one answers with a live
220
+ `sk_live_` key and a claim token, and provisioning an unclaimed org is
221
+ meaningless from a server the caller already authenticated to. It is required
222
+ rather than defaulted to true, because a default would expose the next
223
+ secret-returning endpoint on the day it ships.
224
+
225
+ `core` is the PRD's default tool set, restricted to the operations this table
226
+ covers — the rest of its list (`execute`, `describe_operation`,
227
+ `search_deck_docs`, `create_credential_link`, `build_routine`, …) is CLI- or
228
+ MCP-native, or belongs to the Routines project, so it has no row here.
229
+ `create_credential_link` is offered by the HOSTED MCP server only: the link it
230
+ mints captures a password, and the API sets how long it stays openable from the
231
+ caller's auth type — a `bot` gets an hour, the API key `deck mcp serve` runs on
232
+ would get twenty-four. See `cli/src/native/mcp-tools.ts` for the whole
233
+ argument and what would have to change.
234
+
235
+ `sensitive_rule` marks the calls the PRD gates **at runtime**: before fetching
236
+ screenshots or browser logs, load the task and check `settings.sensitive`; if it
237
+ is set, return `task_sensitive` rather than fetching and redacting. It says a
238
+ check is required before the call — it is not a property of the operation.
239
+
240
+ `scope` is derived from the HTTP method, because that is exactly how the PRD
241
+ defines it: read tools vs write tools. It is not in the overlay, since asking a
242
+ human to restate the verb adds nothing.
243
+
244
+ ## Command and tool names come from the PRD
245
+
246
+ Both are **data, not derivation**. The PRD (Linear P-V2-217, "Complete list")
247
+ spells every command, and its verbs are not the obvious ones: the canonical form
248
+ is `deck tasks retrieve`, with `get`, `show`, `view` and `inspect` listed as
249
+ *unpublished aliases*. An earlier version of this builder derived names from the
250
+ `operationId` and disagreed with the PRD on **32 of 79** operations.
251
+
252
+ So `spec/overlay.json` carries the command per operation, and the build fails
253
+ when one has no name. `tool` is `snake_case(operationId)`, overridden in the
254
+ overlay where the PRD says otherwise (`get_task_run_screenshots`,
255
+ `get_task_run_browser_logs`).
256
+
257
+ Six operations have no PRD name — the Complete list does not cover them — and
258
+ one has a PRD name (`whoami`) that the native command now owns, so its row is
259
+ `auth test`. Each of the seven carries `name_source` in the overlay (`derived —`
260
+ for the six, `ours —` for the one), so review can see which names are ours
261
+ rather than the PRD's.
262
+
263
+
264
+ ## Drift, and who notices it
265
+
266
+ The snapshot is pinned, so nothing in CI notices that the API has moved — and
267
+ `test-cli-table` only runs on changes under `external-components/cli/**`, so an
268
+ API PR adding an endpoint would not have run it either. Both halves are closed:
269
+
270
+ - `.github/workflows/cli-spec-drift.yaml` is **dispatched by `deploy.yaml`** at
271
+ the end of a prod promotion, and waits for the served `info.version` to
272
+ actually move, since `Deploy` finishing only means Kargo was told to promote.
273
+ Dispatched rather than called, so that wait runs on its own clock instead of
274
+ holding the deploy open. It opens a PR when the spec moved and decides
275
+ nothing. When an operation is new the build refuses, and that refusal is
276
+ carried in the PR body and a Slack line rather than by the PR's own checks:
277
+ GitHub does not trigger workflows for a PR opened with `GITHUB_TOKEN`, so
278
+ `pr-checks` never runs on it.
279
+ - `pr-checks.yaml`'s `cli` filter also watches
280
+ `api/src/Deck.Api.Host/Controllers/**`, so a PR adding an endpoint puts the
281
+ table in front of its reviewer.
282
+
283
+ The three operations that once shipped without an `operationId`
284
+ (`POST /v2/tasks/{task_id}/reset`, `POST /v2/organizations`,
285
+ `POST /v2/organizations/claim`) carry `[EndpointName]` as of `2.0.0.552`, so the
286
+ `unnamed_operations` block is gone and the builder treats it as optional —
287
+ absent is the goal, and refusing to run without a block that exists only to be
288
+ deleted would have been a bug.
289
+
290
+ ## What this table cannot cover
291
+
292
+ The PRD's command surface is larger than the published API. These have a command
293
+ in the PRD but no row here, because no spec operation exists to key them:
294
+
295
+ - `deck keys list/retrieve/create/delete` → `/v2/api-keys`, and `deck login` →
296
+ `/v2/bot/token`. Both controllers are `[ApiExplorerSettings(IgnoreApi = true)]`,
297
+ so the paths are absent from the spec entirely. `deck login` is hand-written
298
+ against that unpublished path (`src/native/login.ts`); the four keys commands
299
+ are hand-written too (`src/native/keys.ts`). They are deliberately not table rows and not
300
+ MCP tools: a key-minting operation must not be reachable through `execute`.
301
+ - `deck routine-builds …` and `deck sessions browser-access …` — endpoints that
302
+ arrive with the Routines project.
303
+ - CLI- and MCP-native commands with no endpoint at all: `deck link`, `deck logout`,
304
+ `deck doctor`, `deck orgs switch`, `deck task-runs watch`, and the `execute` /
305
+ `describe_operation` / docs tools.
306
+
307
+ A spec-derived table is the right shape for the 85 published operations and
308
+ cannot be the whole command surface. The handler (2a) needs a second, hand-written
309
+ source for the rest.