castle-web-cli 0.4.193 → 0.4.194

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.
Files changed (75) hide show
  1. package/dist/agent.js +87 -4
  2. package/dist/api.d.ts +1 -0
  3. package/dist/api.js +5 -0
  4. package/dist/bundle.js +2 -1
  5. package/dist/castleJson.d.ts +1 -0
  6. package/dist/check.js +14 -6
  7. package/dist/devSessionServer.d.ts +6 -0
  8. package/dist/devSessionServer.js +23 -1
  9. package/dist/filesChanged.js +7 -3
  10. package/dist/importUpdateHook.d.ts +31 -0
  11. package/dist/importUpdateHook.js +135 -0
  12. package/dist/importUpdateHookRunner.d.ts +2 -0
  13. package/dist/importUpdateHookRunner.js +24 -0
  14. package/dist/imports.js +56 -6
  15. package/dist/index.js +58 -7
  16. package/dist/init.d.ts +1 -0
  17. package/dist/init.js +6 -1
  18. package/dist/native/loop.js +29 -9
  19. package/dist/platformDoc.js +4 -4
  20. package/dist/remix.js +4 -1
  21. package/dist/serve.js +133 -32
  22. package/dist/serverBundle.js +1 -1
  23. package/dist/versions.d.ts +14 -0
  24. package/dist/versions.js +21 -0
  25. package/dist/vitePlugins.d.ts +1 -0
  26. package/dist/vitePlugins.js +18 -0
  27. package/kits/multiplayer-2d/CLAUDE.md +9 -2
  28. package/kits/multiplayer-2d/blueprints/crate.scene +32 -4
  29. package/kits/multiplayer-2d/blueprints/other-player.scene +31 -4
  30. package/kits/multiplayer-2d/blueprints/player.scene +38 -6
  31. package/kits/multiplayer-2d/blueprints/wall.scene +25 -3
  32. package/kits/multiplayer-2d/castle.json +3 -3
  33. package/kits/multiplayer-2d/test/two-client-test.mjs +4 -4
  34. package/kits/multiplayer-3d/CLAUDE.md +5 -2
  35. package/kits/multiplayer-3d/castle.json +3 -3
  36. package/kits/multiplayer-3d/scenes/main.scene +128 -0
  37. package/kits/physics-2d/CLAUDE.md +11 -5
  38. package/kits/physics-2d/behaviors/Camera.jsx +5 -6
  39. package/kits/physics-2d/behaviors/Goal.jsx +5 -2
  40. package/kits/physics-2d/behaviors/Joints.jsx +4 -3
  41. package/kits/physics-2d/behaviors/Layout.jsx +120 -3
  42. package/kits/physics-2d/behaviors/Sprite.jsx +9 -9
  43. package/kits/physics-2d/behaviors/Style.jsx +22 -15
  44. package/kits/physics-2d/behaviors/Text.jsx +7 -6
  45. package/kits/physics-2d/blueprints/ball.scene +27 -5
  46. package/kits/physics-2d/blueprints/block.scene +16 -3
  47. package/kits/physics-2d/blueprints/cauldron.scene +3 -1
  48. package/kits/physics-2d/blueprints/crate.scene +23 -4
  49. package/kits/physics-2d/blueprints/goal.scene +12 -2
  50. package/kits/physics-2d/blueprints/text.scene +13 -3
  51. package/kits/physics-2d/castle.json +2 -1
  52. package/kits/physics-2d/editors/SceneEditor.jsx +26 -2
  53. package/kits/physics-2d/editors/SelectionOverlay.jsx +27 -20
  54. package/kits/physics-2d/engine/blueprint.js +111 -54
  55. package/kits/physics-2d/engine/blueprintCore.js +59 -0
  56. package/kits/physics-2d/engine/collider.js +28 -17
  57. package/kits/physics-2d/engine/layout.js +61 -0
  58. package/kits/physics-2d/engine/layoutOriginMigration.js +223 -0
  59. package/kits/physics-2d/engine/physics/PhysicsSystem.js +11 -7
  60. package/kits/physics-2d/engine/physics/controls.js +4 -8
  61. package/kits/physics-2d/engine/physics/matterBridge.js +13 -8
  62. package/kits/physics-2d/engine/scene.js +38 -34
  63. package/kits/physics-2d/engine/spriteGeometry.js +17 -9
  64. package/kits/physics-2d/engine/tap.js +4 -3
  65. package/kits/physics-2d/scenes/main.scene +59 -6
  66. package/kits/physics-2d/scenes/sandbox.scene +69 -7
  67. package/kits/physics-2d/scripts/onUpdate.mjs +199 -0
  68. package/kits/real-time/castle.json +2 -2
  69. package/kits/real-time/code/server/persist.js +14 -0
  70. package/kits/turn-based/CLAUDE.md +12 -7
  71. package/kits/turn-based/blueprints/board.scene +3 -1
  72. package/kits/turn-based/blueprints/square.scene +3 -1
  73. package/kits/turn-based/castle.json +5 -3
  74. package/kits/turn-based/code/behaviors/Board.jsx +33 -21
  75. package/package.json +1 -1
