@shipd-ai/cli 0.1.3 → 0.3.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.
Files changed (53) hide show
  1. package/README.md +172 -42
  2. package/dist/auth.d.ts +9 -5
  3. package/dist/auth.js +43 -10
  4. package/dist/author.d.ts +11 -0
  5. package/dist/author.js +43 -0
  6. package/dist/backend.d.ts +4 -0
  7. package/dist/backend.js +51 -0
  8. package/dist/checks-view.d.ts +10 -0
  9. package/dist/checks-view.js +12 -0
  10. package/dist/client.d.ts +0 -8
  11. package/dist/client.js +0 -7
  12. package/dist/commands/auth.d.ts +9 -4
  13. package/dist/commands/auth.js +29 -41
  14. package/dist/commands/author-checks.d.ts +306 -0
  15. package/dist/commands/author-checks.js +430 -0
  16. package/dist/commands/author-content.d.ts +198 -0
  17. package/dist/commands/author-content.js +102 -0
  18. package/dist/commands/checks.d.ts +0 -2
  19. package/dist/commands/checks.js +21 -17
  20. package/dist/commands/problems.d.ts +1 -0
  21. package/dist/commands/problems.js +196 -0
  22. package/dist/commands/quests.d.ts +0 -1
  23. package/dist/commands/quests.js +0 -1
  24. package/dist/commands/runs.d.ts +54 -0
  25. package/dist/commands/runs.js +143 -0
  26. package/dist/content.d.ts +105 -0
  27. package/dist/content.js +240 -0
  28. package/dist/contract.d.ts +0 -1
  29. package/dist/contract.js +0 -7
  30. package/dist/errors.d.ts +3 -1
  31. package/dist/errors.js +6 -5
  32. package/dist/format.d.ts +2 -4
  33. package/dist/format.js +29 -7
  34. package/dist/harbor.d.ts +0 -8
  35. package/dist/harbor.js +0 -11
  36. package/dist/index-gate.d.ts +1 -0
  37. package/dist/index-gate.js +5 -0
  38. package/dist/index.js +15 -10
  39. package/dist/model.d.ts +128 -0
  40. package/dist/model.js +68 -0
  41. package/dist/plan.d.ts +0 -15
  42. package/dist/plan.js +0 -21
  43. package/dist/prompt.d.ts +5 -0
  44. package/dist/prompt.js +26 -0
  45. package/dist/quests.d.ts +2 -10
  46. package/dist/quests.js +51 -34
  47. package/dist/report.d.ts +0 -9
  48. package/dist/report.js +1 -7
  49. package/dist/runs.d.ts +36 -0
  50. package/dist/runs.js +59 -0
  51. package/dist/usage.d.ts +2 -0
  52. package/dist/usage.js +16 -0
  53. package/package.json +3 -2
package/README.md CHANGED
@@ -1,33 +1,145 @@
1
1
  # Shipd CLI (`@shipd-ai/cli`)
2
2
 
3
- `shipd` is the admin command line for Shipd quests. Point it at a Harbor task
4
- directory (or an existing task) and it runs the quest's checks on the quest's
5
- own infrastructure, then returns the same structured output the product shows.
6
- The CLI is quest-agnostic: every command takes `--quest <quest>`, and any
7
- quest that implements the small `adhocChecks:*` contract works the same way.
3
+ `shipd` is the command line for Shipd quests. It has two editions, decided by
4
+ the token you sign in with:
5
+
6
+ - **Author edition** — read your own challenges and run their checks from a
7
+ terminal, exactly as the challenge page does (same visibility, same gates,
8
+ same results). `shipd problems …` and the author `shipd checks …` commands.
9
+ - **Admin edition** — everything above, plus the ad-hoc checks: point the CLI
10
+ at a Harbor task directory (or an existing task) and it runs the quest's
11
+ checks on the quest's own infrastructure. `shipd checks list|run|status|cancel`.
12
+
13
+ The CLI is quest-agnostic: every command takes `--quest <quest>`, and
8
14
  `shipd quests` lists the quests available (olympus today, which is also the
9
15
  default when `--quest` is omitted).
10
16
 
11
- Admins only: every quest entrypoint checks the caller's effective admin role.
17
+ ## Install and sign in
18
+
19
+ ```bash
20
+ npm install -g @shipd-ai/cli@0.3.0
21
+ shipd login # opens https://shipd.ai/quests/olympus/cli-auth; or: shipd login --token <jwt>
22
+ shipd whoami # who you are and which edition the token is
23
+ shipd quests # which quests this CLI can talk to
24
+ ```
12
25
 
