@shipd-ai/cli 0.1.3 → 0.2.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 (45) hide show
  1. package/README.md +118 -43
  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 +9 -0
  9. package/dist/checks-view.js +11 -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 +265 -0
  15. package/dist/commands/author-checks.js +365 -0
  16. package/dist/commands/checks.d.ts +0 -2
  17. package/dist/commands/checks.js +21 -17
  18. package/dist/commands/problems.d.ts +1 -0
  19. package/dist/commands/problems.js +189 -0
  20. package/dist/commands/quests.d.ts +0 -1
  21. package/dist/commands/quests.js +0 -1
  22. package/dist/contract.d.ts +0 -1
  23. package/dist/contract.js +0 -7
  24. package/dist/errors.d.ts +3 -1
  25. package/dist/errors.js +6 -5
  26. package/dist/format.d.ts +2 -4
  27. package/dist/format.js +29 -7
  28. package/dist/harbor.d.ts +0 -8
  29. package/dist/harbor.js +0 -11
  30. package/dist/index-gate.d.ts +1 -0
  31. package/dist/index-gate.js +5 -0
  32. package/dist/index.js +14 -10
  33. package/dist/model.d.ts +94 -0
  34. package/dist/model.js +68 -0
  35. package/dist/plan.d.ts +0 -15
  36. package/dist/plan.js +0 -21
  37. package/dist/prompt.d.ts +5 -0
  38. package/dist/prompt.js +26 -0
  39. package/dist/quests.d.ts +2 -10
  40. package/dist/quests.js +51 -34
  41. package/dist/report.d.ts +0 -9
  42. package/dist/report.js +1 -7
  43. package/dist/usage.d.ts +2 -0
  44. package/dist/usage.js +16 -0
  45. package/package.json +3 -2
package/dist/plan.d.ts CHANGED
@@ -2,7 +2,6 @@ import type { QuestApi } from "./client.js";
2
2
  import { type CheckDef, type Handle, type HarborBundle, type Options, type TaskRef, type Verdict } from "./contract.js";
3
3
  import { type CheckResult, type StepRecord } from "./report.js";
4
4
  export declare const DEFAULT_POLL_MS = 15000;
5
- /** The longest worker timeout. */
6
5
  export declare const DEFAULT_MAX_STEP_MS: number;
