@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/dist/quests.js CHANGED
@@ -2,56 +2,69 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
2
2
  import { createRequire } from "node:module";
3
3
  import { resolve } from "node:path";
4
4
  import { ensureShipdDir, shipdDir } from "./auth.js";
5
+ import { assertTrustedBaseUrl, assertTrustedConvexUrl, isDevelopment, overrideHost, } from "./backend.js";
5
6
  import { UsageError } from "./errors.js";
7
+ import { text } from "./format.js";
6
8
  const require = createRequire(import.meta.url);
7
9
  const { version: VERSION, name: PACKAGE_NAME } = require("../package.json");
8
10
  export { VERSION, PACKAGE_NAME };
9
- // A quest entry is just a base URL. Everything else (the Convex deployment,
10
- // the minimum CLI version) comes from the quest's `/api/cli/config`.
11
11
  const REGISTRY = {
12
12
  olympus: {
13
13
  prod: "https://shipd.ai/quests/olympus",
14
14
  dev: "http://localhost:3006/quests/olympus",
15
+ author: true,
15
16
  },
16
17
  };
17
18
  export const DEFAULT_QUEST = "olympus";
18
19
  export function knownQuests() {
19
20
  return Object.keys(REGISTRY);
20
21
  }
22
+ function registryEntry(quest) {
23
+ const entry = REGISTRY[quest];
24
+ if (!entry) {
25
+ throw new UsageError(`Unknown quest "${quest}". Known quests: ${knownQuests().join(", ")}`);
26
+ }
27
+ return entry;
28
+ }
29
+ export function questHasAuthorCommands(quest) {
30
+ return registryEntry(quest).author;
31
+ }
21
32
  function envKey(quest, suffix) {
22
33
  return `SHIPD_${quest.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_${suffix}`;
23
34
  }
24
- /** `SHIPD_<QUEST>_URL` override, or NODE_ENV=development → localhost. */
35
+ const warnedOverrides = new Set();
36
+ function warnOverride(name, url) {
37
+ if (warnedOverrides.has(name))
38
+ return;
39
+ warnedOverrides.add(name);
40
+ console.error(` Using ${name}: ${text(overrideHost(url))}`);
41
+ }
25
42
  export function questBaseUrl(quest) {
26
43
  const override = process.env[envKey(quest, "URL")];
27
- if (override)
28
- return override.replace(/\/+$/, "");
29
- const entry = REGISTRY[quest];
30
- if (!entry) {
31
- throw new UsageError(`Unknown quest "${quest}". Known quests: ${knownQuests().join(", ")}`);
44
+ if (override) {
45
+ const url = assertTrustedBaseUrl(override.replace(/\/+$/, ""), isDevelopment());
46
+ warnOverride(envKey(quest, "URL"), url);
47
+ return url;
32
48
  }
33
- return process.env.NODE_ENV === "development" ? entry.dev : entry.prod;
49
+ const entry = registryEntry(quest);
50
+ return isDevelopment() ? entry.dev : entry.prod;
34
51
  }
35
- // The platform-level token page. The shipd-cli token works for every quest,
36
- // so the browser login lands here; `questAuthUrl` stays for a quest's own
37
- // copy of the page (`shipd login --quest <quest>`).
38
52
  const PLATFORM_AUTH_URL = {
39
53
  prod: "https://shipd.ai/cli-auth",
40
54
  dev: "http://localhost:3010/cli-auth",
41
55
  };
42
- /** `SHIPD_AUTH_URL` override, or NODE_ENV=development → localhost. */
43
56
  export function platformAuthUrl() {
44
57
  const override = process.env.SHIPD_AUTH_URL;
45
58
  if (override)
46
59
  return override;
47
- return process.env.NODE_ENV === "development" ? PLATFORM_AUTH_URL.dev : PLATFORM_AUTH_URL.prod;
60
+ return isDevelopment() ? PLATFORM_AUTH_URL.dev : PLATFORM_AUTH_URL.prod;
48
61
  }
49
- /** A quest's own copy of the token page (the platform page is the default). */
50
62
  export function questAuthUrl(quest) {
51
63
  return `${questBaseUrl(quest)}/cli-auth`;
52
64
  }
53
65
  const CONFIG_TTL_MS = 5 * 60 * 1000;
54
66
  const VERSION_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
67
+ const FETCH_TIMEOUT_MS = 8 * 1000;
55
68
  function configCachePath(quest) {
56
69
  return resolve(shipdDir(), `config-${quest}.json`);
57
70
  }
@@ -64,7 +77,9 @@ function isValidQuestConfig(value) {
64
77
  typeof candidate.minCliVersion === "string" &&
65
78
  candidate.minCliVersion.length > 0 &&
66
79
  typeof candidate.fetchedAt === "string" &&
67
- candidate.fetchedAt.length > 0);
80
+ candidate.fetchedAt.length > 0 &&
81
+ typeof candidate.baseUrl === "string" &&
82
+ candidate.baseUrl.length > 0);
68
83
  }