13
- ## Install and log in
26
+ `login` opens the quest's token page in your browser, which mints the author
27
+ edition for an enrolled author and the admin edition for a real admin; paste
28
+ the token back into the terminal — it is not echoed. `--no-browser` prints the
29
+ page URL instead of opening it; `--platform` opens the platform-level admin
30
+ page instead. The token is stored owner-readable only at
31
+ `~/.shipd/credentials.json` (mode 0600; a file the CLI cannot make owner-only
32
+ refuses the save). It is personal: never commit or share it. Typing `--token`
33
+ by hand leaves it in your shell history, so prefer the prompt there.
34
+ `shipd logout` deletes it. The author token lasts 7 days, the admin token 30;
35
+ a token cannot be revoked before it expires, but it stops working when your
36
+ enrollment (or admin access) ends, from the next command on.
14
37
 
15
- Admin docs, the supported checks, and a copy-paste setup prompt for coding agents live at https://shipd.ai/admin/cli (admins only; direct link to the prompt: https://shipd.ai/admin/cli#agent-setup-prompt).
38
+ ## Author commands
16
39
 
17
40
  ```bash
18
- npm install -g @shipd-ai/cli
19
- shipd login # opens https://shipd.ai/cli-auth (one token for every quest); or: shipd login --token <jwt>
20
- shipd whoami
21
- shipd quests # which quests this CLI can talk to
41
+ shipd problems list [--status <status>] [--limit <n>]
42
+ shipd problems view <challenge-id>
43
+ shipd problems versions <challenge-id>
44
+ shipd problems create [-d <dir>] [--title … --language … --repo … --test-patch-file … …]
45
+ shipd problems pull <challenge-id> -d <dir>
46
+ shipd problems push <challenge-id> [-d <dir>] [--title … --description-file … --clear <fields>]
47
+
48
+ shipd runs list <challenge-id>
49
+ shipd runs download <challenge-id> (--run <runId> | --all) [--artifact <keys> | --all-artifacts] -d <dir>
50
+
51
+ shipd checks view <challenge-id>
52
+ shipd checks run-prechecks <challenge-id>
53
+ shipd checks run-scope-gate <challenge-id>
54
+ shipd checks run-check <challenge-id> --check <checkKey>
55
+ shipd checks run-all <challenge-id>
56
+ shipd checks run-trial-qa <challenge-id>
57
+ shipd checks wait <challenge-id> [--interval <s>] [--timeout <min>]
22
58
  ```
23
59
 
