castle-web-cli 0.4.213 → 0.4.214

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,41 @@
1
+ import { type CommitReason } from './cloudGit.js';
2
+ export declare const MERGE_CHECK_MS: number;
3
+ export declare const REASK_MS: number;
4
+ export interface ServeGitHooksOptions {
5
+ deckDir: string;
6
+ env?: NodeJS.ProcessEnv;
7
+ /** Whether no task agent is running or waiting to run. */
8
+ boardIdle: () => boolean;
9
+ /** Whether the router is in a turn. */
10
+ routerBusy?: () => boolean;
11
+ /** A line in the chat. */
12
+ addLog: (text: string) => void;
13
+ /** Queue a router turn with an instruction the user does not see as their own message. */
14
+ enqueueInstruction: (text: string) => void;
15
+ /** Injected by tests; defaults to spawning this CLI. Resolves to its exit code. */
16
+ runCommit?: (reason: CommitReason, message: string | undefined) => Promise<number>;
17
+ pollMs?: number;
18
+ /** How often an idle serve checks for a merge still waiting (MERGE_CHECK_MS). */
19
+ mergeCheckMs?: number;
20
+ now?: () => number;
21
+ }
22
+ export interface ServeGitHooks {
23
+ /** The router's turn (and any follow-up it drained) is over. */
24
+ routerSettled(): void;
25
+ /** A task agent started. */
26
+ taskStarted(): void;
27
+ /** A task agent finished; `done` when it succeeded. */
28
+ taskFinished(title: string, done: boolean): void;
29
+ /** Check for markers now (the poll does this on its own). */
30
+ checkConflict(): void;
31
+ /** Resolves when no commit is running or queued. For tests. */
32
+ idle(): Promise<void>;
33
+ stop(): void;
34
+ }
35
+ /** Run this CLI as a child and collect its exit code and (the tail of) its output. */
36
+ export declare function runCastleWeb(args: string[], cwd: string, env?: NodeJS.ProcessEnv, timeoutMs?: number, graceMs?: number): Promise<{
37
+ code: number;
38
+ output: string;
39
+ }>;
40
+ /** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
41
+ export declare function createServeGitHooks(opts: ServeGitHooksOptions): ServeGitHooks | null;
@@ -0,0 +1,318 @@
1
+ import { spawn } from 'child_process';
2
+ import * as fs from 'fs';
3
+ import * as path from 'path';
4
+ import { fileURLToPath } from 'url';
5
+ import { AGENT_MARKER_FILES, cloudGitModeAsync, CONFLICT_MARKER_FILE, DEADLINE_ENV, EXIT_CONFLICT, EXIT_NOT_ENABLED, mergeInProgress, readLeavePending, readMergeState, setDeckBusy, } from './cloudGit.js';
6
+ // The serve's half of git in the cloud sandbox (castle-sandboxes docs/git-remotes-phase2.md):
7
+ // - `commit --reason turn` when the router settles with the task board idle,
8
+ // - `commit --reason task` when the task board goes idle,
9
+ // - the busy note (cloudGit's BUSY_FILE) while a task agent or the router is working, which
10
+ // keeps every other commit and sync from merging the remote into files mid-task,
11
+ // - and the markers `git sync` and `git attach` leave (a merge conflict, a cloud copy
12
+ // replaced by the remote's version) become router turns. A merge still unresolved gets
13
+ // another turn -- when a later commit is refused, or on its own every MERGE_CHECK_MS while
14
+ // the deck is idle -- at most every REASK_MS.
15
+ //
16
+ // Commits run as a child `castle-web commit`, never in-process: a commit ends with a fetch
17
+ // and a push, which must not block the serve's event loop, and the CLI's own lock already
18
+ // serializes it against the sandbox agent's commits.
19
+ const CLI_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.js');
20
+ const COMMIT_TIMEOUT_MS = 5 * 60_000;
21
+ // After the time limit a child gets SIGTERM, and stops at its next safe point (never inside a
22
+ // git command, and it skips packing once asked); SIGKILL follows only if it does not. The
23
+ // child is told the moment (DEADLINE_ENV, a margin short of the SIGKILL) and caps every git
24
+ // step's own timeout by it, so no step -- a push may take two minutes -- outlives the grace.
25
+ const KILL_GRACE_MS = 60_000;
26
+ const DEADLINE_MARGIN_MS = 5_000;
27
+ const CONFLICT_POLL_MS = 1500;
28
+ // How often an idle serve looks for a merge still waiting on the agent (asking again is
29
+ // rate-limited by REASK_MS on top of this).
30
+ export const MERGE_CHECK_MS = 2 * 60_000;
31
+ const MAX_TITLES_IN_MESSAGE = 3;
32
+ export const REASK_MS = 10 * 60_000;
33
+ const CONFLICT_NOTICE = 'Changes pushed from another computer conflicted with this deck; the agent is resolving them.';
34
+ /** Run this CLI as a child and collect its exit code and (the tail of) its output. */
35
+ export function runCastleWeb(args, cwd, env = process.env, timeoutMs = COMMIT_TIMEOUT_MS, graceMs = KILL_GRACE_MS) {
36
+ return new Promise((resolve) => {
37
+ const deadline = Date.now() + timeoutMs + graceMs - Math.min(DEADLINE_MARGIN_MS, graceMs / 4);
38
+ // Its own process group, so the SIGKILL reaches every git it started: an orphaned git
39
+ // still writing after the deck lock is taken over would race the next holder.
40
+ const child = spawn(process.execPath, [CLI_ENTRY, ...args], {
41
+ cwd,
42
+ env: { ...env, [DEADLINE_ENV]: String(deadline) },
43
+ stdio: ['ignore', 'pipe', 'pipe'],
44
+ detached: true,
45
+ });
46
+ const killGroup = () => {
47
+ try {
48
+ if (child.pid)
49
+ process.kill(-child.pid, 'SIGKILL');
50
+ }
51
+ catch {
52
+ /* already gone */
53
+ }
54
+ };
55
+ let output = '';
56
+ const collect = (chunk) => {
57
+ output = (output + chunk.toString('utf-8')).slice(-4000);
58
+ };
59
+ child.stdout.on('data', collect);
60
+ child.stderr.on('data', collect);
61
+ let hardKill = null;
62
+ let timedOut = false;
63
+ const timer = setTimeout(() => {
64
+ timedOut = true;
65
+ child.kill('SIGTERM');
66
+ hardKill = setTimeout(killGroup, graceMs);
67
+ hardKill.unref();
68
+ }, timeoutMs);
69
+ timer.unref();
70
+ let settled = false;
71
+ const finish = (code) => {
72
+ if (settled)
73
+ return;
74
+ settled = true;
75
+ clearTimeout(timer);
76
+ if (hardKill)
77
+ clearTimeout(hardKill);
78
+ resolve({ code, output: output.trim() });
79
+ };
80
+ child.on('error', (err) => {
81
+ output += String(err);
82
+ finish(1);
83
+ });
84
+ // Stopped by the time limit: whatever it left running in its group (a git a step timeout
85
+ // gave up on, a hook) goes too -- which also closes the output pipes they inherited.
86
+ child.on('exit', (code) => {
87
+ if (timedOut || code === null)
88
+ killGroup();
89
+ });
90
+ child.on('close', (code) => finish(code ?? 1));
91
+ });
92
+ }
93
+ function spawnCommit(deckDir, env) {
94
+ return async (reason, message) => {
95
+ const args = ['commit', '--reason', reason, '--dir', deckDir];
96
+ if (message)
97
+ args.push('-m', message);
98
+ const { code, output } = await runCastleWeb(args, deckDir, env);
99
+ if (code !== EXIT_NOT_ENABLED) {
100
+ const log = code === 0 || code === EXIT_CONFLICT ? console.log : console.error;
101
+ log(`[git] commit --reason ${reason} exited ${code}: ${output}`);
102
+ }
103
+ return code;
104
+ };
105
+ }
106
+ function taskMessage(titles) {
107
+ if (titles.length === 0)
108
+ return undefined;
109
+ const shown = titles.slice(0, MAX_TITLES_IN_MESSAGE).join('; ');
110
+ const more = titles.length > MAX_TITLES_IN_MESSAGE ? ` (+${titles.length - MAX_TITLES_IN_MESSAGE} more)` : '';
111
+ return `${titles.length === 1 ? 'Task' : 'Tasks'}: ${shown}${more}`;
112
+ }
113
+ /** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
114
+ export function createServeGitHooks(opts) {
115
+ const env = opts.env ?? process.env;
116
+ if (env.CASTLE_GIT !== 'on')
117
+ return null;
118
+ const runCommit = opts.runCommit ?? spawnCommit(opts.deckDir, env);
119
+ const now = opts.now ?? (() => Date.now());
120
+ let running = null;
121
+ let queued = null;
122
+ const finishedTitles = [];
123
+ // A resolver turn is in flight from when its instruction is queued until the router and the
124
+ // board are both idle again.
125
+ let resolverInFlight = false;
126
+ let lastRaisedAt = Number.NEGATIVE_INFINITY;
127
+ let lastBusy = null;
128
+ let lastMergeCheckAt = now();
129
+ function busyNow() {
130
+ return !opts.boardIdle() || (opts.routerBusy?.() ?? false);
131
+ }
132
+ function refreshBusy() {
133
+ const busy = busyNow();
134
+ if (busy === lastBusy)
135
+ return;
136
+ try {
137
+ setDeckBusy(opts.deckDir, busy);
138
+ lastBusy = busy;
139
+ }
140
+ catch (err) {
141
+ console.error(`[git] could not update the busy note: ${String(err)}`);
142
+ }
143
+ }
144
+ function drain() {
145
+ if (running || !queued)
146
+ return;
147
+ const next = queued;
148
+ queued = null;
149
+ running = (async () => {
150
+ // Past this first await, `running` holds this promise: the finally below clears it
151
+ // even when the commit is skipped without waiting on anything.
152
+ await Promise.resolve();
153
+ let code = null;
154
+ try {
155
+ // Checked again at the last moment: a task may have started since this was queued,
156
+ // and its files are not committed half-done or merged into.
157
+ if (!opts.boardIdle()) {
158
+ finishedTitles.unshift(...next.titles);
159
+ return;
160
+ }
161
+ refreshBusy();
162
+ if (!(await cloudGitModeAsync(opts.deckDir, env)))
163
+ return;
164
+ code = await runCommit(next.reason, taskMessage(next.titles));
165
+ }
166
+ catch (err) {
167
+ console.error(`[git] commit --reason ${next.reason} failed: ${String(err)}`);
168
+ }
169
+ finally {
170
+ running = null;
171
+ checkConflict();
172
+ if (code === EXIT_CONFLICT)
173
+ reraiseUnresolvedMerge();
174
+ drain();
175
+ }
176
+ })();
177
+ }
178
+ // One commit at a time, and at most one waiting: a waiting one commits everything dirty
179
+ // when it runs, so a second request adds nothing but its message. A task commit's message
180
+ // wins over a turn's, since it names the work.
181
+ function request(reason, titles = []) {
182
+ if (queued && queued.reason === 'task' && reason === 'turn')
183
+ return;
184
+ if (queued)
185
+ titles = [...queued.titles, ...titles];
186
+ queued = { reason, titles };
187
+ drain();
188
+ }
189
+ function consumeMarker(rel) {
190
+ const file = path.join(opts.deckDir, rel);
191
+ let report;
192
+ try {
193
+ report = JSON.parse(fs.readFileSync(file, 'utf-8'));
194
+ }
195
+ catch (e) {
196
+ if (e.code !== 'ENOENT')
197
+ fs.rmSync(file, { force: true });
198
+ return;
199
+ }
200
+ // Consumed first, so a throw below can never turn one marker into a loop of turns.
201
+ fs.rmSync(file, { force: true });
202
+ if (typeof report.instruction !== 'string' || !report.instruction)
203
+ return;
204
+ opts.addLog(typeof report.notice === 'string' && report.notice ? report.notice : CONFLICT_NOTICE);
205
+ if (rel === CONFLICT_MARKER_FILE) {
206
+ resolverInFlight = true;
207
+ lastRaisedAt = now();
208
+ }
209
+ opts.enqueueInstruction(report.instruction);
210
+ }
211
+ function checkConflict() {
212
+ for (const rel of AGENT_MARKER_FILES)
213
+ consumeMarker(rel);
214
+ }
215
+ // A commit was refused because a merge still waits, and no resolver is working on it: ask
216
+ // again, at most every REASK_MS, so a merge an earlier turn left unresolved is not stuck.
217
+ function reraiseUnresolvedMerge() {
218
+ if (resolverInFlight || now() - lastRaisedAt < REASK_MS || !mergeInProgress(opts.deckDir))
219
+ return;
220
+ const state = readMergeState(opts.deckDir);
221
+ const leave = readLeavePending(opts.deckDir);
222
+ const instruction = [
223
+ '[Castle] The merge with changes from another computer is still not concluded, so no commit can land until it is.',
224
+ ...(leave
225
+ ? [
226
+ `The user left the deck at ${leave.at} with edits that could not be committed because of it${leave.paths.length ? ` (${leave.paths.slice(0, 20).join(', ')}${leave.paths.length > 20 ? ', ...' : ''})` : ''}. They are still on disk; concluding the merge commits them too, so keep them.`,
227
+ ]
228
+ : []),
229
+ state?.instruction ??
230
+ 'Spawn one task agent to remove every conflict marker (<<<<<<< / ||||||| / ======= / >>>>>>>) from the conflicted files, preferring the other computer\'s side, and finish with `castle-web commit --resolve -m "Merge changes from another computer"`. Never force-push.',
231
+ ].join('\n');
232
+ try {
233
+ const file = path.join(opts.deckDir, CONFLICT_MARKER_FILE);
234
+ fs.mkdirSync(path.dirname(file), { recursive: true });
235
+ fs.writeFileSync(file, JSON.stringify({
236
+ instruction,
237
+ notice: 'A merge with changes from another computer is still unresolved; the agent is taking another look.',
238
+ }));
239
+ }
240
+ catch (err) {
241
+ console.error(`[git] could not queue the unresolved merge again: ${String(err)}`);
242
+ return;
243
+ }
244
+ checkConflict();
245
+ }
246
+ // Even with no commit to be refused (an idle deck), a merge left unresolved is raised again.
247
+ function checkWaitingMerge() {
248
+ if (now() - lastMergeCheckAt < (opts.mergeCheckMs ?? MERGE_CHECK_MS))
249
+ return;
250
+ lastMergeCheckAt = now();
251
+ if (running || busyNow())
252
+ return;
253
+ try {
254
+ reraiseUnresolvedMerge();
255
+ }
256
+ catch (err) {
257
+ console.error(`[git] could not check for a waiting merge: ${String(err)}`);
258
+ }
259
+ }
260
+ const poll = setInterval(() => {
261
+ refreshBusy();
262
+ checkConflict();
263
+ checkWaitingMerge();
264
+ }, opts.pollMs ?? CONFLICT_POLL_MS);
265
+ poll.unref();
266
+ // A marker left while the serve was down. Not synchronously: the caller wires the router
267
+ // queue up after creating these hooks.
268
+ setImmediate(() => {
269
+ refreshBusy();
270
+ checkConflict();
271
+ });
272
+ return {
273
+ routerSettled() {
274
+ refreshBusy();
275
+ // Mid-task, the task hook commits when the board empties; the router never commits
276
+ // work a task agent is still doing.
277
+ if (!opts.boardIdle())
278
+ return;
279
+ // The router and the board both idle: whatever a resolver turn was going to do, it did.
280
+ resolverInFlight = false;
281
+ request('turn');
282
+ },
283
+ taskStarted() {
284
+ refreshBusy();
285
+ },
286
+ taskFinished(title, done) {
287
+ if (done && title)
288
+ finishedTitles.push(title);
289
+ // After the scheduler's sweep: a finished task can start (or block) the next one.
290
+ setImmediate(() => {
291
+ refreshBusy();
292
+ if (!opts.boardIdle())
293
+ return;
294
+ if (!opts.routerBusy?.())
295
+ resolverInFlight = false;
296
+ request('task', finishedTitles.splice(0));
297
+ });
298
+ },
299
+ checkConflict,
300
+ async idle() {
301
+ while (running || queued) {
302
+ if (running)
303
+ await running;
304
+ else
305
+ drain();
306
+ }
307
+ },
308
+ stop() {
309
+ clearInterval(poll);
310
+ try {
311
+ setDeckBusy(opts.deckDir, false);
312
+ }
313
+ catch {
314
+ /* best effort */
315
+ }
316
+ },
317
+ };
318
+ }
@@ -33,7 +33,10 @@ export interface GitInitDeps {
33
33
  warn(message: string): void;
34
34
  }