7
6
  export type PlanEvent = {
8
7
  type: "check:start";
@@ -26,9 +25,6 @@ export type PlanEvent = {
26
25
  checkKey: string;
27
26
  started: boolean;
28
27
  detail?: string;
29
- } | {
30
- type: "live:nudge";
31
- checkKey: string;
32
28
  } | {
33
29
  type: "check:end";
34
30
  checkKey: string;
@@ -39,13 +35,6 @@ export type RunControls = {
39
35
  maxStepMs: number;
40
36
  signal?: AbortSignal;
41
37
  onEvent?: (event: PlanEvent) => void;
42
- /**
43
- * What an abort does to in-flight Modal steps. `"cancel"` (default)
44
- * cancels them; `"leave"` keeps them running and only stops polling, so
45
- * their handles survive in the report for `checks status` / `checks
46
- * cancel` later. The interrupt handler flips this to `"leave"` when the
47
- * user declines the cancel prompt.
48
- */
49
38
  onAbort?: () => "cancel" | "leave";
50
39
  };
51
40
  export type RunTarget = {
@@ -55,11 +44,7 @@ export type RunTarget = {
55
44
  kind: "live";
56
45
  task: TaskRef;
57
46
  };
58
- /** The step nothing depends on. With several, the last declared wins. */
59
47
  export declare function sinkStepId(check: CheckDef): string;
60
- /** Run one check against a Harbor bundle without writing anything to the quest. */
61
48
  export declare function executeStatelessCheck(api: QuestApi, bundle: HarborBundle, check: CheckDef, options: Options, controls: RunControls): Promise<CheckResult>;
62
- /** Run one check live on an existing task; the quest writes its normal rows. */
63
49
  export declare function executeLiveCheck(api: QuestApi, task: TaskRef, check: CheckDef, options: Options, controls: RunControls): Promise<CheckResult>;
64
- /** Run the selected checks concurrently and return one result per check. */
65
50
  export declare function runChecks(api: QuestApi, target: RunTarget, checks: CheckDef[], options: Options, controls: RunControls): Promise<CheckResult[]>;
package/dist/plan.js CHANGED
@@ -3,7 +3,6 @@ import { errorMessage } from "./errors.js";
3
3
  import { formatDuration } from "./format.js";
4
4
  import { precheckVerdict } from "./report.js";
5
5
  export const DEFAULT_POLL_MS = 15_000;
6
- /** The longest worker timeout. */
7
6
  export const DEFAULT_MAX_STEP_MS = 3 * 60 * 60 * 1000;
8
7
  function sleep(ms, signal) {
9
8
  if (signal?.aborted)
@@ -28,7 +27,6 @@ const TERMINAL = new Set([
28
27
  function isTerminal(record) {
29
28
  return TERMINAL.has(record.status);
30
29
  }
31
- /** The step nothing depends on. With several, the last declared wins. */
32
30
  export function sinkStepId(check) {
33
31
  const depended = new Set(check.steps.flatMap((s) => s.after));
34
32
  const sinks = check.steps.filter((s) => !depended.has(s.id));
@@ -105,7 +103,6 @@ async function runStatelessPrecheck(api, bundle, check, startedAt, controls) {
105
103
  }, startedAt, controls);
106
104
  }
107
105
  }
108
- /** Run one check against a Harbor bundle without writing anything to the quest. */
109
106
  export async function executeStatelessCheck(api, bundle, check, options, controls) {
110
107
  const startedAt = Date.now();
111
108
  controls.onEvent?.({ type: "check:start", checkKey: check.key });
@@ -157,7 +154,6 @@ export async function executeStatelessCheck(api, bundle, check, options, control
157
154
  return;
158
155
  const elapsed = Date.now() - (record.startedAt ?? Date.now());
159
156
  if (elapsed >= controls.maxStepMs) {
160
- // Keep the handle so `shipd checks status` / `cancel` still work on it.
161
157
  endStep(stepId, {
162
158
  status: "error",
163
159
  error: `timed out after ${formatDuration(controls.maxStepMs)}`,
@@ -192,7 +188,6 @@ export async function executeStatelessCheck(api, bundle, check, options, control
192
188
  await api.cancelStep(record.handle);
193
189
  }
194
190
  catch {
195
- // Best effort: the handle is still in the report for a manual cancel.
196
191
  }
197
192
  }
198
193
  endStep(stepId, {
@@ -212,7 +207,6 @@ export async function executeStatelessCheck(api, bundle, check, options, control
212
207
  await cancelInFlight();
213
208
  break;
214
209
  }
215
- // Schedule: every pending step whose dependencies are all terminal.
216
210
  const toStart = [];
217
211
  let progressed = false;
218
212
  for (const step of check.steps) {
@@ -241,8 +235,6 @@ export async function executeStatelessCheck(api, bundle, check, options, control
241
235
  if (allTerminal)
242
236
  break;
243
237
  if (!progressed) {
244
- // Nothing can start and nothing is running: the plan references steps
245
- // that do not exist. Report rather than spin forever.
246
238
  for (const [stepId, record] of Object.entries(steps)) {
247
239
  if (record.status === "pending") {
248
240
  endStep(stepId, { status: "error", error: "unresolvable step dependencies" });
@@ -279,7 +271,6 @@ export async function executeStatelessCheck(api, bundle, check, options, control
279
271
  const prefix = check.steps.length > 1 && stepId ? `${stepId}: ` : "";
280
272
  return finish(check, { status: "error", error: `${prefix}${record.error ?? "step did not complete"}`, steps }, startedAt, controls);
281
273
  }
282
- /** Run one check live on an existing task; the quest writes its normal rows. */
283
274
  export async function executeLiveCheck(api, task, check, options, controls) {
284
275
  const startedAt = Date.now();
285
276
  controls.onEvent?.({ type: "check:start", checkKey: check.key });
@@ -305,7 +296,6 @@ export async function executeLiveCheck(api, task, check, options, controls) {
305
296
  const reason = started.detail ?? "the quest did not start this check";
306
297
  return finish(check, { status: "skipped", reason, steps: step({ status: "skipped", reason }) }, startedAt, controls);
307
298
  }
308
- let nudged = false;
309
299
  while (true) {
310
300
  if (signal?.aborted) {
311
301
  const reason = "interrupted; the check keeps running in the product";
@@ -324,16 +314,6 @@ export async function executeLiveCheck(api, task, check, options, controls) {
324
314
  return finish(check, { status: "error", error: message, steps: step({ status: "error", error: message }) }, startedAt, controls);
325
315
  }
326
316
  if (live.status === "running") {
327
- if (live.nudgeSynthesis && !nudged) {
328
- nudged = true;
329
- controls.onEvent?.({ type: "live:nudge", checkKey: check.key });
330
- try {
331
- await api.nudgeSynthesis(task.versionId);
332
- }
333
- catch {
334
- // The product's own scheduler will pick it up; keep polling.
335
- }
336
- }
337
317
  await sleep(controls.pollMs, signal);
338
318
  continue;
339
319
  }
@@ -359,7 +339,6 @@ export async function executeLiveCheck(api, task, check, options, controls) {
359
339
  }, startedAt, controls);
360
340
  }
361
341
  }
362
- /** Run the selected checks concurrently and return one result per check. */
363
342
  export function runChecks(api, target, checks, options, controls) {
364
343
  return Promise.all(checks.map((check) => target.kind === "harbor"
365
344
  ? executeStatelessCheck(api, target.bundle, check, options, controls)
@@ -0,0 +1,5 @@
1
+ type SecretInput = NodeJS.ReadableStream & {
2
+ isTTY?: boolean;
3
+ };
4
+ export declare function readSecret(question: string, input?: SecretInput, output?: NodeJS.WritableStream): Promise<string>;
5
+ export {};
package/dist/prompt.js ADDED
@@ -0,0 +1,26 @@
1
+ import { createInterface } from "node:readline";
2
+ import { Writable } from "node:stream";
3
+ export function readSecret(question, input = process.stdin, output = process.stdout) {
4
+ output.write(question);
5
+ const sink = new Writable({
6
+ write(_chunk, _encoding, callback) {
7
+ callback();
8
+ },
9
+ });
10
+ const rl = createInterface({ input, output: sink, terminal: input.isTTY === true });
11
+ return new Promise((resolve) => {
12
+ let answered = false;
13
+ rl.question("", (answer) => {
14
+ answered = true;
15
+ rl.close();
16
+ output.write("\n");
17
+ resolve(answer.trim());
18
+ });
19
+ rl.on("close", () => {
20
+ if (!answered) {
21
+ output.write("\n");
22
+ resolve("");
23
+ }
24
+ });
25
+ });
26
+ }
package/dist/quests.d.ts CHANGED
@@ -2,25 +2,17 @@ declare const VERSION: string, PACKAGE_NAME: string;
2
2
  export { VERSION, PACKAGE_NAME };
3
3
  export declare const DEFAULT_QUEST = "olympus";
4
4
  export declare function knownQuests(): string[];
5
- /** `SHIPD_<QUEST>_URL` override, or NODE_ENV=development → localhost. */
5
+ export declare function questHasAuthorCommands(quest: string): boolean;
6
6
  export declare function questBaseUrl(quest: string): string;
7
- /** `SHIPD_AUTH_URL` override, or NODE_ENV=development → localhost. */
8
7
  export declare function platformAuthUrl(): string;
9
- /** A quest's own copy of the token page (the platform page is the default). */
10
8
  export declare function questAuthUrl(quest: string): string;
11
9
  export interface QuestConfig {
12
10
  convexUrl: string;
13
11
  minCliVersion: string;
14
12
  fetchedAt: string;
13
+ baseUrl: string;
15
14
  }
16
- /** Load the quest's CLI config (cached 5 minutes) or fetch it from the quest. */
17
15
  export declare function questConfig(quest: string): Promise<QuestConfig>;
18
- /** The quest's Convex deployment URL, with `SHIPD_<QUEST>_CONVEX_URL` override. */
19
16
  export declare function questConvexUrl(quest: string): Promise<string>;
20
- /** Compare semver strings numerically (e.g. "0.10.0" > "0.9.0"). */
21
17
  export declare function semverGt(a: string, b: string): boolean;
22
- /**
23
- * Warn (never block) when this CLI is below the quest's minimum or behind the
24
- * latest npm release. Set SHIPD_NO_UPDATE_CHECK=1 to skip.
25
- */
26
18
  export declare function checkVersion(quest?: string): Promise<void>;
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"))
@@ -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.2.0",
4
+ "description": "Shipd CLI \u2014 your quest challenges and their checks (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"