24
- `login` opens the token page in your browser; paste the token back into the
25
- terminal. `--no-browser` prints the page URL instead of opening it. The token is
26
- stored at `~/.shipd/credentials.json` (mode 0600). It is personal: never commit
27
- or share it. Typing `--token` by hand leaves it in your shell history, so prefer
28
- the prompt there. `shipd logout` deletes it.
60
+ `problems view` shows the latest version, submission readiness, prechecks,
61
+ quality checks, Trial QA and the rollout criteria. The CLI reaches only the
62
+ challenges you author or co-author; any other id is "not found".
63
+
64
+ ### Content files
65
+
66
+ `problems pull` writes a challenge's saved content into a directory and
67
+ `problems push` saves the files found there (and any field flags) back onto
68
+ the draft; `problems create` makes a new draft from the same files/flags.
69
+ The layout is the editor's fields, named as the quest names them:
70
+
71
+ | File | Field |
72
+ |---|---|
73
+ | `task.json` | `title`, `language`, `category`, `difficulty`, `githubRepoUrl`, `githubCommitHash`, `githubIssueUrl`, `testOutputMode` (`exit_code` \| `junit_xml`), `estimatedLOC` |
74
+ | `description.md` | `description` |
75
+ | `Dockerfile` | `dockerfile` |
76
+ | `test.patch` | `testPatch` |
77
+ | `solution.patch` | `solutionPatch` |
78
+ | `approach.md` | `solutionApproach` |
79
+ | `environment.md` | `environmentDescription` |
80
+ | `hint.md` | `hintText` |
81
+ | `hint-justification.md` | `hintJustification` |
82
+
83
+ `push` sends only what is present: a missing file or key leaves the saved
84
+ value alone, a flag beats the directory, `--clear hintText,githubIssueUrl`
85
+ empties a text field on purpose, and `--<field>-file -` reads one file from
86
+ stdin. Every save goes through the editor's own rules on the quest: your own
87
+ or co-authored draft only, no edits to a locked (submitted) version or an
88
+ archived draft, the patch size ceilings, the repository and field validators;
89
+ a refusal prints the page's message (exit 1). Build Image, the Scope Gate,
90
+ submitting and archiving stay page steps.
91
+
92
+ ### Agent runs
93
+
94
+ `runs list` shows the latest version's agent runs as the checks tab lists
95
+ them (agent codename, status, verdict, flags, times). `runs download` saves a
96
+ run's files under `<dir>/<runId>/` with the names the page's own download
97
+ uses: `trajectory.json`, `workspace-diff.patch`, `solution-patch.patch`,
98
+ `test-log.txt`, `junit-baseline.xml`, `junit-new.xml`, `eval-result.json` —
99
+ fetched through the page's own download, the evaluator's result through the
100
+ same free-text filter the page applies. A file the quest does not hand an
101
+ author (admin-only diagnostics, a quality check's agent files) or that a run
102
+ never produced is reported as skipped. A later `pull` into the same directory
103
+ removes a content file the challenge no longer has, so a push after it cannot
104
+ restore a cleared field.
105
+
106
+ - `run-prechecks` runs the precheck stages on the saved version, as the page's
107
+ Run button does.
108
+ - `run-check` runs one quality check (`verifyTests`, `verifySolution`,
109
+ `verifyFlakiness`, `descriptionQuality`, `solutionQuality`, `rewardHacking`,
110
+ `verifyFairness`); `run-all` runs that set, the one the page's Run Checks
111
+ runs, in check order. The image build stays the page's Build Image button,
112
+ the one step with no CLI command.
113
+ - `run-scope-gate` runs the Scope Gate as the page's card does, once the
114
+ prechecks pass: the card's own rules apply (your own draft, an unlocked
115
+ version, no run in flight, a verdict not already final for this exact
116
+ content, fresh passing prechecks, a description and both patches, a
117
+ connected GitHub account) and the same 4 tokens are charged; `checks view`
118
+ shows the standing verdict, its reasoning and findings, and `wait` counts a
119
+ gate in flight as active. `run-all` before the gate has passed prints the
120
+ page's refusal ("Run and pass the Scope Gate before running checks").
121
+ - `run-trial-qa` runs Trial QA on the current rollouts.
122
+ - `wait` polls until no check is active (nothing pending, running, waiting for
123
+ a prerequisite or in Trial QA), then prints the results; its progress goes
124
+ to stderr.
29
125
 
