castle-web-cli 0.4.215 → 0.4.216

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.
package/dist/api.d.ts CHANGED
@@ -188,4 +188,18 @@ export type GitEnvironment = 'staging' | 'production';
188
188
  export declare function ensureGitRepo(deckId: string, environment: GitEnvironment): Promise<{
189
189
  remoteUrl: string;
190
190
  }>;
191
+ export interface GitMirrorBundle {
192
+ url: string;
193
+ /** Null for a bundle an older mirror run listed without it: then not checked. */
194
+ bytes: number | null;
195
+ sha256: string | null;
196
+ }
197
+ export interface GitMirrorState {
198
+ /** main as the deck's S3 mirror last recorded it; null before the first mirror. */
199
+ mainSha: string | null;
200
+ mirroredAt: string | null;
201
+ /** The mirror chain in apply order, as presigned GETs; only asked for with includeBundles. */
202
+ bundles: GitMirrorBundle[];
203
+ }
204
+ export declare function gitMirrorState(deckId: string, includeBundles: boolean, timeoutMs: number): Promise<GitMirrorState | null>;
191
205
  export {};
package/dist/api.js CHANGED
@@ -332,3 +332,34 @@ export async function ensureGitRepo(deckId, environment) {
332
332
  }
333
333
  return { remoteUrl: result.remoteUrl };
334
334
  }
335
+ // What the deck's S3 git mirror holds (castle-sandboxes docs/git-remotes-snapshot-without-history.md
336
+ // §4). Sandbox-scoped: the cloud CLI asks it to advance its snapshot floor and, on a cold
337
+ // resume, for the chain of bundles to rebuild history from when code.storage is unreachable.
338
+ // No `environment` argument: from a sandbox, ghost uses the sandbox's own. A deck with no git
339
+ // repo answers with a GIT_REPO_NOT_FOUND error; one not mirrored yet, with nulls and [].
340
+ export async function gitMirrorState(deckId, includeBundles, timeoutMs) {
341
+ const data = await graphql(`query($deckId: ID!, $includeBundles: Boolean) {
342
+ gitMirrorState(deckId: $deckId, includeBundles: $includeBundles) {
343
+ mainSha
344
+ mirroredAt
345
+ bundles { url bytes sha256 }
346
+ }
347
+ }`, { deckId, includeBundles }, { timeoutMs });
348
+ handleAPIError(data);
349
+ const result = pickData(data, 'gitMirrorState');
350
+ if (!result)
351
+ return null;
352
+ const bundles = Array.isArray(result.bundles) ? result.bundles : [];
353
+ return {
354
+ mainSha: typeof result.mainSha === 'string' ? result.mainSha : null,
355
+ mirroredAt: typeof result.mirroredAt === 'string' ? result.mirroredAt : null,
356
+ // In apply order (the full base first); an entry without a URL could not be applied at all.
357
+ bundles: bundles
358
+ .filter((b) => !!b && typeof b.url === 'string')
359
+ .map((b) => ({
360
+ url: b.url,
361
+ bytes: typeof b.bytes === 'number' ? b.bytes : null,
362
+ sha256: typeof b.sha256 === 'string' ? b.sha256 : null,
363
+ })),
364
+ };
365
+ }
@@ -1,4 +1,5 @@
1
1
  import { type GitResult } from './gitRemote.js';
2
+ import type { GitMirrorState } from './api.js';
2
3
  export type CommitReason = 'turn' | 'task' | 'leave' | 'manual' | 'sync';
3
4
  export declare const COMMIT_REASONS: readonly CommitReason[];
4
5
  export declare const AGENT_TRAILER_KEY = "Castle-Agent";
@@ -8,6 +9,13 @@ export declare const EXIT_ERROR = 1;
8
9
  export declare const EXIT_NOT_ENABLED = 2;
9
10
  /** A merge with the remote is waiting on the agent; nothing was committed. */
10
11
  export declare const EXIT_CONFLICT = 3;
