castle-web-cli 0.4.245 → 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/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': {
@@ -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 {};
@@ -0,0 +1,582 @@
1
+ // The save-drop guard: a save that would quietly lose something the live deck has.
2
+ //
3
+ // A deck whose saved copy carries pieces that exist nowhere else -- generator output
4
+ // written into the saved folder (a routes table, named places, a room id), settings or
5
+ // engine flags laid over a scene by hand, a precomputed table -- loses them the moment
6
+ // someone saves a candidate rebuilt from a tree that never had them. Nothing about the
7
+ // scene has to change for that to happen, and every check of the candidate passes,
8
+ // because the candidate is internally consistent: it just lacks the pieces.
9
+ //
10
+ // So, when a deck opts in, save-deck compares the source it is about to upload with
11
+ // the live deck's saved source and refuses a candidate that drops any of it:
12
+ //
13
+ // - a file the live source has and the candidate does not;
14
+ // - in a JSON file (any file whose bytes parse as JSON: castle.json, a scene, a
15
+ // table) or a data module (a .js file that is nothing but `export default
16
+ // <literal>`), an object key the live value has and the candidate lacks, or a
17
+ // value that is non-empty live and null / empty in the candidate.
18
+ //
19
+ // Arrays are compared only for emptiness, never element by element: a scene's actor
20
+ // list changes on every save. Changing a value to another non-empty value is an edit,
21
+ // not a drop. What the guard knows is generic -- files, JSON and data literals --
22
+ // because the CLI knows no kit's vocabulary.
23
+ //
24
+ // An intended removal is named on the command line (`--allow-drop <path>` or
25
+ // `--allow-drop <path>#<pointer>`), and every one it covered is printed in the save's
26
+ // output, so the record of what a save meant to remove is the save itself.
27
+ import * as fs from 'fs';
28
+ import * as os from 'os';
29
+ import * as path from 'path';
30
+ /** Lock files churn on every dependency change and carry nothing of the deck's own. */
31
+ const IGNORED_FILES = new Set(['package-lock.json']);
32
+ /** Larger files are compared as files only (present or not), not parsed. */
33
+ const MAX_PARSED_BYTES = 64 * 1024 * 1024;
34
+ /** Whether a deck asked for the guard: either side's castle.json, or the save's flag. */
35
+ export function dropGuardRequested(live, candidate, flag) {
36
+ const asks = (json) => json?.saveGuard?.refuseDrops === true;
37
+ return flag || asks(live) || asks(candidate);
38
+ }
39
+ // ---------------------------------------------------------------------------
40
+ // Reading data files
41
+ /**
42
+ * A JavaScript literal as data: objects, arrays, strings (' " and ` without
43
+ * interpolation), numbers, true / false / null / undefined, comments, trailing commas
44
+ * and unquoted keys. Never evaluates anything. Throws on anything else.
45
+ */
46
+ export function parseDataLiteral(text) {
47
+ let i = 0;
48
+ const fail = (what) => {
49
+ throw new Error(`${what} at ${i}`);
50
+ };
51
+ const skip = () => {
52
+ for (;;) {
53
+ const c = text[i];
54
+ if (c === ' ' || c === '\n' || c === '\r' || c === '\t' || c === '') {
55
+ i++;
56
+ }
57
+ else if (c === '/' && text[i + 1] === '/') {
58
+ while (i < text.length && text[i] !== '\n')
59
+ i++;
60
+ }
61
+ else if (c === '/' && text[i + 1] === '*') {
62
+ const end = text.indexOf('*/', i + 2);
63
+ if (end < 0)
64
+ fail('unterminated comment');
65
+ i = end + 2;
66
+ }
67
+ else {
68
+ return;
69
+ }
70
+ }
71
+ };
72
+ const string = () => {
73
+ const quote = text[i++];
74
+ let out = '';
75
+ while (i < text.length && text[i] !== quote) {
76
+ const c = text[i++];
77
+ if (quote === '`' && c === '$' && text[i] === '{')
78
+ fail('template interpolation');
79
+ if (c !== '\\') {
80
+ out += c;
81
+ continue;
82
+ }
83
+ const e = text[i++];
84
+ if (e === 'n')
85
+ out += '\n';
86
+ else if (e === 't')
87
+ out += '\t';
88
+ else if (e === 'r')
89
+ out += '\r';
90
+ else if (e === 'b')
91
+ out += '\b';
92
+ else if (e === 'f')
93
+ out += '\f';
94
+ else if (e === 'v')
95
+ out += '\v';
96
+ else if (e === '0' && !/[0-9]/.test(text[i] ?? ''))
97
+ out += '\0';
98
+ else if (e === 'u') {
99
+ if (text[i] === '{') {
100
+ const end = text.indexOf('}', i);
101
+ if (end < 0)
102
+ fail('bad escape');
103
+ out += String.fromCodePoint(parseInt(text.slice(i + 1, end), 16));
104
+ i = end + 1;
105
+ }
106
+ else {
107
+ const hex = text.slice(i, i + 4);
108
+ if (!/^[0-9a-fA-F]{4}$/.test(hex))
109
+ fail('bad escape');
110
+ out += String.fromCharCode(parseInt(hex, 16));
111
+ i += 4;
112
+ }
113
+ }
114
+ else if (e === 'x') {
115
+ const hex = text.slice(i, i + 2);
116
+ if (!/^[0-9a-fA-F]{2}$/.test(hex))
117
+ fail('bad escape');
118
+ out += String.fromCharCode(parseInt(hex, 16));
119
+ i += 2;
120
+ }
121
+ else if (e === '\n') {
122
+ // a line continuation
123
+ }
124
+ else if (e === '\r') {
125
+ if (text[i] === '\n')
126
+ i++;
127
+ }
128
+ else if (e === undefined) {
129
+ fail('unterminated string');
130
+ }
131
+ else {
132
+ out += e;
133
+ }
134
+ }
135
+ if (text[i] !== quote)
136
+ fail('unterminated string');
137
+ i++;
138
+ return out;
139
+ };
140
+ const value = (depth) => {
141
+ if (depth > 512)
142
+ fail('nesting too deep');
143
+ skip();
144
+ const c = text[i];
145
+ if (c === '{') {
146
+ i++;
147
+ const out = {};
148
+ for (;;) {
149
+ skip();
150
+ if (text[i] === '}') {
151
+ i++;
152
+ return out;
153
+ }
154
+ let key;
155
+ if (text[i] === '"' || text[i] === "'" || text[i] === '`')
156
+ key = string();
157
+ else {
158
+ const m = /^[A-Za-z_$][\w$]*|^-?\d+(\.\d+)?/.exec(text.slice(i, i + 256));
159
+ if (!m)
160
+ fail('bad key');
161
+ key = String(m[0].match(/^-?\d/) ? Number(m[0]) : m[0]);
162
+ i += m[0].length;
163
+ }
164
+ skip();
165
+ if (text[i] !== ':')
166
+ fail('expected :');
167
+ i++;
168
+ Object.defineProperty(out, key, { value: value(depth + 1), enumerable: true, writable: true, configurable: true });
169
+ skip();
170
+ if (text[i] === ',')
171
+ i++;
172
+ else if (text[i] !== '}')
173
+ fail('expected , or }');
174
+ }
175
+ }
176
+ if (c === '[') {
177
+ i++;
178
+ const out = [];
179
+ for (;;) {
180
+ skip();
181
+ if (text[i] === ']') {
182
+ i++;
183
+ return out;
184
+ }
185
+ out.push(value(depth + 1));
186
+ skip();
187
+ if (text[i] === ',')
188
+ i++;
189
+ else if (text[i] !== ']')
190
+ fail('expected , or ]');
191
+ }
192
+ }
193
+ if (c === '"' || c === "'" || c === '`')
194
+ return string();
195
+ const m = /^(?:true|false|null|undefined|-?(?:Infinity|NaN)|[-+]?(?:0[xX][0-9a-fA-F]+|(?:\d[\d_]*\.?[\d_]*|\.\d[\d_]*)(?:[eE][-+]?\d+)?))/.exec(text.slice(i, i + 64));
196
+ if (!m)
197
+ fail('unexpected token');
198
+ i += m[0].length;
199
+ const word = m[0];
200
+ if (word === 'true')
201
+ return true;
202
+ if (word === 'false')
203
+ return false;
204
+ if (word === 'null')
205
+ return null;
206
+ if (word === 'undefined')
207
+ return undefined;
208
+ return Number(word.replace(/_/g, ''));
209
+ };
210
+ const result = value(0);
211
+ skip();
212
+ if (text[i] === ';')
213
+ i++;
214
+ skip();
215
+ if (i !== text.length)
216
+ fail('trailing text');
217
+ return result;
218
+ }
219
+ const DATA_MODULE = /^export\s+default(?![\w$])\s*/;
220
+ /** A .js file that is nothing but `export default <literal>`, after its comments. */
221
+ function readDataModule(text) {
222
+ // Leading comments only: a comment inside the literal is the parser's to skip.
223
+ let i = 0;
224
+ for (;;) {
225
+ const rest = text.slice(i);
226
+ const ws = /^\s+/.exec(rest);
227
+ if (ws) {
228
+ i += ws[0].length;
229
+ continue;
230
+ }
231
+ if (rest.startsWith('//')) {
232
+ const nl = text.indexOf('\n', i);
233
+ i = nl < 0 ? text.length : nl + 1;
234
+ continue;
235
+ }
236
+ if (rest.startsWith('/*')) {
237
+ const end = text.indexOf('*/', i + 2);
238
+ if (end < 0)
239
+ return { ok: false };
240
+ i = end + 2;
241
+ continue;
242
+ }
243
+ break;
244
+ }
245
+ const head = DATA_MODULE.exec(text.slice(i));
246
+ if (!head)
247
+ return { ok: false };
248
+ try {
249
+ return { ok: true, value: parseDataLiteral(text.slice(i + head[0].length)) };
250
+ }
251
+ catch {
252
+ return { ok: false };
253
+ }
254
+ }
255
+ /** A file's value when it is JSON or a data module; not ok for anything else. */
256
+ export function readDataFile(file, bytes) {
257
+ if (bytes.byteLength > MAX_PARSED_BYTES)
258
+ return { ok: false };
259
+ const text = bytes.toString('utf-8');
260
+ const first = /\S/.exec(text)?.[0];
261
+ if (first === '{' || first === '[') {
262
+ try {
263
+ return { ok: true, value: JSON.parse(text) };
264
+ }
265
+ catch {
266
+ // not JSON after all
267
+ }
268
+ }
269
+ if (/\.(?:m?js)$/.test(file))
270
+ return readDataModule(text);
271
+ return { ok: false };
272
+ }
273
+ // ---------------------------------------------------------------------------
274
+ // Comparing
275
+ function isPlainObject(v) {
276
+ return typeof v === 'object' && v !== null && !Array.isArray(v);
277
+ }
278
+ /** Null, undefined, '', [] or {}: nothing a candidate could lose. */
279
+ function isEmpty(v) {
280
+ if (v === null || v === undefined || v === '')
281
+ return true;
282
+ if (Array.isArray(v))
283
+ return v.length === 0;
284
+ if (isPlainObject(v))
285
+ return Object.keys(v).length === 0;
286
+ return false;
287
+ }
288
+ function pointerPart(key) {
289
+ return key.replace(/~/g, '~0').replace(/\//g, '~1');
290
+ }
291
+ export function shorten(v) {
292
+ if (v === undefined)
293
+ return 'missing';
294
+ if (Array.isArray(v))
295
+ return `[${v.length} item${v.length === 1 ? '' : 's'}]`;
296
+ if (isPlainObject(v)) {
297
+ const n = Object.keys(v).length;
298
+ // Not a template: the sandbox GraphQL scanner reads a braced template as a query.
299
+ return '{' + String(n) + (n === 1 ? ' key}' : ' keys}');
300
+ }
301
+ const s = JSON.stringify(v) ?? typeof v;
302
+ return s.length > 60 ? `${s.slice(0, 57)}...` : s;
303
+ }
304
+ /** Where the candidate's value loses what the live one has. */
305
+ export function valueDrops(file, live, candidate, pointer = '') {
306
+ if (isEmpty(live))
307
+ return [];
308
+ if (isEmpty(candidate)) {
309
+ return [{ file, pointer, live: shorten(live), candidate: shorten(candidate) }];
310
+ }
311
+ // A table replaced by a scalar (or a list by an object) loses everything in it.
312
+ const shape = (v) => (Array.isArray(v) ? 'array' : isPlainObject(v) ? 'object' : 'scalar');
313
+ if (shape(live) !== 'scalar' && shape(candidate) !== shape(live)) {
314
+ return [{ file, pointer, live: shorten(live), candidate: shorten(candidate) }];
315
+ }
316
+ if (!isPlainObject(live) || !isPlainObject(candidate))
317
+ return [];
318
+ const drops = [];
319
+ for (const key of Object.keys(live)) {
320
+ const at = `${pointer}/${pointerPart(key)}`;
321
+ if (!Object.prototype.hasOwnProperty.call(candidate, key)) {
322
+ // A key is dropped even when it held null or nothing: code can read its presence.
323
+ drops.push({ file, pointer: at, live: shorten(live[key]), candidate: 'missing' });
324
+ continue;
325
+ }
326
+ drops.push(...valueDrops(file, live[key], candidate[key], at));
327
+ }
328
+ return drops;
329
+ }
330
+ /** Every file under `dir`, relative and with forward slashes, without the top-level excludes. */
331
+ export function listFiles(dir, excludeTop) {
332
+ const out = [];
333
+ const walk = (rel) => {
334
+ for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
335
+ if (!rel && excludeTop.includes(entry.name))
336
+ continue;
337
+ const child = rel ? `${rel}/${entry.name}` : entry.name;
338
+ if (entry.isDirectory())
339
+ walk(child);
340
+ else if (entry.isFile() || entry.isSymbolicLink())
341
+ out.push(child);
342
+ }
343
+ };
344
+ walk('');
345
+ return out.sort();
346
+ }
347
+ function lstatOrNull(file) {
348
+ try {
349
+ return fs.lstatSync(file);
350
+ }
351
+ catch {
352
+ return null;
353
+ }
354
+ }
355
+ /** What `candidateDir` drops of `liveDir`: two extracted source archives. */
356
+ /**
357
+ * The candidate's file at `rel`, resolved inside the candidate: a link (the file itself or a
358
+ * folder above it) stands for what it names only when that is a file within the candidate's own
359
+ * source. Anything else is why the live file is not there.
360
+ */
361
+ function candidateFile(candidateRoot, rel) {
362
+ const at = path.join(candidateRoot, rel);
363
+ let real;
364
+ try {
365
+ real = fs.realpathSync(at);
366
+ }
367
+ catch {
368
+ return { why: lstatOrNull(at) ? 'a dangling link' : 'missing' };
369
+ }
370
+ if (real !== candidateRoot && !real.startsWith(`${candidateRoot}${path.sep}`))
371
+ return { why: 'a link out of the source' };
372
+ return fs.statSync(real).isFile() ? { file: real } : { why: 'not a file' };
373
+ }
374
+ export function findDrops(liveDir, candidateDir, excludeTop = []) {
375
+ const drops = [];
376
+ const candidateRoot = fs.realpathSync(candidateDir);
377
+ for (const file of listFiles(liveDir, excludeTop)) {
378
+ if (IGNORED_FILES.has(path.posix.basename(file)))
379
+ continue;
380
+ // Live links are compared as links, never read through: a link can point anywhere.
381
+ if (fs.lstatSync(path.join(liveDir, file)).isSymbolicLink()) {
382
+ if (!lstatOrNull(path.join(candidateDir, file)))
383
+ drops.push({ file, pointer: '', live: 'a link', candidate: 'missing' });
384
+ continue;
385
+ }
386
+ const liveBytes = fs.readFileSync(path.join(liveDir, file));
387
+ const resolved = candidateFile(candidateRoot, file);
388
+ if ('why' in resolved) {
389
+ // An empty file is dropped too: its presence can be the point.
390
+ drops.push({ file, pointer: '', live: `${liveBytes.byteLength} bytes`, candidate: resolved.why });
391
+ continue;
392
+ }
393
+ const candidatePath = resolved.file;
394
+ const candidateBytes = fs.readFileSync(candidatePath);
395
+ if (liveBytes.equals(candidateBytes))
396
+ continue;
397
+ const live = readDataFile(file, liveBytes);
398
+ if (!live.ok)
399
+ continue;
400
+ const candidate = readDataFile(file, candidateBytes);
401
+ if (!candidate.ok) {
402
+ // The live file is data and the candidate's is not: whatever it holds now, the
403
+ // value the deck read is gone.
404
+ if (!isEmpty(live.value)) {
405
+ drops.push({ file, pointer: '', live: shorten(live.value), candidate: 'not data' });
406
+ }
407
+ continue;
408
+ }
409
+ drops.push(...valueDrops(file, live.value, candidate.value));
410
+ }
411
+ return drops;
412
+ }
413
+ /**
414
+ * `path` covers that file, or every file under it when it names a folder; `path#ptr`
415
+ * covers that pointer and everything below it in that file.
416
+ */
417
+ export function splitAllowed(drops, allows) {
418
+ const used = new Set();
419
+ const refused = [];
420
+ const allowed = [];
421
+ for (const drop of drops) {
422
+ const by = allows.find((allow) => covers(allow, drop));
423
+ if (by === undefined)
424
+ refused.push(drop);
425
+ else {
426
+ allowed.push({ drop, by });
427
+ used.add(by);
428
+ }
429
+ }
430
+ return { refused, allowed, unused: allows.filter((a) => !used.has(a)) };
431
+ }
432
+ function covers(allow, drop) {
433
+ const hash = allow.indexOf('#');
434
+ const file = (hash < 0 ? allow : allow.slice(0, hash)).replace(/^\.\//, '').replace(/\/+$/, '');
435
+ if (!file)
436
+ return false;
437
+ if (hash < 0)
438
+ return drop.file === file || drop.file.startsWith(`${file}/`);
439
+ if (drop.file !== file)
440
+ return false;
441
+ // A JSON pointer as written: '' is the whole file, '/' the key named ''.
442
+ const pointer = allow.slice(hash + 1);
443
+ if (!pointer)
444
+ return true;
445
+ return drop.pointer === pointer || drop.pointer.startsWith(`${pointer}/`);
446
+ }
447
+ export function describeDrop(drop) {
448
+ const where = drop.pointer ? `${drop.file}#${drop.pointer}` : drop.file;
449
+ return `${where}: live ${drop.live}, candidate ${drop.candidate}`;
450
+ }
451
+ const LISTED = 40;
452
+ export function refusalMessage(deckId, refused) {
453
+ const lines = [
454
+ `Refused: this save drops ${refused.length} piece${refused.length === 1 ? '' : 's'} the live deck ${deckId} has (castle.json "saveGuard": { "refuseDrops": true }).`,
455
+ 'Nothing was saved. Each is something the saved copy carries and this folder does not:',
456
+ ...refused.slice(0, LISTED).map((d) => ` - ${describeDrop(d)}`),
457
+ ];
458
+ if (refused.length > LISTED)
459
+ lines.push(` ... and ${refused.length - LISTED} more`);
460
+ lines.push('Rebuild the candidate from the saved copy (castle-web get-deck), or carry the pieces over.', 'If a removal is intended, name it: --allow-drop <path> or --allow-drop "<path>#<pointer>" (repeatable).');
461
+ return lines.join('\n');
462
+ }
463
+ /** save-deck's exit code for a save the guard refused. */
464
+ export const EXIT_SAVE_DROPS = 7;
465
+ /**
466
+ * The guard as save-deck runs it, for a deck that already has an id. It is on when the flag, the
467
+ * folder's castle.json or the live deck's castle.json asks; the live one counts so that a
468
+ * candidate rebuilt from a tree without the setting cannot switch the guard off by the very drop
469
+ * it exists to catch. So every save of an existing deck, cloud saves included, reads the live
470
+ * source.
471
+ *
472
+ * A deck with no saved source has nothing to drop (a remix's first save). Once the folder or the
473
+ * flags ask, the check fails closed: a source that cannot be read or unpacked refuses. When
474
+ * only the live deck could have asked, an unreadable source warns and saves -- every save of every
475
+ * deck would otherwise hang on that read -- which leaves the folder's own opt-in as the guarantee.
476
+ */
477
+ export async function checkSaveDrops(check) {
478
+ const allows = check.allowDrops;
479
+ const askedHere = dropGuardRequested(null, check.candidateCastleJson, check.refuseDrops);
480
+ const stop = (message) => {
481
+ console.error(message);
482
+ process.exitCode = EXIT_SAVE_DROPS;
483
+ return { ok: false, compared: null };
484
+ };
485
+ const pass = { ok: true, compared: null };
486
+ const unreadable = (why) => {
487
+ if (askedHere) {
488
+ return stop(`Refused: the save-drop guard could not read deck ${check.deckId}'s saved source (${why}). Nothing was saved.`);
489
+ }
490
+ console.warn(`Could not read the saved source to check for dropped pieces (${why}); saving.`);
491
+ return pass;
492
+ };
493
+ const work = fs.mkdtempSync(path.join(os.tmpdir(), 'castle-save-drops-'));
494
+ try {
495
+ let live;
496
+ try {
497
+ live = await check.fetchLiveArchive();
498
+ }
499
+ catch (e) {
500
+ return unreadable(e instanceof Error ? e.message : String(e));
501
+ }
502
+ if (!live) {
503
+ if (!askedHere)
504
+ return pass;
505
+ console.log(`Save-drop guard: deck ${check.deckId} has no saved source yet; nothing to drop.`);
506
+ return { ok: true, compared: { s3Key: null } };
507
+ }
508
+ const liveDir = path.join(work, 'live');
509
+ const candidateDir = path.join(work, 'candidate');
510
+ fs.mkdirSync(liveDir);
511
+ fs.mkdirSync(candidateDir);
512
+ try {
513
+ await check.untar(live.file, liveDir);
514
+ }
515
+ catch (e) {
516
+ return unreadable(e instanceof Error ? e.message : String(e));
517
+ }
518
+ finally {
519
+ try {
520
+ fs.unlinkSync(live.file);
521
+ }
522
+ catch { /* nothing to clean */ }
523
+ }
524
+ let liveCastleJson = null;
525
+ try {
526
+ liveCastleJson = JSON.parse(fs.readFileSync(path.join(liveDir, 'castle.json'), 'utf-8'));
527
+ }
528
+ catch {
529
+ // no castle.json, or not JSON: the live deck asks for nothing
530
+ }
531
+ if (!dropGuardRequested(liveCastleJson, null, askedHere)) {
532
+ if (allows.length > 0)
533
+ console.warn('--allow-drop has no effect: the save-drop guard is not on for this deck.');
534
+ return pass;
535
+ }
536
+ const candidateFile = path.join(work, 'candidate.tar.gz');
537
+ fs.writeFileSync(candidateFile, check.candidateArchive);
538
+ await check.untar(candidateFile, candidateDir);
539
+ const drops = findDrops(liveDir, candidateDir, check.excludeTop);
540
+ const { refused, allowed, unused } = splitAllowed(drops, allows);
541
+ for (const name of unused)
542
+ console.warn(`--allow-drop ${name} named nothing this save drops.`);
543
+ if (refused.length > 0)
544
+ return stop(refusalMessage(check.deckId, refused));
545
+ if (allowed.length > 0) {
546
+ console.log(`Save-drop guard: ${allowed.length} intended removal${allowed.length === 1 ? '' : 's'} named with --allow-drop:`);
547
+ for (const { drop, by } of allowed)
548
+ console.log(` - ${describeDrop(drop)} (--allow-drop ${by})`);
549
+ }
550
+ else {
551
+ console.log('Save-drop guard: nothing the live deck has is dropped.');
552
+ }
553
+ return { ok: true, compared: { s3Key: live.s3Key } };
554
+ }
555
+ catch (e) {
556
+ const why = e instanceof Error ? e.message : String(e);
557
+ return stop(`Refused: the save-drop guard failed (${why}). Nothing was saved.`);
558
+ }
559
+ finally {
560
+ fs.rmSync(work, { recursive: true, force: true });
561
+ }
562
+ }
563
+ /**
564
+ * The source commit's precondition after the guard. A save that sends none (an unmarked or forced
565
+ * folder) expects what the guard compared with, a key or no source at all. One that already
566
+ * expects a source keeps it, and the guard having read another refuses the save, before anything
567
+ * is published.
568
+ */
569
+ export function bindSourcePrecondition(expectedS3Key, compared) {
570
+ if (!compared)
571
+ return { expectedS3Key };
572
+ if (expectedS3Key === undefined)
573
+ return { expectedS3Key: compared.s3Key };
574
+ if (expectedS3Key === compared.s3Key)
575
+ return { expectedS3Key };
576
+ return {
577
+ refuse: `Refused: the save-drop guard compared this folder with saved source ${compared.s3Key ?? '(none)'}, but ` +
578
+ `this save expects ${expectedS3Key ?? '(none)'}: the deck was saved while this save ran, or the server ` +
579
+ 'has not caught up with a save just made. Nothing was saved. Wait a minute and save again, or refresh ' +
580
+ 'the folder with castle-web get-deck first.',
581
+ };
582
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.245",
3
+ "version": "0.4.246",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"
@@ -12,7 +12,7 @@
12
12
  "scripts": {
13
13
  "build": "rm -rf dist && tsc && chmod +x dist/index.js && vite build && vite build -c vite.cover-bridge.config.ts && cp -R src/castle-host dist/castle-host && chmod -R u+w kits 2>/dev/null; rm -rf kits && cp -R ../kits kits && chmod -R u+w kits && rm -rf kits/*/imports && node ../scripts/vendor-three.mjs",
14
14
  "dev": "tsc --watch",
15
- "check": "node ../scripts/sync-shared.mjs --check && node ../scripts/tests/icon-registry.mjs && node ../scripts/tests/sandbox-graphql-fields.mjs && node ../scripts/tests/kit-package-json.mjs && node ../scripts/tests/kit-catalog.mjs && node ../scripts/tests/import-order.mjs && node ../scripts/tests/import-deck-ref.mjs && node ../scripts/tests/restore-pinned-import.mjs && node ../scripts/tests/hub-server-config.mjs && node ../scripts/tests/save-failure-reason.mjs && node ../scripts/tests/flow-draft-status.mjs && node ../scripts/tests/router-fences.mjs && node ../scripts/tests/held-tasks.mjs && node ../scripts/tests/held-task-prompts.mjs && node ../scripts/tests/router-stops.mjs && node ../scripts/tests/task-steer.mjs && node ../scripts/tests/task-steer-store.mjs && node ../scripts/tests/task-steer-line.mjs && node ../scripts/tests/router-task-endings.mjs && node ../scripts/tests/router-task-report.mjs && node ../scripts/tests/task-resume.mjs && node ../scripts/tests/task-model-request.mjs && node ../scripts/tests/plan-answered-questions.mjs && node ../scripts/tests/plan-no-standing-nudge.mjs && node ../scripts/tests/sdk-readme-limits.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.mjs && node ../scripts/tests/cli-login-pkce.mjs && node ../scripts/tests/publish-timeout.mjs && node ../scripts/tests/bundle-latin1.mjs && eslint . && jscpd && tsc --noEmit && tsc --noEmit -p src/shell/tsconfig.json"
15
+ "check": "node ../scripts/sync-shared.mjs --check && node ../scripts/tests/icon-registry.mjs && node ../scripts/tests/sandbox-graphql-fields.mjs && node ../scripts/tests/kit-package-json.mjs && node ../scripts/tests/kit-catalog.mjs && node ../scripts/tests/import-order.mjs && node ../scripts/tests/import-deck-ref.mjs && node ../scripts/tests/restore-pinned-import.mjs && node ../scripts/tests/hub-server-config.mjs && node ../scripts/tests/save-failure-reason.mjs && node ../scripts/tests/save-drop-guard.mjs && node ../scripts/tests/flow-draft-status.mjs && node ../scripts/tests/router-fences.mjs && node ../scripts/tests/held-tasks.mjs && node ../scripts/tests/held-task-prompts.mjs && node ../scripts/tests/router-stops.mjs && node ../scripts/tests/task-steer.mjs && node ../scripts/tests/task-steer-store.mjs && node ../scripts/tests/task-steer-line.mjs && node ../scripts/tests/router-task-endings.mjs && node ../scripts/tests/router-task-report.mjs && node ../scripts/tests/task-resume.mjs && node ../scripts/tests/task-model-request.mjs && node ../scripts/tests/plan-answered-questions.mjs && node ../scripts/tests/plan-no-standing-nudge.mjs && node ../scripts/tests/sdk-readme-limits.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.mjs && node ../scripts/tests/cli-login-pkce.mjs && node ../scripts/tests/publish-timeout.mjs && node ../scripts/tests/bundle-latin1.mjs && eslint . && jscpd && tsc --noEmit && tsc --noEmit -p src/shell/tsconfig.json"
16
16
  },
17
17
  "jscpd": {
18
18
  "path": [