30
- ## Three input modes
126
+ Every run goes through the same gates as the page: tokens are charged the same
127
+ way (`--use-general-tokens` is the page's "use tokens instead" toggle), the
128
+ submission cooldown, the image build, the Scope Gate, the check order and the
129
+ locked-version rule all apply, and a refusal prints the message the page
130
+ shows (exit 1). Every command takes `--json`: `checks view --json` prints
131
+ `{ version, prechecks, scopeGate, dynamicChecks, trialQa, readiness }`, each
132
+ exactly as the quest returns it to the page.
133
+
134
+ ## Admin ad-hoc checks
135
+
136
+ Admins only: every quest entrypoint checks the caller's effective admin role,
137
+ and the CLI refuses an author token for these commands before any network
138
+ call. Admin docs, the supported checks, and a copy-paste setup prompt for
139
+ coding agents live at https://shipd.ai/admin/cli (admins only; direct link to
140
+ the prompt: https://shipd.ai/admin/cli#agent-setup-prompt).
141
+
142
+ ### Three input modes
31
143
 
32
144
  | Mode | Command | What happens | Writes to production |
33
145
  | --- | --- | --- | --- |
@@ -40,7 +152,7 @@ dispatched; `--create` prints the new task URL as soon as the draft exists.
40
152
  Checks cost real compute: use `--dry-run` first and confirm `--all` with a
41
153
  human when an agent is driving.
42
154
 
43
- ## Harbor layout
155
+ ### Harbor layout
44
156
 
45
157
  Only these paths are read; everything else in the directory is ignored.
46
158
 
@@ -59,14 +171,14 @@ files may total at most 4 MiB. `--repo`, `--commit`, `--title`, `--category`,
59
171
  `--language` and `--difficulty` override the `task.toml` metadata, which is how
60
172
  a non-Olympus bundle fills in what it lacks.
61
173
 
62
- ## Commands
174
+ ### Commands
63
175
 
64
176
  ```bash
65
177
  shipd checks list --quest olympus
66
178
  shipd checks run ./task --all --dry-run # eligibility + adapted inputs, spends nothing
67
179
  shipd checks run ./task --check verifyBuild,descriptionQuality
68
180
  shipd checks run ./task --all --json --out report.json
69
- shipd checks run ./task --create --check autoReview # creates a draft, runs live
181
+ shipd checks run ./task --create --check solutionQuality # creates a draft, runs live
70
182
  shipd checks run --task <problemId> --check scopeGate # runs live on an existing task
71
183
  shipd checks run ./task --check verifyBuild --no-wait # prints handles as JSON lines
72
184
  shipd checks status '<handle json>' # or: shipd checks status report.json
@@ -81,42 +193,56 @@ per step (default 180, the longest worker timeout).
81
193
 
82
194
  Checks whose required bundle parts are missing are reported as `skipped` with
83
195
  the missing list. With `--all` that is informational; with `--check` it fails
84
- the run. Multi-step checks (for example `autoReview`) run as a step plan the
85
- quest describes: independent steps in parallel, each later step fed the
86
- earlier outputs, a failed step marking its dependents `skipped: upstream
87
- failed`. Prechecks (`precheck:<stage>`) run synchronously.
196
+ the run. Multi-step checks (for example `solutionQuality`: `verifySolution`,
197
+ then `evaluate`) run as a step plan the quest describes: independent steps in
198
+ parallel, each later step fed the earlier outputs, a failed step marking its
199
+ dependents `skipped: upstream failed`. Prechecks (`precheck:<stage>`) run
200
+ synchronously.
88
201
 
89
202
  Ctrl-C asks whether to cancel the in-flight steps; a second Ctrl-C leaves them
90
203
  running. Handles stay in the JSON report, so `checks status` and
91
204
  `checks cancel` keep working on them afterwards.
92
205
 
206
+ ### Report
207
+
208
+ `--json` and `--out` produce the same document: `quest`, `mode`, `source`
209
+ (bundle directory and `inputHash`, or the task ids, title and URL), a top-level
210
+ `taskUrl` in live modes, one entry per
211
+ check with `status`, `verdict`, `output`, `error`, `durationMs`, and `steps`
212
+ (each step's handle and output), plus `prechecks` keyed by stage id.
213
+
93
214
  ## Exit codes
94
215
 
95
216
  | Code | Meaning |
96
217
  | --- | --- |
97
- | 0 | every run check passed or warned |
98
- | 1 | a check failed or errored (or an explicitly requested check was skipped) |
218
+ | 0 | every run check passed or warned; the author command succeeded |
219
+ | 1 | a check failed or errored (or an explicitly requested check was skipped); the quest refused an author command |
99
220
  | 2 | usage, auth, or bundle error (nothing was dispatched) |
100
221
  | 3 | cancelled |
101
222
 
102
- ## Report
223
+ ## Where the token goes
103
224
 
104
- `--json` and `--out` produce the same document: `quest`, `mode`, `source`
105
- (bundle directory and `inputHash`, or the task ids, title and URL), a top-level
106
- `taskUrl` in live modes, one entry per
107
- check with `status`, `verdict`, `output`, `error`, `durationMs`, and `steps`
108
- (each step's handle and output), plus `prechecks` keyed by stage id.
225
+ The quest's base URL serves its token page and the `/api/cli/config` endpoint
226
+ that names its Convex deployment; the token is sent only to that deployment.
227
+ Outside development the base URL must be a `shipd.ai` host over https and the
228
+ Convex URL `https://*.convex.cloud` or `https://*.convex.site`, whether it
229
+ came from the endpoint or the cache; `*.convex.cloud` is shared by every
230
+ Convex tenant, so a bare `SHIPD_<QUEST>_CONVEX_URL` is honoured only with
231
+ `NODE_ENV=development`. Any override is named once on stderr (`Using
232
+ SHIPD_OLYMPUS_URL: <host>`) so a stray environment variable cannot quietly
233
+ redirect the CLI. Every string the quest sends back is printed through a
234
+ control-byte filter; `--json` is the quest's payload verbatim.
109
235
 
110
236
  ## Environment
111
237
 
112
238
  | Variable | Effect |
113
239
  | --- | --- |
114
- | `SHIPD_AUTH_URL` | Override the platform login page `shipd login` opens (default `https://shipd.ai/cli-auth`). |
115
- | `SHIPD_<QUEST>_URL` | Override the quest's base URL (for example `SHIPD_OLYMPUS_URL`). |
116
- | `SHIPD_<QUEST>_CONVEX_URL` | Skip `/api/cli/config` and talk to this Convex deployment. |
240
+ | `SHIPD_AUTH_URL` | Override the platform login page `shipd login --platform` opens (default `https://shipd.ai/cli-auth`). |
241
+ | `SHIPD_<QUEST>_URL` | Override the quest's base URL (for example `SHIPD_OLYMPUS_URL`); a `shipd.ai` host over https outside development. |
242
+ | `SHIPD_<QUEST>_CONVEX_URL` | Skip `/api/cli/config` and talk to this Convex deployment — development only. |
117
243
  | `SHIPD_HOME` | Credentials and caches directory (default `~/.shipd`). |
118
- | `SHIPD_NO_UPDATE_CHECK=1` | Skip the version check. |
119
- | `NODE_ENV=development` | Use the localhost quest URLs. |
244
+ | `SHIPD_NO_UPDATE_CHECK=1` | Skip the version check. The quest's `minCliVersion` is advisory (client-enforced): the quest admits a token by its claims and your enrollment, not by the client's version. |
245
+ | `NODE_ENV=development` | Use the localhost quest URLs, and allow any https host, localhost over http, and the overrides. |
120
246
 
121
247
  ## Developer notes
122
248
 
@@ -125,12 +251,16 @@ pnpm --dir packages/shipd-cli typecheck
125
251
  pnpm --dir packages/shipd-cli test
126
252
  pnpm --dir packages/shipd-cli build
127
253
  pnpm --dir packages/shipd-cli cli checks list --quest olympus # runs src/ with tsx
128
- NODE_ENV=development pnpm --dir packages/shipd-cli cli checks list # against a local quest
254
+ NODE_ENV=development pnpm --dir packages/shipd-cli cli problems list # against a local quest
129
255
  ```
130
256
 
131
- The CLI contains no quest logic. It calls `adhocChecks:*` by name through
132
- Convex's `anyApi`; the shared argument and return shapes live in
133
- `src/contract.ts`, and each quest mirrors them with validators. The plan
257
+ The CLI contains no quest logic. The admin commands call `adhocChecks:*` by
258
+ name through Convex's `anyApi`; the shared argument and return shapes live in
259
+ `src/contract.ts`, and each quest mirrors them with validators. The author
260
+ commands call the challenge page's own queries and actions by name
261
+ (`src/author.ts`); on the quest those are the functions that opted in for the
262
+ author-edition token, redacted and gated server-side exactly as for the page
263
+ (Olympus: `convex/helpers/cliToken.boundary.test.ts` pins the list). The plan
134
264
  executor (`src/plan.ts`) and bundle reader (`src/harbor.ts`) are unit-tested
135
265
  against a fake quest and a fixture bundle in `test/`.
136
266
 
package/dist/auth.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export declare function shipdDir(): string;
2
+ export declare function credentialsPath(): string;
2
3
  export interface DecodedIdentity {
3
4
  sub: string;
4
5
  email: string;
@@ -6,12 +7,10 @@ export interface DecodedIdentity {
6
7
  name: string;
7
8
  picture: string;
8
9
  exp: number;
10
+ cli?: unknown;
9
11
  }
10
- /**
11
- * Decode the JWT payload without verifying the signature. The quest's Convex
12
- * deployment verifies it on every request; the CLI only reads the payload for
13
- * display (name, email) and the local expiry check.
14
- */
12
+ export type TokenEdition = "admin" | "author" | "unknown";
13
+ export declare function tokenEdition(identity: Pick<DecodedIdentity, "cli">): TokenEdition;
15
14
  export declare function decodeJwtPayload(token: string): DecodedIdentity;
16
15
  export declare function ensureShipdDir(): string;
17
16
  export declare function saveCredentials(token: string): DecodedIdentity;
@@ -24,3 +23,8 @@ export declare function requireAuth(): {
24
23
  token: string;
25
24
  identity: DecodedIdentity;
26
25
  };
26
+ export declare const ADMIN_EDITION_REQUIRED = "This command needs the admin edition of the token.";
27
+ export declare function requireAdminEdition(): {
28
+ token: string;
29
+ identity: DecodedIdentity;
30
+ };
package/dist/auth.js CHANGED
@@ -1,18 +1,20 @@
1
- import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
1
+ import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
2
2
  import { homedir } from "node:os";
3
3
  import { resolve } from "node:path";
4
- import { AuthError } from "./errors.js";
4
+ import { AuthError, UsageError } from "./errors.js";
5
5
  export function shipdDir() {
6
6
  return resolve(process.env.SHIPD_HOME ?? resolve(homedir(), ".shipd"));
7
7
  }
8
- function credentialsPath() {
8
+ export function credentialsPath() {
9
9
  return resolve(shipdDir(), "credentials.json");
10
10
  }
11
- /**
12
- * Decode the JWT payload without verifying the signature. The quest's Convex
13
- * deployment verifies it on every request; the CLI only reads the payload for
14
- * display (name, email) and the local expiry check.
15
- */
11
+ export function tokenEdition(identity) {
12
+ if (identity.cli === true)
13
+ return "admin";
14
+ if (identity.cli === "author")
15
+ return "author";
16
+ return "unknown";
17
+ }
16
18
  export function decodeJwtPayload(token) {
17
19
  const parts = token.split(".");
18
20
  if (parts.length !== 3) {
@@ -32,12 +34,35 @@ export function ensureShipdDir() {
32
34
  }
33
35
  return dir;
34
36
  }
37
+ function ownerOnly(path, mode) {
38
+ try {
39
+ chmodSync(path, mode);
40
+ }
41
+ catch (error) {
42
+ if (process.platform === "win32")
43
+ return;
44
+ const code = error.code ?? "unknown error";
45
+ throw new AuthError(`Refusing to save credentials: could not make ${path} owner-only (${code}). ` +
46
+ "Fix its owner and permissions, or remove it, then sign in again.");
47
+ }
48
+ }
35
49
  export function saveCredentials(token) {
36
50
  const identity = decodeJwtPayload(token);
37
51
  const expiresAt = new Date(identity.exp * 1000).toISOString();
38
- ensureShipdDir();
52
+ const dir = ensureShipdDir();
53
+ const path = credentialsPath();
54
+ ownerOnly(dir, 0o700);
55
+ if (existsSync(path))
56
+ ownerOnly(path, 0o600);
39
57
  const data = { token, expiresAt };
40
- writeFileSync(credentialsPath(), `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
58
+ writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
59
+ try {
60
+ ownerOnly(path, 0o600);
61
+ }
62
+ catch (error) {
63
+ unlinkSync(path);
64
+ throw error;
65
+ }
41
66
  return identity;
42
67
  }
