castle-web-cli 0.4.245 → 0.4.247

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/cloudGit.js CHANGED
@@ -95,11 +95,21 @@ export const HISTORY_LOST_MARKER_FILE = path.join('.castle', 'agent', 'git-histo
95
95
  * (webSourceSync.ts). Not a git marker: the serve consumes it with git off too.
96
96
  */
97
97
  export const WEB_SOURCE_NEWER_MARKER_FILE = path.join('.castle', 'agent', 'web-source-newer.json');
98
+ /** Written the first time the Castle remote refuses a push as too large (see pushMain). */
99
+ export const PUSH_TOO_LARGE_MARKER_FILE = path.join('.castle', 'agent', 'git-push-too-large.json');
100
+ /**
101
+ * The last push the remote refused as too large, in .git: `{ sha, tree, at, blobs }`. While it is
102
+ * fresh, a push of the same history waits instead of uploading the same refused pack again.
103
+ */
104
+ export const PUSH_TOO_LARGE_STATE_FILE = 'castle-push-too-large.json';
105
+ /** How long a refused-as-too-large history waits before a push tries it again. */
106
+ export const PUSH_TOO_LARGE_BACKOFF_MS = 30 * 60_000;
98
107
  /** Every marker the serve turns into an agent turn. */
99
108
  export const AGENT_MARKER_FILES = [
100
109
  CONFLICT_MARKER_FILE,
101
110
  ADOPTED_MARKER_FILE,
102
111
  HISTORY_LOST_MARKER_FILE,
112
+ PUSH_TOO_LARGE_MARKER_FILE,
103
113
  WEB_SOURCE_NEWER_MARKER_FILE,
104
114
  ];
105
115
  /** The markers the serve consumes whether or not git is on (CASTLE_GIT). */
@@ -2386,13 +2396,196 @@ const BIG_FILE_ARGS = ['-c', 'core.bigFileThreshold=1m'];
2386
2396
  // Main only, never forced. On success castle/main is moved without another fetch, so the next
2387
2397
  // sync's comparisons hold.
2388
2398
  function pushMain(ctx, local) {
2399
+ waitIfRefusedAsTooLarge(ctx, local);
2389
2400
  const push = run(ctx, [...BIG_FILE_ARGS, ...PUSH_ARGS], { timeoutMs: NETWORK_TIMEOUT_MS });
2390
2401
  if (push.status === 0) {
2391
2402
  run(ctx, ['update-ref', REMOTE_MAIN, local]);
2392
2403
  markIntegrated(ctx, local);
2404
+ clearPushTooLarge(ctx);
2405
+ }
2406
+ else if (isTooLargePush(push) || (isBrokenPush(push) && unpushedBytes(ctx, local) > pushCapBytes(ctx))) {
2407
+ recordPushTooLarge(ctx, local);
2408
+ throw new CloudGitError(`The Castle remote refused this push as too large (over ${PUSH_LIMIT_LABEL} at once); ` +
2409
+ `it is tried again in ${PUSH_TOO_LARGE_BACKOFF_MS / 60_000} minutes.`);
2393
2410
  }
2394
2411
  return push;
2395
2412
  }
2413
+ // The Castle remote (castle-sandboxes shared/src/git/handler.ts) answers 413 to a push over
2414
+ // 256 MiB and closes the connection. Git's own words for that, never a remote's ("remote: ..."
2415
+ // lines are whatever the server printed).
2416
+ const PUSH_LIMIT_LABEL = '256 MB';
2417
+ // Blobs at least this big are named to the agent when a push is refused as too large.
2418
+ const LARGE_BLOB_BYTES = 1024 * 1024;
2419
+ const MAX_LARGE_BLOBS_NAMED = 8;
2420
+ // The remote closes the connection right after its 413, so git often never reads it and reports
2421
+ // only the broken upload. Such a failure counts as the cap when what the push had to send -- the
2422
+ // new objects, as stored -- is over it anyway.
2423
+ export const PUSH_CAP_ENV = 'CASTLE_GIT_PUSH_CAP_BYTES';
2424
+ const DEFAULT_PUSH_CAP_BYTES = 256 * 1024 * 1024;
2425
+ function pushCapBytes(ctx) {
2426
+ const set = Number(ctx.deps.env[PUSH_CAP_ENV]);
2427
+ return Number.isFinite(set) && set > 0 ? set : DEFAULT_PUSH_CAP_BYTES;
2428
+ }
2429
+ function isBrokenPush(result) {
2430
+ return /remote end hung up|Broken pipe|unexpected disconnect|Connection reset|Send failure/i.test(result.stderr);
2431
+ }
2432
+ // What the push had to send, roughly: each new object as stored (compressed), except one stored
2433
+ // as a delta against a base that neither travels with it nor is on the remote already -- the
2434
+ // pack then carries it whole, so it counts at its full size.
2435
+ function unpushedBytes(ctx, local) {
2436
+ const base = revParse(ctx, REMOTE_MAIN);
2437
+ const listed = run(ctx, ['rev-list', '--objects', '--no-object-names', local, ...(base ? ['--not', base] : [])]);
2438
+ if (listed.status !== 0 || !listed.stdout.trim())
2439
+ return 0;
2440
+ const sending = new Set(lines(listed.stdout));
2441
+ const sizes = run(ctx, ['cat-file', '--batch-check=%(objectname) %(objectsize:disk) %(objectsize) %(deltabase)'], {
2442
+ input: listed.stdout,
2443
+ });
2444
+ let total = 0;
2445
+ for (const line of lines(sizes.stdout)) {
2446
+ const [, disk, full, deltaBase] = line.split(' ');
2447
+ const isDelta = Boolean(deltaBase) && !/^0+$/.test(deltaBase);
2448
+ const baseThere = !isDelta || sending.has(deltaBase) || (base !== null && objectReachable(ctx, deltaBase, base));
2449
+ total += Number(baseThere ? disk : full) || 0;
2450
+ }
2451
+ return total;
2452
+ }
2453
+ // Whether an object is in a commit's history: a blob or tree by its presence in that history's
2454
+ // object list is too slow per object, so it is asked once per base and cached for this run.
2455
+ const reachableCache = new Map();
2456
+ function objectReachable(ctx, object, commit) {
2457
+ let known = reachableCache.get(commit);
2458
+ if (!known) {
2459
+ const listed = run(ctx, ['rev-list', '--objects', '--no-object-names', commit]);
2460
+ known = new Set(listed.status === 0 ? lines(listed.stdout) : []);
2461
+ reachableCache.set(commit, known);
2462
+ }
2463
+ return known.has(object);
2464
+ }
2465
+ function isTooLargePush(result) {
2466
+ return result.stderr
2467
+ .split('\n')
2468
+ .some((line) => !/^\s*remote:/.test(line) && /RPC failed; HTTP 413\b|The requested URL returned error: 413\b/.test(line));
2469
+ }
2470
+ function pushTooLargeStatePath(ctx) {
2471
+ return path.join(gitDir(ctx.dir), PUSH_TOO_LARGE_STATE_FILE);
2472
+ }
2473
+ function readPushTooLarge(ctx) {
2474
+ try {
2475
+ const state = JSON.parse(fs.readFileSync(pushTooLargeStatePath(ctx), 'utf-8'));
2476
+ return typeof state?.sha === 'string' && typeof state.tree === 'string' && Array.isArray(state.blobs) ? state : null;
2477
+ }
2478
+ catch {
2479
+ return null;
2480
+ }
2481
+ }
2482
+ function clearPushTooLarge(ctx) {
2483
+ fs.rmSync(pushTooLargeStatePath(ctx), { force: true });
2484
+ }
2485
+ function treeOf(ctx, commit) {
2486
+ return must(ctx, ['rev-parse', `${commit}^{tree}`]).trim();
2487
+ }
2488
+ // Whether `local` still carries the history a push was refused for, against the same remote:
2489
+ // built on it, or the same files (a seed that failed is undone and made again with a new sha but
2490
+ // the same tree).
2491
+ function sameRefusedHistory(ctx, state, local, opts) {
2492
+ // The remote moved (a collaborator or a laptop pushed, perhaps the very files): what this push
2493
+ // has to send is different now, so it is not held back -- though it is no news to announce.
2494
+ if (opts.sameRemote && (state.remote ?? null) !== revParse(ctx, REMOTE_MAIN))
2495
+ return false;
2496
+ return state.sha === local || ok(ctx, ['merge-base', '--is-ancestor', state.sha, local]) || state.tree === treeOf(ctx, local);
2497
+ }
2498
+ // The big blobs a push of `local` would carry: those not already on the remote.
2499
+ function largeUnpushedBlobs(ctx, local) {
2500
+ const base = revParse(ctx, REMOTE_MAIN);
2501
+ const range = base ? [local, '--not', base] : [local];
2502
+ const listed = run(ctx, ['rev-list', '--objects', '--no-object-names', '--filter=blob:limit=1m', '--filter-print-omitted', ...range]);
2503
+ if (listed.status !== 0)
2504
+ return [];
2505
+ const big = new Set(lines(listed.stdout).filter((l) => l.startsWith('~')).map((l) => l.slice(1)));
2506
+ if (big.size === 0)
2507
+ return [];
2508
+ const named = run(ctx, ['rev-list', '--objects', ...range]);
2509
+ const paths = new Map();
2510
+ for (const line of lines(named.stdout)) {
2511
+ const space = line.indexOf(' ');
2512
+ if (space > 0 && big.has(line.slice(0, space)) && !paths.has(line.slice(0, space))) {
2513
+ paths.set(line.slice(0, space), line.slice(space + 1));
2514
+ }
2515
+ }
2516
+ const sizes = run(ctx, ['cat-file', '--batch-check=%(objectname) %(objectsize)'], { input: [...big].join('\n') + '\n' });
2517
+ const blobs = [];
2518
+ for (const line of lines(sizes.stdout)) {
2519
+ const [sha, size] = line.split(' ');
2520
+ const bytes = Number(size);
2521
+ if (sha && Number.isFinite(bytes) && bytes >= LARGE_BLOB_BYTES) {
2522
+ blobs.push({ sha, path: paths.get(sha) ?? '(unknown path)', bytes });
2523
+ }
2524
+ }
2525
+ return blobs.sort((a, b) => b.bytes - a.bytes);
2526
+ }
2527
+ function formatMegabytes(bytes) {
2528
+ return `${(bytes / (1024 * 1024)).toFixed(bytes >= 10 * 1024 * 1024 ? 0 : 1)} MB`;
2529
+ }
2530
+ // The first refusal for a history is told once (a chat line and an agent turn); a repeat of the
2531
+ // same history only refreshes the state, so a deck stuck over the limit is not re-announced
2532
+ // on every turn.
2533
+ function recordPushTooLarge(ctx, local) {
2534
+ const previous = readPushTooLarge(ctx);
2535
+ const repeat = previous !== null && sameRefusedHistory(ctx, previous, local, { sameRemote: false });
2536
+ const blobs = largeUnpushedBlobs(ctx, local);
2537
+ const tree = treeOf(ctx, local);
2538
+ const state = {
2539
+ sha: local,
2540
+ tree,
2541
+ at: new Date(ctx.deps.now()).toISOString(),
2542
+ remote: revParse(ctx, REMOTE_MAIN),
2543
+ blobs,
2544
+ };
2545
+ try {
2546
+ writeJsonAtomic(pushTooLargeStatePath(ctx), state);
2547
+ }
2548
+ catch (err) {
2549
+ ctx.deps.warn(`Could not record the refused push: ${err instanceof Error ? err.message : String(err)}`);
2550
+ }
2551
+ if (repeat)
2552
+ return;
2553
+ const named = blobs
2554
+ .slice(0, MAX_LARGE_BLOBS_NAMED)
2555
+ .map((b) => `${b.path} (${formatMegabytes(b.bytes)})`)
2556
+ .join(', ');
2557
+ writeJsonAtomic(path.join(ctx.dir, PUSH_TOO_LARGE_MARKER_FILE), {
2558
+ at: state.at,
2559
+ notice: `This deck's latest changes are too large to save to its Castle git history (over ${PUSH_LIMIT_LABEL} at once).`,
2560
+ instruction: `Castle's git remote refused this deck's latest commits because together they are over ${PUSH_LIMIT_LABEL}, so ` +
2561
+ "they are not reaching the deck's history on Castle (the files themselves are fine, and autosave still keeps " +
2562
+ `them). ${named ? `The largest new files are: ${named}. ` : ''}Tell the user in a few sentences, and suggest ` +
2563
+ 'making those files smaller (compress or downscale them) or removing ones the deck does not use. Changes waiting ' +
2564
+ 'to upload still carry the files as they were, so say plainly that the deck history on Castle stays behind ' +
2565
+ 'until this is sorted out; do not promise when it catches up. Do not rewrite git history yourself and never ' +
2566
+ 'force-push.',
2567
+ });
2568
+ }
2569
+ // After a refusal, a push of the same history (built on the refused commit, or the same files)
2570
+ // waits PUSH_TOO_LARGE_BACKOFF_MS rather than uploading the same oversized pack on every turn.
2571
+ function waitIfRefusedAsTooLarge(ctx, local) {
2572
+ const state = readPushTooLarge(ctx);
2573
+ if (!state)
2574
+ return;
2575
+ if (!sameRefusedHistory(ctx, state, local, { sameRemote: false })) {
2576
+ clearPushTooLarge(ctx);
2577
+ return;
2578
+ }
2579
+ // The same history against a remote that has moved since: try it now, but keep the record, so
2580
+ // a second refusal is not announced again.
2581
+ if (!sameRefusedHistory(ctx, state, local, { sameRemote: true }))
2582
+ return;
2583
+ const waited = ctx.deps.now() - Date.parse(state.at);
2584
+ if (Number.isFinite(waited) && waited < PUSH_TOO_LARGE_BACKOFF_MS) {
2585
+ const minutes = Math.max(1, Math.ceil((PUSH_TOO_LARGE_BACKOFF_MS - waited) / 60_000));
2586
+ throw new CloudGitError(`Not pushing: the Castle remote refused this history as too large (over ${PUSH_LIMIT_LABEL}); trying again in about ${minutes} min.`);
2587
+ }
2588
+ }
2396
2589
  /**
2397
2590
  * The remote's main as local main last took it in: what a recovery may start the deck again
2398
2591
  * from. castle/main can be ahead of it -- fetched, but its merge deferred while tasks were busy,
@@ -3008,15 +3201,26 @@ export function writeCloudExcludes(dir) {
3008
3201
  function topUpCloudExcludes(ctx) {
3009
3202
  writeCloudExcludes(ctx.dir);
3010
3203
  const lockfiles = new Set(CLOUD_LOCKFILES);
3011
- const tracked = must(ctx, ['ls-files', '-z'])
3012
- .split('\0')
3013
- .filter((file) => file && lockfiles.has(path.posix.basename(file)));
3014
- if (tracked.length === 0)
3015
- return;
3204
+ const tracked = must(ctx, ['ls-files', '-z']).split('\0').filter(Boolean);
3016
3205
  // Two sandboxes install dependencies independently, so tracked lockfiles conflict on nearly
3017
3206
  // every sync. package.json still carries the deck's dependencies; keep each lockfile in the
3018
3207
  // working copy while removing it from the shared cloud history once.
3019
- must(ctx, ['rm', '--cached', '--quiet', '--ignore-unmatch', '--', ...tracked]);
3208
+ const specs = new Set(tracked.filter((file) => lockfiles.has(path.posix.basename(file))).map(literal));
3209
+ // A node_modules a laptop committed, likewise: the excludes only keep untracked files out. One
3210
+ // pathspec per node_modules directory, not per file -- matching tens of thousands of literal
3211
+ // paths takes longer than a leave commit has.
3212
+ for (const file of tracked) {
3213
+ const parts = file.split('/');
3214
+ const at = parts.slice(0, -1).indexOf('node_modules');
3215
+ if (at >= 0)
3216
+ specs.add(literal(parts.slice(0, at + 1).join('/')));
3217
+ }
3218
+ if (specs.size === 0)
3219
+ return;
3220
+ // From stdin, past any argv limit.
3221
+ must(ctx, ['rm', '-r', '--cached', '--quiet', '--ignore-unmatch', '--pathspec-from-file=-', '--pathspec-file-nul'], {
3222
+ input: [...specs].join('\0') + '\0',
3223
+ });
3020
3224
  }
3021
3225
  /** `castle-web git attach <dir> --remote <url>`. */
3022
3226
  export async function cloudAttach(dir, remoteUrl, deps) {
@@ -9,7 +9,7 @@ import { WebSocketServer, WebSocket } from 'ws';
9
9
  import { readCastleJson, resolveServerConfig } from './castleJson.js';
10
10
  import { OutboundFrameMeter } from './devSessionFrameBudget.js';
11
11
  import { SAVE_VERBS } from './devSaveStorage.js';
12
- import { REFUSAL_HOLD_MS, runDevSave, runDevStorageOperation } from './devSessionStorage.js';
12
+ import { REFUSAL_HOLD_MS, refuseDevWriterCheck, runDevSave, runDevStorageOperation } from './devSessionStorage.js';
13
13
  import { rawDataToString } from './rawData.js';
14
14
  import { bundleServerModule } from './serverBundle.js';
15
15
  import { devDeckCastleJsons, devDeckSessionKey } from './contentPack.js';
@@ -606,7 +606,8 @@ class DevSessionImpl {
606
606
  // funded audience sends to the signed-in CLI user's own subject.
607
607
  const result = SAVE_VERBS.has(op)
608
608
  ? runDevSave(this.projectDir, this.sessionId, op, args)
609
- : await runDevStorageOperation(deckId, op, args, this.connectedPlayers().map((player) => player.userId));
609
+ : refuseDevWriterCheck(op, args) ??
610
+ await runDevStorageOperation(deckId, op, args, this.connectedPlayers().map((player) => player.userId));
610
611
  if (!result.ok && typeof result.error?.heldUntil === 'number') {
611
612
  this.log('error', `storage refused: ${result.error.message} (${result.error.code}). Serve answers this deck's storage calls with that refusal for the next ${REFUSAL_HOLD_MS / 60_000} minutes instead of asking the API again.`);
612
613
  }
@@ -11,6 +11,13 @@ export interface DevStorageResult {
11
11
  export declare const REFUSAL_HOLD_MS: number;
12
12
  /** A session server's save. Its args are what the platform's storage route takes. */
13
13
  export declare function runDevSave(projectDir: string, sessionId: string, op: string, args: Record<string, unknown>): DevStorageResult;
14
+ /**
15
+ * An ordinary write carrying a writer check is refused by serve, before anything is
16
+ * sent. Serve's claims live in its memory while ordinary writes go to the deck's real
17
+ * storage, and no check across the two can be atomic with the write, so an emulated
18
+ * check would claim protection it cannot give. Null when the call carries none.
19
+ */
20
+ export declare function refuseDevWriterCheck(op: string, args: Record<string, unknown>): DevStorageResult | null;
14
21
  /**
15
22
  * A page's save, answered in place of the GraphQL call the browser host makes
16
23
  * for it. Undefined for every other document, which goes to the real API.
@@ -37,6 +37,25 @@ export function runDevSave(projectDir, sessionId, op, args) {
37
37
  replyBytes: SERVER_REPLY_BYTES,
38
38
  });
39
39
  }
40
+ /**
41
+ * An ordinary write carrying a writer check is refused by serve, before anything is
42
+ * sent. Serve's claims live in its memory while ordinary writes go to the deck's real
43
+ * storage, and no check across the two can be atomic with the write, so an emulated
44
+ * check would claim protection it cannot give. Null when the call carries none.
45
+ */
46
+ export function refuseDevWriterCheck(op, args) {
47
+ if (args.writerCheck === undefined || args.writerCheck === null)
48
+ return null;
49
+ return {
50
+ ok: false,
51
+ error: {
52
+ code: 'CAULDRON_STORAGE_UNAVAILABLE',
53
+ message: `castle-web serve cannot run a writer check on ${op}: its claims are local and the write would go to the deck's real storage. Nothing was written.`,
54
+ committed: false,
55
+ retryable: false,
56
+ },
57
+ };
58
+ }
40
59
  const SAVE_FIELDS = {
41
60
  cauldronStorageSnapshot: 'snapshot',
42
61
  cauldronStorageOperation: 'operation',
package/dist/index.js CHANGED
@@ -31,6 +31,7 @@ const FLAGS_WITH_VALUES = new Set([
31
31
  '--title',
32
32
  '--caption',
33
33
  '--visibility',
34
+ '--allow-drop',
34
35
  '--as',
35
36
  '--kind',
36
37
  '--dir',
@@ -190,7 +191,7 @@ function usageText() {
190
191
  castle-web serve [dir] [--port PORT] [--host HOST | --lan] [--open] [--detach] (listens on localhost only by default; --host ADDR binds that address and --lan is --host 0.0.0.0 -- both expose the unauthenticated editor, its terminal and the project files to the network)
191
192
  castle-web restart [--port PORT]
192
193
  castle-web screenshot [--out FILE] [--port PORT]
193
- castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private] [--force] [--pin-installed-imports] [--chunked-bundle] (--force: save over a newer saved copy; --pin-installed-imports: move import pins to the versions imports/ holds instead of refusing; --chunked-bundle: publish the JS as cacheable classic-script chunks, as castle.json "bundle": { "chunks": "classic" } does)
194
+ castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private] [--force] [--pin-installed-imports] [--chunked-bundle] [--refuse-drops] [--allow-drop PATH[#POINTER]]... (--force: save over a newer saved copy; --pin-installed-imports: move import pins to the versions imports/ holds instead of refusing; --chunked-bundle: publish the JS as cacheable classic-script chunks, as castle.json "bundle": { "chunks": "classic" } does; --refuse-drops: refuse a save that drops a file, key or non-empty value the live deck's saved source has, as castle.json "saveGuard": { "refuseDrops": true } in the folder or the live deck does; --allow-drop: name one intended removal, printed in the save's output)
194
195
  castle-web get-deck [dir] [--deck-id ID] [--force] (replaces the source if the deck is already there)
195
196
  castle-web get-deck <dir> --side [--deck-id ID] [--json] (fetches the saved copy into <dir>/.castle/agent/saved-source/<stamp>/, touching nothing else)
196
197
  castle-web source-status <dir> [--adopt] [--notify] [--json] (whether the deck's saved copy is newer than this folder)
@@ -541,6 +542,35 @@ async function gitVersionCommand(name) {
541
542
  }
542
543
  return true;
543
544
  }
545
+ // save-deck's save-drop guard flags, read the way findPositionalDir reads arguments: a flag's
546
+ // value (a --title or --caption that happens to read "--allow-drop") is never a flag itself.
547
+ function readDropFlags() {
548
+ if (args.some((arg) => /^--(?:allow-drop|refuse-drops)=/.test(arg))) {
549
+ console.error('Pass --allow-drop VALUE with a space, and --refuse-drops without a value.');
550
+ process.exit(1);
551
+ }
552
+ let refuseDrops = false;
553
+ const allowDrops = [];
554
+ for (let i = 1; i < args.length; i++) {
555
+ const arg = args[i];
556
+ if (arg === '--refuse-drops') {
557
+ refuseDrops = true;
558
+ }
559
+ else if (arg === '--allow-drop') {
560
+ const value = args[i + 1];
561
+ if (value === undefined || value.startsWith('--') || value.trim() === '') {
562
+ console.error('--allow-drop needs a path, for example --allow-drop code/server/old.js or --allow-drop "castle.json#/hub/old".');
563
+ process.exit(1);
564
+ }
565
+ allowDrops.push(value);
566
+ i++;
567
+ }
568
+ else if (FLAGS_WITH_VALUES.has(arg)) {
569
+ i++;
570
+ }
571
+ }
572
+ return { refuseDrops, allowDrops };
573
+ }
544
574
  async function main() {
545
575
  // Before the switch: `--version` is a flag, not a command, and it has to work
546
576
  // when there is no command at all. Which version is installed is the first
@@ -616,7 +646,15 @@ async function main() {
616
646
  const visibility = getFlagValue('--visibility');
617
647
  const pinInstalledImports = hasFlag('--pin-installed-imports');
618
648
  const chunkedBundle = hasFlag('--chunked-bundle');
619
- await saveDeck(dir, { title, caption, visibility, force: hasFlag('--force'), pinInstalledImports, chunkedBundle });
649
+ await saveDeck(dir, {
650
+ title,
651
+ caption,
652
+ visibility,
653
+ force: hasFlag('--force'),
654
+ pinInstalledImports,
655
+ chunkedBundle,
656
+ ...readDropFlags(),
657
+ });
620
658
  break;
621
659
  }
622
660
  case 'get-deck': {
package/dist/init.js CHANGED
@@ -64,7 +64,7 @@ const BARE_SCAFFOLDS = [
64
64
  // Registry version of castle-web-sdk to inject when scaffolding from a
65
65
  // globally-installed castle-web (not from inside the workspace). Bumped
66
66
  // alongside cli/sdk version bumps.
67
- const PUBLISHED_SDK_VERSION = '0.4.57';
67
+ const PUBLISHED_SDK_VERSION = '0.4.58';
68
68
  // Range, not a pin: `castle-web-fonts` is its own package precisely so a tenth
69
69
  // face can ship without a cli release, and a caret range means an existing
70
70
  // deck's next install picks it up. Nothing here has to move when it does.
@@ -1,6 +1,8 @@
1
1
  export declare const PLATFORM_DOCS_DIR: string;
2
2
  export declare const PLATFORM_DOC_REL: string;
3
3
  export declare const MULTIPLAYER_DOC_REL: string;
4
+ export declare const CHARACTER_DOC_REL: string;
5
+ export declare function deckDeclaresCharacters(deckDir: string): boolean;
4
6
  export declare function everyDeckBullets(deckDir: string): string[];
5
7
  export declare const HOST_LIMIT_BULLETS: string[];
6
8
  export declare const CASTLE_UI_BULLETS: string[];
@@ -3,6 +3,8 @@ import * as fs from 'fs';
3
3
  import * as path from 'path';
4
4
  import { resolveFileTypes } from './editorConfig.js';
5
5
  import { MULTIPLAYER_DOC } from './multiplayerDoc.js';
6
+ import { CHARACTER_DOC } from './characterDoc.js';
7
+ import { readCastleJson } from './castleJson.js';
6
8
  // The platform's own guidance to agents -- the rules identical in a bare deck
7
9
  // and a kit deck: the card, touch, assets and formats, imports, reloading,
8
10
  // editors. Its one home is here. The serve writes it under the deck's .castle/
@@ -26,6 +28,19 @@ export const PLATFORM_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'platform.md');
26
28
  // holds its text, platform.md's Multiplayer section points at this path, and
27
29
  // nothing puts it in a prompt.
28
30
  export const MULTIPLAYER_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'multiplayer.md');
31
+ // The characters guide (characterDoc.ts), written only for a deck whose
32
+ // castle.json declares a characterBundle, and removed again when it no longer
33
+ // does. Characters are not open to creators, so no other deck hears of them.
34
+ export const CHARACTER_DOC_REL = path.join(PLATFORM_DOCS_DIR, 'characters.md');
35
+ export function deckDeclaresCharacters(deckDir) {
36
+ const castleJson = readCastleJson(deckDir);
37
+ const bundle = castleJson?.characterBundle;
38
+ return typeof bundle === 'object' && bundle !== null && !Array.isArray(bundle);
39
+ }
40
+ const CHARACTER_POINTER = `## Characters
41
+
42
+ - **Read \`${CHARACTER_DOC_REL}\` before writing or changing this deck's \`characterBundle\`, its \`Characters\` client code, or its server's story calls.** Characters are experimental; that guide has the bundle rules, the publish-before-testing rule, and the send, recovery and reset handling a hand-written conversation gets wrong.
43
+ `;
29
44
  const MEDIA = {
30
45
  images: ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'],
31
46
  audio: ['.mp3', '.wav', '.m4a'],
@@ -343,7 +358,7 @@ How every Castle deck works, from the Castle CLI. Written fresh at every serve
343
358
  start; the deck's own guide (its kit's CLAUDE.md under imports/) adds what its
344
359
  kit provides on top of this.
345
360
 
346
- ${platformGuide(deckDir)}`;
361
+ ${platformGuide(deckDir)}${deckDeclaresCharacters(deckDir) ? `\n${CHARACTER_POINTER}` : ''}`;
347
362
  }
348
363
  // Written by the serve at every start, so the copy in a deck is exactly as
349
364
  // fresh as the CLI serving it. platform.md is the always-loaded one; the
@@ -361,6 +376,16 @@ export function writePlatformDocs(deckDir) {
361
376
  catch (error) {
362
377
  console.warn(`Could not write ${MULTIPLAYER_DOC_REL}: ${error instanceof Error ? error.message : String(error)}`);
363
378
  }
379
+ const characterDoc = path.join(deckDir, CHARACTER_DOC_REL);
380
+ try {
381
+ if (deckDeclaresCharacters(deckDir))
382
+ fs.writeFileSync(characterDoc, CHARACTER_DOC);
383
+ else
384
+ fs.rmSync(characterDoc, { force: true });
385
+ }
386
+ catch (error) {
387
+ console.warn(`Could not write ${CHARACTER_DOC_REL}: ${error instanceof Error ? error.message : String(error)}`);
388
+ }
364
389
  }
365
390
  // What the deck's root CLAUDE.md carries for the platform: one @import line
366
391
  // (which claude auto-loads) inside a short section that says what it is, for
@@ -91,6 +91,10 @@ export interface SaveDeckOptions {
91
91
  pinInstalledImports?: boolean;
92
92
  /** Publish a classic chunked bundle, as castle.json `"bundle": { "chunks": "classic" }` does. */
93
93
  chunkedBundle?: boolean;
94
+ /** Run the save-drop guard even when neither castle.json asks for it. */
95
+ refuseDrops?: boolean;
96
+ /** Intended removals the save-drop guard lets through: `<path>` or `<path>#<pointer>`. */
97
+ allowDrops?: string[];
94
98
  }
95
99
  export declare function saveDeck(dir: string, opts?: SaveDeckOptions): Promise<void>;
96
100
  export declare function builtinRefreshOptions(env?: NodeJS.ProcessEnv): {
package/dist/save-deck.js CHANGED
@@ -17,6 +17,7 @@ import { importRegressionMessage, importRegressions, savedDeckImportPins } from
17
17
  import { isSandboxEnv } from './cloudGit.js';
18
18
  import { settleImportPins } from './importPinMismatch.js';
19
19
  import { refreshStaleBuiltinImports } from './imports.js';
20
+ import { bindSourcePrecondition, checkSaveDrops, EXIT_SAVE_DROPS } from './saveDropGuard.js';
20
21
  import { decideSavePrecondition, EXIT_IMPORTS_OLDER, EXIT_SAVED_DECK_NEWER, fetchServerSourceVersion, readSyncMarker, saveRefusedLine, saveRefusedMessage, WEB_DECK_SOURCE_STALE_CODE, writeSyncMarker, } from './webSourceSync.js';
21
22
  import { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, SAVE_FAILURE_ENV, classifySaveFailure, saveFailedLine, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
22
23
  export { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
@@ -768,6 +769,42 @@ function buildSceneData(bundle) {
768
769
  },
769
770
  };
770
771
  }
772
+ // The save-drop guard (saveDropGuard.ts), with this file's network and tar, for a deck that
773
+ // already has an id. When it compared, the source commit expects the very source it compared
774
+ // with (or none, when it saw none): one saved in between, which the guard never saw, is refused
775
+ // instead of overwritten -- for an unmarked or forced folder too, which otherwise sends no
776
+ // precondition. A folder that already expects a source keeps that precondition, and a guard that
777
+ // read a different source stops the save here, before anything is published.
778
+ async function saveDropCheck(deckId, candidateArchive, candidateCastleJson, opts, expectedS3Key) {
779
+ if (!deckId)
780
+ return { ok: true, expectedS3Key };
781
+ const result = await checkSaveDrops({
782
+ deckId,
783
+ candidateArchive,
784
+ candidateCastleJson: candidateCastleJson,
785
+ refuseDrops: opts.refuseDrops === true,
786
+ allowDrops: opts.allowDrops ?? [],
787
+ excludeTop: SOURCE_ARCHIVE_EXCLUDES,
788
+ fetchLiveArchive: async () => {
789
+ const source = await api.webDeckSource(deckId);
790
+ if (!source)
791
+ return null;
792
+ return { file: await downloadSourceArchive(source, 'castle-save-drops', () => { }), s3Key: source.s3Key };
793
+ },
794
+ untar: async (archive, dir) => {
795
+ await runTar(['-xzf', archive, '--no-same-owner', '-C', dir]);
796
+ },
797
+ });
798
+ if (!result.ok)
799
+ return { ok: false, expectedS3Key };
800
+ const bound = bindSourcePrecondition(expectedS3Key, result.compared);
801
+ if ('refuse' in bound) {
802
+ console.error(bound.refuse);
803
+ process.exitCode = EXIT_SAVE_DROPS;
804
+ return { ok: false, expectedS3Key };
805
+ }
806
+ return { ok: true, expectedS3Key: bound.expectedS3Key };
807
+ }
771
808
  export async function saveDeck(dir, opts = {}) {
772
809
  if (!config.getToken()) {
773
810
  console.error('Not logged in. Run `castle-web login` first.');
@@ -929,6 +966,11 @@ async function saveDeckAfterValidation(dir, opts, projectDir, visibility) {
929
966
  // Packed now, from the same files as the bundle, with the castle.json this save will write, and
930
967
  // uploaded as is after the deck is published.
931
968
  const sourceArchive = await traceSaveStage('source_archive', () => packSourceForSave(projectDir, castleJsonAfterSave(castleJson, deckId, cardId, title)), (value) => ({ bytes: value.byteLength }));
969
+ // Before anything is published: the source about to be uploaded against the live deck's.
970
+ const guarded = await saveDropCheck(existingDeckId, sourceArchive, castleJson, opts, expectedS3Key);
971
+ if (!guarded.ok)
972
+ return;
973
+ expectedS3Key = guarded.expectedS3Key;
932
974
  // Capturing and uploading the cover depends only on the already-running serve. Start it as
933
975
  // soon as the bundle has passed, while the independent scene upload is being authorized and
934
976
  // transferred. The promise is deliberately non-throwing: a thumbnail must never make the
@@ -0,0 +1,116 @@
1
+ export interface Drop {
2
+ /** The file, relative to the deck, with forward slashes. */
3
+ file: string;
4
+ /** A JSON pointer into the file's value, or '' when the whole file is gone. */
5
+ pointer: string;
6
+ /** What the live deck has there, shortened for a message. */
7
+ live: string;
8
+ /** What the candidate has instead: 'missing' or a shortened value. */
9
+ candidate: string;
10
+ }
11
+ export interface CastleJsonGuardShape {
12
+ saveGuard?: {
13
+ refuseDrops?: unknown;
14
+ } | null;
15
+ }
16
+ /** Whether a deck asked for the guard: either side's castle.json, or the save's flag. */
17
+ export declare function dropGuardRequested(live: CastleJsonGuardShape | null, candidate: CastleJsonGuardShape | null, flag: boolean): boolean;
18
+ /**
19
+ * A JavaScript literal as data: objects, arrays, strings (' " and ` without
20
+ * interpolation), numbers, true / false / null / undefined, comments, trailing commas
21
+ * and unquoted keys. Never evaluates anything. Throws on anything else.
22
+ */
23
+ export declare function parseDataLiteral(text: string): unknown;
24
+ type DataRead = {
25
+ ok: true;
26
+ value: unknown;
27
+ } | {
28
+ ok: false;
29
+ };
30
+ /** A file's value when it is JSON or a data module; not ok for anything else. */
31
+ export declare function readDataFile(file: string, bytes: Buffer): DataRead;
32
+ export declare function shorten(v: unknown): string;
33
+ /** Where the candidate's value loses what the live one has. */
34
+ export declare function valueDrops(file: string, live: unknown, candidate: unknown, pointer?: string): Drop[];
35
+ /** Every file under `dir`, relative and with forward slashes, without the top-level excludes. */
36
+ export declare function listFiles(dir: string, excludeTop: readonly string[]): string[];
37
+ export declare function findDrops(liveDir: string, candidateDir: string, excludeTop?: readonly string[]): Drop[];
38
+ export interface AllowedSplit {
39
+ refused: Drop[];
40
+ allowed: {
41
+ drop: Drop;
42
+ by: string;
43
+ }[];
44
+ /** Names that covered nothing: a typo, or a removal that is not happening. */
45
+ unused: string[];
46
+ }
47
+ /**
48
+ * `path` covers that file, or every file under it when it names a folder; `path#ptr`
49
+ * covers that pointer and everything below it in that file.
50
+ */
51
+ export declare function splitAllowed(drops: Drop[], allows: string[]): AllowedSplit;
52
+ export declare function describeDrop(drop: Drop): string;
53
+ export declare function refusalMessage(deckId: string, refused: Drop[]): string;
54
+ /** save-deck's exit code for a save the guard refused. */
55
+ export declare const EXIT_SAVE_DROPS = 7;
56
+ export interface SaveDropCheck {
57
+ deckId: string;
58
+ /** The source archive save-deck is about to upload. */
59
+ candidateArchive: Buffer;
60
+ /** The folder's castle.json. */
61
+ candidateCastleJson: CastleJsonGuardShape | null;
62
+ /** --refuse-drops */
63
+ refuseDrops: boolean;
64
+ /** Every --allow-drop. */
65
+ allowDrops: string[];
66
+ /** Top-level names no source archive carries. */
67
+ excludeTop: readonly string[];
68
+ /**
69
+ * The live deck's saved source: a .tar.gz file the check may delete and the saved source's key,
70
+ * or null when the deck has no saved source.
71
+ */
72
+ fetchLiveArchive: () => Promise<{
73
+ file: string;
74
+ s3Key: string;
75
+ } | null>;
76
+ untar: (archive: string, dir: string) => Promise<void>;
77
+ }
78
+ export interface SaveDropResult {
79
+ /** False, with process.exitCode set: the save must stop. */
80
+ ok: boolean;
81
+ /**
82
+ * When the guard compared: the key of the saved source it compared with, or null when it saw no
83
+ * saved source. The source commit must expect exactly that, so a save made in between is
84
+ * refused rather than overwritten unseen. Null when the guard did not compare.
85
+ */
86
+ compared: {
87
+ s3Key: string | null;
88
+ } | null;
89
+ }
90
+ /**
91
+ * The guard as save-deck runs it, for a deck that already has an id. It is on when the flag, the
92
+ * folder's castle.json or the live deck's castle.json asks; the live one counts so that a
93
+ * candidate rebuilt from a tree without the setting cannot switch the guard off by the very drop
94
+ * it exists to catch. So every save of an existing deck, cloud saves included, reads the live
95
+ * source.
96
+ *
97
+ * A deck with no saved source has nothing to drop (a remix's first save). Once the folder or the
98
+ * flags ask, the check fails closed: a source that cannot be read or unpacked refuses. When
99
+ * only the live deck could have asked, an unreadable source warns and saves -- every save of every
100
+ * deck would otherwise hang on that read -- which leaves the folder's own opt-in as the guarantee.
101
+ */
102
+ export declare function checkSaveDrops(check: SaveDropCheck): Promise<SaveDropResult>;
103
+ /**
104
+ * The source commit's precondition after the guard. A save that sends none (an unmarked or forced
105
+ * folder) expects what the guard compared with, a key or no source at all. One that already
106
+ * expects a source keeps it, and the guard having read another refuses the save, before anything
107
+ * is published.
108
+ */
109
+ export declare function bindSourcePrecondition(expectedS3Key: string | null | undefined, compared: {
110
+ s3Key: string | null;
111
+ } | null): {
112
+ expectedS3Key: string | null | undefined;
113
+ } | {
114
+ refuse: string;
115
+ };
116
+ export {};