castle-web-cli 0.4.228 → 0.4.229

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.
@@ -15,6 +15,11 @@ export declare const EXIT_CONFLICT = 3;
15
15
  * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
16
16
  */
17
17
  export declare const EXIT_HISTORY_UNAVAILABLE = 4;
18
+ /**
19
+ * A first attach outran the caller's deadline and carries on in the background (see
20
+ * attachThroughChild). Not attached yet; the deck works without git until it is.
21
+ */
22
+ export declare const EXIT_ATTACH_CONTINUING = 5;
18
23
  export declare const HISTORY_UNAVAILABLE_CODE = "GIT_HISTORY_UNAVAILABLE";
19
24
  export declare class CloudGitError extends Error {
20
25
  readonly exitCode: number;
@@ -240,6 +245,16 @@ export declare const REHYDRATE_STATE_FILE: string;
240
245
  export declare const REHYDRATE_LOG_FILE: string;
241
246
  /** `off` stops commands from starting a background rehydrate (tests). */
242
247
  export declare const BACKGROUND_REHYDRATE_ENV = "CASTLE_GIT_BACKGROUND_REHYDRATE";
248
+ /** A file each rehydrate appends one JSON outcome line to. The sandbox image points it at the
249
+ * container's own stdout (/proc/1/fd/1), which the host ships to Loki; the log file above does
250
+ * not leave the container. Unset: no event. */
251
+ export declare const CONTAINER_EVENT_LOG_ENV = "CASTLE_CONTAINER_EVENT_LOG";
252
+ /** Held by the child a first attach runs in, for its whole run (see attachThroughChild). */
253
+ export declare const ATTACH_LOCK_FILE: string;
254
+ /** Where that child writes its output. */
255
+ export declare const ATTACH_LOG_FILE: string;
256
+ /** `1` in that child: it attaches in its own process, bound by no caller's deadline. */
257
+ export declare const BACKGROUND_ATTACH_ENV = "CASTLE_GIT_BACKGROUND_ATTACH";
243
258
  export declare const SNAPSHOT_CAP_BYTES: number;
244
259
  /** A smaller cap, for tests. */
245
260
  export declare const SNAPSHOT_CAP_ENV = "CASTLE_GIT_SNAPSHOT_CAP_BYTES";
@@ -346,8 +361,12 @@ export interface AttachOutcome {
346
361
  /** For `adopted`: where the cloud copy's differing files were saved, if any differed. */
347
362
  backup?: string;
348
363
  }
364
+ /** A first attach a child ran to the end within the caller's deadline: the child's own output. */
365
+ export interface ChildAttachOutcome {
366
+ output: string;
367
+ }
349
368
  /** `castle-web git attach <dir> --remote <url>`. */
350
- export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome>;
369
+ export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome | ChildAttachOutcome>;
351
370
  export type GitChangeKind = 'added' | 'changed' | 'deleted';
352
371
  export interface GitVersionEntry {
353
372
  id: string;
package/dist/cloudGit.js CHANGED
@@ -38,6 +38,11 @@ export const EXIT_CONFLICT = 3;
38
38
  * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
39
39
  */
40
40
  export const EXIT_HISTORY_UNAVAILABLE = 4;
41
+ /**
42
+ * A first attach outran the caller's deadline and carries on in the background (see
43
+ * attachThroughChild). Not attached yet; the deck works without git until it is.
44
+ */
45
+ export const EXIT_ATTACH_CONTINUING = 5;
41
46
  export const HISTORY_UNAVAILABLE_CODE = 'GIT_HISTORY_UNAVAILABLE';
42
47
  export class CloudGitError extends Error {
43
48
  exitCode;
@@ -964,6 +969,16 @@ export const REHYDRATE_STATE_FILE = path.join('.git', 'castle-rehydrate-state.js
964
969
  export const REHYDRATE_LOG_FILE = path.join('.castle', 'agent', 'git-rehydrate.log');
965
970
  /** `off` stops commands from starting a background rehydrate (tests). */
966
971
  export const BACKGROUND_REHYDRATE_ENV = 'CASTLE_GIT_BACKGROUND_REHYDRATE';
972
+ /** A file each rehydrate appends one JSON outcome line to. The sandbox image points it at the
973
+ * container's own stdout (/proc/1/fd/1), which the host ships to Loki; the log file above does
974
+ * not leave the container. Unset: no event. */
975
+ export const CONTAINER_EVENT_LOG_ENV = 'CASTLE_CONTAINER_EVENT_LOG';
976
+ /** Held by the child a first attach runs in, for its whole run (see attachThroughChild). */
977
+ export const ATTACH_LOCK_FILE = path.join('.git', 'castle-attach-lock');
978
+ /** Where that child writes its output. */
979
+ export const ATTACH_LOG_FILE = path.join('.castle', 'agent', 'git-attach.log');
980
+ /** `1` in that child: it attaches in its own process, bound by no caller's deadline. */
981
+ export const BACKGROUND_ATTACH_ENV = 'CASTLE_GIT_BACKGROUND_ATTACH';
967
982
  // The host's capture refuses any file over 32 MiB and fails the whole checkpoint with it. The
968
983
  // snapshot and one set-aside lost snapshot stay under 48 MiB together.
969
984
  export const SNAPSHOT_CAP_BYTES = 24 * 1024 * 1024;
@@ -1955,6 +1970,7 @@ function dropBrokenRefs(ctx) {
1955
1970
  // Under the deck lock, after rehydrateObjects: give up lost local commits only when every
1956
1971
  // source answered cleanly, settle castle/main and the other refs, check the history is whole,
1957
1972
  // and re-hash staged blobs. Throws GIT_HISTORY_UNAVAILABLE (nothing changed) otherwise.
1973
+ // True when it gave up local commits nobody had (recoverLostHistory).
1958
1974
  async function finishRehydrate(ctx, result) {
1959
1975
  const tried = () => `Tried: ${result.notes.join('; ') || 'nothing could be tried'}.`;
1960
1976
  const branches = historyMissing(ctx).filter((tip) => isBranchTip(tip.name));
@@ -1977,6 +1993,7 @@ async function finishRehydrate(ctx, result) {
1977
1993
  }
1978
1994
  await recoverLostHistory(ctx, branches, result);
1979
1995
  }
1996
+ const lost = branches.length > 0;
1980
1997
  // castle/main is where the remote was last seen: kept while its commit is here (the next
1981
1998
  // sync fetches), else what was just fetched, else the mirror's main.
1982
1999
  const remote = refValue(ctx, REMOTE_MAIN);
@@ -2001,6 +2018,7 @@ async function finishRehydrate(ctx, result) {
2001
2018
  refreshSnapshot(ctx, false);
2002
2019
  ctx.deps.log(`Rebuilt this deck's git history from ${result.used.join(', ') || 'what was already here'}` +
2003
2020
  (reindexed.length ? `; re-hashed ${reindexed.length} staged file(s) from disk.` : '.'));
2021
+ return lost;
2004
2022
  }
2005
2023
  // The whole rehydrate, under REHYDRATE_LOCK_FILE: objects first, without the deck lock, then
2006
2024
  // the deck's refs under it. Any failure is recorded for the backoff and surfaces as
@@ -2020,13 +2038,13 @@ async function runRehydrate(ctx) {
2020
2038
  }
2021
2039
  if (historyMissing(ctx).length === 0) {
2022
2040
  fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
2023
- return 'complete';
2041
+ return { outcome: 'complete', historyLost: false, used: [] };
2024
2042
  }
2025
2043
  const budgetEnd = ctx.deadline ?? ctx.deps.now() + REHYDRATE_BUDGET_MS;
2026
2044
  const result = await rehydrateObjects(ctx, budgetEnd);
2027
- await withDeckLock(ctx, () => finishRehydrate(ctx, result));
2045
+ const historyLost = await withDeckLock(ctx, () => finishRehydrate(ctx, result));
2028
2046
  fs.rmSync(path.join(ctx.dir, REHYDRATE_STATE_FILE), { force: true });
2029
- return 'rebuilt';
2047
+ return { outcome: 'rebuilt', historyLost, used: result.used };
2030
2048
  }
2031
2049
  catch (e) {
2032
2050
  const error = e instanceof CloudGitError && e.exitCode === EXIT_HISTORY_UNAVAILABLE
@@ -2066,7 +2084,57 @@ export async function cloudRehydrate(dir, deps) {
2066
2084
  catch {
2067
2085
  throw new CloudGitError(`${ctx.dir} has no git repo to rehydrate.`, EXIT_NOT_ENABLED);
2068
2086
  }
2069
- return runRehydrate(ctx);
2087
+ const startedAt = ctx.deps.now();
2088
+ const emit = (fields) => emitContainerEvent(ctx.deps.env, {
2089
+ event: 'sandbox_git_rehydrate',
2090
+ // castle.json is the user's to edit: only a real deck id goes in.
2091
+ deck_id: /^[A-Za-z0-9_-]{1,64}$/.test(readDeckId(ctx.dir) ?? '') ? readDeckId(ctx.dir) : null,
2092
+ ...fields,
2093
+ duration_ms: ctx.deps.now() - startedAt,
2094
+ });
2095
+ let run;
2096
+ try {
2097
+ run = await runRehydrate(ctx);
2098
+ }
2099
+ catch (e) {
2100
+ emit({ outcome: 'failed', error: errorText(e).slice(0, 500) });
2101
+ throw e;
2102
+ }
2103
+ emit({ outcome: run.historyLost ? 'history_lost' : run.outcome, used: run.used });
2104
+ return run.outcome;
2105
+ }
2106
+ // One JSON line to CONTAINER_EVENT_LOG_ENV's file, at most PIPE_BUF bytes so a pipe takes it
2107
+ // whole (an event that would not fit loses its error and sources). Opened non-blocking: a full
2108
+ // pipe drops the line (EAGAIN) rather than stalling the rehydrate. Best effort throughout.
2109
+ const CONTAINER_EVENT_MAX_BYTES = 4096;
2110
+ function emitContainerEvent(env, event) {
2111
+ const target = env[CONTAINER_EVENT_LOG_ENV];
2112
+ if (!target)
2113
+ return;
2114
+ let line = Buffer.from(`${JSON.stringify(event)}\n`);
2115
+ if (line.length > CONTAINER_EVENT_MAX_BYTES) {
2116
+ line = Buffer.from(`${JSON.stringify({ ...event, error: undefined, used: undefined, truncated: true })}\n`);
2117
+ if (line.length > CONTAINER_EVENT_MAX_BYTES)
2118
+ return;
2119
+ }
2120
+ let fd;
2121
+ try {
2122
+ fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_NONBLOCK, 0o600);
2123
+ fs.writeSync(fd, line);
2124
+ }
2125
+ catch {
2126
+ /* best effort */
2127
+ }
2128
+ finally {
2129
+ if (fd !== undefined) {
2130
+ try {
2131
+ fs.closeSync(fd);
2132
+ }
2133
+ catch {
2134
+ /* best effort */
2135
+ }
2136
+ }
2137
+ }
2070
2138
  }
2071
2139
  // Concludes the merge in progress as one whole commit -- only when no conflicted file still
2072
2140
  // has markers. Git refuses a partial commit mid-merge, so named paths are not used.
@@ -2158,13 +2226,13 @@ async function commitLocked(ctx, opts) {
2158
2226
  const specs = commitPathspecs(ctx, opts.paths);
2159
2227
  if (specs.length === 0)
2160
2228
  return { sha: null };
2161
- must(ctx, ['add', '-A', '--', ...specs]);
2229
+ must(ctx, [...BIG_FILE_ARGS, 'add', '-A', '--', ...specs]);
2162
2230
  if (ok(ctx, ['diff', '--cached', '--quiet', '--', ...specs]))
2163
2231
  return { sha: null };
2164
2232
  await commit([...commitMessageArgs(opts, reason), '--', ...specs]);
2165
2233
  }
2166
2234
  else {
2167
- must(ctx, ['add', '-A']);
2235
+ must(ctx, [...BIG_FILE_ARGS, 'add', '-A']);
2168
2236
  if (ok(ctx, ['diff', '--cached', '--quiet']))
2169
2237
  return { sha: null };
2170
2238
  await commit(commitMessageArgs(opts, reason));
@@ -2308,10 +2376,17 @@ function isRejectedPush(result) {
2308
2376
  return /\[rejected\]|non-fast-forward|fetch first|failed to update ref|incorrect old value|cannot lock ref|stale info/i.test(result.stderr);
2309
2377
  }
2310
2378
  const PUSH_ARGS = ['push', '--quiet', GIT_REMOTE_NAME, `${MAIN}:refs/heads/${MAIN}`];
2379
+ // For a commit's add and a push only: blobs over a megabyte go straight into a pack as they are,
2380
+ // and a push sends them without a delta search against the deck's other files. A deck's big
2381
+ // files are images and audio that never delta, and that search was most of a first push (a
2382
+ // 144 MB deck took 35 s in a sandbox; locally its push went from 9 s to 1.4 s). Not repo config:
2383
+ // snapshot bundles and repacks still delta, so a big file's many revisions stay small in the
2384
+ // capped snapshot, and the agent's own git diff still reads such a file as text.
2385
+ const BIG_FILE_ARGS = ['-c', 'core.bigFileThreshold=1m'];
2311
2386
  // Main only, never forced. On success castle/main is moved without another fetch, so the next
2312
2387
  // sync's comparisons hold.
2313
2388
  function pushMain(ctx, local) {
2314
- const push = run(ctx, PUSH_ARGS, { timeoutMs: NETWORK_TIMEOUT_MS });
2389
+ const push = run(ctx, [...BIG_FILE_ARGS, ...PUSH_ARGS], { timeoutMs: NETWORK_TIMEOUT_MS });
2315
2390
  if (push.status === 0) {
2316
2391
  run(ctx, ['update-ref', REMOTE_MAIN, local]);
2317
2392
  markIntegrated(ctx, local);
@@ -2340,6 +2415,21 @@ function pushOnly(ctx) {
2340
2415
  ctx.deps.warn('The Castle remote has changes this sandbox does not have yet; they are merged once the deck is idle.');
2341
2416
  return { merge: 'deferred', pushed: false };
2342
2417
  }
2418
+ // The child's seed push: never a merge, so a remote that moved meanwhile fails it (and the seed
2419
+ // is undone) rather than have the working tree written under the user.
2420
+ async function seedPushOnly(ctx) {
2421
+ requireMainBranch(ctx);
2422
+ if (mergeWaiting(ctx.dir))
2423
+ throw mergeWaitingError(ctx);
2424
+ await commitLocked(ctx, { reason: 'sync' });
2425
+ const local = revParse(ctx, 'HEAD');
2426
+ if (!local)
2427
+ return { merge: 'none', pushed: false };
2428
+ const push = pushMain(ctx, local);
2429
+ if (push.status !== 0)
2430
+ throw new CloudGitError(describeFailure(PUSH_ARGS, push));
2431
+ return { merge: 'seeded', pushed: true };
2432
+ }
2343
2433
  async function syncLocked(ctx, opts) {
2344
2434
  requireMainBranch(ctx);
2345
2435
  if (mergeWaiting(ctx.dir))
@@ -2828,6 +2918,11 @@ function forgetOtherDecksRemote(ctx, deckId) {
2828
2918
  const other = CASTLE_REMOTE_RE.exec(current)?.[2];
2829
2919
  if (!other || other === deckId)
2830
2920
  return null;
2921
+ // The other deck's snapshot key would let a checkpoint leave out objects this deck's remote
2922
+ // does not have yet (its first push can run in the background). Gone first, before the other
2923
+ // remote is: from here on a checkpoint keeps the objects until this deck has a snapshot of its own.
2924
+ for (const rel of [SNAPSHOT_KEY_FILE, SNAPSHOT_BUNDLE_FILE])
2925
+ fs.rmSync(path.join(ctx.dir, rel), { force: true });
2831
2926
  must(ctx, ['remote', 'remove', GIT_REMOTE_NAME]);
2832
2927
  for (const key of ['castle.cloud', 'castle.seed', 'user.name', 'user.email']) {
2833
2928
  run(ctx, ['config', '--local', '--unset-all', key]);
@@ -2962,13 +3057,33 @@ export async function cloudAttach(dir, remoteUrl, deps) {
2962
3057
  must(ctx, ['config', '--local', 'core.createObject', 'rename']);
2963
3058
  // The base in conflict markers is what lets the agent see what each side changed.
2964
3059
  must(ctx, ['config', '--local', 'merge.conflictStyle', 'diff3']);
3060
+ if (deps.env[BACKGROUND_ATTACH_ENV] === '1')
3061
+ return attachInChild(ctx, repo);
3062
+ if (ctx.deadline === undefined || localConfig(ctx, 'castle.cloud') === 'true')
3063
+ return attachLocked(ctx, repo, 'inline');
3064
+ // An earlier open's child is still pushing: wait on it rather than queue on the deck lock.
3065
+ if ((await waitForAttachChild(ctx)) && localConfig(ctx, 'castle.cloud') === 'true') {
3066
+ return attachLocked(ctx, repo, 'inline');
3067
+ }
3068
+ try {
3069
+ return await attachLocked(ctx, repo, 'seed-elsewhere');
3070
+ }
3071
+ catch (e) {
3072
+ if (!(e instanceof SeedInChild))
3073
+ throw e;
3074
+ }
3075
+ return attachThroughChild(ctx, remoteUrl);
3076
+ }
3077
+ class SeedInChild extends Error {
3078
+ }
3079
+ async function attachLocked(ctx, repo, seedMode) {
2965
3080
  return withDeckLock(ctx, async () => {
2966
3081
  // A cold resume's repo has refs but no objects: the rehydrate runs in the background, and
2967
3082
  // this attach stops at once (castle-www runs it in the background on open).
2968
3083
  requireHistory(ctx, { leave: false });
2969
3084
  try {
2970
3085
  ensureMainBranch(ctx);
2971
- const outcome = await firstSync(ctx, repo);
3086
+ const outcome = await firstSync(ctx, repo, seedMode);
2972
3087
  // Marked attached only once the repo shares history with the remote: a deck whose
2973
3088
  // first fetch failed must not start a local history of its own, which the next attach
2974
3089
  // could not merge. The next open retries the whole attach.
@@ -2982,6 +3097,143 @@ export async function cloudAttach(dir, remoteUrl, deps) {
2982
3097
  }
2983
3098
  });
2984
3099
  }
3100
+ // --- attach: a first seed, in a child of its own ----------------------------------------------
3101
+ //
3102
+ // A first attach onto an empty remote pushes the whole deck, and castle-www's open waits on it:
3103
+ // it is the one attach on an open's critical path. A big deck's push can outlast the open's
3104
+ // budget every time -- the seed is undone each time it is cut short -- so the deck would never
3105
+ // get git, and every open would wait out the budget first. So under a deadline that seed and
3106
+ // push run in a detached child bound by no deadline, and the command waits for it only until its
3107
+ // own deadline: a small deck attaches within the wait exactly as before, a big one finishes in
3108
+ // the background (EXIT_ATTACH_CONTINUING) and the next open finds it attached. Only the seed: a
3109
+ // first attach that takes or merges the remote's version writes the working tree, which must
3110
+ // finish before the deck is served.
3111
+ // Short of the caller's deadline: relaying the child's outcome takes a moment.
3112
+ const ATTACH_WAIT_MARGIN_MS = 1_000;
3113
+ const ATTACH_POLL_MS = 200;
3114
+ const ATTACH_LOG_MAX_BYTES = 256 * 1024;
3115
+ const ATTACH_OUTPUT_MAX_BYTES = 64 * 1024;
3116
+ function attachContinuing(why) {
3117
+ return new CloudGitError(`${why} It carries on in the background (log: ${ATTACH_LOG_FILE}); the deck has git once it finishes.`, EXIT_ATTACH_CONTINUING);
3118
+ }
3119
+ function attachChildRunning(ctx) {
3120
+ try {
3121
+ const seen = inspectLock(path.join(ctx.dir, ATTACH_LOCK_FILE));
3122
+ return seen !== null && !holderIsGone(ctx.deps, seen);
3123
+ }
3124
+ catch {
3125
+ return false;
3126
+ }
3127
+ }
3128
+ function attachWaitUntil(ctx) {
3129
+ return ctx.deadline - ATTACH_WAIT_MARGIN_MS;
3130
+ }
3131
+ function delay(ms) {
3132
+ return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
3133
+ }
3134
+ // False when no child was running; true when one was and has finished. Still running at the
3135
+ // deadline: EXIT_ATTACH_CONTINUING.
3136
+ async function waitForAttachChild(ctx) {
3137
+ if (!attachChildRunning(ctx))
3138
+ return false;
3139
+ while (attachChildRunning(ctx)) {
3140
+ if (ctx.deps.now() >= attachWaitUntil(ctx))
3141
+ throw attachContinuing('An earlier first attach of this deck is still running.');
3142
+ await delay(Math.min(ATTACH_POLL_MS, attachWaitUntil(ctx) - ctx.deps.now()));
3143
+ }
3144
+ return true;
3145
+ }
3146
+ // What a file gained past `offset`, at most the last ATTACH_OUTPUT_MAX_BYTES of it.
3147
+ function readFrom(file, offset) {
3148
+ try {
3149
+ const size = fileSize(file);
3150
+ const start = Math.max(offset, size - ATTACH_OUTPUT_MAX_BYTES);
3151
+ if (size <= start)
3152
+ return '';
3153
+ const fd = fs.openSync(file, 'r');
3154
+ try {
3155
+ const buffer = Buffer.alloc(size - start);
3156
+ const read = fs.readSync(fd, buffer, 0, buffer.length, start);
3157
+ return buffer.subarray(0, read).toString('utf-8');
3158
+ }
3159
+ finally {
3160
+ fs.closeSync(fd);
3161
+ }
3162
+ }
3163
+ catch {
3164
+ return '';
3165
+ }
3166
+ }
3167
+ /** Starts the child for a seed firstSync found to be needed, and waits for it until the deadline. */
3168
+ async function attachThroughChild(ctx, remoteUrl) {
3169
+ const log = path.join(ctx.dir, ATTACH_LOG_FILE);
3170
+ fs.mkdirSync(path.dirname(log), { recursive: true });
3171
+ if (fileSize(log) > ATTACH_LOG_MAX_BYTES)
3172
+ fs.rmSync(log, { force: true });
3173
+ const offset = fileSize(log);
3174
+ const childEnv = { ...ctx.deps.env, [BACKGROUND_ATTACH_ENV]: '1' };
3175
+ delete childEnv[DEADLINE_ENV];
3176
+ const fd = fs.openSync(log, 'a');
3177
+ let child;
3178
+ try {
3179
+ child = spawn(process.execPath, [CLI_ENTRY, 'git', 'attach', ctx.dir, '--remote', remoteUrl], {
3180
+ cwd: ctx.dir,
3181
+ env: childEnv,
3182
+ detached: true,
3183
+ stdio: ['ignore', fd, fd],
3184
+ });
3185
+ }
3186
+ finally {
3187
+ fs.closeSync(fd);
3188
+ }
3189
+ const exited = new Promise((resolve) => {
3190
+ child.on('error', () => resolve('error'));
3191
+ child.on('exit', (code) => resolve(code ?? EXIT_ERROR));
3192
+ });
3193
+ const code = await Promise.race([exited, delay(attachWaitUntil(ctx) - ctx.deps.now()).then(() => 'running')]);
3194
+ if (code === 'running') {
3195
+ child.unref();
3196
+ throw attachContinuing("This deck's first push is taking longer than the open waits.");
3197
+ }
3198
+ if (code === 'error')
3199
+ throw new CloudGitError('Could not start the attach.');
3200
+ const output = readFrom(log, offset);
3201
+ if (code === EXIT_OK)
3202
+ return { output };
3203
+ throw new CloudGitError(output.trim() || `The attach exited ${code}.`, code);
3204
+ }
3205
+ /** The child's side: one at a time, and its outcome to the container's event log. */
3206
+ async function attachInChild(ctx, repo) {
3207
+ const startedAt = ctx.deps.now();
3208
+ const deckId = remoteDeckId(ctx);
3209
+ const emit = (fields) => emitContainerEvent(ctx.deps.env, {
3210
+ event: 'sandbox_git_attach',
3211
+ deck_id: deckId && /^[A-Za-z0-9_-]{1,64}$/.test(deckId) ? deckId : null,
3212
+ ...fields,
3213
+ duration_ms: ctx.deps.now() - startedAt,
3214
+ });
3215
+ let release;
3216
+ try {
3217
+ release = acquireLockFile(path.join(ctx.dir, ATTACH_LOCK_FILE), ctx.deps);
3218
+ }
3219
+ catch (e) {
3220
+ emit({ outcome: 'failed', error: errorText(e).slice(0, 500) });
3221
+ throw e;
3222
+ }
3223
+ try {
3224
+ const outcome = await attachLocked(ctx, repo, 'seed-only');
3225
+ emit({ outcome: 'attached', attach: outcome.outcome });
3226
+ return outcome;
3227
+ }
3228
+ catch (e) {
3229
+ const code = e instanceof CloudGitError ? e.exitCode : EXIT_ERROR;
3230
+ emit({ outcome: code === EXIT_HISTORY_UNAVAILABLE ? 'history_loading' : 'failed', error: errorText(e).slice(0, 500) });
3231
+ throw e;
3232
+ }
3233
+ finally {
3234
+ release();
3235
+ }
3236
+ }
2985
3237
  // The seed commit an attach made for an empty remote, until it is pushed. Should the push
2986
3238
  // fail (or the process die first), the commit is undone so the next attach starts from an
2987
3239
  // unborn main again: it then takes whatever the remote has by then, where keeping the seed
@@ -2999,12 +3251,17 @@ function undoUnpushedSeed(ctx) {
2999
3251
  }
3000
3252
  run(ctx, ['config', '--local', '--unset-all', SEED_KEY]);
3001
3253
  }
3002
- async function firstSync(ctx, repo) {
3254
+ async function firstSync(ctx, repo, seedMode) {
3003
3255
  undoUnpushedSeed(ctx);
3004
3256
  await commitRecoveredRoot(ctx);
3005
3257
  const remote = fetchRemote(ctx);
3006
3258
  const head = revParse(ctx, 'HEAD');
3259
+ if (remote && seedMode === 'seed-only') {
3260
+ throw new CloudGitError('The Castle remote has history now; the next open of the deck takes it.');
3261
+ }
3007
3262
  if (!remote) {
3263
+ if (seedMode === 'seed-elsewhere')
3264
+ throw new SeedInChild();
3008
3265
  if (!head) {
3009
3266
  const seed = await commitLocked(ctx, { reason: 'sync', message: 'Start of history' });
3010
3267
  if (seed.sha)
@@ -3012,7 +3269,7 @@ async function firstSync(ctx, repo) {
3012
3269
  }
3013
3270
  let sync;
3014
3271
  try {
3015
- sync = await syncLocked(ctx, { commitFirst: true, mode: 'full' });
3272
+ sync = seedMode === 'seed-only' ? await seedPushOnly(ctx) : await syncLocked(ctx, { commitFirst: true, mode: 'full' });
3016
3273
  }
3017
3274
  catch (e) {
3018
3275
  undoUnpushedSeed(ctx);
package/dist/imports.js CHANGED
@@ -594,11 +594,13 @@ async function placeFetchedImport(targetDir, deckId, givenAlias) {
594
594
  ? await api.webDeckSource(canonicalDeckId)
595
595
  : initialSource;
596
596
  if (!source) {
597
- if (meta && meta.initialCard?.type !== 'experimentalWeb') {
597
+ // 'cauldron' is the new name for the 'experimentalWeb' card type.
598
+ const cardType = meta?.initialCard?.type;
599
+ if (meta && cardType !== 'cauldron' && cardType !== 'experimentalWeb') {
598
600
  const title = meta.title?.trim();
599
601
  const subject = title ? `"${title}"` : `Deck ${canonicalDeckId}`;
600
602
  throw new ImportError('classic-deck', `${subject} is a classic Castle deck, made in the Castle app's editor. ` +
601
- `Only web decks built with castle-web can be imported; a classic deck's scenes can't be.`);
603
+ `Only Cauldron decks can be imported; a classic deck's scenes can't be.`);
602
604
  }
603
605
  throw new ImportError('no-source', `No source archive on the server for deck ${canonicalDeckId}. ` +
604
606
  'Its owner needs to run `castle-web save-deck` before it can be imported.');
package/dist/index.js CHANGED
@@ -442,6 +442,11 @@ async function cloudGitCommand(sub) {
442
442
  throw new Error('Usage: castle-web git attach <dir> --remote <url>');
443
443
  }
444
444
  const outcome = await cloudGit.cloudAttach(dir, remote, deps);
445
+ if ('output' in outcome) {
446
+ // The attach ran in a child of its own; this is what it said.
447
+ process.stdout.write(outcome.output);
448
+ return;
449
+ }
445
450
  console.log(`Attached ${path.resolve(dir)} to ${remote} (${outcome.repo} repo, ${outcome.outcome}).`);
446
451
  if (outcome.backup)
447
452
  console.log(`The cloud copy's differing files are saved in ${outcome.backup}.`);
package/dist/save-deck.js CHANGED
@@ -272,6 +272,9 @@ async function publishServerBundle(projectDir, deckId) {
272
272
  maxPlayers: serverConfig.maxPlayers,
273
273
  voice: { enabled: serverConfig.voiceEnabled },
274
274
  ...(serverConfig.destinations ? { destinations: serverConfig.destinations } : {}),
275
+ ...(serverConfig.worldNotifications
276
+ ? { worldNotifications: serverConfig.worldNotifications }
277
+ : {}),
275
278
  });
276
279
  // The server hashes what it actually stored. A mismatch means the bytes that
277
280
  // will run in sessions are not the bytes we bundled.
@@ -0,0 +1,42 @@
1
+ import * as api from './api.js';
2
+ import type { ServerSourceVersion } from './webSourceSync.js';
3
+ export declare const LINEAGE_BUDGET_MS = 9000;
4
+ /** path (posix, relative) -> sha256 hex */
5
+ export type SourceManifest = Map<string, string>;
6
+ /** Whether a source path counts toward a match: skips noise, dotfiles at the top, `._*`. */
7
+ export declare function countsTowardMatch(rel: string): boolean;
8
+ /**
9
+ * The folder's regular files as the archive would carry them, hashed in chunks; null past the
10
+ * size caps or once `expired` says the time is up.
11
+ */
12
+ export declare function folderManifest(dir: string, expired?: () => boolean): SourceManifest | null;
13
+ /**
14
+ * The regular files of a gzipped tar, hashed as they stream (ustar, pax `path`, GNU long
15
+ * names). Links and everything else are skipped; nothing is written to disk.
16
+ */
17
+ export declare function archiveManifest(gz: Buffer, expired?: () => boolean): Promise<SourceManifest>;
18
+ /** How many files the two copies hold identically. */
19
+ export declare function matchScore(folder: SourceManifest, saved: SourceManifest): number;
20
+ export type LineageOutcome = 'current' | 'older' | 'skipped';
21
+ export interface Lineage {
22
+ outcome: LineageOutcome;
23
+ /** The version to record: the current one unless an older one matches strictly better. */
24
+ version: ServerSourceVersion;
25
+ /** Saved versions compared (the current one included). */
26
+ examined: number;
27
+ /** Why the history was not compared, or why the comparison stopped early. */
28
+ reason?: string;
29
+ }
30
+ export interface LineageDeps {
31
+ listVersions?: (deckId: string, timeoutMs: number) => Promise<api.SavedSourceVersion[]>;
32
+ fetchArchive?: (url: string, timeoutMs: number) => Promise<Buffer>;
33
+ nowMs?: () => number;
34
+ /** When the comparison must be settled by (epoch ms); defaults to now + LINEAGE_BUDGET_MS. */
35
+ deadlineMs?: number;
36
+ }
37
+ /**
38
+ * The saved version this folder descends from. Never throws: any failure (an older Ghost,
39
+ * a fetch error, the budget) settles on the current version, which is what adopt recorded
40
+ * before this existed.
41
+ */
42
+ export declare function findLineage(dir: string, deckId: string, server: ServerSourceVersion, deps?: LineageDeps): Promise<Lineage>;