@thermai/flightdeck-cli 0.1.0-pilot.2 → 0.1.0-pilot.4

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 (3) hide show
  1. package/README.md +141 -6
  2. package/dist/index.js +175 -59
  3. package/package.json +3 -2
package/README.md CHANGED
@@ -9,23 +9,48 @@ service; downloading the CLI does not create an account or grant compute credit.
9
9
 
10
10
  The package is `@thermai/flightdeck-cli`. The first pilot, `0.1.0-pilot.1`, was
11
11
  published manually on 5 September 2026 and its anonymous install was verified.
12
- This revision prepares `0.1.0-pilot.2` to qualify GitHub Actions trusted
13
- publishing; it is not published merely by merging the version change. The
14
- installation command below targets that candidate once its release completes.
12
+ `0.1.0-pilot.2` subsequently passed GitHub Actions trusted publishing and an
13
+ anonymous install check on the same date. Releases publish through the
14
+ versioned GitHub Release workflow, not merely by merging a version change. The
15
+ installation command below follows the published `next` channel without
16
+ tracking an unpublished candidate version.
15
17
  Proprietary terms in `LICENSE` permit redistribution of unchanged official
16
18
  releases. Internal service qualification is still in progress; package
17
19
  availability does not open partner onboarding.
18
20
 
21
+ **`0.1.0-pilot.3`** was published through GitHub Actions on 8 September 2026,
22
+ including complete log pagination and concise authentication errors. Its
23
+ anonymous Node 22 install and packaged dry run passed; `next` selects this
24
+ version. Use the operator-approved exact version for a recorded rehearsal.
25
+
26
+ **Candidate `0.1.0-pilot.4`** adds customer credits and requires a backend
27
+ advertising `X-Flightdeck-Accounting: credits-v1`. It is not published merely
28
+ by merging this change. After the coordinated release, upgrade with the install
29
+ command below before accessing account/job data. An incompatible backend is
30
+ rejected before job submission; login and credential revocation do not require
31
+ the accounting contract. See the
32
+ [operator rollout checklist](../docs/runbooks/customer-credits-rollout.md).
33
+
34
+ Members and organization administrators receive whole-credit balances,
35
+ estimates and actual customer charges, without provider-cost information.
36
+ Platform administrators retain their authorized monetary API fields. Credits
37
+ are not GPU-hours; consumption depends on the selected hardware/provider and
38
+ the accepted job pricing. Existing limits and customer charge caps still apply.
39
+
19
40
  ## Installation and login
20
41
 
21
42
  Requires Node.js 22 and npm. Use a user-owned Node installation or npm prefix;
22
43
  the CLI does not require administrator/root privileges.
23
44
 
45
+ <!-- flightdeck-cli-install:start -->
46
+
24
47
  ```sh
25
- npm install -g @thermai/flightdeck-cli@0.1.0-pilot.2
48
+ npm install -g @thermai/flightdeck-cli@next
26
49
  flightdeck login
27
50
  ```
28
51
 
52
+ <!-- flightdeck-cli-install:end -->
53
+
29
54
  Login prints a URL and verification code. Open that URL, sign into
30
55
  `https://portal.thermai.uk`, and approve the named CLI credential and requested
31
56
  scopes. The CLI waits for approval; no API key needs to be copied manually.
@@ -44,6 +69,55 @@ permissions. Never share that file or include it in a workload bundle. Use
44
69
  `flightdeck logout` to revoke the credential and remove the local login. Portal
45
70
  credential management can revoke an individual workstation as well.
46
71
 
72
+ `--name` labels a credential, not a local account profile. There is one saved
73
+ login per OS user. If already logged in, use `whoami` to inspect it; `login`
74
+ refuses to replace it. Use a separate OS user to preserve an operator's working
75
+ credential, or explicitly choose logout/re-login on the same workstation.
76
+ Logging out revokes that saved CLI credential; it does not delete the account or
77
+ its roles. A later login creates a new credential.
78
+
79
+ ## Pilot quick-start
80
+
81
+ Before live use, your ThermAI operator must provision your organization/account,
82
+ provide a single-use portal invitation, and approve your policy and credit.
83
+ Activate through the portal, then follow the installation/login commands above.
84
+ Confirm the expected account with `whoami` and the available credit with
85
+ `balance`. The internal proving run comes before partner invitations.
86
+
87
+ For a **local-only** readiness check, save the following as `readiness.sbatch`
88
+ in a new empty directory. Run the dry run from that directory; no account,
89
+ upload, API request, or paid resource is needed:
90
+
91
+ <!-- flightdeck-cli-readiness-script:start -->
92
+
93
+ ```bash
94
+ #!/bin/bash
95
+ #SBATCH --array=1-2
96
+ #SBATCH --gres=gpu:A10:1
97
+ #SBATCH --time=00:01:00
98
+ #SBATCH --output=%A_%a.out
99
+ echo smoke
100
+ ```
101
+
102
+ <!-- flightdeck-cli-readiness-script:end -->
103
+
104
+ ```sh
105
+ flightdeck --version
106
+ flightdeck sbatch readiness.sbatch --dry-run
107
+ ```
108
+
109
+ Expect A10 x1, 60 seconds and **two flights would be submitted**, with no
110
+ warnings. Keep `--dry-run`: this is a translation exercise, not the approved
111
+ pilot workload or permission to launch it. A dry run does not check provider
112
+ capacity, account policy/credit, bundle contents, image access or GPU execution.
113
+
114
+ For the real workload, obtain the reviewed private bundle, exact runner-image
115
+ digest, provider selection and runtime from the operator. Review its dry run,
116
+ then use the supplied submission command only after execution approval. Do not
117
+ copy internal test data into public packages or partner bundles. Use explicit
118
+ `--files` selections from a clean directory; the submission default includes
119
+ the current directory. Never include credentials or private workstation files.
120
+
47
121
  ## Workload commands
