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/castle-host/host.js +362 -4
- package/dist/characterDoc.d.ts +1 -0
- package/dist/characterDoc.js +149 -0
- package/dist/cloudGit.d.ts +10 -0
- package/dist/cloudGit.js +210 -6
- package/dist/devSessionServer.js +3 -2
- package/dist/devSessionStorage.d.ts +7 -0
- package/dist/devSessionStorage.js +19 -0
- package/dist/index.js +40 -2
- package/dist/init.js +1 -1
- package/dist/platformDoc.d.ts +2 -0
- package/dist/platformDoc.js +26 -1
- package/dist/save-deck.d.ts +4 -0
- package/dist/save-deck.js +42 -0
- package/dist/saveDropGuard.d.ts +116 -0
- package/dist/saveDropGuard.js +582 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +174 -39
- package/kits/base/sdk/castle.d.ts +3 -0
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +37 -0
- package/kits/base/sdk/deckInvites.d.ts +27 -0
- package/kits/base/sdk/deckInvites.js +22 -0
- package/kits/base/sdk/runtime.js +49 -0
- package/kits/base/sdk/server/storage.d.ts +17 -4
- package/kits/base/sdk/server/storage.js +35 -7
- package/kits/hub-game/code/server/writerLease.js +156 -167
- package/kits/hub-game/docs/contract.md +33 -22
- package/kits/hub-game/scripts/test-writer-lease-server.mjs +11 -8
- package/kits/hub-game/scripts/test-writer-lease.mjs +310 -386
- package/kits/hub-game/scripts/writer-storage-fixture.mjs +38 -6
- package/package.json +2 -2
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
|
-
|
|
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) {
|
package/dist/devSessionServer.js
CHANGED
|
@@ -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
|
-
:
|
|
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, {
|
|
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.
|
|
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.
|
package/dist/platformDoc.d.ts
CHANGED
|
@@ -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[];
|
package/dist/platformDoc.js
CHANGED
|
@@ -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
|
package/dist/save-deck.d.ts
CHANGED
|
@@ -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 {};
|