43
68
  export function loadCredentials() {
@@ -73,3 +98,11 @@ export function requireAuth() {
73
98
  }
74
99
  return creds;
75
100
  }
101
+ export const ADMIN_EDITION_REQUIRED = "This command needs the admin edition of the token.";
102
+ export function requireAdminEdition() {
103
+ const creds = requireAuth();
104
+ if (tokenEdition(creds.identity) === "author") {
105
+ throw new UsageError(ADMIN_EDITION_REQUIRED);
106
+ }
107
+ return creds;
108
+ }
@@ -0,0 +1,11 @@
1
+ import { ConvexHttpClient } from "convex/browser";
2
+ import type { ProblemWithLatestVersion, VersionSummary } from "./model.js";
3
+ export declare const api: import("convex/server").AnyApi;
4
+ export type AuthorClient = ConvexHttpClient;
5
+ export declare function connectAuthor(quest: string): Promise<AuthorClient>;
6
+ export declare function refusalMessage(error: unknown): string;
7
+ export declare function backend<T>(call: () => Promise<T>): Promise<T>;
8
+ export declare function requireProblemVersion(client: AuthorClient, problemId: string): Promise<{
9
+ problem: ProblemWithLatestVersion;
10
+ version: VersionSummary;
11
+ }>;
package/dist/author.js ADDED
@@ -0,0 +1,43 @@
1
+ import { ConvexHttpClient } from "convex/browser";
2
+ import { anyApi } from "convex/server";
3
+ import { ConvexError } from "convex/values";
4
+ import { requireAuth } from "./auth.js";
5
+ import { RefusedError, UsageError } from "./errors.js";
6
+ import { text } from "./format.js";
7
+ import { questConvexUrl, questHasAuthorCommands } from "./quests.js";
8
+ export const api = anyApi;
9
+ export async function connectAuthor(quest) {
10
+ if (!questHasAuthorCommands(quest)) {
11
+ throw new UsageError(`The author commands are not available for "${quest}".`);
12
+ }
13
+ const { token } = requireAuth();
14
+ const convexUrl = await questConvexUrl(quest);
15
+ const client = new ConvexHttpClient(convexUrl);
16
+ client.setAuth(token);
17
+ return client;
18
+ }
19
+ export function refusalMessage(error) {
20
+ if (error instanceof ConvexError && typeof error.data === "string")
21
+ return text(error.data);
22
+ const raw = error instanceof Error ? error.message : String(error);
23
+ return text(raw.split("\n")[0].replace(/^Uncaught (?:ConvexError|Error): /, ""));
24
+ }
25
+ export async function backend(call) {
26
+ try {
27
+ return await call();
28
+ }
29
+ catch (error) {
30
+ throw new RefusedError(refusalMessage(error));
31
+ }
32
+ }
33
+ export async function requireProblemVersion(client, problemId) {
34
+ const data = (await backend(() => client.query(api.problems.getWithLatestVersion, { problemId })));
35
+ if (!data) {
36
+ throw new UsageError(`Challenge not found: ${text(problemId)}`);
37
+ }
38
+ const version = data.latestVersion;
39
+ if (!version) {
40
+ throw new UsageError("No version found.");
41
+ }
42
+ return { problem: data, version };
43
+ }
@@ -0,0 +1,4 @@
1
+ export declare function isDevelopment(): boolean;
2
+ export declare function assertTrustedBaseUrl(url: string, development: boolean): string;
3
+ export declare function assertTrustedConvexUrl(url: string, development: boolean): string;
4
+ export declare function overrideHost(url: string): string;
@@ -0,0 +1,51 @@
1
+ const CONVEX_HOST_SUFFIXES = [".convex.cloud", ".convex.site"];
2
+ const SHIPD_HOST = "shipd.ai";
3
+ export function isDevelopment() {
4
+ return process.env.NODE_ENV === "development";
5
+ }
6
+ function parse(url, what) {
7
+ try {
8
+ return new URL(url);
9
+ }
10
+ catch {
11
+ throw new Error(`Refusing ${what} "${url}": not a valid URL.`);
12
+ }
13
+ }
14
+ function isLocalhost(parsed) {
15
+ return parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
16
+ }
17
+ function isShipdHost(parsed) {
18
+ return parsed.hostname === SHIPD_HOST || parsed.hostname.endsWith(`.${SHIPD_HOST}`);
19
+ }
20
+ function isConvexHost(parsed) {
21
+ return CONVEX_HOST_SUFFIXES.some((suffix) => parsed.hostname.endsWith(suffix));
22
+ }
23
+ export function assertTrustedBaseUrl(url, development) {
24
+ const parsed = parse(url, "the quest URL");
25
+ if (development) {
26
+ if (parsed.protocol === "https:")
27
+ return url;
28
+ if (parsed.protocol === "http:" && isLocalhost(parsed))
29
+ return url;
30
+ throw new Error(`Refusing the quest URL ${parsed.host}: it must be https, or localhost over http.`);
31
+ }
32
+ if (parsed.protocol === "https:" && isShipdHost(parsed))
33
+ return url;
34
+ throw new Error(`Refusing the quest URL ${parsed.host}: outside development the CLI only talks to https://${SHIPD_HOST} (set NODE_ENV=development for another host).`);
35
+ }
36
+ export function assertTrustedConvexUrl(url, development) {
37
+ const parsed = parse(url, "the backend URL");
38
+ if (development && parsed.protocol === "http:" && isLocalhost(parsed))
39
+ return url;
40
+ if (parsed.protocol === "https:" && isConvexHost(parsed))
41
+ return url;
42
+ throw new Error(`Refusing the backend URL ${parsed.host}: the token is only sent to https://*.convex.cloud or https://*.convex.site (localhost over http only with NODE_ENV=development).`);
43
+ }
44
+ export function overrideHost(url) {
45
+ try {
46
+ return new URL(url).host;
47
+ }
48
+ catch {
49
+ return url;
50
+ }
51
+ }
@@ -0,0 +1,10 @@
1
+ export declare const CHECKS_VIEW_KEYS: readonly ["version", "prechecks", "scopeGate", "dynamicChecks", "trialQa", "readiness"];
2
+ export type ChecksViewPayload = {
3
+ version: number;
4
+ prechecks: unknown;
5
+ scopeGate: unknown;
6
+ dynamicChecks: unknown;
7
+ trialQa: unknown;
8
+ readiness: unknown;
9
+ };
10
+ export declare function buildChecksViewPayload(input: ChecksViewPayload): ChecksViewPayload;
@@ -0,0 +1,12 @@
1
+ export const CHECKS_VIEW_KEYS = [
2
+ "version",
3
+ "prechecks",
4
+ "scopeGate",
5
+ "dynamicChecks",
6
+ "trialQa",
7
+ "readiness",
8
+ ];
9
+ export function buildChecksViewPayload(input) {
10
+ const { version, prechecks, scopeGate, dynamicChecks, trialQa, readiness } = input;
11
+ return { version, prechecks, scopeGate, dynamicChecks, trialQa, readiness };
12
+ }
package/dist/client.d.ts CHANGED
@@ -1,8 +1,4 @@
1
1
  import type { AdaptResult, Catalog, Handle, HarborBundle, LiveStatus, Options, PrecheckResult, StartStepResult, StepStatus, TaskRef } from "./contract.js";