48
122
 
49
123
  After internal qualification and explicit policy/credit approval:
@@ -62,6 +136,65 @@ Submission, including `flightdeck slurm-test`, can provision paid resources.
62
136
  supports a subset of single-node Slurm directives, not an arbitrary HPC cluster.
63
137
  Workload images must satisfy the Flightdeck runner contract.
64
138
 
139
+ An array prints a separate Flightdeck ID for each accepted task. Record them
140
+ all: inspect, download and cancel each flight individually. Partial submission
141
+ can leave accepted flights running even if the command exits unsuccessfully;
142
+ do not blindly resubmit the whole array. Choose a fresh download directory for
143
+ each flight: downloads use filename basenames and refuse to overwrite existing
144
+ files. Check terminal status and exit code as well as the expected artifacts;
145
+ successful submission or download alone does not mean the workload succeeded.
146
+
147
+ For an incident, stop submitting, cancel the known active flights, and contact
148
+ your named ThermAI operator. Logging out does **not** stop jobs. The operator
149
+ must confirm provider teardown and reconcile any outstanding charges before a
150
+ retry. Support contact, supported hours and credit increases come from your
151
+ agreed pilot handoff; this client does not promise unattended support.
152
+
153
+ ### Slurm differences
154
+
155
+ - Single-node jobs only; this is not a full Slurm scheduler or an HPC login node.
156
+ - Array `%N` concurrency throttles are not enforced: tasks are submitted
157
+ immediately. Admission ceilings may reject excess tasks rather than queue
158
+ them for later admission. Review every warning before real submission.
159
+ - Use explicit `%A_%a` output names for arrays, and write results under
160
+ `$OUTPUTS_DIR`. There is no shared university filesystem or implicit `module`,
161
+ Singularity, nested Docker, or cluster software environment.
162
+ - Hardware, runtime, image and credit must fit the operator-approved policy.
163
+ A compatible runner image is required, not just any CUDA image.
164
+
165
+ ### Reading logs completely
166
+
167
+ From `0.1.0-pilot.3` (containing the #99 pagination fix), `flightdeck logs`
168
+ drains all pages in the current stored-log snapshot, then returns. For a running
169
+ job it may append one current live tail after the stored pages. `--follow`
170
+ drains those pages immediately, then polls every two seconds until the job is
171
+ terminal and its stored backlog is exhausted. Every new invocation starts at
172
+ the beginning; stdout/stderr retain their respective output streams.
173
+
174
+ **Rollout order:** deploy and verify the pagination-capable backend before
175
+ releasing/upgrading this CLI. A backend without the `has_more` response field
176
+ produces an explicit compatibility error and exit status 1, not a silently
177
+ partial read. Older `0.1.0-pilot.2` installations do not contain this fix;
178
+ merging source alone neither replaces that immutable package nor publishes a
179
+ new version. Older non-following clients still need upgrading for full paging.
180
+
181
+ ### Error handling and support
182
+
183
+ The CLI exits with status 1 on command failure. Expected authentication,
184
+ network and HTTP failures have concise diagnostics instead of a Node stack.
185
+ An already-configured login leaves the saved credential unchanged; a failed
186
+ logout/revocation retains it so you can retry. `logout --local` deliberately
187
+ removes only the local copy and does not revoke remote access; use portal
188
+ credential management if remote revocation is needed.
189
+
190
+ For unexpected faults, `flightdeck --debug <command>` adds allowlisted error
191
+ types/codes and bundled CLI line locations, not raw stacks or error bodies.
192
+ It is not a dry-run flag: only repeat an operation that is safe to repeat.
193
+ Provide support with the CLI/Node versions, exit status, redacted command and
194
+ flight ID if available. Review output before sharing: account details and
195
+ workload logs/results can contain private information. Never send passwords,
196
+ tokens, activation links or `~/.flightdeck/config.json`.
197
+
65
198
  ## Versions
66
199
 
67
200
  ```sh
@@ -69,8 +202,10 @@ flightdeck --version
69
202
  npm install -g @thermai/flightdeck-cli@<approved-version>
70
203
  ```
71
204
 
72
- Stable releases use npm's `latest` tag. Explicit pilot/prerelease versions use
73
- `next`; they do not automatically replace stable installations. Updating is an
205
+ Stable releases will use npm's `latest` tag. Explicit pilot/prerelease versions use
206
+ `next`; they do not automatically replace stable installations. Currently
207
+ `latest` still points at the initial pilot.1 bootstrap, not a qualified stable
208
+ release; use `next` or the approved exact pilot version. Updating is an
74
209
  explicit install, not an automatic mutation performed when the CLI runs.
75
210
  Once a stable release exists, `npm install -g @thermai/flightdeck-cli` selects it.
76
211
 
package/dist/index.js CHANGED
@@ -23,16 +23,71 @@ import {
23
23
  } from "node:fs";
24
24
  import { homedir } from "node:os";
25
25
  import { dirname, join } from "node:path";
26
+
27
+ // src/errors.ts
28
+ var CliError = class extends Error {
29
+ constructor(message, options) {
30
+ super(message, options);
31
+ this.name = "CliError";
32
+ }
33
+ };
34
+ function httpError(action, status2) {
35
+ const guidance = status2 === 401 ? " Check the account with flightdeck whoami; sign in again if the credential expired or was revoked." : status2 === 403 ? " Check the account permissions and requested credential scopes." : status2 === 429 ? " Wait briefly before retrying." : "";
36
+ return new CliError(`${action} (HTTP ${status2}).${guidance}`);
37
+ }
38
+ var ERROR_TYPES = /* @__PURE__ */ new Set(["Error", "TypeError", "RangeError", "SyntaxError", "CliError", "AbortError"]);
39
+ var ERROR_CODES = /* @__PURE__ */ new Set([
40
+ "EACCES",
41
+ "EPERM",
42
+ "ENOENT",
43
+ "ENOSPC",
44
+ "EEXIST",
45
+ "ECONNREFUSED",
46
+ "ECONNRESET",
47
+ "ENOTFOUND",
48
+ "EAI_AGAIN",
49
+ "ETIMEDOUT",
50
+ "ABORT_ERR",
51
+ "UND_ERR_CONNECT_TIMEOUT",
52
+ "ERR_TLS_CERT_ALTNAME_INVALID",
53
+ "CERT_HAS_EXPIRED",
54
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
55
+ ]);
56
+ function commandFailure(error, debug = false) {
57
+ const message = error instanceof CliError ? error.message.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 1e3) : "Unexpected command failure. Retry with --debug for safe diagnostics and contact your ThermAI operator if it persists.";
58
+ if (!debug) return `Flightdeck: ${message}`;
59
+ const details = [];
60
+ let current = error;
61
+ for (let depth = 0; depth < 3 && current instanceof Error; depth += 1) {
62
+ const code = current.code;
63
+ details.push(`${depth ? "cause" : "error"}=${ERROR_TYPES.has(current.name) ? current.name : "Error"}`);
64
+ if (code && ERROR_CODES.has(code)) details.push(`code=${code}`);
65
+ const frame = current.stack?.match(/\/dist\/index\.js:(\d+):(\d+)/);
66
+ if (frame) details.push(`cli=index.js:${frame[1]}:${frame[2]}`);
67
+ current = current.cause;
68
+ }
69
+ return `Flightdeck: ${message}
70
+ Diagnostic: ${details.join("; ") || "unknown error type"}`;
71
+ }
72
+
73
+ // src/client.ts
26
74
  var DEFAULT_API_URL = "https://api.flightdeck.thermai.uk";