12
+ /**
13
+ * GIT_HISTORY_UNAVAILABLE: the deck's refs name commits whose objects are gone (a cold resume,
14
+ * whose checkpoint carries no `.git/objects`) and neither the Castle remote, the S3 mirror nor
15
+ * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
16
+ */
17
+ export declare const EXIT_HISTORY_UNAVAILABLE = 4;
18
+ export declare const HISTORY_UNAVAILABLE_CODE = "GIT_HISTORY_UNAVAILABLE";
11
19
  export declare class CloudGitError extends Error {
12
20
  readonly exitCode: number;
13
21
  constructor(message: string, exitCode?: number);
@@ -20,6 +28,11 @@ export declare const DECK_LOCK_FILE: string;
20
28
  export declare const CONFLICT_MARKER_FILE: string;
21
29
  /** Written by `git attach` when it took the remote's version over a differing cloud copy. */
22
30
  export declare const ADOPTED_MARKER_FILE: string;
31
+ /** Written when a rehydrate gave up local commits nobody had (see recoverLostHistory). */
32
+ export declare const HISTORY_RECOVERED_FILE: string;
33
+ export declare const RECOVERED_COMMIT_MESSAGE = "Edits restored after lost history";
34
+ /** Written with it, once: the notice and instruction the serve turns into an agent turn. */
35
+ export declare const HISTORY_LOST_MARKER_FILE: string;
23
36
  /** Every marker the serve turns into an agent turn. */
24
37
  export declare const AGENT_MARKER_FILES: readonly string[];
25
38
  /** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
@@ -46,6 +59,17 @@ export interface GitRunOptions {
46
59
  timeoutMs?: number;
47
60
  /** A scratch index instead of the repo's own. */
48
61
  indexFile?: string;
62
+ /** Extra environment for this one command (on top of cloudGitEnv's). */
63
+ env?: Record<string, string>;
64
+ /** Written to the command's stdin. */
65
+ input?: string;
66
+ }
67
+ export interface DownloadOptions {
68
+ timeoutMs: number;
69
+ /** The exact size the file must have (the download stops once past it); null: not checked. */
70
+ bytes: number | null;
71
+ /** Hex SHA-256 the file must have; null: not checked. */
72
+ sha256: string | null;
49
73
  }