69
84
  function readFreshCache(path, ttlMs, isValid) {
70
85
  if (!existsSync(path))
@@ -86,19 +101,17 @@ function writeCache(path, value) {
86
101
  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
87
102
  }
88
103
  catch {
89
- // A cache write failure must not break the command.
90
104
  }
91
105
  }
92
- /** Load the quest's CLI config (cached 5 minutes) or fetch it from the quest. */
93
106
  export async function questConfig(quest) {
107
+ const baseUrl = questBaseUrl(quest);
94
108
  const cached = readFreshCache(configCachePath(quest), CONFIG_TTL_MS, isValidQuestConfig);
95
- if (cached)
109
+ if (cached && cached.baseUrl === baseUrl)
96
110
  return cached;
97
- const baseUrl = questBaseUrl(quest);
98
111
  const configUrl = `${baseUrl}/api/cli/config`;
99
112
  let res;
100
113
  try {
101
- res = await fetch(configUrl);
114
+ res = await fetch(configUrl, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
102
115
  }
103
116
  catch (error) {
104
117
  const detail = error instanceof Error ? error.message : String(error);
@@ -111,24 +124,31 @@ export async function questConfig(quest) {
111
124
  const data = (await res.json());
112
125
  if (typeof data.convexUrl !== "string" || !data.convexUrl) {
113
126
  throw new UsageError(`CLI config from ${configUrl} is missing convexUrl.\n` +
114
- ` Temporary workaround: set ${envKey(quest, "CONVEX_URL")} manually.`);
127
+ ` Temporary workaround (development only): set ${envKey(quest, "CONVEX_URL")}.`);
115
128
  }
116
129
  const config = {
117
130
  convexUrl: data.convexUrl,
118
131
  minCliVersion: typeof data.minCliVersion === "string" ? data.minCliVersion : "0.0.0",
119
132
  fetchedAt: new Date().toISOString(),
133
+ baseUrl,
120
134
  };
121
135
  writeCache(configCachePath(quest), config);
122
136
  return config;
123
137
  }
124
- /** The quest's Convex deployment URL, with `SHIPD_<QUEST>_CONVEX_URL` override. */
125
138
  export async function questConvexUrl(quest) {
126
- const override = process.env[envKey(quest, "CONVEX_URL")];
127
- if (override)
128
- return override;
129
- return (await questConfig(quest)).convexUrl;
139
+ const overrideName = envKey(quest, "CONVEX_URL");
140
+ const override = process.env[overrideName];
141
+ if (override) {
142
+ if (!isDevelopment()) {
143
+ throw new UsageError(`Ignoring ${overrideName} (${text(overrideHost(override))}): outside development the backend is the one the quest's config endpoint names. Unset it, or set NODE_ENV=development for your own deployment.`);
144
+ }
145
+ const url = assertTrustedConvexUrl(override, true);
146
+ warnOverride(overrideName, url);
147
+ return url;
148
+ }
149
+ const config = await questConfig(quest);
150
+ return assertTrustedConvexUrl(config.convexUrl, isDevelopment());
130
151
  }
131
- /** Compare semver strings numerically (e.g. "0.10.0" > "0.9.0"). */
132
152
  export function semverGt(a, b) {
133
153
  const pa = a.split(".").map(Number);
134
154
  const pb = b.split(".").map(Number);
@@ -157,6 +177,7 @@ async function latestPublishedVersion() {
157
177
  try {
158
178
  const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`, {
159
179
  headers: { Accept: "application/json" },
180
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
160
181
  });
161
182
  if (!res.ok)
162
183
  return null;
@@ -170,10 +191,6 @@ async function latestPublishedVersion() {
170
191
  return null;
171
192
  }
172
193
  }
173
- /**
174
- * Warn (never block) when this CLI is below the quest's minimum or behind the
175
- * latest npm release. Set SHIPD_NO_UPDATE_CHECK=1 to skip.
176
- */
177
194
  export async function checkVersion(quest = DEFAULT_QUEST) {
178
195
  if (process.env.SHIPD_NO_UPDATE_CHECK === "1")
179
196
  return;
@@ -182,14 +199,14 @@ export async function checkVersion(quest = DEFAULT_QUEST) {
182
199
  latestPublishedVersion(),
183
200
  ]);
184
201
  if (configResult.status === "fulfilled" && semverGt(configResult.value.minCliVersion, VERSION)) {
185
- console.error(`\n CLI v${VERSION} is below the minimum required v${configResult.value.minCliVersion}` +
202
+ console.error(`\n CLI v${VERSION} is below the minimum required v${text(configResult.value.minCliVersion)}` +
186
203
  "\n Run: shipd update\n");
187
204
  return;
188
205
  }
189
206
  if (latestResult.status === "fulfilled" &&
190
207
  latestResult.value &&
191
208
  semverGt(latestResult.value, VERSION)) {
192
- console.error(`\n CLI v${VERSION} is behind the latest published v${latestResult.value}` +
209
+ console.error(`\n CLI v${VERSION} is behind the latest published v${text(latestResult.value)}` +
193
210
  "\n Run: shipd update\n");
194
211
  }
195
212
  }
package/dist/report.d.ts CHANGED
@@ -22,7 +22,6 @@ export type CheckResult = {
22
22
  reason?: string;
23
23
  durationMs: number;
24
24
  steps: Record<string, StepRecord>;
25
- /** Live modes only: the quest's job ids behind this check. */
26
25
  jobIds?: Record<string, string>;
27
26
  };
28
27
  export type ReportMode = "harbor" | "harbor-create" | "task";
@@ -37,26 +36,18 @@ export type ReportSource = {
37
36
  export type Report = {
38
37
  quest: string;
39
38
  mode: ReportMode;
40
- /** `explicit` = --check; `all` = --all. Skips are failures only for explicit selections. */
41
39
  selection: "explicit" | "all";
42
40
  source: ReportSource;
43
- /** Live modes only: the task's page in the product (also in `source.url`). */
44
41
  taskUrl?: string;
45
42
  generatedAt: string;
46
43
  checks: Record<string, CheckResult>;
47
44
  prechecks: Record<string, PrecheckResult>;
48
45
  };
49
46
  export declare function modeLabel(mode: ReportMode): string;
50
- /** The precheck stage status, as the product spells it, mapped to a verdict. */
51
47
  export declare function precheckVerdict(status: string): Verdict;
52
- /** A one-line human detail for a check row. */
53
48
  export declare function checkDetail(check: CheckResult): string;
54
49
  export declare function renderTable(report: Report, opts?: {
55
50
  color?: boolean;
56
51
  }): string;
57
- /**
58
- * 0 when every run check passed or warned; 1 when any failed or errored (or
59
- * an explicitly requested check was skipped); 3 when any check was cancelled.
60
- */
61
52
  export declare function exitCodeFor(report: Report): number;
62
53
  export declare function writeReport(report: Report, path: string): Promise<string>;
package/dist/report.js CHANGED
@@ -3,16 +3,14 @@ import { dirname, resolve } from "node:path";
3
3
  import { EXIT_CANCELLED, EXIT_CHECK_FAILED, EXIT_OK } from "./errors.js";
4
4
  import { formatDuration, formatTable, statusBadge, truncate } from "./format.js";
5
5
  export function modeLabel(mode) {
6
- return mode === "harbor" ? "stateless, nothing written" : "live: writes to production";
6
+ return mode === "harbor" ? "stateless, only cost logged" : "live: writes to production";
7
7
  }
8
- /** The precheck stage status, as the product spells it, mapped to a verdict. */
9
8
  export function precheckVerdict(status) {
10
9
  const lower = status.toLowerCase();
11
10
  if (lower === "missing_fields")
12
11
  return "skipped";
13
12
  return lower;
14
13
  }
15
- /** A one-line human detail for a check row. */
16
14
  export function checkDetail(check) {
17
15
  if (check.error)
18
16
  return check.error;
@@ -80,10 +78,6 @@ function sourceLines(source) {
80
78
  return lines;
81
79
  }
82
80
  const BAD_VERDICTS = new Set(["fail", "error"]);
83
- /**
84
- * 0 when every run check passed or warned; 1 when any failed or errored (or
85
- * an explicitly requested check was skipped); 3 when any check was cancelled.
86
- */
87
81
  export function exitCodeFor(report) {
88
82
  const checks = Object.values(report.checks);
89
83
  if (checks.some((c) => c.status === "cancelled"))
package/dist/runs.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ export declare const RUN_ARTIFACT_FILES: {
2
+ readonly trajectory: "trajectory.json";
3
+ readonly workspaceDiff: "workspace-diff.patch";
4
+ readonly solutionPatch: "solution-patch.patch";
5
+ readonly testLog: "test-log.txt";
6
+ readonly junitBaselineXml: "junit-baseline.xml";
7
+ readonly junitNewXml: "junit-new.xml";
8
+ readonly evalResult: "eval-result.json";
9
+ };
10
+ export type RunArtifactKey = keyof typeof RUN_ARTIFACT_FILES;
11
+ export declare const RUN_ARTIFACT_KEYS: RunArtifactKey[];
12
+ export declare function parseArtifactKeys(artifact: string | undefined, all: boolean | undefined): RunArtifactKey[];
13
+ export type AgentRunRow = {
14
+ id: string;
15
+ jobId?: string;
16
+ taskAgentType?: string;
17
+ taskAgentCodename?: string;
18
+ status?: string;
19
+ verdict?: string;
20
+ fault?: string;
21
+ runPhase?: string;
22
+ label?: string;
23
+ batchName?: string;
24
+ hinted?: boolean;
25
+ legacy?: boolean;
26
+ stale?: boolean;
27
+ scratched?: boolean;
28
+ createdAt?: number;
29
+ completedAt?: number;
30
+ currentStep?: string;
31
+ error?: string;
32
+ };
33
+ export declare function runLabel(run: AgentRunRow): string;
34
+ export declare function selectRuns(runs: AgentRunRow[], runId: string | undefined, all: boolean | undefined): AgentRunRow[];
35
+ export declare function artifactPath(dir: string, runId: string, key: RunArtifactKey): string;
36
+ export declare function downloadArtifact(url: string, dest: string, fetchImpl?: typeof fetch): Promise<number>;
package/dist/runs.js ADDED
@@ -0,0 +1,59 @@
1
+ import { mkdirSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { assertTrustedConvexUrl, isDevelopment } from "./backend.js";
4
+ import { RefusedError, UsageError } from "./errors.js";
5
+ export const RUN_ARTIFACT_FILES = {
6
+ trajectory: "trajectory.json",
7
+ workspaceDiff: "workspace-diff.patch",
8
+ solutionPatch: "solution-patch.patch",
9
+ testLog: "test-log.txt",
10
+ junitBaselineXml: "junit-baseline.xml",
11
+ junitNewXml: "junit-new.xml",
12
+ evalResult: "eval-result.json",
13
+ };
14
+ export const RUN_ARTIFACT_KEYS = Object.keys(RUN_ARTIFACT_FILES);
15
+ export function parseArtifactKeys(artifact, all) {
16
+ if (all && artifact)
17
+ throw new UsageError("Pass --artifact or --all-artifacts, not both.");
18
+ if (!artifact)
19
+ return [...RUN_ARTIFACT_KEYS];
20
+ const keys = artifact
21
+ .split(",")
22
+ .map((k) => k.trim())
23
+ .filter((k) => k.length > 0);
24
+ for (const key of keys) {
25
+ if (!(key in RUN_ARTIFACT_FILES)) {
26
+ throw new UsageError(`Unknown artifact "${key}". One of: ${RUN_ARTIFACT_KEYS.join(", ")} (or --all-artifacts).`);
27
+ }
28
+ }
29
+ return [...new Set(keys)];
30
+ }
31
+ export function runLabel(run) {
32
+ return run.taskAgentCodename ?? "run";
33
+ }
34
+ export function selectRuns(runs, runId, all) {
35
+ if (all && runId)
36
+ throw new UsageError("Pass --run or --all, not both.");
37
+ if (all)
38
+ return runs;
39
+ if (!runId)
40
+ throw new UsageError("Name a run with --run <runId>, or pass --all.");
41
+ const run = runs.find((r) => r.id === runId || r.jobId === runId);
42
+ if (!run)
43
+ throw new UsageError(`Run not found on this challenge's latest version: ${runId}`);
44
+ return [run];
45
+ }
46
+ export function artifactPath(dir, runId, key) {
47
+ return join(dir, runId, RUN_ARTIFACT_FILES[key]);
48
+ }
49
+ export async function downloadArtifact(url, dest, fetchImpl = fetch) {
50
+ assertTrustedConvexUrl(url, isDevelopment());
51
+ const response = await fetchImpl(url, { signal: AbortSignal.timeout(120_000) });
52
+ if (!response.ok) {
53
+ throw new RefusedError(`Download failed (${response.status}) for ${dest}`);
54
+ }
55
+ const bytes = new Uint8Array(await response.arrayBuffer());
56
+ mkdirSync(join(dest, ".."), { recursive: true });
57
+ writeFileSync(dest, bytes);
58
+ return bytes.byteLength;
59
+ }
@@ -0,0 +1,2 @@
1
+ import { type ArgsDef, type CommandDef } from "citty";
2
+ export declare function createShowUsage<R extends ArgsDef>(root: CommandDef<R>, groups: Record<string, object>): <T extends ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>) => Promise<void>;
package/dist/usage.js ADDED
@@ -0,0 +1,16 @@
1
+ import { renderUsage } from "citty";
2
+ export function createShowUsage(root, groups) {
3
+ const rootMeta = root.meta;
4
+ const rootName = rootMeta?.name ?? "shipd";
5
+ const fullNames = new Map([[root, rootName]]);
6
+ for (const [name, group] of Object.entries(groups)) {
7
+ fullNames.set(group, `${rootName} ${name}`);
8
+ }
9
+ return async (cmd, parent) => {
10
+ const name = parent ? fullNames.get(parent) : undefined;
11
+ const named = parent && name
12
+ ? { ...parent, meta: { ...parent.meta, name, version: rootMeta?.version } }
13
+ : parent;
14
+ console.log(`${await renderUsage(cmd, named)}\n`);
15
+ };
16
+ }
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@shipd-ai/cli",
3
- "version": "0.1.3",
4
- "description": "Shipd admin CLI — run quest checks on Harbor tasks or existing tasks",
3
+ "version": "0.3.0",
4
+ "description": "Shipd CLI \u2014 your quest challenges, their content, checks and agent runs (authors), ad-hoc quest checks on Harbor tasks or existing tasks (admins)",
5
5
  "type": "module",
6
6
  "homepage": "https://shipd.ai",
7
7
  "keywords": [
8
8
  "shipd",
9
+ "olympus",
9
10
  "harbor",
10
11
  "cli",
11
12
  "convex"