ccdeck 3.82.4 → 4.0.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 (145) hide show
  1. package/LICENSING.md +42 -4
  2. package/README.md +183 -72
  3. package/THIRD_PARTY_NOTICES.md +243 -17
  4. package/bin/cli/tui.js +58 -4
  5. package/bin/deck.js +27 -1
  6. package/dist/web/assets/AccountBridge-OQHT5qmS.js +1 -0
  7. package/dist/web/assets/AccountSection-BpIHPhF3.js +1 -0
  8. package/dist/web/assets/BrowserWatchModal-DBdt52v7.js +1 -0
  9. package/dist/web/assets/FeedbackConversations-BJjgXI0-.js +1 -0
  10. package/dist/web/assets/IntegrationModal-DQ0vEz4X.js +7 -0
  11. package/dist/web/assets/IntegrationSkeleton-JCPbqp96.js +1 -0
  12. package/dist/web/assets/RadioPanel-Be6AkrKl.js +1 -0
  13. package/dist/web/assets/StageShell-Dq0JOQhd.js +4 -0
  14. package/dist/web/assets/TrafficRadar-7jqJbhaK.js +8 -0
  15. package/dist/web/assets/UsageHistoryModal-ckawZGoe.js +1 -0
  16. package/dist/web/assets/addon-unicode-graphemes-DW3WJwyh.js +18 -0
  17. package/dist/web/assets/addon-web-links-BWjmmSgS.js +12 -0
  18. package/dist/web/assets/addon-webgl-CLK4R-_u.js +75 -0
  19. package/dist/web/assets/app-40gNTTfq.js +361 -0
  20. package/dist/web/assets/app-BRjYF6oD.css +1 -0
  21. package/dist/web/assets/{index-B-l-VxLm.js → index-XIY3yFiN.js} +1 -1
  22. package/dist/web/assets/inspector-status-pane-BV_m7eBv.js +1 -0
  23. package/dist/web/assets/screens-9_ivqfcF.js +12 -0
  24. package/dist/web/assets/screens-DUniTTbC.css +1 -0
  25. package/dist/web/assets/stage-board-NF_wgGRA.js +2 -0
  26. package/dist/web/assets/use-account-BUmI-A8e.js +1 -0
  27. package/dist/web/assets/xterm-4jYizCpg.js +27 -0
  28. package/dist/web/assets/xterm-sheet-6GBZ9nXN.css +32 -0
  29. package/dist/web/index.html +16 -6
  30. package/package.json +13 -1
  31. package/release-notes.json +67 -0
  32. package/src/server/account-client.mjs +196 -0
  33. package/src/server/account-connect.mjs +238 -0
  34. package/src/server/account-flag.mjs +106 -0
  35. package/src/server/account-projects.mjs +1 -1
  36. package/src/server/account-service.mjs +532 -0
  37. package/src/server/account-status.mjs +293 -0
  38. package/src/server/account-store.mjs +137 -0
  39. package/src/server/account-sync.mjs +473 -0
  40. package/src/server/account-token-store.mjs +216 -0
  41. package/src/server/account-ui-fields.mjs +126 -0
  42. package/src/server/account-watch.mjs +1 -1
  43. package/src/server/browser-watch-log.mjs +1 -1
  44. package/src/server/browser-watch-store.mjs +1 -1
  45. package/src/server/ccdeck-account-routes.mjs +252 -0
  46. package/src/server/ccusage-install.mjs +2 -2
  47. package/src/server/ccusage-registry.mjs +4 -4
  48. package/src/server/ccusage-session.mjs +11 -0
  49. package/src/server/claude-accounts.mjs +1 -1
  50. package/src/server/claude-recovery.mjs +9 -4
  51. package/src/server/claude-settings-catalog.mjs +6 -6
  52. package/src/server/claude-settings.mjs +1 -1
  53. package/src/server/codex-auto.mjs +1 -1
  54. package/src/server/codex-cost-usage.mjs +7 -2
  55. package/src/server/codex-live-checkpoint.mjs +24 -9
  56. package/src/server/codex-live-engine.mjs +14 -4
  57. package/src/server/codex-live-handoff.mjs +53 -9
  58. package/src/server/codex-names.mjs +49 -0
  59. package/src/server/codex-translate.mjs +1 -1
  60. package/src/server/codex-ultrafast.d.mts +3 -0
  61. package/src/server/codex-ultrafast.mjs +5 -0
  62. package/src/server/codex-watch.mjs +25 -0
  63. package/src/server/command-panel-engine.mjs +300 -0
  64. package/src/server/command-panel-platform.mjs +99 -0
  65. package/src/server/cswap-auto-choice.mjs +1 -1
  66. package/src/server/cswap-auto-loop.mjs +1 -1
  67. package/src/server/cswap-install.mjs +21 -40
  68. package/src/server/deck-home.mjs +6 -0
  69. package/src/server/deck-prefs.mjs +53 -1
  70. package/src/server/detach.mjs +1 -1
  71. package/src/server/engine-download.mjs +277 -0
  72. package/src/server/engine-install.mjs +378 -0
  73. package/src/server/engine-package.mjs +267 -0
  74. package/src/server/event-log.mjs +7 -1
  75. package/src/server/event-pipeline.mjs +29 -1
  76. package/src/server/ghostty-handoff.mjs +81 -0
  77. package/src/server/index.mjs +143 -5
  78. package/src/server/installer.mjs +4 -1
  79. package/src/server/integrations/jira-write-guard.mjs +14 -208
  80. package/src/server/integrations/store.mjs +37 -19
  81. package/src/server/integrations/write-guard.mjs +223 -0
  82. package/src/server/intel-cpu-temperature.mjs +26 -0
  83. package/src/server/lifecycle.mjs +69 -6
  84. package/src/server/log-replay.mjs +4 -0
  85. package/src/server/login-service.mjs +7 -1
  86. package/src/server/macmon.mjs +1 -1
  87. package/src/server/npm-latest.mjs +1 -1
  88. package/src/server/org-telemetry.mjs +1 -1
  89. package/src/server/output-watch.mjs +4 -1
  90. package/src/server/panel-provenance.mjs +390 -0
  91. package/src/server/pinned-build.mjs +14 -0
  92. package/src/server/prefs-refusal.mjs +8 -1
  93. package/src/server/prefs-routes.mjs +60 -11
  94. package/src/server/pro-engine-client.mjs +339 -0
  95. package/src/server/pro-engine-install.mjs +294 -0
  96. package/src/server/pro-engine-terminal.mjs +308 -0
  97. package/src/server/project-discovery.mjs +139 -0
  98. package/src/server/provider-session-name.mjs +58 -0
  99. package/src/server/quota-closes.mjs +1 -1
  100. package/src/server/quota-history.mjs +1 -1
  101. package/src/server/reports.mjs +86 -21
  102. package/src/server/request-gates.mjs +34 -5
  103. package/src/server/restart-note.mjs +1 -1
  104. package/src/server/seed-boundary.mjs +489 -0
  105. package/src/server/session-counts.mjs +244 -0
  106. package/src/server/session-deck-names.mjs +143 -0
  107. package/src/server/session-enrichment.mjs +43 -6
  108. package/src/server/session-name-route.mjs +73 -0
  109. package/src/server/session-summary.mjs +12 -1
  110. package/src/server/session-transcript-routes.mjs +167 -0
  111. package/src/server/swap-log.mjs +1 -1
  112. package/src/server/system-metrics.mjs +57 -0
  113. package/src/server/terminal-bridge.mjs +485 -0
  114. package/src/server/terminal-folder.mjs +61 -0
  115. package/src/server/terminal-js-routes.mjs +752 -0
  116. package/src/server/terminal-routes.mjs +553 -0
  117. package/src/server/terminal-sessions.mjs +759 -0
  118. package/src/server/terminal-socket.mjs +403 -0
  119. package/src/server/terminal-target.mjs +928 -0
  120. package/src/server/thermal-metrics.mjs +13 -9
  121. package/src/server/tmux-control.mjs +1319 -0
  122. package/src/server/tmux-download.mjs +220 -0
  123. package/src/server/tmux.mjs +542 -0
  124. package/src/server/token-redact.mjs +42 -3
  125. package/src/server/tool-audit-report.mjs +44 -6
  126. package/src/server/tool-audit-routes.mjs +12 -1
  127. package/src/server/tool-audit.mjs +42 -8
  128. package/src/server/traffic-radar-monitor.mjs +1 -1
  129. package/src/server/traffic-radar-permission.mjs +1 -1
  130. package/src/server/transcript-gate.mjs +1 -1
  131. package/src/server/transcript-scan.mjs +15 -7
  132. package/src/server/transcript-turns.mjs +154 -0
  133. package/src/server/tui-network.mjs +1 -0
  134. package/src/server/tui-view.mjs +28 -0
  135. package/src/server/utf8-carry.mjs +159 -0
  136. package/src/server/uv-bootstrap.mjs +2 -2
  137. package/src/server/windows-acl.mjs +158 -0
  138. package/src/server/ws-frames.mjs +690 -0
  139. package/dist/web/assets/BrowserWatchModal-CWVooKxD.js +0 -1
  140. package/dist/web/assets/IntegrationModal-DLX43RIK.js +0 -7
  141. package/dist/web/assets/RadioPanel-Cj6PjrvQ.js +0 -1
  142. package/dist/web/assets/TrafficRadar-Bq1YcuHB.js +0 -8
  143. package/dist/web/assets/UsageHistoryModal-CMSCca5_.js +0 -1
  144. package/dist/web/assets/app-BHxsMz3-.js +0 -358
  145. package/dist/web/assets/app-CbXmr9rC.css +0 -1