package/dist/agent.js CHANGED
@@ -402,6 +402,8 @@ systemPrompt) {
402
402
  const direct = viaOpenrouter ? orAuth.mode === 'user-key' : anAuth.mode !== 'proxy';
403
403
  return {
404
404
  command: 'claude',
405
+ model: spawnModel,
406
+ systemText,
405
407
  args: [
406
408
  '-p',
407
409
  '--verbose',
@@ -1237,6 +1239,11 @@ function makeAgentEventHandler(opts, state) {
1237
1239
  };
1238
1240
  return handleClaudeEvent;
1239
1241
  }
1242
+ // How long a settled run waits for its log stream to flush before resolving
1243
+ // anyway. Long enough that an ordinary append always lands first (so a retry's
1244
+ // next attempt cannot interleave with it), short enough that a wedged disk
1245
+ // never becomes a stuck turn.
1246
+ const LOG_FLUSH_TIMEOUT_MS = 2_000;
1240
1247
  // One headless claude CLI run, normalized to delta/activity/result hooks:
1241
1248
  // stream_event wraps anthropic SSE deltas, and a result event carries the
1242
1249
  // canonical final text.
@@ -1271,7 +1278,42 @@ function runAgentCli(opts) {
1271
1278
  }
1272
1279
  opts.children.add(child);
1273
1280
  opts.onSpawn?.(child.pid);
1274
- const log = opts.logPath ? fs.createWriteStream(opts.logPath, { flags: 'a' }) : null;
1281
+ // The run log is strictly best-effort -- it must never take the run, or
1282
+ // the serve, down with it. A write stream reports ENOSPC, EACCES and a
1283
+ // removed directory as an ASYNC 'error' event, and an unhandled 'error'
1284
+ // on a stream is FATAL to the process: without this listener the whole
1285
+ // serve dies because logging failed. So the stream lives in a nullable
1286
+ // the handler clears, and every use goes through writeLog, which quietly
1287
+ // becomes a no-op once the stream is gone. (Same discipline as
1288
+ // createRunLogger in native/loop.ts.)
1289
+ let logStream = null;
1290
+ if (opts.logPath) {
1291
+ try {
1292
+ logStream = fs.createWriteStream(opts.logPath, { flags: 'a' });
1293
+ logStream.on('error', () => {
1294
+ logStream = null;
1295
+ });
1296
+ }
1297
+ catch {
1298
+ logStream = null;
1299
+ }
1300
+ }
1301
+ const writeLog = (line) => {
1302
+ try {
1303
+ logStream?.write(line);
1304
+ }
1305
+ catch {
1306
+ /* never fail a run over logging */
1307
+ }
1308
+ };
1309
+ // Ahead of every stream line: what this turn was asked (see logHeader).
1310
+ if (opts.logHeader) {
1311
+ writeLog(JSON.stringify({
1312
+ type: 'castle_prompt',
1313
+ at: new Date().toISOString(),
1314
+ ...opts.logHeader,
1315
+ }) + '\n');
1316
+ }
1275
1317
  let settled = false;
1276
1318
  let stderrTail = '';
1277
1319
  let lineBuffer = '';
@@ -1282,8 +1324,36 @@ function runAgentCli(opts) {
1282
1324
  settled = true;
1283
1325
  clearTimeout(timeout);
1284
1326
  opts.children.delete(child);
1285
- log?.end();
1286
- resolve(result);
1327
+ // Resolve only once the log's buffered lines have actually reached disk.
1328
+ // A task's retry loop opens a NEW append stream on this SAME file for
1329
+ // the next attempt, so resolving before the flush let attempt 2's
1330
+ // castle_prompt header land in the middle of attempt 1's lines -- two
1331
+ // runs interleaved in one file, which a corpus reader cannot untangle.
1332
+ // The timer is the escape hatch: a hung disk delays the log, never the
1333
+ // run, and a flush callback that arrives after it is ignored.
1334
+ const stream = logStream;
1335
+ if (!stream) {
1336
+ resolve(result);
1337
+ return;
1338
+ }
1339
+ let flushed = false;
1340
+ // Declared before the timer it clears: nothing calls this until after
1341
+ // the timer below exists (end's callback and the timer itself are both
1342
+ // async, and the catch path runs after the assignment).
1343
+ const finishFlush = () => {
1344
+ if (flushed)
1345
+ return;
1346
+ flushed = true;
1347
+ clearTimeout(flushTimer);
1348
+ resolve(result);
1349
+ };
1350
+ const flushTimer = setTimeout(finishFlush, LOG_FLUSH_TIMEOUT_MS);
1351
+ try {
1352
+ stream.end(finishFlush);
1353
+ }
1354
+ catch {
1355
+ finishFlush();
1356
+ }
1287
1357
  };
1288
1358
  const timeout = setTimeout(() => {
1289
1359
  try {
@@ -1307,7 +1377,7 @@ function runAgentCli(opts) {
1307
1377
  const line = lineBuffer.slice(0, nl);
1308
1378
  lineBuffer = lineBuffer.slice(nl + 1);
1309
1379
  if (line.trim()) {
1310
- log?.write(line + '\n');
1380
+ writeLog(line + '\n');
1311
1381
  try {
1312
1382
  handleEvent(JSON.parse(line));
1313
1383
  }
@@ -1703,6 +1773,19 @@ async function runAgentTurn(opts) {
1703
1773
  env: invocation.env,
1704
1774
  timeoutMs: opts.timeoutMs,
1705
1775
  logPath: opts.logPath,
1776
+ // The question this run was asked, recorded once at the top of the run log
1777
+ // -- the stream-json lines that follow carry only the answer. `model` and
1778
+ // `systemText` come back from buildAgentInvocation so they are literally
1779
+ // what was spawned, not a recomputation of it.
1780
+ logHeader: {
1781
+ role: opts.role,
1782
+ sessionId,
1783
+ backend: 'claude',
1784
+ model: invocation.model,
1785
+ effort: opts.effort,
1786
+ systemPrompt: invocation.systemText || undefined,
1787
+ prompt: opts.prompt,
1788
+ },
1706
1789
  children: opts.children,
1707
1790
  onDelta: opts.onDelta,
1708
1791
  onActivity: opts.onActivity,
package/dist/api.d.ts CHANGED
@@ -69,6 +69,7 @@ export interface MeProfile {
69
69
  } | null;
70
70
  }
71
71
  export declare function me(): Promise<MeProfile | null>;
72
+ export declare function whoAmI(): Promise<Pick<MeProfile, 'userId' | 'username'> | null>;
72
73
  export interface DeckRow {
73
74
  deckId: string;
74
75
  title: string | null;
package/dist/api.js CHANGED
@@ -98,6 +98,11 @@ export async function me() {
98
98
  return null;
99
99
  }
100
100
  }
101
+ export async function whoAmI() {
102
+ const data = await graphql(`query { me { userId username } }`);
103
+ handleAPIError(data);
104
+ return pickData(data, 'me');
105
+ }
101
106
  // Everything an import-picker row shows for one deck: what it is, whose it is,
102
107
  // what it looks like, and who it was remixed from. One fragment, so the three
103
108
  // list queries below can't drift apart.
package/dist/bundle.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as path from 'path';
2
2
  import { build } from 'vite';
3
3
  import { viteSingleFile } from 'vite-plugin-singlefile';
4
- import { sceneFilesPlugin, importsAliasPlugin, forksOverlayPlugin, sdkAliasPlugin, } from './vitePlugins.js';
4
+ import { sceneFilesPlugin, importsAliasPlugin, forksOverlayPlugin, sdkAliasPlugin, singleFileBuildCompatPlugin, } from './vitePlugins.js';
5
5
  export async function bundleProject(dir) {
6
6
  const result = await build({
7
7
  root: dir,
@@ -10,6 +10,7 @@ export async function bundleProject(dir) {
10
10
  importsAliasPlugin(),
11
11
  sdkAliasPlugin(),
12
12
  viteSingleFile(),
13
+ singleFileBuildCompatPlugin(),
13
14
  sceneFilesPlugin(),
14
15
  ],
15
16
  build: {
@@ -16,6 +16,7 @@ export interface CastleJson {
16
16
  cardId?: string;
17
17
  imports?: Record<string, DeckImport>;
18
18
  autoUpdateWhenImported?: boolean;
19
+ onUpdate?: string;
19
20
  main?: string;
20
21
  agent?: {
21
22
  plan?: 'on' | 'off';
package/dist/check.js CHANGED
@@ -1,13 +1,15 @@
1
1
  import * as fs from 'fs';
2
2
  import * as path from 'path';
3
3
  import { bundleProject } from './bundle.js';
4
- // `castle-web check` -- does this deck still build?
4
+ import { resolveServerConfig } from './castleJson.js';
5
+ import { buildServerBundle } from './serverBundle.js';
6
+ // `castle-web check` -- do this deck and its authoritative server still build?
5
7
  //
6
- // The bundle is the gate that matters wherever a deck came from: it is the same
7
- // build `save-deck` runs, so anything it refuses is a deck that would publish
8
+ // These are the gates that matter wherever a deck came from: they are the same
9
+ // builds `save-deck` runs, so anything they refuse is a deck that would publish
8
10
  // broken. A kit adds its own lint and duplicate gates on top through its own
9
- // `check` script; a deck built on nothing has no lint config to run, and used
10
- // to have no way to answer the question at all.
11
+ // `check` script; a deck built on nothing has no lint config to run, and used to
12
+ // have no way to answer the question at all.
11
13
  export async function check(dir) {
12
14
  const deckDir = path.resolve(dir);
13
15
  if (!fs.existsSync(path.join(deckDir, 'index.html'))) {
@@ -16,10 +18,16 @@ export async function check(dir) {
16
18
  }
17
19
  try {
18
20
  await bundleProject(deckDir);
21
+ console.log('Bundle OK.');
22
+ if (resolveServerConfig(deckDir)) {
23
+ const serverBundle = await buildServerBundle(deckDir);
24
+ if (!serverBundle)
25
+ throw new Error('Server entry disappeared while bundling.');
26
+ console.log('Server bundle OK.');
27
+ }
19
28
  }
20
29
  catch (e) {
21
30
  console.error(e instanceof Error ? e.message : String(e));
22
31
  process.exit(1);
23
32
  }
24
- console.log('Bundle OK.');
25
33
  }
@@ -17,3 +17,9 @@ export declare function startDevSessionServer(opts: {
17
17
  projectDir: string;
18
18
  log: (level: 'log' | 'error', text: string) => void;
19
19
  }): Promise<DevSessionServer>;
20
+ export declare function serverRestartNeeded(changes: ReadonlyArray<{
21
+ path: string;
22
+ }>, opts: {
23
+ serverEntry: string;
24
+ serverDir: string;
25
+ }): boolean;
@@ -33,6 +33,25 @@ function serverDirOf(entry) {
33
33
  const slash = entry.lastIndexOf('/');
34
34
  return slash < 0 ? '' : entry.slice(0, slash + 1);
35
35
  }
36
+ export function serverRestartNeeded(changes, opts) {
37
+ const forkEntry = opts.serverEntry.startsWith('imports/')
38
+ ? `forks/${opts.serverEntry.slice('imports/'.length)}`
39
+ : null;
40
+ const forkDir = opts.serverDir.startsWith('imports/')
41
+ ? `forks/${opts.serverDir.slice('imports/'.length)}`
42
+ : null;
43
+ return changes.some((change) => change.path === opts.serverEntry ||
44
+ (!!opts.serverDir && change.path.startsWith(opts.serverDir)) ||
45
+ change.path.startsWith('server/') ||
46
+ change.path.startsWith('code/server/') ||
47
+ change.path === forkEntry ||
48
+ (!!forkDir && change.path.startsWith(forkDir)) ||
49
+ // The server bundle pulls in every import's server code (a multiplayer-2d
50
+ // entry imports castle.real-time's), so a sibling import's server file,
51
+ // or a fork of one, restarts it too.
52
+ IMPORTED_SERVER_PATH.test(change.path));
53
+ }
54
+ const IMPORTED_SERVER_PATH = /^(imports|forks)\/[^/]+\/(code\/)?server\//;
36
55
  class DevSessionServerImpl {
37
56
  projectDir;
38
57
  log;
@@ -103,7 +122,10 @@ class DevSessionServerImpl {
103
122
  nextSettings !== this.serverSettings;
104
123
  this.serverSettings = nextSettings;
105
124
  if (!serverSettingsChanged &&
106
- !message.changes.some((change) => change.path === this.serverEntry || change.path.startsWith(this.serverDir)))
125
+ !serverRestartNeeded(message.changes, {
126
+ serverEntry: this.serverEntry,
127
+ serverDir: this.serverDir,
128
+ }))
107
129
  return;
108
130
  if (this.restartTimer)
109
131
  clearTimeout(this.restartTimer);
@@ -57,9 +57,13 @@ export function installFilesChangedWatcher(opts) {
57
57
  affected.add(p);
58
58
  }
59
59
  const affectedList = [...affected].sort();
60
- log?.(`[watch] ${changes
61
- .map((c) => `${c.event} ${c.path}${c.affected.length ? ` (+${c.affected.length})` : ''}`)
62
- .join(', ')} | affected ${affectedList.length}\n`);
60
+ const loggedChanges = changes
61
+ .slice(0, 5)
62
+ .map((c) => `${c.event} ${c.path}${c.affected.length ? ` (+${c.affected.length})` : ''}`);
63
+ if (changes.length > loggedChanges.length) {
64
+ loggedChanges.push(`and ${changes.length - loggedChanges.length} more`);
65
+ }
66
+ log?.(`[watch] ${loggedChanges.join(', ')} | affected ${affectedList.length}\n`);
63
67
  broadcast({ type: 'files_changed', changes, affected: affectedList });
64
68
  };
65
69
  const schedule = () => {
@@ -0,0 +1,31 @@
1
+ /** What a hook is handed, plus the module to run. */
2
+ export interface ImportUpdateHook {
3
+ /** The declared module, resolved to an absolute path. */
4
+ modulePath: string;
5
+ deckDir: string;
6
+ importDir: string;
7
+ alias: string;
8
+ /** The version the deck was pinned at -- what the hook gates on. */
9
+ from: string;
10
+ to: string;
11
+ }
12
+ /**
13
+ * The hook module `imports/<alias>` declares, or null when it declares none or
14
+ * the path it names is not usable. Read from the copy ON DISK, which is the
15
+ * incoming version -- an update's hook is the new code's own migration, so it
16
+ * has to be the new copy's.
17
+ */
18
+ export declare function findImportUpdateHook(deckDir: string, alias: string): string | null;
19
+ /**
20
+ * Save a version, run the hook, and put the deck's files back if it fails.
21
+ *
22
+ * A child process rather than an in-process `import()`: `updateImport` is called
23
+ * from inside the running serve, and a child buys a fresh module graph on every
24
+ * run (so a rewritten hook is the one that runs), a timeout, and isolation from
25
+ * a `process.exit` in kit code -- none of which are available in-process.
26
+ *
27
+ * The version is the recovery path, and it is saved even when the hook is about
28
+ * to succeed: a migration that ran correctly and is not what the creator wanted
29
+ * is the same problem as one that ran wrong.
30
+ */
31
+ export declare function runImportUpdateHook(hook: ImportUpdateHook, log: (message: string) => void): Promise<void>;
@@ -0,0 +1,135 @@
1
+ // Running an import's `onUpdate` hook: the one moment code that knows a kit's
2
+ // own vocabulary gets to touch a deck's files.
3
+ //
4
+ // The CLI knows nothing about what a hook does. It resolves the module the
5
+ // INCOMING copy declares (castle.json `onUpdate`, see castleJson.ts for the
6
+ // contract), saves a version of the deck first, runs it, and rolls the deck's
7
+ // files back if it fails. Everything about `.scene`, origins, or any other kit
8
+ // concept lives on the other side of that boundary.
9
+ import { execFile } from 'child_process';
10
+ import * as fs from 'fs';
11
+ import * as path from 'path';
12
+ import { fileURLToPath } from 'url';
13
+ import { promisify } from 'util';
14
+ import { IMPORTS_DIR, readCastleJson } from './castleJson.js';
15
+ import { createVersion, discardPendingChanges } from './versions.js';
16
+ import { readHead } from './versionStore.js';
17
+ const execFileAsync = promisify(execFile);
18
+ const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
19
+ const RUNNER = path.join(DIST_DIR, 'importUpdateHookRunner.js');
20
+ // A hook is somebody else's code with the deck's files in front of it, so it
21
+ // gets a wall clock rather than the chance to hang a serve start forever. The
22
+ // env override exists for the test that proves the clock works
23
+ // (scripts/tests/import-update-hook.mjs); nothing else should set it.
24
+ function hookTimeoutMs() {
25
+ const raw = Number(process.env.CASTLE_IMPORT_HOOK_TIMEOUT_MS);
26
+ return Number.isFinite(raw) && raw > 0 ? raw : 120_000;
27
+ }
28
+ // stdout can carry a whole migration's worth of per-file lines, so the default
29
+ // 1MB pipe buffer is not enough of a margin to be worth the risk.
30
+ const MAX_HOOK_OUTPUT = 8 * 1024 * 1024;
31
+ // Only the fields the contract names cross into the child. `modulePath` is the
32
+ // CLI's business, not the hook's.
33
+ function childContext(hook) {
34
+ return {
35
+ deckDir: hook.deckDir,
36
+ importDir: hook.importDir,
37
+ alias: hook.alias,
38
+ from: hook.from,
39
+ to: hook.to,
40
+ };
41
+ }
42
+ // A declared path names a file inside the import's own tree and nothing else: it
43
+ // is written by whoever published that deck, and the module runs with the
44
+ // deck's files in reach, so `../../…` or an absolute path would be a way to run
45
+ // code from anywhere on the machine. POSIX-relative because that is how every
46
+ // other path in a castle.json is written.
47
+ function resolveHookModule(importDir, declared) {
48
+ const rel = declared.trim();
49
+ if (!rel || rel.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(rel) || rel.includes('\\'))
50
+ return null;
51
+ if (rel.split('/').includes('..'))
52
+ return null;
53
+ const abs = path.resolve(importDir, rel);
54
+ const inside = path.relative(importDir, abs);
55
+ if (!inside || inside.startsWith('..') || path.isAbsolute(inside))
56
+ return null;
57
+ try {
58
+ return fs.statSync(abs).isFile() ? abs : null;
59
+ }
60
+ catch {
61
+ return null;
62
+ }
63
+ }
64
+ /**
65
+ * The hook module `imports/<alias>` declares, or null when it declares none or
66
+ * the path it names is not usable. Read from the copy ON DISK, which is the
67
+ * incoming version -- an update's hook is the new code's own migration, so it
68
+ * has to be the new copy's.
69
+ */
70
+ export function findImportUpdateHook(deckDir, alias) {
71
+ const importDir = path.join(deckDir, IMPORTS_DIR, alias);
72
+ const declared = readCastleJson(importDir)?.onUpdate;
73
+ if (typeof declared !== 'string' || !declared.trim())
74
+ return null;
75
+ const resolved = resolveHookModule(importDir, declared);
76
+ if (!resolved) {
77
+ console.warn(`"${alias}" declares an update hook at "${declared}", which is not a file inside it -- skipping it.`);
78
+ }
79
+ return resolved;
80
+ }
81
+ function outputLines(text) {
82
+ return text.split('\n').map((line) => line.trimEnd()).filter(Boolean);
83
+ }
84
+ // The last few lines of stderr are what says WHY a hook failed; the whole stack
85
+ // of a 200-line module is not.
86
+ function failureDetail(e) {
87
+ const stderr = e?.stderr ?? '';
88
+ const tail = outputLines(stderr).slice(-8).join('\n');
89
+ if (tail)
90
+ return tail;
91
+ if (e?.killed)
92
+ return `it did not finish in ${hookTimeoutMs()}ms`;
93
+ return e instanceof Error ? e.message : String(e);
94
+ }
95
+ /**
96
+ * Save a version, run the hook, and put the deck's files back if it fails.
97
+ *
98
+ * A child process rather than an in-process `import()`: `updateImport` is called
99
+ * from inside the running serve, and a child buys a fresh module graph on every
100
+ * run (so a rewritten hook is the one that runs), a timeout, and isolation from
101
+ * a `process.exit` in kit code -- none of which are available in-process.
102
+ *
103
+ * The version is the recovery path, and it is saved even when the hook is about
104
+ * to succeed: a migration that ran correctly and is not what the creator wanted
105
+ * is the same problem as one that ran wrong.
106
+ */
107
+ export async function runImportUpdateHook(hook, log) {
108
+ const { version } = createVersion(hook.deckDir, {
109
+ message: `before ${hook.alias} update ${hook.from} -> ${hook.to}`,
110
+ });
111
+ // A deck with nothing outstanding records no new version, and does not need
112
+ // one: head already describes the tree the hook is about to change. Either
113
+ // way there is one id to name, and naming it is the whole recovery story.
114
+ const restorePoint = version?.id ?? readHead(hook.deckDir);
115
+ if (restorePoint) {
116
+ const lead = version
117
+ ? `Saved version ${restorePoint}`
118
+ : `This deck is already saved at version ${restorePoint}`;
119
+ log(`${lead} before letting ${hook.alias} migrate this deck's files ` +
120
+ `(\`castle-web restore-version ${restorePoint}\` puts them back).`);
121
+ }
122
+ try {
123
+ const { stdout, stderr } = await execFileAsync(process.execPath, [RUNNER, hook.modulePath, JSON.stringify(childContext(hook))], { cwd: hook.deckDir, timeout: hookTimeoutMs(), maxBuffer: MAX_HOOK_OUTPUT });
124
+ for (const line of [...outputLines(stdout), ...outputLines(stderr)]) {
125
+ log(`${hook.alias} hook: ${line}`);
126
+ }
127
+ }
128
+ catch (e) {
129
+ // The version above is head, so head describes the deck as the hook found
130
+ // it -- whatever it managed to write goes away.
131
+ const discarded = discardPendingChanges(hook.deckDir);
132
+ const undone = discarded.length > 0 ? ` Undid ${discarded.length} file write(s).` : '';
133
+ throw new Error(`${hook.alias}'s update hook failed.${undone}\n${failureDetail(e)}`);
134
+ }
135
+ }
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/env node
2
+ // The child process one import's `onUpdate` hook runs in. Why a child at all is
3
+ // in importUpdateHook.ts; this is only the entry point.
4
+ //
5
+ // argv: the hook module's absolute path, then its context as JSON. `log` is
6
+ // supplied here rather than serialized, because a function cannot cross the
7
+ // process boundary -- the parent reads stdout back and labels it.
8
+ import { pathToFileURL } from 'url';
9
+ async function main() {
10
+ const [modulePath, contextJson] = process.argv.slice(2);
11
+ if (!modulePath || !contextJson) {
12
+ throw new Error('usage: importUpdateHookRunner <module> <contextJson>');
13
+ }
14
+ const mod = (await import(pathToFileURL(modulePath).href));
15
+ if (typeof mod.default !== 'function') {
16
+ throw new Error(`${modulePath} does not default-export a function.`);
17
+ }
18
+ const hook = mod.default;
19
+ await hook({ ...JSON.parse(contextJson), log: (message) => console.log(message) });
20
+ }
21
+ main().catch((e) => {
22
+ console.error(e instanceof Error ? (e.stack ?? e.message) : String(e));
23
+ process.exit(1);
24
+ });
package/dist/imports.js CHANGED
@@ -7,6 +7,7 @@ import { normalizeDeckPackageJson } from './normalize.js';
7
7
  import { getKitsDir } from './localPaths.js';
8
8
  import { SDK_PACKAGE } from './sdkResolve.js';
9
9
  import { writePlatformDocs } from './platformDoc.js';
10
+ import { findImportUpdateHook, runImportUpdateHook, } from './importUpdateHook.js';
10
11
  import { ensureVisibleGlob, IMPORTS_DIR, IMPORT_VERSION_FILE, STARTER_THEME_FILES, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
11
12
  // Adding another deck as a dependency (`castle-web add-import`; removing one is a
12
13
  // later command). Deliberately NOT `get-deck`: that one
@@ -672,10 +673,54 @@ function seedKitTheme(deckDir, alias, log) {
672
673
  return;
673
674
  log(`Seeded ${seeded.join(' + ')} from ${alias} (new in this version; the deck's to edit)`);
674
675
  }
676
+ // An update's hook, if the incoming copy declares one and the account gate lets
677
+ // it run. The gate is the same leash `autoUpdateImports` is under, for a bigger
678
+ // reason: a hook is code from another deck writing THIS deck's files. Resolved
679
+ // lazily -- `autoUpdateImports` has already answered the question, and
680
+ // `updateImport` must not pay a lookup for the overwhelming majority of updates
681
+ // that carry no hook at all.
682
+ //
683
+ // Untrusted plus a hook keeps the update and skips the hook: the files are
684
+ // already in place and refetching them is what the person asked for, so the
685
+ // honest outcome is new code against un-migrated data, said out loud.
686
+ async function resolveUpdateHook(deckDir, alias, update, to, log) {
687
+ const modulePath = findImportUpdateHook(deckDir, alias);
688
+ if (!modulePath)
689
+ return null;
690
+ const trusted = update.trusted ?? (await importIsOnTrustedAccount(update.deckId));
691
+ if (!trusted) {
692
+ log(`${alias} ships an update hook, which only runs for imports on the ${AUTO_UPDATE_ACCOUNT} ` +
693
+ `account -- skipped. Its new files are in place; this deck's own files were not migrated.`);
694
+ return null;
695
+ }
696
+ return {
697
+ modulePath,
698
+ deckDir,
699
+ importDir: path.join(deckDir, IMPORTS_DIR, alias),
700
+ alias,
701
+ from: update.from,
702
+ to,
703
+ };
704
+ }
675
705
  async function applyImportUpdate(deckDir, alias, update, source, log) {
676
706
  await placeImport(deckDir, alias, update.deckId, source, update.via);
677
707
  log(`Updated ${alias} (${update.from} -> ${source.updatedAt})`);
708
+ const hook = await resolveUpdateHook(deckDir, alias, update, source.updatedAt, log);
709
+ // Before the hook, so a migration sees the deck the new code will run
710
+ // against, seeded files included.
678
711
  seedKitTheme(deckDir, alias, log);
712
+ if (hook) {
713
+ try {
714
+ await runImportUpdateHook(hook, log);
715
+ }
716
+ catch (e) {
717
+ // Put the import back at the version whose data this deck still has. The
718
+ // hook already rolled the deck's own files back, so the pair stays
719
+ // consistent -- old kit, old data -- and the caller reports why.
720
+ revertImport(deckDir, alias, log);
721
+ throw e;
722
+ }
723
+ }
679
724
  // Its own dependencies may have moved too.
680
725
  const transitive = await addTransitiveImports(deckDir, alias, importedDeckIds(deckDir));
681
726
  for (const t of transitive)
@@ -762,7 +807,10 @@ export async function autoUpdateImports(deckDir) {
762
807
  // current version, so a marker that doesn't match is reason to refetch.
763
808
  if (source.updatedAt === pin.version && importFilesMatchPin(deckDir, alias, pin))
764
809
  continue;
765
- await applyImportUpdate(deckDir, alias, { deckId: pin.deckId, from: pin.version, via: pin.via }, source, (message) => console.log(`auto-update: ${message}`));
810
+ await applyImportUpdate(deckDir, alias,
811
+ // The account gate is already satisfied above, so an `onUpdate` hook
812
+ // does not pay for the same lookup a second time.
813
+ { deckId: pin.deckId, from: pin.version, via: pin.via, trusted: true }, source, (message) => console.log(`auto-update: ${message}`));
766
814
  updated.push({ alias, from: pin.version, to: source.updatedAt });
767
815
  }
768
816
  catch (e) {
@@ -799,7 +847,7 @@ export async function updateImport(dir, options = {}) {
799
847
  }
800
848
  if (options.revert) {
801
849
  for (const alias of aliases)
802
- revertImport(deckDir, alias);
850
+ revertImport(deckDir, alias, (message) => console.log(message));
803
851
  await installAddedDependencies(deckDir, syncImportDependencies(deckDir));
804
852
  writePlatformDocs(deckDir);
805
853
  return;
@@ -850,8 +898,10 @@ export async function updateImport(dir, options = {}) {
850
898
  writePlatformDocs(deckDir);
851
899
  console.log('Play the deck to check the update before saving; `--revert` puts the old version back.');
852
900
  }
853
- // Restore the copy taken when this import was last replaced.
854
- function revertImport(deckDir, alias) {
901
+ // Restore the copy taken when this import was last replaced. `log` labels the
902
+ // lines, because this is reached both from `--revert` (bare) and from an update
903
+ // whose hook failed (where the caller is already prefixing its output).
904
+ function revertImport(deckDir, alias, log) {
855
905
  const backup = backupPath(deckDir, alias);
856
906
  if (!fs.existsSync(backup)) {
857
907
  console.error(`No previous version of "${alias}" is kept here -- nothing to revert to.`);
@@ -883,8 +933,8 @@ function revertImport(deckDir, alias) {
883
933
  fs.rmSync(backup, { recursive: true, force: true });
884
934
  lockImportTree(destDir);
885
935
  clearStatusCache(deckDir);
886
- console.log(`Reverted ${alias} to its previous version.`);
936
+ log(`Reverted ${alias} to its previous version.`);
887
937
  if (!fs.existsSync(path.join(destDir, IMPORT_VERSION_FILE))) {
888
- console.log(`That copy predates version records; run \`castle-web update-import ${alias}\` to refetch it before it can be published.`);
938
+ log(`That copy predates version records; run \`castle-web update-import ${alias}\` to refetch it before it can be published.`);
889
939
  }
890
940
  }