27
75
  var CONFIG_PATH = join(homedir(), ".flightdeck", "config.json");
76
+ var ACCOUNTING_HEADER = "X-Flightdeck-Accounting";
77
+ var ACCOUNTING_CONTRACT = "credits-v1";
28
78
  function normalizeApiUrl(value) {
29
- const url = new URL(value);
79
+ let url;
80
+ try {
81
+ url = new URL(value);
82
+ } catch {
83
+ throw new CliError("Invalid FlightDeck API URL. Use an HTTPS URL.");
84
+ }
30
85
  const localHost = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
31
86
  if (url.protocol !== "https:" && !(url.protocol === "http:" && localHost)) {
32
- throw new Error("FlightDeck API URLs must use HTTPS (HTTP is allowed only for localhost)");
87
+ throw new CliError("FlightDeck API URLs must use HTTPS (HTTP is allowed only for localhost)");
33
88
  }
34
89
  if (url.username || url.password || url.search || url.hash) {
35
- throw new Error("FlightDeck API URL must not contain credentials, a query, or a fragment");
90
+ throw new CliError("FlightDeck API URL must not contain credentials, a query, or a fragment");
36
91
  }
37
92
  url.pathname = url.pathname.replace(/\/$/, "");
38
93
  return url.toString().replace(/\/$/, "");
@@ -61,11 +116,7 @@ function readConfig(path = CONFIG_PATH) {
61
116
  function loadConfig() {
62
117
  const config = readConfig();
63
118
  if (!config) {
64
- console.error(
65
- `No valid login found at ${CONFIG_PATH}.
66
- Run: flightdeck login`
67
- );
68
- process.exit(1);
119
+ throw new CliError("No valid local login found. Run flightdeck login.");
69
120
  }
70
121
  const stat = statSync(CONFIG_PATH);
71
122
  if ((stat.mode & 63) !== 0) {
@@ -109,7 +160,7 @@ function endpoint(apiUrl, path) {
109
160
  }
110
161
  async function publicApiRequest(apiUrl, method, path, body) {
111
162
  const headers = {};
112
- return fetch(endpoint(apiUrl, path), {
163
+ return request(endpoint(apiUrl, path), {
113
164
  method,
114
165
  headers,
115
166
  body: requestBody(body, headers)
@@ -118,13 +169,37 @@ async function publicApiRequest(apiUrl, method, path, body) {
118
169
  async function apiRequest(method, path, body) {
119
170
  const config = loadConfig();
120
171
  const headers = {
121
- Authorization: `Bearer ${config.api_key}`
172
+ Authorization: `Bearer ${config.api_key}`,
173
+ [ACCOUNTING_HEADER]: ACCOUNTING_CONTRACT
122
174
  };
123
- return fetch(endpoint(config.api_url, path), {
175
+ if (method === "POST" && (path === "/jobs/submit" || path === "/flights")) {
176
+ const health = await request(endpoint(config.api_url, "/health"), { method: "GET" });
177
+ assertAccountingContract(health);
178
+ if (!health.ok) throw new CliError("The Flightdeck API is not ready. No job was submitted.");
179
+ }
180
+ const response = await request(endpoint(config.api_url, path), {
124
181
  method,
125
182
  headers,
126
183
  body: requestBody(body, headers)
127
184
  });
185
+ if (path !== "/auth/credential/revoke" && (response.ok || response.status === 402)) assertAccountingContract(response);
186
+ if (response.status === 409) {
187
+ const body2 = await response.clone().json().catch(() => ({}));
188
+ if (body2.error === "accounting_client_upgrade_required") throw new CliError("Update the Flightdeck CLI to use credits accounting.");
189
+ }
190
+ return response;
191
+ }
192
+ function assertAccountingContract(response) {
193
+ if (response.headers.get(ACCOUNTING_HEADER) !== ACCOUNTING_CONTRACT) {
194
+ throw new CliError("The API does not support this CLI's credits contract yet. Contact your ThermAI operator. No accounting amounts were displayed.");
195
+ }
196
+ }
197
+ async function request(url, options) {
198
+ try {
199
+ return await fetch(url, options);
200
+ } catch (cause) {
201
+ throw new CliError("Could not reach the Flightdeck API. Check your network connection and API URL before retrying.", { cause });
202
+ }
128
203
  }
129
204
 
130
205
  // ../backend/contracts/environment.js
@@ -216,7 +291,7 @@ function parseEnvironmentArguments(envArgs) {
216
291
  const result = {};
217
292
  for (const arg of envArgs ?? []) {
218
293
  const equals = arg.indexOf("=");
219
- if (equals < 1) throw new Error(`invalid env var format: ${arg} (expected KEY=VALUE)`);
294
+ if (equals < 1) throw new CliError("invalid env var format (expected KEY=VALUE)");
220
295
  result[arg.slice(0, equals)] = arg.slice(equals + 1);
221
296
  }
222
297
  assertEnvironmentContract(result, "customer");
@@ -300,7 +375,7 @@ async function submit(entrypoint, options) {
300
375
  Flight submitted successfully!`);
301
376
  console.log(` Flight ID: ${body.flight_id}`);
302
377
  console.log(` Status: ${body.status}`);
303
- console.log(` Est. cost: ${body.estimated_cost_pence}p`);
378
+ console.log(` Est. credits: ${body.estimated_credits}`);
304
379
  console.log(` Queue position: ${body.position_in_queue}`);
305
380
  console.log(`
306
381
  Track with: flightdeck status ${body.flight_id}`);
@@ -896,11 +971,8 @@ ${submitted.length} submitted, ${failures} failed.`);
896
971
  // src/commands/status.ts
897
972
  async function status(flightId) {
898
973
  const response = await apiRequest("GET", `/flights/${flightId}`);
974
+ if (!response.ok) throw httpError("Unable to read flight status", response.status);
899
975
  const body = await response.json();
900
- if (!response.ok) {
901
- console.error(`Failed (${response.status}):`, JSON.stringify(body, null, 2));
902
- process.exit(1);
903
- }
904
976
  console.log(`Flight: ${body.flight_id}`);
905
977
  console.log(` Name: ${body.name}`);
906
978
  console.log(` Status: ${body.status}`);
@@ -911,40 +983,71 @@ async function status(flightId) {
911
983
  if (body.completed_at) console.log(` Finished: ${body.completed_at}`);
912
984
  if (body.exit_code != null) console.log(` Exit: ${body.exit_code}`);
913
985
  if (body.error_message) console.log(` Error: ${body.error_message}`);
914
- if (body.cost_pence) console.log(` Cost: ${body.cost_pence}p`);
986
+ if (body.charge_credits != null) console.log(` Charged: ${body.charge_credits} credits`);
987
+ if (body.cost_pence != null) console.log(` Provider cost: ${body.cost_pence}p`);
915
988
  }
916
989
 
917
- // src/commands/logs.ts
918
- async function logs(flightId, options) {
990
+ // src/log-reader.ts
991
+ async function drainLogs(follow, deps) {
919
992
  let cursor;
920
- do {
921
- const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
922
- const response = await apiRequest("GET", `/flights/${flightId}/logs${query}`);
923
- const body = await response.json();
924
- if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
925
- for (const entry of body.logs) {
926
- const target = entry.stream === "stderr" ? process.stderr : process.stdout;
927
- target.write(entry.content);
993
+ const seen = /* @__PURE__ */ new Set();
994
+ while (true) {
995
+ const body = await deps.readPage(cursor);
996
+ if (typeof body.has_more !== "boolean") {
997
+ throw new CliError("This backend does not support complete log pagination. Deploy the updated backend before using this CLI log command.");
998
+ }
999
+ if (!Array.isArray(body.logs) || !body.logs.every((entry) => entry && typeof entry.stream === "string" && typeof entry.content === "string") || typeof body.complete !== "boolean" || typeof body.next_cursor !== "string" || !body.next_cursor || body.has_more && body.complete) {
1000
+ throw new CliError("Invalid log pagination response from backend.");
928
1001
  }
1002
+ if (body.has_more && (body.next_cursor === cursor || seen.has(body.next_cursor))) {
1003
+ throw new CliError("Log pagination cursor did not advance; stopping to avoid repeated output.");
1004
+ }
1005
+ for (const entry of body.logs) deps.write(entry.stream, entry.content);
929
1006
  cursor = body.next_cursor;
930
- if (!options.follow || body.complete) break;
931
- await new Promise((resolve4) => setTimeout(resolve4, 2e3));
932
- } while (true);
1007
+ if (body.has_more) {
1008
+ seen.add(cursor);
1009
+ continue;
1010
+ }
1011
+ if (!follow || body.complete) return;
1012
+ seen.clear();
1013
+ await deps.wait();
1014
+ }
1015
+ }
1016
+
1017
+ // src/commands/logs.ts
1018
+ async function logs(flightId, options) {
1019
+ try {
1020
+ await drainLogs(options.follow ?? false, {
1021
+ async readPage(cursor) {
1022
+ const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
1023
+ const response = await apiRequest("GET", `/flights/${flightId}/logs${query}`);
1024
+ if (!response.ok) throw httpError("Log request failed", response.status);
1025
+ const body = await response.json();
1026
+ return body;
1027
+ },
1028
+ write(stream, content) {
1029
+ (stream === "stderr" ? process.stderr : process.stdout).write(content);
1030
+ },
1031
+ wait: () => new Promise((resolve4) => setTimeout(resolve4, 2e3))
1032
+ });
1033
+ } catch (error) {
1034
+ if (error instanceof CliError) throw new CliError(`Unable to read logs: ${error.message}`, { cause: error });
1035
+ throw error;
1036
+ }
933
1037
  }
934
1038
 
935
1039
  // src/commands/cancel.ts
936
1040
  async function cancel(flightId) {
937
1041
  const response = await apiRequest("DELETE", `/flights/${flightId}`);
938
- const body = await response.json();
939
- if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
1042
+ if (!response.ok) throw httpError("Unable to cancel flight", response.status);
940
1043
  console.log(`Cancelled ${flightId}`);
941
1044
  }
942
1045
 
943
1046
  // src/commands/outputs.ts
944
1047
  async function listOutputs(flightId) {
945
1048
  const response = await apiRequest("GET", `/flights/${flightId}/outputs`);
1049
+ if (!response.ok) throw httpError("Unable to list outputs", response.status);
946
1050
  const body = await response.json();
947
- if (!response.ok) throw new Error(`Failed (${response.status}): ${JSON.stringify(body)}`);
948
1051
  const outputs = body.outputs ?? [];
949
1052
  if (!outputs.length) console.log("No outputs available.");
950
1053
  for (const output of outputs) console.log(`${output.artifact_id} ${output.size_bytes} bytes ${output.filename}`);
@@ -956,13 +1059,13 @@ import { mkdir, writeFile } from "node:fs/promises";
956
1059
  import { basename, join as join3, resolve as resolve3 } from "node:path";
957
1060
  async function download(flightId, options) {
958
1061
  const manifestResponse = await apiRequest("GET", `/flights/${flightId}/outputs`);
1062
+ if (!manifestResponse.ok) throw httpError("Unable to list outputs for download", manifestResponse.status);
959
1063
  const manifest = await manifestResponse.json();
960
- if (!manifestResponse.ok) throw new Error(`Failed (${manifestResponse.status}): ${JSON.stringify(manifest)}`);
961
1064
  const root = resolve3(options.outputDir);
962
1065
  await mkdir(root, { recursive: true });
963
1066
  for (const output of manifest.outputs ?? []) {
964
1067
  const response = await apiRequest("GET", `/flights/${flightId}/outputs/${output.artifact_id}`);
965
- if (!response.ok) throw new Error(`Download failed for ${output.filename} (${response.status})`);
1068
+ if (!response.ok) throw httpError("Unable to download output", response.status);
966
1069
  const target = join3(root, basename(output.filename));
967
1070
  await writeFile(target, Buffer.from(await response.arrayBuffer()), { flag: "wx" });
968
1071
  console.log(`Downloaded ${target}`);
@@ -1000,14 +1103,14 @@ printf 'FLIGHTDECK_SLURM_CONFORMANCE task=%s
1000
1103
  `;
1001
1104
  function positiveSeconds(value, option) {
1002
1105
  if (!/^\d+$/.test(value) || Number(value) < 1) {
1003
- throw new Error(`${option} must be a positive number of seconds`);
1106
+ throw new CliError(`${option} must be a positive number of seconds`);
1004
1107
  }
1005
1108
  return Number(value);
1006
1109
  }
1007
1110
  async function readFlight(flightId) {
1008
1111
  const response = await apiRequest("GET", `/flights/${flightId}`);
1112
+ if (!response.ok) throw httpError("Unable to read conformance flight", response.status);
1009
1113
  const body = await response.json();
1010
- if (!response.ok) throw new Error(`status ${flightId} failed (${response.status}): ${JSON.stringify(body)}`);
1011
1114
  return body;
1012
1115
  }
1013
1116
  async function verifyResults(flightId, taskId) {
@@ -1015,16 +1118,16 @@ async function verifyResults(flightId, taskId) {
1015
1118
  apiRequest("GET", `/flights/${flightId}/logs`),
1016
1119
  apiRequest("GET", `/flights/${flightId}/outputs`)
1017
1120
  ]);
1121
+ if (!logsResponse.ok) throw httpError("Unable to read conformance logs", logsResponse.status);
1122
+ if (!outputsResponse.ok) throw httpError("Unable to read conformance outputs", outputsResponse.status);
1018
1123
  const logs2 = await logsResponse.json();
1019
1124
  const outputs = await outputsResponse.json();
1020
- if (!logsResponse.ok) throw new Error(`logs ${flightId} failed (${logsResponse.status}): ${JSON.stringify(logs2)}`);
1021
- if (!outputsResponse.ok) throw new Error(`outputs ${flightId} failed (${outputsResponse.status}): ${JSON.stringify(outputs)}`);
1022
1125
  const combinedLogs = (logs2.logs ?? []).map((entry) => entry.content).join("\n");
1023
1126
  if (!combinedLogs.includes(`FLIGHTDECK_SLURM_CONFORMANCE task=${taskId}`)) {
1024
- throw new Error(`${flightId}: provider logs do not contain the task ${taskId} conformance marker`);
1127
+ throw new CliError(`${flightId}: provider logs do not contain the task ${taskId} conformance marker`);
1025
1128
  }
1026
1129
  if (!(outputs.outputs ?? []).some((output) => output.size_bytes > 0)) {
1027
- throw new Error(`${flightId}: provider returned no non-empty output artifact`);
1130
+ throw new CliError(`${flightId}: provider returned no non-empty output artifact`);
1028
1131
  }
1029
1132
  }
1030
1133
  async function slurmTest(options) {
@@ -1042,7 +1145,7 @@ async function slurmTest(options) {
1042
1145
  } finally {
1043
1146
  rmSync2(tempDir, { recursive: true, force: true });
1044
1147
  }
1045
- if (submitted.length !== 2) throw new Error(`expected 2 conformance flights, submitted ${submitted.length}`);
1148
+ if (submitted.length !== 2) throw new CliError(`expected 2 conformance flights, submitted ${submitted.length}`);
1046
1149
  const deadline = Date.now() + timeoutMs;
1047
1150
  const pending = new Map(submitted.map((task) => [task.flightId, task]));
1048
1151
  const finished = /* @__PURE__ */ new Map();
@@ -1058,12 +1161,12 @@ async function slurmTest(options) {
1058
1161
  if (pending.size > 0) await new Promise((resolve4) => setTimeout(resolve4, pollIntervalMs));
1059
1162
  }
1060
1163
  if (pending.size > 0) {
1061
- throw new Error(`timed out waiting for: ${[...pending.keys()].join(", ")}`);
1164
+ throw new CliError(`timed out waiting for: ${[...pending.keys()].join(", ")}`);
1062
1165
  }
1063
1166
  for (const task of submitted) {
1064
1167
  const flight = finished.get(task.flightId);
1065
1168
  if (flight.status !== "completed" || flight.exit_code !== 0) {
1066
- throw new Error(`${task.flightId} failed conformance: ${flight.error_message ?? `exit ${flight.exit_code}`}`);
1169
+ throw new CliError(`${task.flightId} failed conformance. Inspect flightdeck status and logs for this flight.`);
1067
1170
  }
1068
1171
  await verifyResults(task.flightId, task.taskId);
1069
1172
  }
@@ -1076,24 +1179,32 @@ var SCOPES = ["jobs:read", "jobs:submit", "jobs:cancel", "account:read"];
1076
1179
  function sleep(milliseconds) {
1077
1180
  return new Promise((resolve4) => setTimeout(resolve4, milliseconds));
1078
1181
  }
1079
- async function errorMessage(response) {
1182
+ async function loginFailure(response) {
1080
1183
  try {
1081
1184
  const body = await response.json();
1082
- return body.error ?? response.statusText;
1185
+ if (body.error === "device_authorization_denied") {
1186
+ return new CliError("Login was not approved. Run flightdeck login to try again.");
1187
+ }
1188
+ if (body.error === "expired_device_code") {
1189
+ return new CliError("Login expired before it was approved. Run flightdeck login to try again.");
1190
+ }
1191
+ if (body.error === "credential_name_in_use") {
1192
+ return new CliError("That credential name is already in use. Choose another --name or revoke the old credential in the portal.");
1193
+ }
1083
1194
  } catch {
1084
- return response.statusText;
1085
1195
  }
1196
+ return httpError("Login failed", response.status);
1086
1197
  }
1087
1198
  async function login(options) {
1088
1199
  if (readConfig()) {
1089
- throw new Error("Already logged in. Run `flightdeck logout` before replacing this credential.");
1200
+ throw new CliError("Already logged in. Run flightdeck whoami to check the account, or flightdeck logout before signing in again.");
1090
1201
  }
1091
1202
  const apiUrl = normalizeApiUrl(options.apiUrl ?? DEFAULT_API_URL);
1092
1203
  const started = await publicApiRequest(apiUrl, "POST", "/auth/device/code", {
1093
1204
  credential_name: options.name ?? "flightdeck-cli",
1094
1205
  scopes: SCOPES
1095
1206
  });
1096
- if (!started.ok) throw new Error(`Unable to start login: ${await errorMessage(started)}`);
1207
+ if (!started.ok) throw httpError("Unable to start login", started.status);
1097
1208
  const authorization = await started.json();
1098
1209
  console.log(`Open this URL to approve the CLI:
1099
1210
  ${authorization.verification_uri_complete}`);
@@ -1112,13 +1223,13 @@ Verification code: ${authorization.user_code}`);
1112
1223
  if (Number.isFinite(retryAfter) && retryAfter > 0) intervalSeconds = retryAfter;
1113
1224
  continue;
1114
1225
  }
1115
- if (!response.ok) throw new Error(`Login failed: ${await errorMessage(response)}`);
1226
+ if (!response.ok) throw await loginFailure(response);
1116
1227
  const token = await response.json();
1117
1228
  saveConfig({ api_url: apiUrl, api_key: token.access_token, credential_id: token.credential_id });
1118
1229
  console.log("Logged in. The credential was stored in ~/.flightdeck/config.json.");
1119
1230
  return;
1120
1231
  }
1121
- throw new Error("Login expired before it was approved. Run `flightdeck login` to try again.");
1232
+ throw new CliError("Login expired before it was approved. Run flightdeck login to try again.");
1122
1233
  }
1123
1234
 
1124
1235
  // src/commands/logout.ts
@@ -1131,11 +1242,11 @@ async function logout(options) {
1131
1242
  let response;
1132
1243
  try {
1133
1244
  response = await apiRequest("POST", "/auth/credential/revoke");
1134
- } catch (error) {
1135
- throw new Error(`Credential revocation failed; local login retained: ${String(error)}`);
1245
+ } catch (cause) {
1246
+ throw new CliError("Credential revocation failed; local login retained. Check your connection and retry flightdeck logout.", { cause });
1136
1247
  }
1137
1248
  if (!response.ok && response.status !== 401) {
1138
- throw new Error(`Credential revocation failed (${response.status}); local login retained.`);
1249
+ throw new CliError(`Credential revocation failed (HTTP ${response.status}); local login retained. Retry flightdeck logout.`);
1139
1250
  }
1140
1251
  }
1141
1252
  deleteConfig();
@@ -1145,20 +1256,20 @@ async function logout(options) {
1145
1256
  // src/commands/whoami.ts
1146
1257
  async function whoami() {
1147
1258
  const response = await apiRequest("GET", "/auth/me");
1148
- if (!response.ok) throw new Error(`Unable to read account (${response.status}).`);
1259
+ if (!response.ok) throw httpError("Unable to read account", response.status);
1149
1260
  console.log(JSON.stringify(await response.json(), null, 2));
1150
1261
  }
1151
1262
 
1152
1263
  // src/commands/balance.ts
1153
1264
  async function balance() {
1154
1265
  const response = await apiRequest("GET", "/billing/summary");
1155
- if (!response.ok) throw new Error(`Unable to read credit balance (${response.status}).`);
1266
+ if (!response.ok) throw httpError("Unable to read credit balance", response.status);
1156
1267
  console.log(JSON.stringify(await response.json(), null, 2));
1157
1268
  }
1158
1269
 
1159
1270
  // src/index.ts
1160
1271
  var program = new Command();
1161
- program.name("flightdeck").description("FlightDeck CLI \u2014 submit GPU compute jobs").version(JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version);
1272
+ program.name("flightdeck").description("FlightDeck CLI \u2014 submit GPU compute jobs").option("--debug", "include safe error type/code and CLI frame diagnostics (no raw stack or credentials)").version(JSON.parse(readFileSync4(new URL("../package.json", import.meta.url), "utf8")).version);
1162
1273
  program.command("login").description("Log in through the FlightDeck portal").option("--api-url <url>", "FlightDeck API URL", DEFAULT_API_URL).option("--name <name>", "name for this CLI credential", "flightdeck-cli").action(login);
1163
1274
  program.command("logout").description("Revoke this CLI credential and remove the local login").option("--local", "remove the local login without revoking the credential").action(logout);
1164
1275
  program.command("whoami").description("Show the current FlightDeck account").action(whoami);
@@ -1173,4 +1284,9 @@ program.command("logs").description("Stream flight logs").argument("<flight_id>"
1173
1284
  program.command("cancel").description("Cancel a flight").argument("<flight_id>").action(cancel);
1174
1285
  program.command("outputs").description("List flight outputs").argument("<flight_id>").action(listOutputs);
1175
1286
  program.command("download").description("Download all flight outputs").argument("<flight_id>").option("-o, --output-dir <dir>", "destination directory", ".").action(download);
1176
- program.parse();
1287
+ try {
1288
+ await program.parseAsync();
1289
+ } catch (error) {
1290
+ console.error(commandFailure(error, program.opts().debug === true));
1291
+ process.exitCode = 1;
1292
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thermai/flightdeck-cli",
3
- "version": "0.1.0-pilot.2",
3
+ "version": "0.1.0-pilot.4",
4
4
  "description": "FlightDeck CLI — submit GPU compute jobs",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "publishConfig": {
@@ -23,7 +23,8 @@
23
23
  "scripts": {
24
24
  "build": "tsc -p tsconfig.json --noEmit && esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --external:commander --external:tar --outfile=dist/index.js",
25
25
  "dev": "tsx src/index.ts",
26
- "test": "node --import tsx --test \"src/**/*.test.ts\" && node --test scripts/release-policy.test.mjs",
26
+ "test": "node --import tsx --test \"src/**/*.test.ts\" && node --test scripts/release-policy.test.mjs && node scripts/sync-install-instructions.mjs --check",
27
+ "sync:install": "node scripts/sync-install-instructions.mjs --write",
27
28
  "prepack": "npm run build",
28
29
  "test:package": "node scripts/test-package.mjs"
29
30
  },