@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 +308 -2
- package/dist/deck.js +27650 -0
- package/package.json +56 -4
- package/spec/table.json +3640 -0
- package/templates/agents-section.md +12 -0
package/README.md
CHANGED
|
@@ -1,3 +1,309 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@deckco/cli` — command table
|
|
2
2
|
|
|
3
|
-
|
|
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.
|