35
35
  export declare function isOnPath(name: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
36
- export declare function runGit(args: string[], cwd: string): GitResult;
36
+ export declare function runGit(args: string[], cwd: string, opts?: {
37
+ env?: NodeJS.ProcessEnv;
38
+ timeoutMs?: number;
39
+ }): GitResult;
37
40
  export declare function cloudKitFor(castleJson: Record<string, unknown> | null): CloudDeckKit;
38
41
  export declare const PENDING_INIT_FILE: string;
39
42
  export interface GitInitResult {
package/dist/gitRemote.js CHANGED
@@ -92,13 +92,15 @@ export function isOnPath(name, env = process.env, platform = process.platform) {
92
92
  }
93
93
  return false;
94
94
  }
95
- export function runGit(args, cwd) {
95
+ export function runGit(args, cwd, opts = {}) {
96
96
  // Force git's untranslated messages: callers match stderr text (e.g. "not a git repository"),
97
97
  // which a localized git would print in another language.
98
98
  const result = spawnSync('git', args, {
99
99
  cwd,
100
100
  encoding: 'utf-8',
101
- env: { ...process.env, LC_ALL: 'C', LANGUAGE: 'C' },
101
+ env: { ...(opts.env ?? process.env), LC_ALL: 'C', LANGUAGE: 'C' },
102
+ timeout: opts.timeoutMs,
103
+ maxBuffer: 64 * 1024 * 1024,
102
104
  });
103
105
  return {
104
106
  status: result.status,
package/dist/ide.js CHANGED
@@ -28,6 +28,8 @@ import { recordParamsWrite } from './paramsWrites.js';
28
28
  import { applyDeckWrite } from './paramsTunes.js';
29
29
  import { PARAMS_DECLARATION, PARAMS_EXTS } from './paramsFile.js';
30
30
  import { applyVersionRestore, createVersion, NotOnThisLine, pendingChanges, UnsavedChanges, versionSummaries, } from './versions.js';
31
+ import { cloudGitModeAsync, EXIT_CONFLICT, gitVersionHistory } from './cloudGit.js';
32
+ import { runCastleWeb } from './cloudGitServe.js';
31
33
  import { envForUserShell, installCliShims } from './byo-auth.js';
32
34
  import { playCoverOffered } from './playCoverGate.js';
33
35
  const HeadlessTerminal = headlessPkg.Terminal;
@@ -479,7 +481,13 @@ function withJsonBody(req, res, handler) {
479
481
  catch {
480
482
  return sendJson(res, 400, { error: 'Invalid JSON body.' });
481
483
  }
482
- handler(body);
484
+ try {
485
+ await handler(body);
486
+ }
487
+ catch (e) {
488
+ if (!res.headersSent)
489
+ sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
490
+ }
483
491
  })();
484
492
  }
485
493
  // The shape every single-path mutation handler starts with: parse the body,
@@ -499,8 +507,15 @@ function sendFailure(res, action, rel, err) {
499
507
  // The version panel's three calls, on the same store the `save-version` /
500
508
  // `restore-version` commands use -- the editor is another way to run them, not
501
509
  // a second history.
502
- function handleVersionsList(deckDir, res) {
510
+ async function handleVersionsList(deckDir, res) {
503
511
  try {
512
+ if (await cloudGitModeAsync(deckDir)) {
513
+ // With git on, the history is the git log and "pending" is git status. The old
514
+ // store's versions stay listed as older versions: readable, never imported.
515
+ const { versions, pending } = await gitVersionHistory(deckDir);
516
+ const older = versionSummaries(deckDir).map((v) => ({ ...v, later: false, older: true }));
517
+ return sendJson(res, 200, { git: true, versions: [...versions, ...older], pending });
518
+ }
504
519
  // The history and what is outstanding against it, together: the panel shows
505
520
  // them as one picture, and two calls could disagree about the moment.
506
521
  sendJson(res, 200, { versions: versionSummaries(deckDir), pending: pendingChanges(deckDir) });
@@ -512,8 +527,14 @@ function handleVersionsList(deckDir, res) {
512
527
  // Saves everything dirty: the panel has no path selection, so partial saves
513
528
  // stay a CLI and agent thing.
514
529
  function handleVersionSave(deckDir, req, res) {
515
- withJsonBody(req, res, (body) => {
530
+ withJsonBody(req, res, async (body) => {
516
531
  const message = typeof body.message === 'string' ? body.message : '';
532
+ if (await cloudGitModeAsync(deckDir)) {
533
+ await gitPanelAction(res, ['commit', '--reason', 'manual', '-m', message, '--dir', deckDir], deckDir, (output) => {
534
+ sendJson(res, 200, { ok: true, id: /^Committed ([0-9a-f]{40})$/m.exec(output)?.[1] ?? null });
535
+ });
536
+ return;
537
+ }
517
538
  try {
518
539
  const { version } = createVersion(deckDir, { message });
519
540
  sendJson(res, 200, { ok: true, id: version?.id ?? null });
@@ -527,10 +548,21 @@ function handleVersionSave(deckDir, req, res) {
527
548
  // naming the files, which the panel shows -- saving a version first is the fix,
528
549
  // and it is one click away in the same panel.
529
550
  function handleVersionRestore(deckDir, req, res, restart) {
530
- withJsonBody(req, res, (body) => {
551
+ withJsonBody(req, res, async (body) => {
531
552
  if (typeof body.id !== 'string' || !body.id) {
532
553
  return sendJson(res, 400, { error: 'Missing version id.' });
533
554
  }
555
+ if (/^[0-9a-f]{7,40}$/.test(body.id) && (await cloudGitModeAsync(deckDir))) {
556
+ // A new commit restoring that tree: nothing is rewritten and pending work is committed
557
+ // first, so there is nothing to refuse over.
558
+ await gitPanelAction(res, ['restore-version', body.id, '--dir', deckDir], deckDir, (output) => {
559
+ const restored = /^Restored /m.test(output);
560
+ if (restored)
561
+ setImmediate(() => restart?.());
562
+ sendJson(res, 200, { ok: true, restored: restored ? 1 : 0, offChain: 0, alreadyThere: !restored });
563
+ });
564
+ return;
565
+ }
534
566
  try {
535
567
  const outcome = applyVersionRestore(deckDir, body.id);
536
568
  // A restore rewrites the deck wholesale, so every panel rendering it is
@@ -562,6 +594,14 @@ function handleVersionRestore(deckDir, req, res, restart) {
562
594
  }
563
595
  });
564
596
  }
597
+ // The panel's git actions run the CLI, which holds the deck's commit lock and pushes; a
598
+ // conflict still waiting on the agent is a refusal (409), anything else a fault.
599
+ async function gitPanelAction(res, args, deckDir, onSuccess) {
600
+ const { code, output } = await runCastleWeb(args, deckDir);
601
+ if (code === 0)
602
+ return onSuccess(output);
603
+ sendJson(res, code === EXIT_CONFLICT ? 409 : 500, { error: output || `castle-web ${args[0]} exited ${code}` });
604
+ }
565
605
  // `ifMatch` is optional and unchanged writes behave as they always did: a
566
606
  // client that names the text it edited gets a 409 instead of silently writing
567
607
  // over whatever landed in between, and the Parameters panel is the one that
@@ -931,7 +971,7 @@ function handleFilesApi(deckDir, req, res, reqPath, restart, invalidate, tuneLed
931
971
  return true;
932
972
  }
933
973
  if (action === 'versions') {
934
- handleVersionsList(deckDir, res);
974
+ void handleVersionsList(deckDir, res);
935
975
  return true;
936
976
  }
937
977
  if (action === 'save-version') {