2
- /**
3
- * Everything the plan executor needs from a quest. `QuestClient` implements it
4
- * over Convex; tests implement it with a fake.
5
- */
6
2
  export interface QuestApi {
7
3
  readonly quest: string;
8
4
  listChecks(): Promise<Catalog>;
@@ -21,9 +17,7 @@ export interface QuestApi {
21
17
  detail?: string;
22
18
  }>;
23
19
  getLiveCheck(versionId: string, checkKey: string): Promise<LiveStatus>;
24
- nudgeSynthesis(versionId: string): Promise<null>;
25
20
  }
26
- /** The bundle as sent over the wire: `dir`, `metadata`, `files` and nothing else. */
27
21
  export declare function toWireBundle(bundle: HarborBundle): HarborBundle;
28
22
  export declare class QuestClient implements QuestApi {
29
23
  readonly quest: string;
@@ -45,7 +39,5 @@ export declare class QuestClient implements QuestApi {
45
39
  detail?: string;
46
40
  }>;
47
41
  getLiveCheck(versionId: string, checkKey: string): Promise<LiveStatus>;
48
- nudgeSynthesis(versionId: string): Promise<null>;
49
42
  }
50
- /** Build an authenticated client for a quest, or throw an AuthError/UsageError. */
51
43
  export declare function connectQuest(quest: string): Promise<QuestClient>;
