castle-web-cli 0.4.244 → 0.4.246

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/api.d.ts CHANGED
@@ -267,6 +267,7 @@ export interface DeckMeta {
267
267
  }
268
268
  export declare function deckMeta(deckId: string): Promise<DeckMeta | null>;
269
269
  export declare function webDeckSource(deckId: string): Promise<WebDeckSource | null>;
270
+ export declare function webDeckSourceAtVersion(deckId: string, version: string): Promise<WebDeckSource | null>;
270
271
  export interface SavedSourceVersion {
271
272
  s3Key: string;
272
273
  archiveUrl: string;
package/dist/api.js CHANGED
@@ -450,6 +450,19 @@ export async function webDeckSource(deckId) {
450
450
  handleAPIError(data);
451
451
  return pickData(data, 'webDeckSource');
452
452
  }
453
+ // The deck's source as it was saved at `version` (a webDeckSource updatedAt, as an import
454
+ // pin records it). Ghost serves older versions of the castle account's kits to anyone who
455
+ // may read the kit, and of any deck to its publisher; null when it does not serve that
456
+ // version. A Ghost without the field fails this, and callers fall back to webDeckSource.
457
+ export async function webDeckSourceAtVersion(deckId, version) {
458
+ const data = await graphql(`query($deckId: ID!, $version: String!) {
459
+ webDeckSourceVersion(deckId: $deckId, version: $version) {
460
+ deckId archiveUrl s3Key updatedAt
461
+ }
462
+ }`, { deckId, version });
463
+ handleAPIError(data);
464
+ return pickData(data, 'webDeckSourceVersion');
465
+ }
453
466
  // Every saved version of the deck's source, newest first (Ghost lists at most 50), for its
454
467
  // creator or an edit collaborator. A Ghost without the field fails this, as does anyone else.
455
468
  export async function savedSourceHistory(deckId, timeoutMs) {
@@ -0,0 +1,13 @@
1
+ /** The shell renews its content origins when less than this remains on them. */
2
+ export declare const CONTENT_ORIGIN_REFRESH_BEFORE_SECONDS: number;
3
+ /**
4
+ * Margin between the two: the serve reuses a grant (same hostname, same
5
+ * browser storage and module cache) only while at least
6
+ * REFRESH_BEFORE + this remains, so every grant it hands out -- to a new
7
+ * shell, a reopened one, or a renewal -- starts outside the shell's renewal
8
+ * window by at least this much. It also absorbs a shell clock running up to
9
+ * this far ahead of the serve's.
10
+ */
11
+ export declare const CONTENT_ORIGIN_REUSE_MARGIN_SECONDS: number;
12
+ /** The least a grant handed to a shell has left: about 10h45m of reuse per 12h grant. */
13
+ export declare const MIN_CONTENT_GRANT_REMAINING_SECONDS: number;
@@ -0,0 +1,15 @@
1
+ // Timing shared by the serve (which mints signed content-origin grants) and the
2
+ // shell (which renews them), so the two can never drift into a renewal loop.
3
+ /** The shell renews its content origins when less than this remains on them. */
4
+ export const CONTENT_ORIGIN_REFRESH_BEFORE_SECONDS = 60 * 60;
5
+ /**
6
+ * Margin between the two: the serve reuses a grant (same hostname, same
7
+ * browser storage and module cache) only while at least
8
+ * REFRESH_BEFORE + this remains, so every grant it hands out -- to a new
9
+ * shell, a reopened one, or a renewal -- starts outside the shell's renewal
10
+ * window by at least this much. It also absorbs a shell clock running up to
11
+ * this far ahead of the serve's.
12
+ */
13
+ export const CONTENT_ORIGIN_REUSE_MARGIN_SECONDS = 15 * 60;
14
+ /** The least a grant handed to a shell has left: about 10h45m of reuse per 12h grant. */
15
+ export const MIN_CONTENT_GRANT_REMAINING_SECONDS = CONTENT_ORIGIN_REFRESH_BEFORE_SECONDS + CONTENT_ORIGIN_REUSE_MARGIN_SECONDS;
package/dist/imports.js CHANGED
@@ -8,6 +8,7 @@ import { normalizeDeckPackageJson } from './normalize.js';
8
8
  import { getKitsDir } from './localPaths.js';
9
9
  import { shippedFrameworkKit, shippedKitAlias } from './kitCatalog.js';
10
10
  import { SDK_PACKAGE } from './sdkResolve.js';
11
+ import { classifySaveFailure } from './saveFailure.js';
11
12
  import { importIsOnTrustedAccount, TRUSTED_IMPORT_ACCOUNT } from './importTrust.js';
12
13
  import { writePlatformDocs } from './platformDoc.js';
13
14
  import { findImportUpdateHook, runImportUpdateHook, } from './importUpdateHook.js';
@@ -530,19 +531,40 @@ export async function restoreMissingImports(deckDir) {
530
531
  if (fs.existsSync(destDir))
531
532
  continue;
532
533
  if (pin?.deckId) {
533
- const source = await api.webDeckSource(pin.deckId).catch(() => null);
534
+ // The pinned save first: Ghost indexes each save of a deck and serves a kit's
535
+ // older ones by version. When Ghost answers that it will not -- null (another
536
+ // account's deck, a save from before the index), an error, a Ghost or sandbox
537
+ // proxy without the field -- the latest is placed instead, as before. When Ghost
538
+ // could not be reached, nothing is placed: a later install skips an import that
539
+ // is already there, so placing the latest now would keep it past the outage.
540
+ let pinned = null;
541
+ if (pin.version) {
542
+ try {
543
+ pinned = await api.webDeckSourceAtVersion(pin.deckId, pin.version);
544
+ }
545
+ catch (e) {
546
+ const { reason } = classifySaveFailure(null, e);
547
+ // A gateway error (the sandbox proxy's 502 when Ghost is down) reaches here as
548
+ // api.graphql's "Castle API <status>"; it is an outage, not an answer.
549
+ const gatewayFailed = e instanceof Error && /^Castle API 5\d\d\b/.test(e.message);
550
+ if (reason === 'network' || reason === 'upload_timeout' || gatewayFailed) {
551
+ console.warn(`Could not reach Castle to fetch import "${alias}" at ${pin.version}; skipped it. Run \`castle-web install\` again.`);
552
+ continue;
553
+ }
554
+ }
555
+ }
556
+ const source = pinned ?? (await api.webDeckSource(pin.deckId).catch(() => null));
534
557
  if (!source) {
535
558
  console.warn(`Could not fetch import "${alias}" (${pin.deckId}); it has no source on the server.`);
536
559
  continue;
537
560
  }
538
561
  await fetchDeckSourceInto(source.archiveUrl, destDir);
539
- // The server only serves its latest archive, so what landed here is
540
- // `source.updatedAt`, not necessarily what the pin says. Record the
541
- // truth: the pin stays as committed, and publish-kits compares the two
542
- // to refuse bundling against files no pin describes.
562
+ // A fallback places `source.updatedAt`, not necessarily what the pin says.
563
+ // Record the truth: the pin stays as committed, and publish-kits compares
564
+ // the two to refuse bundling against files no pin describes.
543
565
  writeImportVersion(destDir, { deckId: pin.deckId, version: source.updatedAt });
544
566
  if (source.updatedAt !== pin.version) {
545
- console.warn(`Import "${alias}" is pinned at ${pin.version}, but the server only has ${source.updatedAt}, so that is what was placed. ` +
567
+ console.warn(`Import "${alias}" is pinned at ${pin.version}, but the server does not serve that version, so ${source.updatedAt} was placed. ` +
546
568
  '`castle-web check` and `save-deck` refuse until the two agree (see `--pin-installed-imports`).');
547
569
  }
548
570
  }
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',
@@ -187,10 +188,10 @@ function usageText() {
187
188
  return `Usage:
188
189
  castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME] [--port PORT] (kits: ${initKits}; default physics-2d)
189
190
  castle-web init <dir> --remix <deckId> [--deck-id ID] [--card-id ID] [--port PORT] (starts from a published deck instead of a kit)
190
- castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
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
@@ -585,7 +615,25 @@ async function main() {
585
615
  case 'serve': {
586
616
  const dir = findPositionalDir();
587
617
  const port = getFlagValue('--port');
588
- const host = getFlagValue('--host');
618
+ // Only the spaced form is parsed; reject the rest rather than drop it
619
+ // silently (with --lan, a dropped --host=127.0.0.1 would expose the serve).
620
+ const unparsed = args.find((arg) => /^--(?:host|lan)=/.test(arg));
621
+ if (unparsed) {
622
+ console.error(`Unsupported flag spelling ${unparsed.split('=')[0]}=...; pass it as "${unparsed.split('=')[0]} VALUE".`);
623
+ process.exit(1);
624
+ }
625
+ let host = getFlagValue('--host');
626
+ if (hasFlag('--host') && (host === undefined || host.trim() === '' || host.startsWith('--'))) {
627
+ console.error('--host needs an address, for example --host 127.0.0.1 (or --lan for every interface).');
628
+ process.exit(1);
629
+ }
630
+ if (hasFlag('--lan')) {
631
+ if (host !== undefined && host !== '0.0.0.0') {
632
+ console.error('--lan means --host 0.0.0.0; pass one or the other.');
633
+ process.exit(1);
634
+ }
635
+ host = '0.0.0.0';
636
+ }
589
637
  const open = args.includes('--open');
590
638
  const detach = args.includes('--detach');
591
639
  await serve(dir, { port, host, open, detach });
@@ -598,7 +646,15 @@ async function main() {
598
646
  const visibility = getFlagValue('--visibility');
599
647
  const pinInstalledImports = hasFlag('--pin-installed-imports');
600
648
  const chunkedBundle = hasFlag('--chunked-bundle');
601
- 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
+ });
602
658
  break;
603
659
  }
604
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.56';
67
+ const PUBLISHED_SDK_VERSION = '0.4.57';
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.
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Where the serve keeps per-project runtime state: `.castle/runtime/`, which
3
+ * cloud checkpoint capture leaves out (castle-sandboxes checkpointCapture.ts),
4
+ * so these files never block a checkpoint and never travel with the deck.
5
+ */
6
+ export declare const PROJECT_STATE_SEGMENTS: readonly string[];
7
+ /** Where an earlier build of this branch kept the same files (migrated on start). */
8
+ export declare const LEGACY_STATE_SEGMENTS: readonly string[];
9
+ export type StateDir = {
10
+ status: 'ok';
11
+ dir: string;
12
+ } | {
13
+ status: 'missing';
14
+ } | {
15
+ status: 'unsafe';
16
+ reason: string;
17
+ };
18
+ /**
19
+ * The directory `segments` names under `projectDir`, if every component is a
20
+ * real directory (not a symlink). With `create`, missing components are made.
21
+ * `missing` only without `create`; `unsafe` for a symlink or non-directory.
22
+ */
23
+ export declare function projectStateDir(projectDir: string, segments: readonly string[], create: boolean): StateDir;
24
+ /**
25
+ * The text of a small regular file, or null for anything else: missing, a
26
+ * symlink, a FIFO or device (opened non-blocking, so it can never hang the
27
+ * serve), a directory, or larger than `maxBytes`.
28
+ */
29
+ export declare function readSmallStateFile(file: string, maxBytes?: number): string | null;
30
+ /** Whether anything at all (file, link, FIFO...) exists at `file`, without following or opening it. */
31
+ export declare function statePathPresent(file: string): boolean;
32
+ /** Remove a leftover state entry (a file or a symlink; never what a link points at). */
33
+ export declare function removeStateEntry(file: string): boolean;
@@ -0,0 +1,97 @@
1
+ // Small serve state files kept inside a project, which deck code (and anything
2
+ // else that can write the project) can tamper with. Every path is checked
3
+ // component by component below the project root -- a symlinked `.castle` or
4
+ // `.castle/runtime` is refused, never followed -- and a file is opened without
5
+ // following a symlink or blocking on a FIFO, then must be a small regular file.
6
+ import * as fs from 'fs';
7
+ import * as path from 'path';
8
+ /**
9
+ * Where the serve keeps per-project runtime state: `.castle/runtime/`, which
10
+ * cloud checkpoint capture leaves out (castle-sandboxes checkpointCapture.ts),
11
+ * so these files never block a checkpoint and never travel with the deck.
12
+ */
13
+ export const PROJECT_STATE_SEGMENTS = ['.castle', 'runtime'];
14
+ /** Where an earlier build of this branch kept the same files (migrated on start). */
15
+ export const LEGACY_STATE_SEGMENTS = ['.castle'];
16
+ /**
17
+ * The directory `segments` names under `projectDir`, if every component is a
18
+ * real directory (not a symlink). With `create`, missing components are made.
19
+ * `missing` only without `create`; `unsafe` for a symlink or non-directory.
20
+ */
21
+ export function projectStateDir(projectDir, segments, create) {
22
+ let current = projectDir;
23
+ for (const segment of segments) {
24
+ current = path.join(current, segment);
25
+ let stat;
26
+ try {
27
+ stat = fs.lstatSync(current);
28
+ }
29
+ catch (error) {
30
+ if (error.code !== 'ENOENT') {
31
+ return { status: 'unsafe', reason: `cannot inspect ${current}` };
32
+ }
33
+ if (!create)
34
+ return { status: 'missing' };
35
+ try {
36
+ fs.mkdirSync(current);
37
+ stat = fs.lstatSync(current);
38
+ }
39
+ catch (mkdirError) {
40
+ return {
41
+ status: 'unsafe',
42
+ reason: `cannot create ${current}: ${mkdirError instanceof Error ? mkdirError.message : String(mkdirError)}`,
43
+ };
44
+ }
45
+ }
46
+ if (stat.isSymbolicLink())
47
+ return { status: 'unsafe', reason: `${current} is a symlink` };
48
+ if (!stat.isDirectory())
49
+ return { status: 'unsafe', reason: `${current} is not a directory` };
50
+ }
51
+ return { status: 'ok', dir: current };
52
+ }
53
+ /**
54
+ * The text of a small regular file, or null for anything else: missing, a
55
+ * symlink, a FIFO or device (opened non-blocking, so it can never hang the
56
+ * serve), a directory, or larger than `maxBytes`.
57
+ */
58
+ export function readSmallStateFile(file, maxBytes = 4096) {
59
+ let fd = null;
60
+ try {
61
+ fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
62
+ const stat = fs.fstatSync(fd);
63
+ if (!stat.isFile() || stat.size > maxBytes)
64
+ return null;
65
+ return fs.readFileSync(fd, 'utf8');
66
+ }
67
+ catch {
68
+ return null;
69
+ }
70
+ finally {
71
+ if (fd !== null)
72
+ fs.closeSync(fd);
73
+ }
74
+ }
75
+ /** Whether anything at all (file, link, FIFO...) exists at `file`, without following or opening it. */
76
+ export function statePathPresent(file) {
77
+ try {
78
+ fs.lstatSync(file);
79
+ return true;
80
+ }
81
+ catch (error) {
82
+ return error.code !== 'ENOENT';
83
+ }
84
+ }
85
+ /** Remove a leftover state entry (a file or a symlink; never what a link points at). */
86
+ export function removeStateEntry(file) {
87
+ try {
88
+ const stat = fs.lstatSync(file);
89
+ if (stat.isDirectory())
90
+ return false;
91
+ fs.unlinkSync(file);
92
+ return true;
93
+ }
94
+ catch (error) {
95
+ return error.code === 'ENOENT';
96
+ }
97
+ }
@@ -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 {};