50
74
  export interface CloudGitDeps {
51
75
  git: (args: string[], cwd: string, opts?: GitRunOptions) => GitResult;
@@ -64,11 +88,26 @@ export interface CloudGitDeps {
64
88
  isAlive: (pid: number) => boolean;
65
89
  /** Whether this command has been asked to stop (SIGTERM). Lets pending signals in first. */
66
90
  stopRequested: () => Promise<boolean>;
91
+ /** Ghost's `gitMirrorState` for a deck. Absent: never asked (the floor stays castle/main). */
92
+ mirrorState?: (deckId: string, opts: {
93
+ includeBundles: boolean;
94
+ timeoutMs: number;
95
+ }) => Promise<GitMirrorState | null>;
96
+ /** Fetches one mirror bundle to `dest`, verifying its size and sha256; throws otherwise. */
97
+ download?: (url: string, dest: string, opts: DownloadOptions) => Promise<void>;
98
+ /** Starts a detached `castle-web git rehydrate` for a deck (spawnDetachedRehydrate). */
99
+ spawnRehydrate?: (dir: string, env: NodeJS.ProcessEnv) => void;
67
100
  }
68
101
  /** A process's start time (in clock ticks since boot, from /proc), which tells a reused pid apart. */
69
102
  export declare function processStartTime(pid: number): string | null;
70
103
  export declare function cloudGitRunner(baseEnv?: NodeJS.ProcessEnv): CloudGitDeps['git'];
71
- export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI']): CloudGitDeps;
104
+ /**
105
+ * Downloads `url` to `dest`, checking its exact size and SHA-256 where the mirror recorded them
106
+ * (a bundle listed by an older mirror run has neither); removes `dest` on any failure.
107
+ */
108
+ export declare const UNSIZED_DOWNLOAD_MAX_BYTES: number;
109
+ export declare function downloadVerified(url: string, dest: string, opts: DownloadOptions): Promise<void>;
110
+ export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI'], extra?: Pick<CloudGitDeps, 'mirrorState'>): CloudGitDeps;
72
111
  interface Ctx {
73
112
  dir: string;
74
113
  deps: CloudGitDeps;
@@ -76,7 +115,10 @@ interface Ctx {
76
115
  /** Epoch ms by which the command must be done (DEADLINE_ENV); none when not set. */
77
116
  deadline?: number;
78
117
  }
118
+ export declare function repairGitSkeleton(dir: string): void;
79
119
  export declare function mergeInProgress(dir: string): boolean;
120
+ /** A merge (or a recovered one's conflict markers) waits on the agent: only `--resolve` commits. */
121
+ export declare function mergeWaiting(dir: string): boolean;
80
122
  export declare function isSandboxEnv(env: NodeJS.ProcessEnv): boolean;
81
123
  /** Whether `git attach` set this deck up: its own `.git` directory, marked in its config. */
82
124
  export declare function isAttached(dir: string, git?: CloudGitDeps['git']): boolean;
@@ -135,6 +177,11 @@ export interface MergeState {
135
177
  mergeHead: string;
136
178
  files: ConflictedFile[];
137
179
  instruction: string;
180
+ /**
181
+ * Left by a rehydrate that gave up lost history mid-merge: no MERGE_HEAD any more, but the
182
+ * files still have markers, and the next commit must be a `--resolve`.
183
+ */
184
+ recovered?: boolean;
138
185
  }
139
186
  export declare function readMergeState(dir: string): MergeState | null;
140
187
  export interface ConflictReport {
@@ -163,6 +210,63 @@ export interface CommitOutcome {
163
210
  sha: string | null;
164
211
  }
165
212
  export declare function packIfNeeded(ctx: Ctx): boolean;
213
+ /** Every object the deck's local state reaches that the S3 mirror is not known to have. */
214
+ export declare const SNAPSHOT_BUNDLE_FILE: string;
215
+ export declare const SNAPSHOT_KEY_FILE: string;
216
+ /** main as ghost last reported the deck's S3 mirror had it: the bundle's floor. Only moves forward. */
217
+ export declare const MIRRORED_REF = "refs/castle/mirrored";
218
+ /**
219
+ * One rehydrate at a time. Not named `*.lock`: clearStaleGitLocks removes those at the top of
220
+ * .git after a minute, and a rehydrate runs far longer than that.
221
+ */
222
+ export declare const REHYDRATE_LOCK_FILE: string;
223
+ /** Failed rehydrates and when the next background one may start (exponential backoff). */
224
+ export declare const REHYDRATE_STATE_FILE: string;
225
+ /** Where a background rehydrate writes its output. */
226
+ export declare const REHYDRATE_LOG_FILE: string;
227
+ /** `off` stops commands from starting a background rehydrate (tests). */
228
+ export declare const BACKGROUND_REHYDRATE_ENV = "CASTLE_GIT_BACKGROUND_REHYDRATE";
229
+ export declare const SNAPSHOT_CAP_BYTES: number;
230
+ /** A smaller cap, for tests. */
231
+ export declare const SNAPSHOT_CAP_ENV = "CASTLE_GIT_SNAPSHOT_CAP_BYTES";
232
+ /** Whether the deck's history is being rebuilt: refs name objects that are not here. */
233
+ export declare function historyLoading(dir: string, git?: CloudGitDeps['git']): boolean;
234
+ interface RehydrateState {
235
+ failures: number;
236
+ lastFailureAt: string;
237
+ nextAttemptAt: number;
238
+ lastError: string;
239
+ /** The container (and its boot) the failures happened in: another's backoff does not apply. */
240
+ host: string;
241
+ bootId: string | null;
242
+ }
243
+ /** This container's rehydrate backoff; state another host (or boot) wrote does not count. */
244
+ export declare function readRehydrateState(dir: string, host?: string): RehydrateState | null;
245
+ /** Starts `castle-web git rehydrate` for the deck in its own session, its output to REHYDRATE_LOG_FILE. */
246
+ export declare function spawnDetachedRehydrate(dir: string, env: NodeJS.ProcessEnv): void;
247
+ export interface HistoryRecovered {
248
+ at: string;
249
+ lost: {
250
+ ref: string;
251
+ sha: string;
252
+ }[];
253
+ /** Where main now points: the checkpoint's castle/main, or the remote's main as a fallback. */
254
+ newHead: string | null;
255
+ /** The lost tips the snapshot had deliberately left out (over the cap). */
256
+ skippedOverCap: string[];
257
+ /** A merge was in progress; its conflicted files wait for the agent (castle-merge.json). */
258
+ conflict: boolean;
259
+ keptBundle: string | null;
260
+ reason: string;
261
+ tried: string[];
262
+ /** Whether the commit of the kept files has landed. */
263
+ committed: boolean;
264
+ }
265
+ export declare function recoveredConflictInstruction(files: string[] | null): string;
266
+ export declare function historyLostInstruction(lost: string[]): string;
267
+ export type RehydrateOutcome = 'complete' | 'rebuilt';
268
+ /** `castle-web git rehydrate --dir <deck>`: rebuild a cold-resumed deck's git history. */
269
+ export declare function cloudRehydrate(dir: string, deps: CloudGitDeps): Promise<RehydrateOutcome>;
166
270
  export interface LeavePending {
167
271
  at: string;
168
272
  /** What `git status` showed as changed when the user left. */
@@ -180,6 +284,12 @@ export interface SyncOutcome {
180
284
  merge: 'none' | 'fast-forward' | 'merged' | 'conflict' | 'seeded' | 'deferred';
181
285
  pushed: boolean;
182
286
  }
287
+ /**
288
+ * The remote's main as local main last took it in: what a recovery may start the deck again
289
+ * from. castle/main can be ahead of it -- fetched, but its merge deferred while tasks were busy,
290
+ * or refused -- and starting from castle/main would revert whatever came in with it.
291
+ */
292
+ export declare const INTEGRATED_REF = "refs/castle/integrated";
183
293
  export interface DraftDifference {
184
294
  path: string;
185
295
  /** How the cloud copy differs from castle/main: `deleted` means it lacks a file the remote has. */
@@ -255,6 +365,7 @@ export declare function gitVersionHistory(dir: string, env?: NodeJS.ProcessEnv):
255
365
  path: string;
256
366
  kind: GitChangeKind;
257
367
  }[];
368
+ loading?: boolean;
258
369
  }>;
259
370
  export declare function printGitLog(dir: string, from?: string, git?: CloudGitDeps['git']): void;
260
371
  export declare function printGitShow(dir: string, target: string, git?: CloudGitDeps['git']): void;