@ptkl/toolkit 1.7.0 → 1.9.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.
@@ -0,0 +1,693 @@
1
+ import { Command } from "commander";
2
+ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
3
+ import { createInterface } from "node:readline";
4
+ import { registerCommand, withProfile } from "../lib/scaffold.js";
5
+ import KilnClient from "../lib/kilnClient.js";
6
+ import KilnPack from "../lib/kilnPack.js";
7
+ /** `ptkl kiln` — Kiln machines: short-lived gVisor sandboxes leased by the minute (sandbox `/v1/kiln`,
8
+ * reached through luma at `/luma/kiln`). Time left, when the API returns it, goes to stderr so stdout
9
+ * stays the machine's own output or the JSON. */
10
+ function collect(value, prev = []) {
11
+ return [...prev, value];
12
+ }
13
+ function fail(message) {
14
+ console.error(message);
15
+ process.exit(1);
16
+ }
17
+ function duration(sec) {
18
+ if (sec <= 0)
19
+ return "expired";
20
+ const h = Math.floor(sec / 3600), m = Math.floor((sec % 3600) / 60), s = Math.floor(sec % 60);
21
+ return [h ? `${h}h` : "", h || m ? `${m}m` : "", `${s}s`].filter(Boolean).join(" ");
22
+ }
23
+ /** Prints the time left from a reply: `time_left_sec`, or `expires_at` (a machine), else nothing. */
24
+ function showTimeLeft(body, headerSec) {
25
+ let sec = body?.time_left_sec ?? headerSec;
26
+ if (sec === undefined && body?.expires_at && body?.state !== "deleted") {
27
+ sec = Math.round((new Date(body.expires_at).getTime() - Date.now()) / 1000);
28
+ }
29
+ if (typeof sec === "number" && Number.isFinite(sec))
30
+ console.error(`time left: ${duration(sec)}`);
31
+ }
32
+ function showAllTimeLeft(body) {
33
+ if (Array.isArray(body?.machines)) {
34
+ for (const m of body.machines) {
35
+ if (m.expires_at && m.state !== "deleted") {
36
+ const sec = Math.round((new Date(m.expires_at).getTime() - Date.now()) / 1000);
37
+ console.error(`${m.uuid}: time left ${duration(sec)}`);
38
+ }
39
+ }
40
+ }
41
+ else
42
+ showTimeLeft(body);
43
+ }
44
+ /** Bytes as 1.5 GiB, 320 MiB, 12 KiB. */
45
+ function human(bytes) {
46
+ const units = ["B", "KiB", "MiB", "GiB", "TiB"];
47
+ let v = Number(bytes) || 0, i = 0;
48
+ while (v >= 1024 && i < units.length - 1) {
49
+ v /= 1024;
50
+ i++;
51
+ }
52
+ return i === 0 ? `${Math.round(v)} B` : `${v >= 100 ? Math.round(v) : Math.round(v * 10) / 10} ${units[i]}`;
53
+ }
54
+ /** Elapsed seconds as 3d4h, 2h05m, 4m09s, 7s. */
55
+ function elapsed(sec) {
56
+ sec = Math.max(0, Math.floor(Number(sec) || 0));
57
+ const d = Math.floor(sec / 86400), h = Math.floor((sec % 86400) / 3600), m = Math.floor((sec % 3600) / 60), s = sec % 60;
58
+ if (d)
59
+ return `${d}d${h}h`;
60
+ if (h)
61
+ return `${h}h${String(m).padStart(2, "0")}m`;
62
+ if (m)
63
+ return `${m}m${String(s).padStart(2, "0")}s`;
64
+ return `${s}s`;
65
+ }
66
+ function used(now, max) {
67
+ return max > 0 ? `${human(now)} of ${human(max)}` : human(now);
68
+ }
69
+ /** The process table: a totals line, then PID USER CPU% MEM STATE TIME COMMAND, the command cut to the terminal. */
70
+ function processTable(res, width) {
71
+ const rows = (res.processes ?? []).map((p) => [
72
+ String(p.pid), String(p.user ?? ""), `${(Number(p.cpu_percent) || 0).toFixed(1)}`, human(p.memory_bytes),
73
+ String(p.state ?? ""), elapsed(p.elapsed_sec), String(p.command ?? ""),
74
+ ]);
75
+ const head = ["PID", "USER", "CPU%", "MEM", "STATE", "TIME", "COMMAND"];
76
+ const widths = head.slice(0, 6).map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
77
+ const right = new Set([0, 2, 3, 5]);
78
+ const cell = (v, i) => (right.has(i) ? v.padStart(widths[i]) : v.padEnd(widths[i]));
79
+ const fixed = widths.reduce((a, w) => a + w + 1, 0);
80
+ const room = Math.max(10, width - fixed);
81
+ const cut = (c) => (c.length > room ? `${c.slice(0, room - 1)}…` : c);
82
+ const lines = [`CPU ${(Number(res.cpu_percent) || 0).toFixed(1)}% MEM ${human(res.memory_bytes)} ${res.count ?? rows.length} processes`];
83
+ lines.push([...head.slice(0, 6).map(cell), "COMMAND"].join(" "));
84
+ for (const r of rows)
85
+ lines.push([...r.slice(0, 6).map(cell), cut(r[6])].join(" "));
86
+ return lines.join("\n");
87
+ }
88
+ function statusText(s) {
89
+ const lines = [
90
+ `state ${s.state ?? "-"}${s.exit_code != null ? ` (exit ${s.exit_code})` : ""}`,
91
+ `memory ${used(s.memory_bytes, s.memory_max_bytes)}`,
92
+ `swap ${used(s.swap_bytes, s.swap_max_bytes)}`,
93
+ `disk ${used(s.disk_used_bytes, s.disk_limit_bytes)}`,
94
+ `oom kills ${s.oom_kills ?? 0}`,
95
+ `uptime ${elapsed(s.uptime_sec)}`,
96
+ ];
97
+ return lines.join("\n");
98
+ }
99
+ const LEASE_FIELDS = ["minutes", "leased_at", "expires_at", "started_at"];
100
+ /** A saved machine has no lease: its lease fields are null, shown as `-`. */
101
+ function leaseDashes(m) {
102
+ if (!m || typeof m !== "object")
103
+ return m;
104
+ const out = { ...m };
105
+ for (const f of LEASE_FIELDS)
106
+ if (f in out && out[f] === null)
107
+ out[f] = "-";
108
+ return out;
109
+ }
110
+ /** Turns the API's lease refusals into plain messages; any other error passes through. */
111
+ async function leaseErrors(fn) {
112
+ try {
113
+ return await fn();
114
+ }
115
+ catch (err) {
116
+ const body = err?.response?.data;
117
+ const code = body?.error;
118
+ if (code === "lease_active")
119
+ throw new Error("this machine still has time; use `ptkl kiln extend`");
120
+ if (code === "not_leased")
121
+ throw new Error("this machine is saved and not leased; start it with --minutes");
122
+ const onMinutes = body?.field === "minutes" || (Array.isArray(body?.problems) && body.problems.some((p) => p?.field === "minutes"));
123
+ if (err?.response?.status === 400 && onMinutes) {
124
+ throw new Error(`--minutes: ${body.message ?? "not accepted"}`);
125
+ }
126
+ const onProjectEnv = body?.field === "project_env" || (Array.isArray(body?.problems) && body.problems.some((p) => p?.field === "project_env"));
127
+ if (err?.response?.status === 400 && onProjectEnv) {
128
+ throw new Error(`--project-env: ${body.message ?? "not accepted"}`);
129
+ }
130
+ const onEnv = body?.field === "env" || (Array.isArray(body?.problems) && body.problems.some((p) => p?.field === "env"));
131
+ if (err?.response?.status === 400 && onEnv) {
132
+ const p = Array.isArray(body?.problems) ? body.problems.find((x) => x?.field === "env") : undefined;
133
+ throw new Error(`--env-var: ${p?.message ?? body.message ?? "not accepted"}`);
134
+ }
135
+ throw err;
136
+ }
137
+ }
138
+ function parseEnv(pairs = []) {
139
+ if (pairs.length === 0)
140
+ return undefined;
141
+ const env = {};
142
+ for (const p of pairs) {
143
+ const i = p.indexOf("=");
144
+ if (i < 1)
145
+ fail(`--env takes KEY=VALUE, got "${p.split("=")[0]}"`);
146
+ env[p.slice(0, i)] = p.slice(i + 1);
147
+ }
148
+ return env;
149
+ }
150
+ function int(label, v) {
151
+ const n = Number(v);
152
+ if (!Number.isInteger(n) || n <= 0)
153
+ fail(`${label} must be a positive whole number`);
154
+ return n;
155
+ }
156
+ /** `--media MEDIA` pairs with the one `--to` folder: the intake of a start. */
157
+ function mediaIntake(media, to) {
158
+ if (!media?.length)
159
+ return undefined;
160
+ return media.map((m) => ({ media: m, to }));
161
+ }
162
+ const NO_START_DIR = "--to is needed: the machine has no start directory";
163
+ /** Where a start's code goes: --to, else that start's directory (--cwd, else the machine's own). There is no default folder. */
164
+ async function codeFolder(opts, machineCwd) {
165
+ const to = opts.to ?? opts.cwd ?? (machineCwd ? await machineCwd() : undefined);
166
+ if (!to)
167
+ fail(NO_START_DIR);
168
+ return to;
169
+ }
170
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
171
+ /** The archive to upload: a `.tar.gz` file as it is, or a directory packed (.gitignore respected). */
172
+ async function archiveBytes(path) {
173
+ if (!existsSync(path))
174
+ fail(`--archive: ${path} does not exist`);
175
+ if (!statSync(path).isDirectory())
176
+ return readFileSync(path);
177
+ try {
178
+ return await new KilnPack().pack(path);
179
+ }
180
+ catch (err) {
181
+ fail(err.message);
182
+ }
183
+ }
184
+ /** Waits until the machine is `created` (placed, code intake done, not running). A `failed` machine
185
+ * stops the wait with its reason. */
186
+ async function waitCreated(client, uuid, intervalMs = 1000, timeoutMs = 5 * 60_000) {
187
+ const end = Date.now() + timeoutMs;
188
+ for (;;) {
189
+ const m = await client.get(uuid);
190
+ if (m?.state === "created")
191
+ return;
192
+ if (m?.state === "failed") {
193
+ throw new Error(`the machine failed to start: ${m.failure_reason ?? m.reason ?? m.error ?? m.message ?? "no reason given"}`);
194
+ }
195
+ if (["deleted", "saved", "expired"].includes(m?.state))
196
+ throw new Error(`the machine is ${m.state}, not starting`);
197
+ if (Date.now() > end)
198
+ throw new Error("timed out waiting for the machine to be created");
199
+ await sleep(intervalMs);
200
+ }
201
+ }
202
+ /** A start that brings code: Media paths go in the first start; an archive is `start {run:false}`,
203
+ * wait for `created`, upload, `start {}`. `first` is the first start's call (a start or a create). */
204
+ async function startWithCode(client, uuid, first, body, archive, to) {
205
+ if (!archive)
206
+ return leaseErrors(() => first(body));
207
+ const bytes = await archiveBytes(archive);
208
+ await leaseErrors(() => first({ ...body, run: false }));
209
+ await waitCreated(client, uuid);
210
+ await leaseErrors(() => client.putArchive(uuid, bytes, to));
211
+ return leaseErrors(() => client.start(uuid, {}));
212
+ }
213
+ async function readStdin() {
214
+ const chunks = [];
215
+ for await (const c of process.stdin)
216
+ chunks.push(Buffer.from(c));
217
+ return Buffer.concat(chunks);
218
+ }
219
+ /** Adds what `kiln create` and `kiln jobs create` share: the machine's spec flags. */
220
+ function machineBody(body, opts, command) {
221
+ if (opts.step?.length && command?.length)
222
+ fail("Give --step lines or a command after --, not both");
223
+ if (opts.name)
224
+ body.name = opts.name;
225
+ if (opts.size)
226
+ body.size = int("--size", opts.size);
227
+ if (opts.disk)
228
+ body.disk = int("--disk", opts.disk);
229
+ if (opts.image)
230
+ body.image = opts.image;
231
+ if (opts.egress)
232
+ body.egress = opts.egress;
233
+ if (opts.cwd)
234
+ body.cwd = opts.cwd;
235
+ if (opts.extraHost)
236
+ body.extra_hosts = opts.extraHost;
237
+ if (opts.runAs)
238
+ body.run_as = opts.runAs;
239
+ if (opts.step?.length)
240
+ body.sequence = { steps: opts.step };
241
+ else if (command?.length)
242
+ body.sequence = { command };
243
+ if (opts.intake) {
244
+ body.intake = opts.intake.map((p) => {
245
+ const i = p.indexOf("=");
246
+ if (i < 1)
247
+ fail("--intake takes MEDIA=TO");
248
+ return { media: p.slice(0, i), to: p.slice(i + 1) };
249
+ });
250
+ }
251
+ }
252
+ /** A job's env: global env keys only, from `--global-env NAME=KEY`. A literal `--env-var` is refused. */
253
+ function jobEnv(opts) {
254
+ if (opts.envVar?.length)
255
+ fail("A job takes global env keys, not values: use --global-env NAME=KEY (the key of the project's global env)");
256
+ return globalEnv(opts.globalEnv);
257
+ }
258
+ /** A machine's env: `--env-var` values and `--global-env` references, one variable never both. */
259
+ function machineEnv(opts) {
260
+ const values = parseEnv(opts.envVar);
261
+ const refs = globalEnv(opts.globalEnv);
262
+ if (!values && !refs)
263
+ return undefined;
264
+ for (const name of Object.keys(refs ?? {})) {
265
+ if (values && name in values)
266
+ fail(`${name} is given by both --env-var and --global-env: pick one`);
267
+ }
268
+ return { ...values, ...refs };
269
+ }
270
+ /** `--global-env NAME=KEY` pairs as `{NAME: {global_env: KEY}}`. */
271
+ function globalEnv(pairs = []) {
272
+ if (pairs.length === 0)
273
+ return undefined;
274
+ const env = {};
275
+ for (const p of pairs) {
276
+ const i = p.indexOf("=");
277
+ if (i < 1 || i === p.length - 1)
278
+ fail(`--global-env takes NAME=KEY, got "${p}"`);
279
+ env[p.slice(0, i)] = { global_env: p.slice(i + 1) };
280
+ }
281
+ return env;
282
+ }
283
+ const PROJECT_ENVS = ["dev", "live"];
284
+ /** `--project-env`: the env of the lease, which the machine's PROJECT_ENV and token follow. The global --env stays the env of the API call. */
285
+ function projectEnv(v) {
286
+ if (!PROJECT_ENVS.includes(v))
287
+ fail("--project-env must be dev or live");
288
+ return v;
289
+ }
290
+ const PROJECT_ENV_FLAG = "Project env of the lease, dev or live (default dev); the machine's PROJECT_ENV and token follow it. Not the --env of this call";
291
+ const OVERLAPS = ["skip", "parallel", "queue"];
292
+ function overlap(v) {
293
+ if (!OVERLAPS.includes(v))
294
+ fail("--overlap must be skip, parallel or queue");
295
+ return v;
296
+ }
297
+ /** The spec flags a job shares with a machine, plus its schedule. */
298
+ function specOptions(c) {
299
+ return c
300
+ .option("-s, --size <mib>", "Memory in MiB (128 to 2048)")
301
+ .option("--disk <gib>", "Disk in GiB")
302
+ .option("-i, --image <image>", "Image name")
303
+ .option("--step <line>", "A start sequence shell line, run in order (repeatable)", collect)
304
+ .option("-e, --env-var <KEY=VALUE>", "Refused for jobs: use --global-env", collect)
305
+ .option("--global-env <NAME=KEY>", "Env variable NAME from the global env KEY (repeatable)", collect)
306
+ .option("--cwd <dir>", "Working directory of the start sequence")
307
+ .option("--egress <mode>", "Network egress policy")
308
+ .option("--extra-host <host>", "Extra allowed egress host (repeatable)", collect)
309
+ .option("--intake <media=to>", "Copy a Media path into the machine (repeatable)", collect)
310
+ .option("--run-as <identity>", "Identity every run acts as")
311
+ .option("--schedule <cron>", "5-field cron expression; empty text makes the job run on request only")
312
+ .option("--timezone <zone>", "Time zone of the schedule (UTC if omitted)")
313
+ .option("--project-env <env>", "Project env every run works in, dev or live (default dev); PROJECT_ENV and the token follow it. Not the --env of this call");
314
+ }
315
+ class KilnCommand {
316
+ register() {
317
+ const cmd = new Command("kiln").description("Lease and work with Kiln sandboxes. Inside a machine ptkl is ready, authenticated as the machine's run identity (PROJECT_API_TOKEN)");
318
+ cmd.addCommand(this.machines());
319
+ cmd.addCommand(this.create());
320
+ cmd.addCommand(this.jobs());
321
+ cmd.addCommand(this.exec());
322
+ cmd.addCommand(this.logs());
323
+ cmd.addCommand(this.status());
324
+ cmd.addCommand(this.ps());
325
+ cmd.addCommand(this.files());
326
+ cmd.addCommand(this.push());
327
+ this.lifecycle().forEach((c) => cmd.addCommand(c));
328
+ cmd.addCommand(this.usage());
329
+ return cmd;
330
+ }
331
+ machines() {
332
+ const machines = new Command("machines").description("List and show machines");
333
+ machines.addCommand(registerCommand(new Command("list").description("List the project's machines").option("--deleted", "Include deleted machines"))
334
+ .action(withProfile(async (profile, opts) => {
335
+ const res = await new KilnClient(profile).list(Boolean(opts.deleted));
336
+ showAllTimeLeft(res);
337
+ return Array.isArray(res.machines) ? res.machines.map(leaseDashes) : res;
338
+ })));
339
+ machines.addCommand(registerCommand(new Command("get").description("Show one machine").argument("<uuid>"))
340
+ .action(withProfile(async (profile, uuid) => {
341
+ const res = await new KilnClient(profile).get(uuid);
342
+ showTimeLeft(res);
343
+ return leaseDashes(res);
344
+ })));
345
+ return machines;
346
+ }
347
+ create() {
348
+ return registerCommand(new Command("create")
349
+ .description("Save a machine definition and, unless --no-start, start it for --minutes. A machine is only a definition: code (--media, --archive) and minutes come with each start. A command after -- is the start command")
350
+ .option("-m, --minutes <n>", "Minutes the machine runs (required unless --no-start)")
351
+ .option("-n, --name <name>", "Machine name")
352
+ .option("-s, --size <mib>", "Memory in MiB (128 to 2048)")
353
+ .option("--disk <gib>", "Disk in GiB")
354
+ .option("-i, --image <image>", "Image name")
355
+ .option("--step <line>", "A start sequence shell line, run in order (repeatable)", collect)
356
+ .option("-e, --env-var <KEY=VALUE>", "Environment variable (repeatable)", collect)
357
+ .option("--global-env <NAME=KEY>", "Env variable NAME from the project's global env KEY (the key only, not its group), read when the machine starts; the run identity must read its group (repeatable), e.g. --global-env NPM_TOKEN=NPM_TOKEN", collect)
358
+ .option("--cwd <dir>", "Working directory of the start sequence")
359
+ .option("--egress <mode>", "Network egress policy")
360
+ .option("--extra-host <host>", "Extra allowed egress host (repeatable)", collect)
361
+ .option("--media <path>", "Media path to copy into the machine when it starts (repeatable)", collect)
362
+ .option("--archive <file.tar.gz|dir>", "A .tar.gz, or a directory to pack, unpacked in the machine when it starts")
363
+ .option("--to <folder>", "Folder in the machine for --media and --archive (default: the start directory)")
364
+ .option("--run-as <identity>", "Run identity of the machine")
365
+ .option("--project-env <env>", PROJECT_ENV_FLAG)
366
+ .option("--no-start", "Only save the definition; minutes and code are given when it starts")
367
+ .argument("[command...]", "Start command (argv), after --")).action(withProfile(async (profile, command, opts) => {
368
+ if (opts.step?.length && command?.length)
369
+ fail("Give --step lines or a command after --, not both");
370
+ const starts = opts.start !== false;
371
+ if (!starts && opts.minutes !== undefined)
372
+ fail("minutes are given when the machine starts: drop --minutes with --no-start");
373
+ if (starts && opts.minutes === undefined)
374
+ fail("--minutes is required to start the machine; use --no-start to only save it");
375
+ if (!starts && (opts.media?.length || opts.archive))
376
+ fail("code is given when the machine starts: drop --media/--archive with --no-start");
377
+ const body = { start: starts };
378
+ if (!starts && opts.projectEnv !== undefined)
379
+ fail("the env is set when the machine starts: drop --project-env with --no-start");
380
+ if (starts)
381
+ body.minutes = int("--minutes", opts.minutes);
382
+ if (opts.projectEnv !== undefined)
383
+ body.project_env = projectEnv(opts.projectEnv);
384
+ machineBody(body, opts, command);
385
+ const env = machineEnv(opts);
386
+ if (env)
387
+ body.env = env;
388
+ const client = new KilnClient(profile);
389
+ let res;
390
+ const hasCode = Boolean(opts.media?.length || opts.archive);
391
+ const to = hasCode ? await codeFolder(opts) : "";
392
+ if (opts.archive) {
393
+ // Save first, then start with the code: the archive goes in between two starts.
394
+ const { minutes, project_env, ...def } = body;
395
+ const intake = mediaIntake(opts.media, to);
396
+ const saved = await leaseErrors(() => client.create({ ...def, start: false }));
397
+ res = await startWithCode(client, saved.uuid, (b) => client.start(saved.uuid, b), { minutes, ...(project_env ? { project_env } : {}), ...(intake ? { intake } : {}) }, opts.archive, to);
398
+ }
399
+ else {
400
+ const intake = mediaIntake(opts.media, to);
401
+ if (intake)
402
+ body.intake = intake;
403
+ res = await leaseErrors(() => client.create(body));
404
+ }
405
+ showTimeLeft(res);
406
+ return res;
407
+ }));
408
+ }
409
+ jobs() {
410
+ const jobs = new Command("jobs").description("Saved machine specs that run on a schedule or on request");
411
+ jobs.addCommand(registerCommand(new Command("list").description("List the project's jobs"))
412
+ .action(withProfile(async (profile) => (await new KilnClient(profile).jobs()).jobs ?? [])));
413
+ jobs.addCommand(registerCommand(new Command("get").description("Show one job").argument("<ref>", "Job name or id"))
414
+ .action(withProfile(async (profile, ref) => new KilnClient(profile).job(ref))));
415
+ jobs.addCommand(registerCommand(specOptions(new Command("create").description("Save a job. A command after -- is the start command"))
416
+ .requiredOption("--name <name>", "Job name")
417
+ .requiredOption("-m, --minutes <n>", "Minutes each run is leased for (paid in full per run)")
418
+ .requiredOption("--overlap <mode>", "When a run is due while one is going: skip, parallel or queue")
419
+ .option("--disabled", "Save it with its schedule off")
420
+ .argument("[command...]", "Start command (argv), after --")).action(withProfile(async (profile, command, opts) => {
421
+ const env = jobEnv(opts);
422
+ const body = { minutes: int("--minutes", opts.minutes), overlap: overlap(opts.overlap) };
423
+ machineBody(body, opts, command);
424
+ if (env)
425
+ body.env = env;
426
+ if (opts.schedule)
427
+ body.schedule = opts.schedule;
428
+ if (opts.timezone)
429
+ body.time_zone = opts.timezone;
430
+ if (opts.projectEnv !== undefined)
431
+ body.project_env = projectEnv(opts.projectEnv);
432
+ if (opts.disabled)
433
+ body.enabled = false;
434
+ return new KilnClient(profile).createJob(body);
435
+ })));
436
+ jobs.addCommand(registerCommand(specOptions(new Command("update").description("Change a job; flags left out keep their value"))
437
+ .argument("<ref>", "Job name or id")
438
+ .option("-m, --minutes <n>", "Minutes each run is leased for")
439
+ .option("--overlap <mode>", "skip, parallel or queue")
440
+ .option("--rename <name>", "A new name")
441
+ .option("--enable", "Turn the schedule on")
442
+ .option("--disable", "Turn the schedule off")
443
+ .argument("[command...]", "New start command (argv), after --")).action(withProfile(async (profile, ref, command, opts) => {
444
+ if (opts.enable && opts.disable)
445
+ fail("Give --enable or --disable, not both");
446
+ const env = jobEnv(opts);
447
+ const body = {};
448
+ machineBody(body, { ...opts, name: opts.rename }, command);
449
+ if (opts.minutes)
450
+ body.minutes = int("--minutes", opts.minutes);
451
+ if (opts.overlap)
452
+ body.overlap = overlap(opts.overlap);
453
+ if (env)
454
+ body.env = env;
455
+ if (opts.schedule !== undefined)
456
+ body.schedule = opts.schedule;
457
+ if (opts.timezone)
458
+ body.time_zone = opts.timezone;
459
+ if (opts.projectEnv !== undefined)
460
+ body.project_env = projectEnv(opts.projectEnv);
461
+ if (opts.enable)
462
+ body.enabled = true;
463
+ if (opts.disable)
464
+ body.enabled = false;
465
+ if (Object.keys(body).length === 0)
466
+ fail("Nothing to change: give at least one flag");
467
+ return new KilnClient(profile).updateJob(ref, body);
468
+ })));
469
+ jobs.addCommand(registerCommand(new Command("delete").description("Delete a job and its schedule").argument("<ref>", "Job name or id"))
470
+ .action(withProfile(async (profile, ref) => {
471
+ await new KilnClient(profile).removeJob(ref);
472
+ return { deleted: true, job: ref };
473
+ })));
474
+ jobs.addCommand(registerCommand(new Command("run").description("Start a run now").argument("<ref>", "Job name or id"))
475
+ .action(withProfile(async (profile, ref) => new KilnClient(profile).runJob(ref))));
476
+ jobs.addCommand(registerCommand(new Command("runs").description("List a job's runs").argument("<ref>", "Job name or id"))
477
+ .action(withProfile(async (profile, ref) => (await new KilnClient(profile).jobRuns(ref)).runs ?? [])));
478
+ jobs.addCommand(registerCommand(new Command("run-get").description("Show one run").argument("<ref>", "Job name or id").argument("<run>", "Run uuid"))
479
+ .action(withProfile(async (profile, ref, run) => new KilnClient(profile).jobRun(ref, run))));
480
+ return jobs;
481
+ }
482
+ exec() {
483
+ return new Command("exec")
484
+ .description("Run a command in a running machine and print its output")
485
+ .argument("<uuid>")
486
+ .argument("<command...>", "Command, after --")
487
+ .option("--cwd <dir>", "Working directory")
488
+ .option("--user <user>", "User to run as")
489
+ .option("-e, --env-var <KEY=VALUE>", "Environment variable (repeatable)", collect)
490
+ .option("--timeout <sec>", "Timeout in seconds (up to 900)")
491
+ .option("--detach", "Return at once; the output goes to the machine's log")
492
+ .action(withProfile(async (profile, uuid, command, opts) => {
493
+ const body = { command };
494
+ if (opts.cwd)
495
+ body.cwd = opts.cwd;
496
+ if (opts.user)
497
+ body.user = opts.user;
498
+ if (opts.timeout)
499
+ body.timeout_sec = int("--timeout", opts.timeout);
500
+ if (opts.detach)
501
+ body.detach = true;
502
+ const env = parseEnv(opts.envVar);
503
+ if (env)
504
+ body.env = env;
505
+ const res = await new KilnClient(profile).exec(uuid, body);
506
+ if (res.stdout)
507
+ process.stdout.write(res.stdout);
508
+ if (res.stderr)
509
+ process.stderr.write(res.stderr);
510
+ if (res.exec_id && res.detached)
511
+ console.error(`exec ${res.exec_id} detached`);
512
+ if (res.truncated)
513
+ console.error("output truncated");
514
+ if (res.timed_out)
515
+ console.error("timed out");
516
+ showTimeLeft(res);
517
+ if (res.exit_code)
518
+ process.exitCode = res.exit_code;
519
+ }));
520
+ }
521
+ status() {
522
+ return registerCommand(new Command("status").description("Memory, swap and disk used of their limits, out-of-memory kills and uptime of a running machine").argument("<uuid>"))
523
+ .action(withProfile(async (profile, uuid, opts) => {
524
+ const res = await new KilnClient(profile).status(uuid);
525
+ showTimeLeft(res);
526
+ return opts.format ? res : statusText(res);
527
+ }));
528
+ }
529
+ ps() {
530
+ return registerCommand(new Command("ps").description("List the processes in a running machine, busiest first (CPU over about a second; 100% is one CPU)")
531
+ .argument("<uuid>")
532
+ .option("--limit <n>", "How many processes (default 50, at most 200)")).action(withProfile(async (profile, uuid, opts) => {
533
+ const res = await new KilnClient(profile).processes(uuid, opts.limit ? int("--limit", opts.limit) : undefined);
534
+ showTimeLeft(res);
535
+ return opts.format ? res : processTable(res, process.stdout.columns || 120);
536
+ }));
537
+ }
538
+ logs() {
539
+ return new Command("logs")
540
+ .description("Print the machine's log; --follow streams it until the machine ends")
541
+ .argument("<uuid>")
542
+ .option("-f, --follow", "Stream new lines")
543
+ .option("--since <time>", "Only lines since this RFC 3339 time")
544
+ .action(withProfile(async (profile, uuid, opts) => {
545
+ const client = new KilnClient(profile);
546
+ const print = (l) => (l.stream === "stderr" ? process.stderr : process.stdout).write(`${l.text}\n`);
547
+ if (!opts.follow) {
548
+ const res = await client.logs(uuid, opts.since);
549
+ (res.lines ?? []).forEach(print);
550
+ showTimeLeft(res);
551
+ return;
552
+ }
553
+ const stream = await client.followLogs(uuid, opts.since);
554
+ for await (const line of createInterface({ input: stream, crlfDelay: Infinity })) {
555
+ if (!line.trim())
556
+ continue;
557
+ let ev;
558
+ try {
559
+ ev = JSON.parse(line);
560
+ }
561
+ catch {
562
+ continue;
563
+ }
564
+ if (ev.event === "ready")
565
+ showTimeLeft(ev);
566
+ else if (ev.event === "line" && ev.line)
567
+ print(ev.line);
568
+ else if (ev.event === "end") {
569
+ console.error(`log ended${ev.reason ? `: ${ev.reason}` : ""}`);
570
+ break;
571
+ }
572
+ }
573
+ }));
574
+ }
575
+ files() {
576
+ const files = new Command("files").description("Read, write and list files in a machine");
577
+ files.addCommand(new Command("get")
578
+ .description("Print a file, or save it with --out")
579
+ .argument("<uuid>").argument("<path>")
580
+ .option("--out <file>", "Save to a local file")
581
+ .action(withProfile(async (profile, uuid, path, opts) => {
582
+ const res = await new KilnClient(profile).getFile(uuid, path);
583
+ if (opts.out)
584
+ writeFileSync(opts.out, res.data);
585
+ else
586
+ process.stdout.write(res.data);
587
+ showTimeLeft({}, res.timeLeftSec);
588
+ })));
589
+ files.addCommand(registerCommand(new Command("put").description("Write a file from --from <local file>, or from stdin")
590
+ .argument("<uuid>").argument("<path>")
591
+ .option("--from <file>", "Local file to upload")
592
+ .option("--mode <octal>", "File mode, like 0644")).action(withProfile(async (profile, uuid, path, opts) => {
593
+ const content = opts.from ? readFileSync(opts.from) : await readStdin();
594
+ const res = await new KilnClient(profile).putFile(uuid, path, content, opts.mode);
595
+ showTimeLeft(res);
596
+ return res;
597
+ })));
598
+ files.addCommand(registerCommand(new Command("list").description("List a directory")
599
+ .argument("<uuid>").argument("[path]", "Directory", "/")
600
+ .option("--depth <n>", "How deep to list")).action(withProfile(async (profile, uuid, path, opts) => {
601
+ const res = await new KilnClient(profile).listFiles(uuid, path, opts.depth ? Number(opts.depth) : undefined);
602
+ showTimeLeft(res);
603
+ if (res.truncated)
604
+ console.error("listing truncated");
605
+ return res.entries ?? res;
606
+ })));
607
+ return files;
608
+ }
609
+ push() {
610
+ return registerCommand(new Command("push")
611
+ .description("Pack a directory (.gitignore respected) and unpack it in a machine")
612
+ .argument("<dir>").argument("<uuid>")
613
+ .requiredOption("--to <path>", "Directory in the machine to unpack into")).action(withProfile(async (profile, dir, uuid, opts) => {
614
+ let archive;
615
+ try {
616
+ archive = await new KilnPack().pack(dir);
617
+ }
618
+ catch (err) {
619
+ fail(err.message);
620
+ }
621
+ const res = await leaseErrors(() => new KilnClient(profile).putArchive(uuid, archive, opts.to));
622
+ showTimeLeft(res);
623
+ return res;
624
+ }));
625
+ }
626
+ lifecycle() {
627
+ const start = registerCommand(new Command("start").description("Start the machine: a machine is a saved definition, so code (--media, --archive) and minutes come with each start. Runs its sequence, or a new one for this start (--step lines, or a command after --)")
628
+ .argument("<uuid>").argument("[command...]", "New start command, after --")
629
+ .option("--step <line>", "New start sequence line (repeatable)", collect)
630
+ .option("-e, --env-var <KEY=VALUE>", "Environment variable for this start (repeatable; --env is the environment to target)", collect)
631
+ .option("--global-env <NAME=KEY>", "Env variable NAME from the project's global env KEY (the key only, not its group), read when the machine starts; the run identity must read its group (repeatable), e.g. --global-env NPM_TOKEN=NPM_TOKEN", collect)
632
+ .option("--cwd <dir>", "Working directory")
633
+ .option("-m, --minutes <n>", "Minutes to lease; needed when the machine is saved (no time left)")
634
+ .option("--media <path>", "Media path to copy into the machine before it runs (repeatable)", collect)
635
+ .option("--archive <file.tar.gz|dir>", "A .tar.gz, or a directory to pack, unpacked in the machine before it runs")
636
+ .option("--to <folder>", "Folder in the machine for --media and --archive (default: the start directory)")
637
+ .option("--project-env <env>", PROJECT_ENV_FLAG + "; a machine with time left keeps its lease's")
638
+ .option("--files-first", "Lease and copy the Media in, but do not run yet (upload files, then start again)")).action(withProfile(async (profile, uuid, command, opts) => {
639
+ if (opts.step?.length && command?.length)
640
+ fail("Give --step lines or a command after --, not both");
641
+ const body = {};
642
+ if (opts.minutes !== undefined)
643
+ body.minutes = int("--minutes", opts.minutes);
644
+ if (opts.archive && opts.filesFirst)
645
+ fail("--files-first is redundant with --archive: the archive is uploaded before the machine runs");
646
+ if (opts.projectEnv !== undefined)
647
+ body.project_env = projectEnv(opts.projectEnv);
648
+ if (opts.filesFirst)
649
+ body.run = false;
650
+ if (opts.step?.length)
651
+ body.sequence = { steps: opts.step };
652
+ else if (command?.length)
653
+ body.sequence = { command };
654
+ const env = machineEnv(opts);
655
+ if (env)
656
+ body.env = env;
657
+ if (opts.cwd)
658
+ body.cwd = opts.cwd;
659
+ const client = new KilnClient(profile);
660
+ const to = opts.media?.length || opts.archive ? await codeFolder(opts, async () => (await client.get(uuid))?.cwd) : "";
661
+ const intake = mediaIntake(opts.media, to);
662
+ if (intake)
663
+ body.intake = intake;
664
+ const res = await startWithCode(client, uuid, (b) => client.start(uuid, Object.keys(b).length ? b : undefined), body, opts.archive, to);
665
+ showTimeLeft(res);
666
+ return res;
667
+ }));
668
+ const stop = registerCommand(new Command("stop").description("Stop the machine's main process; --force kills it")
669
+ .argument("<uuid>").option("--force", "Kill at once instead of SIGTERM and a 30 s wait")).action(withProfile(async (profile, uuid, opts) => {
670
+ const client = new KilnClient(profile);
671
+ const res = await client.stop(uuid, Boolean(opts.force));
672
+ showTimeLeft(res);
673
+ return res;
674
+ }));
675
+ const extend = registerCommand(new Command("extend").description("Buy more minutes for the lease")
676
+ .argument("<uuid>").argument("<minutes>")).action(withProfile(async (profile, uuid, minutes) => {
677
+ const res = await leaseErrors(() => new KilnClient(profile).extend(uuid, int("minutes", minutes)));
678
+ showTimeLeft(res);
679
+ return res;
680
+ }));
681
+ const del = registerCommand(new Command("delete").description("Give the machine back now (no refund)").argument("<uuid>")).action(withProfile(async (profile, uuid) => {
682
+ const client = new KilnClient(profile);
683
+ const m = await client.get(uuid);
684
+ return client.remove(uuid, m.name || m.uuid || uuid);
685
+ }));
686
+ return [start, stop, extend, del];
687
+ }
688
+ usage() {
689
+ return registerCommand(new Command("usage").description("Hours used and left this month, and the limits"))
690
+ .action(withProfile(async (profile) => new KilnClient(profile).usage()));
691
+ }
692
+ }
693
+ export default new KilnCommand();