package/dist/client.js CHANGED
@@ -2,15 +2,12 @@ import { ConvexHttpClient } from "convex/browser";
2
2
  import { anyApi } from "convex/server";
3
3
  import { requireAuth } from "./auth.js";
4
4
  import { questConvexUrl } from "./quests.js";
5
- /** The bundle as sent over the wire: `dir`, `metadata`, `files` and nothing else. */
6
5
  export function toWireBundle(bundle) {
7
6
  return { dir: bundle.dir, metadata: bundle.metadata, files: bundle.files };
8
7
  }
9
8
  function withOptions(args, options) {
10
9
  return options && Object.keys(options).length > 0 ? { ...args, options } : args;
11
10
  }
12
- // Functions are addressed by name through `anyApi` so the CLI has no
13
- // dependency on any quest's generated API at typecheck time.
14
11
  const fns = anyApi.adhocChecks;
15
12
  export class QuestClient {
16
13
  quest;
@@ -58,11 +55,7 @@ export class QuestClient {
58
55
  getLiveCheck(versionId, checkKey) {
59
56
  return this.convex.query(fns.getLiveCheck, { versionId, checkKey });
60
57
  }
61
- nudgeSynthesis(versionId) {
62
- return this.convex.action(fns.nudgeSynthesis, { versionId });
63
- }
64
58
  }
65
- /** Build an authenticated client for a quest, or throw an AuthError/UsageError. */
66
59
  export async function connectQuest(quest) {
67
60
  const { token } = requireAuth();
68
61
  const convexUrl = await questConvexUrl(quest);
@@ -1,4 +1,13 @@
1
1
  export declare const login: import("citty").CommandDef<{
2
+ readonly quest: {
3
+ readonly type: "string";
4
+ readonly description: "Open this quest's login page (default: olympus); it mints the author or the admin edition for whoever is enrolled there";
5
+ };
6
+ readonly platform: {
7
+ readonly type: "boolean";
8
+ readonly description: "Open the platform login page (admins only) instead of a quest's";
9
+ readonly default: false;
10
+ };
2
11
  readonly token: {
3
12
  readonly type: "string";
4
13
  readonly description: "Paste the token directly instead of prompting";
@@ -9,10 +18,6 @@ export declare const login: import("citty").CommandDef<{
9
18
  readonly description: "Open the login page in a browser";
10
19
  readonly negativeDescription: "Print the login URL instead of opening a browser";
11
20
  };
12
- readonly quest: {
13
- readonly type: "string";
14
- readonly description: "Open this quest's own login page instead of the platform page (the token works for every quest either way)";
15
- };
16
21
  }>;
17
22
  export declare const logout: import("citty").CommandDef<import("citty").ArgsDef>;
18
23
  export declare const whoami: import("citty").CommandDef<{