@@ -274,7 +274,7 @@ export async function detachAndWatch({
274
274
  exit = (code) => process.exit(code),
275
275
  } = {}) {
276
276
  const path = join(logDir, DECK_LOG);
277
- try { mkdirSync(logDir, { recursive: true }); } catch { /* reported by the open below */ }
277
+ try { mkdirSync(logDir, { recursive: true, mode: 0o700 }); } catch { /* reported by the open below */ }
278
278
 
279
279
  if (startsFresh(liveCount, booting)) {
280
280
  try { renameSync(path, `${path}.1`); } catch { /* no log yet, or held where it cannot move: carry on in it */ }
@@ -0,0 +1,277 @@
1
+ // The Command Panel's engine fetched from the npm registry, for a deck that
2
+ // did not come with it: an install made with --omit=optional, a git checkout,
3
+ // a mirror that skipped the platform package.
4
+ //
5
+ // THE SAME PACKAGE, NOT A SECOND CHANNEL. What is fetched is the platform
6
+ // package npm would have installed beside the deck (ENGINE_PACKAGE_NAMES in
7
+ // engine-package.mjs), at the exact version the deck's own package.json pins
8
+ // in its optionalDependencies — the pin the desktop build reads too
9
+ // (desktop/scripts/deck-runtime.cjs). No pin, no download: a deck released
10
+ // before the engine packages exist offers none.
11
+ //
12
+ // THE TRUST IS NOT IN THE REGISTRY. The registry's sha512 integrity is checked
13
+ // so a cut or garbled transfer fails here, but what makes an engine trusted is
14
+ // what makes the package beside the deck trusted: its manifest signed by one
15
+ // of the deck's keys, the executable's size and SHA-256, its header and its
16
+ // version, all checked by importEngine on the unpacked bytes. This file only
17
+ // fetches and unpacks; it never installs and never runs anything.
18
+ //
19
+ // ONLY ON A PRESS. Nothing here is called except by engine-install.mjs, and
20
+ // that only from the route a person's Install press reaches. Importing this
21
+ // does no I/O.
22
+ //
23
+ // UNPACKED STRICTLY. A package tarball is a gzipped tar of `package/<file>`
24
+ // entries. Only plain files directly under `package/` with plain names are
25
+ // written, each new (O_EXCL, never through a link) and owner-only; a link,
26
+ // a device, a nested path, `..`, a repeated name or an archive past the caps
27
+ // refuses the whole package.
28
+ import { constants, promises as fs } from "node:fs";
29
+ import { createHash } from "node:crypto";
30
+ import { gunzipSync } from "node:zlib";
31
+ import { dirname, join } from "node:path";
32
+ import { fileURLToPath } from "node:url";
33
+ import { ENGINE_PACKAGE_NAMES } from "./engine-package.mjs";
34
+
35
+ /** The registry the deck itself is published to. */
36
+ export const ENGINE_REGISTRY = "https://registry.npmjs.org/";
37
+
38
+ /** A package is one executable and its manifest: tens of MB at most. A
39
+ * download or an unpacked archive past these is not one. */
40
+ export const ENGINE_TARBALL_MAX = 160 * 1024 * 1024;
41
+ const UNPACKED_MAX = 320 * 1024 * 1024;
42
+ const METADATA_MAX = 256 * 1024;
43
+ const FILES_MAX = 16;
44
+ const METADATA_TIMEOUT_MS = 30_000;
45
+ const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
46
+
47
+ /** Where the deck's own package.json is: two folders up from this file. */
48
+ const DECK_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
49
+ const EXACT = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
50
+
51
+ /** A failure this file names, with the step it happened at. */
52
+ export class EngineDownloadError extends Error {
53
+ constructor(code, step) {
54
+ super(code);
55
+ this.code = code;
56
+ this.step = step;
57
+ }
58
+ }
59
+
60
+ /** The package and exact version the deck pins for this machine, or null:
61
+ * no package for the platform, no pin in package.json, or a pin that is a
62
+ * range rather than one version. */
63
+ export async function enginePin({ platform = process.platform, arch = process.arch, root = DECK_ROOT } = {}) {
64
+ const name = Object.hasOwn(ENGINE_PACKAGE_NAMES, `${platform}-${arch}`) ? ENGINE_PACKAGE_NAMES[`${platform}-${arch}`] : null;
65
+ if (!name) return null;
66
+ try {
67
+ const manifest = JSON.parse(await fs.readFile(join(root, "package.json"), "utf8"));
68
+ const spec = manifest?.optionalDependencies?.[name];
69
+ return typeof spec === "string" && EXACT.test(spec) ? { name, version: spec } : null;
70
+ } catch {
71
+ return null;
72
+ }
73
+ }
74
+
75
+ /** Whether `error` is the network not answering rather than an answer. */
76
+ function offline(error) {
77
+ const codes = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "ENETUNREACH", "EHOSTUNREACH", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET"]);
78
+ const cause = error?.cause ?? {};
79
+ return error?.name === "TimeoutError" || codes.has(error?.code) || codes.has(cause.code) || (error instanceof TypeError && /fetch failed/i.test(error.message));
80
+ }
81
+
82
+ /** One signal that aborts when either does. AbortSignal.any is not in
83
+ * Node 18, the deck's floor. */
84
+ function eitherSignal(timeout, signal) {
85
+ const controller = new AbortController();
86
+ const timer = setTimeout(() => controller.abort(new DOMException("timed out", "TimeoutError")), timeout);
87
+ timer.unref?.();
88
+ const onAbort = () => controller.abort(signal.reason);
89
+ if (signal?.aborted) controller.abort(signal.reason);
90
+ else signal?.addEventListener("abort", onAbort, { once: true });
91
+ return { signal: controller.signal, done: () => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); } };
92
+ }
93
+
94
+ /** A fetch that names its failure: `cancelled` when `signal` was aborted,
95
+ * `offline` when the network did not answer, `download-failed` otherwise.
96
+ * The timeout covers the whole body, which the caller reads before `done`. */
97
+ async function request(fetchImpl, url, signal, timeout) {
98
+ const either = eitherSignal(timeout, signal);
99
+ try {
100
+ return { res: await fetchImpl(url, { redirect: "error", signal: either.signal }), done: either.done };
101
+ } catch (error) {
102
+ either.done();
103
+ if (signal?.aborted) throw new EngineDownloadError("cancelled", "download");
104
+ throw new EngineDownloadError(offline(error) ? "offline" : "download-failed", "download");
105
+ }
106
+ }
107
+
108
+ /** The body, chunk by chunk, telling `progress` the bytes so far; refused
109
+ * past `cap`. */
110
+ async function readCapped(res, cap, progress, signal) {
111
+ const reader = res.body?.getReader?.();
112
+ if (!reader) {
113
+ const whole = Buffer.from(await res.arrayBuffer());
114
+ if (whole.length > cap) throw new EngineDownloadError("too-large", "download");
115
+ progress(whole.length);
116
+ return whole;
117
+ }
118
+ const chunks = [];
119
+ let received = 0;
120
+ try {
121
+ for (;;) {
122
+ const { done, value } = await reader.read();
123
+ if (done) break;
124
+ received += value.byteLength;
125
+ if (received > cap) throw new EngineDownloadError("too-large", "download");
126
+ chunks.push(Buffer.from(value));
127
+ progress(received);
128
+ }
129
+ } catch (error) {
130
+ await reader.cancel().catch(() => {});
131
+ if (error instanceof EngineDownloadError) throw error;
132
+ if (signal?.aborted) throw new EngineDownloadError("cancelled", "download");
133
+ throw new EngineDownloadError(offline(error) ? "offline" : "download-failed", "download");
134
+ }
135
+ return Buffer.concat(chunks, received);
136
+ }
137
+
138
+ /**
139
+ * The pinned package's tarball from the registry, its sha512 integrity
140
+ * checked. Throws EngineDownloadError: `offline`, `not-published` (the
141
+ * registry has no such version), `download-failed`, `too-large`,
142
+ * `cancelled`, or `check-failed` (the bytes are not the ones the registry
143
+ * describes).
144
+ *
145
+ * `onProgress({ received, total })` hears the bytes as they arrive; `total`
146
+ * is null when neither the registry nor the server said.
147
+ */
148
+ export async function fetchEngineTarball({
149
+ name, version, registry = ENGINE_REGISTRY, fetchImpl = globalThis.fetch, signal, onProgress = () => {},
150
+ } = {}) {
151
+ const base = new URL(registry);
152
+ let dist;
153
+ const meta = await request(fetchImpl, new URL(`${name.replace("/", "%2f")}/${encodeURIComponent(version)}`, base), signal, METADATA_TIMEOUT_MS);
154
+ try {
155
+ if (meta.res.status === 404) throw new EngineDownloadError("not-published", "download");
156
+ if (!meta.res.ok) throw new EngineDownloadError("download-failed", "download");
157
+ const text = (await readCapped(meta.res, METADATA_MAX, () => {}, signal)).toString("utf8");
158
+ const doc = JSON.parse(text);
159
+ if (doc?.name !== name || doc?.version !== version) throw new Error("other package");
160
+ dist = doc.dist;
161
+ } catch (error) {
162
+ if (error instanceof EngineDownloadError) throw error;
163
+ throw new EngineDownloadError("download-failed", "download");
164
+ } finally { meta.done(); }
165
+ const integrity = /^sha512-([A-Za-z0-9+/]{86}==)$/.exec(String(dist?.integrity ?? ""));
166
+ let tarball;
167
+ try { tarball = new URL(String(dist?.tarball ?? "")); } catch { tarball = null; }
168
+ // From the registry itself, over https, carrying no credentials.
169
+ if (!integrity || !tarball || tarball.protocol !== "https:" || tarball.origin !== base.origin || tarball.username || tarball.password) {
170
+ throw new EngineDownloadError("download-failed", "download");
171
+ }
172
+ const { res, done } = await request(fetchImpl, tarball, signal, DOWNLOAD_TIMEOUT_MS);
173
+ let bytes;
174
+ try {
175
+ if (!res.ok) throw new EngineDownloadError(res.status === 404 ? "not-published" : "download-failed", "download");
176
+ const length = Number(res.headers?.get?.("content-length") ?? 0);
177
+ if (length > ENGINE_TARBALL_MAX) throw new EngineDownloadError("too-large", "download");
178
+ const total = length > 0 ? length : null;
179
+ onProgress({ received: 0, total });
180
+ bytes = await readCapped(res, ENGINE_TARBALL_MAX, (received) => onProgress({ received, total }), signal);
181
+ } finally { done(); }
182
+ if (createHash("sha512").update(bytes).digest("base64") !== integrity[1]) throw new EngineDownloadError("check-failed", "verify");
183
+ return bytes;
184
+ }
185
+
186
+ const PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
187
+
188
+ /** A tar header's octal number, or NaN. */
189
+ function octal(block, at, length) {
190
+ const text = block.subarray(at, at + length).toString("latin1").replace(/\0.*$/s, "").trim();
191
+ return /^[0-7]+$/.test(text) ? parseInt(text, 8) : (text === "" ? 0 : NaN);
192
+ }
193
+
194
+ /** A pax header's `path`, when it sets one. */
195
+ function paxPath(data) {
196
+ let at = 0;
197
+ let path = null;
198
+ while (at < data.length) {
199
+ const space = data.indexOf(0x20, at);
200
+ if (space < 0) break;
201
+ const length = Number(data.subarray(at, space).toString("latin1"));
202
+ if (!Number.isSafeInteger(length) || length <= 0 || at + length > data.length) throw new Error("pax");
203
+ const record = data.subarray(space + 1, at + length - 1).toString("utf8");
204
+ const eq = record.indexOf("=");
205
+ if (eq > 0 && record.slice(0, eq) === "path") path = record.slice(eq + 1);
206
+ at += length;
207
+ }
208
+ return path;
209
+ }
210
+
211
+ /**
212
+ * The plain files directly under `package/` in a gzipped package tarball, as
213
+ * `[{ name, data }]`. Throws for anything else: a link or a device, a nested
214
+ * or climbing path, a repeated name, an archive past the caps.
215
+ */
216
+ export function readPackageTarball(tgz) {
217
+ let tar;
218
+ try {
219
+ tar = gunzipSync(tgz, { maxOutputLength: UNPACKED_MAX });
220
+ } catch {
221
+ throw new EngineDownloadError("check-failed", "verify");
222
+ }
223
+ const files = [];
224
+ const seen = new Set();
225
+ let at = 0;
226
+ let pending = null;
227
+ try {
228
+ while (at + 512 <= tar.length) {
229
+ const block = tar.subarray(at, at + 512);
230
+ if (block.every((b) => b === 0)) break;
231
+ const size = octal(block, 124, 12);
232
+ if (!Number.isSafeInteger(size) || size < 0 || at + 512 + size > tar.length) throw new Error("size");
233
+ const type = String.fromCharCode(block[156] || 0x30);
234
+ const data = tar.subarray(at + 512, at + 512 + size);
235
+ at += 512 + Math.ceil(size / 512) * 512;
236
+ if (type === "x") { pending = paxPath(data); continue; }
237
+ if (type === "g") continue;
238
+ const prefix = block.subarray(345, 500).toString("utf8").replace(/\0.*$/s, "");
239
+ const short = block.subarray(0, 100).toString("utf8").replace(/\0.*$/s, "");
240
+ const path = pending ?? (prefix ? `${prefix}/${short}` : short);
241
+ pending = null;
242
+ if (type === "5") continue; // a folder entry: the folder is ours to make
243
+ if (type !== "0") throw new Error("not a plain file");
244
+ const parts = path.split("/");
245
+ if (parts.length !== 2 || parts[0] !== "package" || !PLAIN_NAME.test(parts[1]) || parts[1].includes("..")) throw new Error("path");
246
+ if (seen.has(parts[1])) throw new Error("repeated");
247
+ seen.add(parts[1]);
248
+ files.push({ name: parts[1], data: Buffer.from(data) });
249
+ if (files.length > FILES_MAX) throw new Error("too many");
250
+ }
251
+ } catch {
252
+ throw new EngineDownloadError("check-failed", "verify");
253
+ }
254
+ if (!files.some((f) => f.name === "manifest.json") || !files.some((f) => f.name === "package.json")) {
255
+ throw new EngineDownloadError("check-failed", "verify");
256
+ }
257
+ return files;
258
+ }
259
+
260
+ /**
261
+ * Writes a package's files where importEngine looks for it when asked to
262
+ * start at `staging`: `<staging>/node_modules/<name>/`. The folders are made
263
+ * owner-only, each file new and owner-only, flushed. `staging` must exist.
264
+ */
265
+ export async function placePackage(staging, name, files) {
266
+ const folder = join(staging, "node_modules", ...name.split("/"));
267
+ await fs.mkdir(folder, { recursive: true, mode: 0o700 });
268
+ for (let dir = folder; dir !== staging; dir = dirname(dir)) await fs.chmod(dir, 0o700).catch(() => {});
269
+ for (const { name: file, data } of files) {
270
+ const handle = await fs.open(join(folder, file), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
271
+ try {
272
+ await handle.writeFile(data);
273
+ await handle.sync();
274
+ } finally { await handle.close(); }
275
+ }
276
+ return folder;
277
+ }
@@ -0,0 +1,378 @@
1
+ // Getting the Command Panel's engine onto this machine when the terminal
2
+ // needs it, and taking it off again: the one install at a time, its progress,
3
+ // its failure, and what an install cut short left behind.
4
+ //
5
+ // THREE SOURCES, ONE INSTALLER. The package npm put beside the deck, and the
6
+ // desktop app's copy, are brought in by command-panel-engine.mjs with no
7
+ // question (engine-package.mjs). This file adds the third source the page
8
+ // offers when neither is there: the same package from the npm registry after
9
+ // an Install press (engine-download.mjs), or a package file the person picks.
10
+ // Each ends in importEngine, so every engine is held to the one standard:
11
+ // signed manifest, size and SHA-256, header, no downgrade, an atomic swap.
12
+ //
13
+ // NOTHING STARTS BY ITSELF. Importing this does no I/O; `status` reads only
14
+ // this machine (no network); a download starts only from `install`, which
15
+ // only the Install route calls. AGENTS_DECK_NO_INSTALL=1 or
16
+ // AGENTS_DECK_NO_DOWNLOAD=1 turn the download off, as they do for tmux; a
17
+ // package file can still be installed.
18
+ //
19
+ // ONE AT A TIME, ACROSS TABS AND DECKS. In this process the job is one value
20
+ // that every tab reads (so a second tab mirrors the first one's progress),
21
+ // and every change to the engine folder runs under `withEngineLock`, which
22
+ // command-panel-engine.mjs's own import takes too. Across processes sharing
23
+ // the data folder, a lock file beside the engine folder names the holder;
24
+ // a holder that is gone, or a lock older than LOCK_STALE_MS, is taken over.
25
+ //
26
+ // CUT SHORT IS PUT RIGHT. A deck that stopped mid-install can leave a
27
+ // download or an import folder, or the previous engine set aside with no
28
+ // engine in its place (importEngine renames the old folder away before the
29
+ // new one lands). The next status, when nothing is installing, removes the
30
+ // leftovers and renames the previous engine back, and says so once.
31
+ import { constants, promises as fs } from "node:fs";
32
+ import { randomBytes } from "node:crypto";
33
+ import { homedir } from "node:os";
34
+ import { join, relative, sep } from "node:path";
35
+ import { deckDataDir } from "./deck-home.mjs";
36
+ import {
37
+ EngineDownloadError, ENGINE_REGISTRY, enginePin, fetchEngineTarball, placePackage, readPackageTarball,
38
+ } from "./engine-download.mjs";
39
+ import { ENGINE_PACKAGE_NAMES, importEngine } from "./engine-package.mjs";
40
+ import { TARGETS, UNSAFE_FOLDER, compareVersions, verifyEngineInstallation } from "./pro-engine-install.mjs";
41
+ import { RUNNING_VERSION } from "./running-version.mjs";
42
+
43
+ /** The lock file beside the engine folder. */
44
+ export const LOCK_FILE = "engine.lock";
45
+ /** A lock this old is a deck that died holding it. An install is a download
46
+ * of tens of MB and a copy; ten minutes is far past one. */
47
+ export const LOCK_STALE_MS = 10 * 60_000;
48
+ /**
49
+ * ccdeck's own data folder, made writable by its owner alone. The engine is
50
+ * verified only where no parent folder is writable by anyone else
51
+ * (pro-engine-install.mjs), and older decks' writers created this folder
52
+ * with the default mode, so under a 0002 umask (Ubuntu's default) it can be
53
+ * 0775 and every engine in it refused, read as a check that failed. The
54
+ * deck's writers now make it, and any missing folder above it, 0700; one
55
+ * made before that is still put right here.
56
+ * Only this one folder, only when it is the user's own and never on Windows,
57
+ * whose ACLs are checked their own way; any parent above it is left as is.
58
+ */
59
+ export async function tightenDataFolder(dir, platform = process.platform) {
60
+ if (platform === "win32" || typeof process.getuid !== "function") return;
61
+ try {
62
+ const s = await fs.stat(dir);
63
+ if (!s.isDirectory() || s.uid !== process.getuid() || !(s.mode & 0o022)) return;
64
+ await fs.chmod(dir, s.mode & 0o7755 & ~0o022);
65
+ } catch {
66
+ // Not there yet, or not ours to change: the check says why later.
67
+ }
68
+ }
69
+
70
+ /** How long the page is told an install cut short was put right. */
71
+ const RECOVERED_SAID_MS = 15_000;
72
+
73
+ // Every change to the engine folder in this process, one after another.
74
+ let lockTail = Promise.resolve();
75
+ let lockHeld = 0;
76
+
77
+ /** Runs `fn` once every earlier change to the engine folder has finished. */
78
+ export function withEngineLock(fn) {
79
+ lockHeld += 1;
80
+ const run = lockTail.then(fn);
81
+ lockTail = run.catch(() => {}).finally(() => { lockHeld -= 1; });
82
+ return run;
83
+ }
84
+
85
+ /** Whether a change to the engine folder runs, or waits, in this process. */
86
+ export const engineLockHeld = () => lockHeld > 0;
87
+
88
+ /** Whether process `pid` is alive (EPERM: alive, another user's). */
89
+ function alive(pid) {
90
+ if (!Number.isSafeInteger(pid) || pid <= 0) return false;
91
+ try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
92
+ }
93
+
94
+ /** Takes the data folder's lock file, or answers false when a live holder
95
+ * has it. A gone or stale holder's lock is taken over once. */
96
+ async function takeLock(dataDir, now) {
97
+ const file = join(dataDir, LOCK_FILE);
98
+ for (let attempt = 0; attempt < 2; attempt += 1) {
99
+ try {
100
+ const handle = await fs.open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
101
+ try { await handle.writeFile(JSON.stringify({ pid: process.pid, at: now() })); } finally { await handle.close(); }
102
+ return true;
103
+ } catch (error) {
104
+ if (error?.code !== "EEXIST") throw error;
105
+ }
106
+ let holder = null;
107
+ try { holder = JSON.parse(await fs.readFile(file, "utf8")); } catch { /* unreadable: treated as stale */ }
108
+ const fresh = holder && Number.isFinite(holder.at) && now() - holder.at < LOCK_STALE_MS;
109
+ if (fresh && holder.pid !== process.pid && alive(holder.pid)) return false;
110
+ if (fresh && holder.pid === process.pid) return false;
111
+ await fs.rm(file, { force: true });
112
+ }
113
+ return false;
114
+ }
115
+
116
+ async function dropLock(dataDir) {
117
+ const file = join(dataDir, LOCK_FILE);
118
+ try {
119
+ const holder = JSON.parse(await fs.readFile(file, "utf8"));
120
+ if (holder?.pid === process.pid) await fs.rm(file, { force: true });
121
+ } catch { /* already gone */ }
122
+ }
123
+
124
+ /** Whether another live process holds the data folder's lock now. */
125
+ async function lockedElsewhere(dataDir, now) {
126
+ try {
127
+ const holder = JSON.parse(await fs.readFile(join(dataDir, LOCK_FILE), "utf8"));
128
+ return holder?.pid !== process.pid && Number.isFinite(holder?.at) && now() - holder.at < LOCK_STALE_MS && alive(holder.pid);
129
+ } catch {
130
+ return false;
131
+ }
132
+ }
133
+
134
+ /** The bytes under `dir`, for "Frees N MB": the engine folder is a handful
135
+ * of files, so a walk is cheap. Links are counted as themselves. */
136
+ async function folderBytes(dir) {
137
+ let total = 0;
138
+ let entries;
139
+ try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return 0; }
140
+ for (const entry of entries) {
141
+ const path = join(dir, entry.name);
142
+ if (entry.isDirectory()) total += await folderBytes(path);
143
+ else total += (await fs.lstat(path).catch(() => null))?.size ?? 0;
144
+ }
145
+ return total;
146
+ }
147
+
148
+ /** The data folder as `~/…` for the one command that gives it back to its
149
+ * user, or null where it is not under the home folder (a path with another
150
+ * user's name is never sent) or on Windows, which has no such one line.
151
+ * Only plain names: nothing a shell would read as more than a path. */
152
+ function fixPathOf(dir, platform, home) {
153
+ if (platform === "win32" || !home) return null;
154
+ const rel = relative(home, dir);
155
+ if (!rel || rel.startsWith("..") || rel.startsWith(sep)) return null;
156
+ const parts = rel.split(sep);
157
+ if (!parts.every((part) => /^[A-Za-z0-9._-]+$/.test(part))) return null;
158
+ return `~/${parts.join("/")}`;
159
+ }
160
+
161
+ /** The failure an error is, with the step it happened at. */
162
+ function failureOf(error, step) {
163
+ if (error instanceof EngineDownloadError) return { code: error.code === "too-large" ? "check-failed" : error.code, step: error.step };
164
+ if (error?.code === "EACCES" || error?.code === "EPERM" || error?.code === "EROFS") return { code: "no-permission", step };
165
+ if (error?.code === "ENOSPC" || error?.code === "EDQUOT") return { code: "no-space", step };
166
+ return { code: "failed", step };
167
+ }
168
+
169
+ /**
170
+ * The deck's engine installer. `status()`, `install()`, `installFile(bytes)`,
171
+ * `cancel()`, `remove()`, `recover()`.
172
+ *
173
+ * `keys` are the deck's trusted keys (ENGINE_PUBLIC_KEYS); with none, nothing
174
+ * can be verified, so nothing is offered. `beforeChange` stops the running
175
+ * engine before its folder is swapped or removed (a running executable cannot
176
+ * be replaced on Windows). `platform`, `arch`, `env`, `dataFolder`, `root`
177
+ * (where the deck's package.json is), `registry`, `fetchImpl`,
178
+ * `importPackage`, `now` and `home` are there for tests.
179
+ */
180
+ export function createEngineInstaller({
181
+ platform = process.platform, arch = process.arch, env = process.env, keys = [], dataFolder, root,
182
+ registry = ENGINE_REGISTRY, fetchImpl, importPackage = importEngine, beforeChange = async () => {}, now = Date.now,
183
+ home = () => { try { return homedir(); } catch { return ""; } },
184
+ } = {}) {
185
+ const dataDir = () => dataFolder ?? deckDataDir(platform, env);
186
+ const destination = () => join(dataDir(), "engine");
187
+ const machine = `${platform}-${arch}`;
188
+ const packageName = Object.hasOwn(ENGINE_PACKAGE_NAMES, machine) ? ENGINE_PACKAGE_NAMES[machine] : null;
189
+ const supported = !!packageName && !!TARGETS[machine];
190
+ let job = null; // { id, phase, received, total, source, startedAt, controller }
191
+ let last = null; // { id, outcome, code?, step?, version?, at }
192
+ let recoveredAt = null;
193
+
194
+ const downloadOff = () => env.AGENTS_DECK_NO_INSTALL === "1" || env.AGENTS_DECK_NO_DOWNLOAD === "1";
195
+
196
+ /** Why nothing can be installed here at all, or null. */
197
+ const blockedAlways = () => (!supported ? "unsupported" : keys.length === 0 ? "no-keys" : null);
198
+
199
+ const installed = async () => {
200
+ if (keys.length === 0) return null;
201
+ try {
202
+ const found = await verifyEngineInstallation({ directory: destination(), publicKey: keys, platform, arch });
203
+ return { version: found.version, bytes: await folderBytes(destination()) };
204
+ } catch {
205
+ return null;
206
+ }
207
+ };
208
+
209
+ /** Removes what an install cut short left behind, and puts a set-aside
210
+ * engine back where none stands. Only while nothing installs, here or in
211
+ * another deck. Answers whether anything was put right. */
212
+ async function recover() {
213
+ if (job || engineLockHeld()) return false;
214
+ const dir = dataDir();
215
+ if (await lockedElsewhere(dir, now)) return false;
216
+ return withEngineLock(async () => {
217
+ let names;
218
+ try { names = await fs.readdir(dir); } catch { return false; }
219
+ let changed = false;
220
+ for (const name of names) {
221
+ if (/^engine-(?:download|import)-/.test(name)) {
222
+ await fs.rm(join(dir, name), { recursive: true, force: true }).catch(() => {});
223
+ changed = true;
224
+ }
225
+ }
226
+ const aside = names.filter((name) => /^engine-previous-/.test(name));
227
+ if (aside.length) {
228
+ const standing = await fs.lstat(destination()).then(() => true, () => false);
229
+ const stats = await Promise.all(aside.map(async (name) => ({ name, at: (await fs.lstat(join(dir, name)).catch(() => null))?.mtimeMs ?? 0 })));
230
+ stats.sort((a, b) => b.at - a.at);
231
+ let rest = stats;
232
+ if (!standing) {
233
+ await fs.rename(join(dir, stats[0].name), destination()).catch(() => {});
234
+ rest = stats.slice(1);
235
+ }
236
+ for (const { name } of rest) await fs.rm(join(dir, name), { recursive: true, force: true }).catch(() => {});
237
+ changed = true;
238
+ }
239
+ if (changed) recoveredAt = now();
240
+ return changed;
241
+ });
242
+ }
243
+
244
+ /** What the page reads: this machine only, never the network. */
245
+ async function status() {
246
+ await recover().catch(() => {});
247
+ const pin = await enginePin({ platform, arch, ...(root ? { root } : {}) });
248
+ const always = blockedAlways();
249
+ const blocked = always ?? (!pin ? "not-published" : downloadOff() ? "download-disabled" : null);
250
+ const present = await fs.lstat(destination()).then(() => true, () => false);
251
+ return {
252
+ platform: machine,
253
+ app: RUNNING_VERSION ?? null,
254
+ fixPath: fixPathOf(dataDir(), platform, home()),
255
+ supported,
256
+ blocked,
257
+ canInstallFile: always === null,
258
+ installed: await installed(),
259
+ present,
260
+ pinned: pin?.version ?? null,
261
+ job: job ? { id: job.id, phase: job.phase, received: job.received, total: job.total, source: job.source, startedAt: job.startedAt } : null,
262
+ last,
263
+ recovered: recoveredAt !== null && now() - recoveredAt < RECOVERED_SAID_MS,
264
+ elsewhere: !job && await lockedElsewhere(dataDir(), now),
265
+ };
266
+ }
267
+
268
+ /** Runs one job: `getBytes` brings the package tarball (a download or a
269
+ * file), then it is unpacked, checked and installed. */
270
+ function run(source, getBytes, expectVersion) {
271
+ const id = randomBytes(8).toString("hex");
272
+ const controller = new AbortController();
273
+ job = { id, phase: source === "download" ? "downloading" : "verifying", received: 0, total: null, source, startedAt: now(), controller };
274
+ const mine = job;
275
+ (async () => {
276
+ const dir = dataDir();
277
+ let staging = null;
278
+ let locked = false;
279
+ let step = mine.phase === "downloading" ? "download" : "verify";
280
+ try {
281
+ await fs.mkdir(dir, { recursive: true, mode: 0o700 });
282
+ await tightenDataFolder(dir, platform);
283
+ locked = await takeLock(dir, now);
284
+ if (!locked) throw new EngineDownloadError("elsewhere", "install");
285
+ const tgz = await getBytes(mine);
286
+ step = "verify";
287
+ mine.phase = "verifying";
288
+ const files = readPackageTarball(tgz);
289
+ let manifest;
290
+ try { manifest = JSON.parse(files.find((f) => f.name === "package.json").data.toString("utf8")); } catch { manifest = null; }
291
+ // Another platform's package, or not one of ours at all.
292
+ if (manifest?.name !== packageName) {
293
+ const ours = Object.values(ENGINE_PACKAGE_NAMES).includes(manifest?.name);
294
+ throw new EngineDownloadError(ours ? "wrong-machine" : "check-failed", "verify");
295
+ }
296
+ if (expectVersion && manifest.version !== expectVersion) throw new EngineDownloadError("check-failed", "verify");
297
+ staging = await fs.mkdtemp(join(dir, "engine-download-"));
298
+ await fs.chmod(staging, 0o700).catch(() => {});
299
+ await placePackage(staging, packageName, files);
300
+ step = "install";
301
+ mine.phase = "installing";
302
+ await beforeChange();
303
+ const result = await withEngineLock(() => importPackage({ platform, arch, env, keys: [...keys], from: staging, ...(dataFolder ? { dataFolder } : {}) }));
304
+ if (result?.status === "imported" || result?.status === "current") {
305
+ last = { id, outcome: "done", version: (await installed())?.version ?? manifest.version, at: now() };
306
+ } else {
307
+ const code = ["downgrade", "wrong-machine", UNSAFE_FOLDER].includes(result?.reason) ? result.reason : "check-failed";
308
+ last = { id, outcome: "failed", code, step: "verify", version: manifest.version, at: now() };
309
+ }
310
+ } catch (error) {
311
+ const failure = failureOf(error, step);
312
+ // How far a download got, so the page can say where it stopped.
313
+ last = failure.code === "cancelled"
314
+ ? { id, outcome: "cancelled", at: now() }
315
+ : { id, outcome: "failed", ...failure, received: mine.received, total: mine.total, version: expectVersion ?? null, at: now() };
316
+ } finally {
317
+ if (staging) await fs.rm(staging, { recursive: true, force: true }).catch(() => {});
318
+ if (locked) await dropLock(dir);
319
+ if (job === mine) job = null;
320
+ }
321
+ })();
322
+ return id;
323
+ }
324
+
325
+ return Object.freeze({
326
+ status,
327
+ recover,
328
+ /** Starts the download and install of the pinned package, or joins the
329
+ * one running. `{ ok: true, id }`, or `{ ok: false, code }` naming why
330
+ * not: unsupported, no-keys, not-published, download-disabled. */
331
+ async install() {
332
+ if (job) return { ok: true, id: job.id };
333
+ const pin = await enginePin({ platform, arch, ...(root ? { root } : {}) });
334
+ const blocked = blockedAlways() ?? (!pin ? "not-published" : downloadOff() ? "download-disabled" : null);
335
+ if (blocked) return { ok: false, code: blocked };
336
+ const id = run("download", (mine) => fetchEngineTarball({
337
+ name: pin.name, version: pin.version, registry, ...(fetchImpl ? { fetchImpl } : {}), signal: mine.controller.signal,
338
+ onProgress: ({ received, total }) => { mine.received = received; mine.total = total; },
339
+ }), pin.version);
340
+ return { ok: true, id };
341
+ },
342
+ /** Installs a package file the person picked: the same checks as a
343
+ * download, any version the floor allows. */
344
+ async installFile(bytes) {
345
+ if (job) return { ok: false, code: "busy" };
346
+ const blocked = blockedAlways();
347
+ if (blocked) return { ok: false, code: blocked };
348
+ if (!Buffer.isBuffer(bytes) || bytes.length === 0) return { ok: false, code: "check-failed" };
349
+ return { ok: true, id: run("file", async () => bytes, null) };
350
+ },
351
+ /** Cancels a download; past the download there is nothing safe to cut. */
352
+ cancel() {
353
+ if (!job || job.phase !== "downloading") return { ok: false, code: "nothing-to-cancel" };
354
+ job.controller.abort();
355
+ return { ok: true };
356
+ },
357
+ /** Removes the installed engine (the kept floor stays, so a removed
358
+ * engine is never replaced by an older one). */
359
+ async remove() {
360
+ if (job) return { ok: false, code: "busy" };
361
+ const dir = dataDir();
362
+ if (!(await takeLock(dir, now).catch(() => false))) return { ok: false, code: "elsewhere" };
363
+ try {
364
+ await beforeChange();
365
+ await withEngineLock(() => fs.rm(destination(), { recursive: true, force: true }));
366
+ return { ok: true };
367
+ } catch (error) {
368
+ return { ok: false, code: failureOf(error, "remove").code };
369
+ } finally {
370
+ await dropLock(dir);
371
+ }
372
+ },
373
+ /** Whether an installed version is older than the pinned one. */
374
+ olderThanPin(installedVersion, pinned) {
375
+ try { return !!installedVersion && !!pinned && compareVersions(installedVersion, pinned) < 0; } catch { return false; }
376
+ },
377
+ });
378
+ }