castle-web-cli 0.4.192 → 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.
- package/dist/agent.js +87 -4
- package/dist/api.d.ts +14 -0
- package/dist/api.js +13 -1
- package/dist/bundle.js +2 -1
- package/dist/castleJson.d.ts +1 -0
- package/dist/check.js +14 -6
- package/dist/devSessionServer.d.ts +6 -0
- package/dist/devSessionServer.js +23 -1
- package/dist/filesChanged.js +7 -3
- package/dist/importUpdateHook.d.ts +31 -0
- package/dist/importUpdateHook.js +135 -0
- package/dist/importUpdateHookRunner.d.ts +2 -0
- package/dist/importUpdateHookRunner.js +24 -0
- package/dist/imports.js +56 -6
- package/dist/index.js +58 -7
- package/dist/init.d.ts +1 -0
- package/dist/init.js +6 -1
- package/dist/native/loop.js +29 -9
- package/dist/native/playtest-remote.js +53 -5
- package/dist/native/playtest.d.ts +11 -0
- package/dist/native/playtest.js +91 -5
- package/dist/platformDoc.js +4 -4
- package/dist/remix.js +4 -1
- package/dist/serve.js +133 -32
- package/dist/serverBundle.js +1 -1
- package/dist/versions.d.ts +14 -0
- package/dist/versions.js +21 -0
- package/dist/vitePlugins.d.ts +1 -0
- package/dist/vitePlugins.js +18 -0
- package/kits/multiplayer-2d/CLAUDE.md +9 -2
- package/kits/multiplayer-2d/blueprints/crate.scene +32 -4
- package/kits/multiplayer-2d/blueprints/other-player.scene +31 -4
- package/kits/multiplayer-2d/blueprints/player.scene +38 -6
- package/kits/multiplayer-2d/blueprints/wall.scene +25 -3
- package/kits/multiplayer-2d/castle.json +3 -3
- package/kits/multiplayer-2d/test/two-client-test.mjs +4 -4
- package/kits/multiplayer-3d/CLAUDE.md +5 -2
- package/kits/multiplayer-3d/castle.json +3 -3
- package/kits/multiplayer-3d/scenes/main.scene +128 -0
- package/kits/physics-2d/CLAUDE.md +11 -5
- package/kits/physics-2d/behaviors/Camera.jsx +5 -6
- package/kits/physics-2d/behaviors/Goal.jsx +5 -2
- package/kits/physics-2d/behaviors/Joints.jsx +4 -3
- package/kits/physics-2d/behaviors/Layout.jsx +120 -3
- package/kits/physics-2d/behaviors/Sprite.jsx +9 -9
- package/kits/physics-2d/behaviors/Style.jsx +22 -15
- package/kits/physics-2d/behaviors/Text.jsx +7 -6
- package/kits/physics-2d/blueprints/ball.scene +27 -5
- package/kits/physics-2d/blueprints/block.scene +16 -3
- package/kits/physics-2d/blueprints/cauldron.scene +3 -1
- package/kits/physics-2d/blueprints/crate.scene +23 -4
- package/kits/physics-2d/blueprints/goal.scene +12 -2
- package/kits/physics-2d/blueprints/text.scene +13 -3
- package/kits/physics-2d/castle.json +2 -1
- package/kits/physics-2d/editors/SceneEditor.jsx +26 -2
- package/kits/physics-2d/editors/SelectionOverlay.jsx +27 -20
- package/kits/physics-2d/engine/blueprint.js +111 -54
- package/kits/physics-2d/engine/blueprintCore.js +59 -0
- package/kits/physics-2d/engine/collider.js +28 -17
- package/kits/physics-2d/engine/layout.js +61 -0
- package/kits/physics-2d/engine/layoutOriginMigration.js +223 -0
- package/kits/physics-2d/engine/physics/PhysicsSystem.js +11 -7
- package/kits/physics-2d/engine/physics/controls.js +4 -8
- package/kits/physics-2d/engine/physics/matterBridge.js +13 -8
- package/kits/physics-2d/engine/scene.js +38 -34
- package/kits/physics-2d/engine/spriteGeometry.js +17 -9
- package/kits/physics-2d/engine/tap.js +4 -3
- package/kits/physics-2d/scenes/main.scene +59 -6
- package/kits/physics-2d/scenes/sandbox.scene +69 -7
- package/kits/physics-2d/scripts/onUpdate.mjs +199 -0
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/server/persist.js +14 -0
- package/kits/turn-based/CLAUDE.md +12 -7
- package/kits/turn-based/blueprints/board.scene +3 -1
- package/kits/turn-based/blueprints/square.scene +3 -1
- package/kits/turn-based/castle.json +5 -3
- package/kits/turn-based/code/behaviors/Board.jsx +33 -21
- 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
|
-
|
|
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
|
|
1286
|
-
|
|
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
|
-
|
|
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
|
@@ -24,11 +24,24 @@ export type BrowserOperation = {
|
|
|
24
24
|
} | {
|
|
25
25
|
kind: 'cover';
|
|
26
26
|
};
|
|
27
|
+
export interface BrowserConsoleEntry {
|
|
28
|
+
t: number;
|
|
29
|
+
phase: 'load' | 'settle' | 'session';
|
|
30
|
+
level: 'log' | 'warn' | 'error' | 'pageerror';
|
|
31
|
+
text: string;
|
|
32
|
+
}
|
|
33
|
+
export interface BrowserTruncation {
|
|
34
|
+
consoleEntriesOmitted: number;
|
|
35
|
+
consoleEntriesTruncated: number;
|
|
36
|
+
}
|
|
27
37
|
export interface BrowserJobResult {
|
|
28
38
|
protocolVersion: number;
|
|
29
39
|
jobId: string;
|
|
30
40
|
operation: 'playtest' | 'cover';
|
|
31
41
|
ok: boolean;
|
|
42
|
+
error?: string;
|
|
43
|
+
console?: BrowserConsoleEntry[];
|
|
44
|
+
truncation?: BrowserTruncation;
|
|
32
45
|
[key: string]: unknown;
|
|
33
46
|
}
|
|
34
47
|
export declare function runBrowserJob(contentGrant: string, operation: BrowserOperation, signal?: AbortSignal): Promise<BrowserJobResult>;
|
|
@@ -56,6 +69,7 @@ export interface MeProfile {
|
|
|
56
69
|
} | null;
|
|
57
70
|
}
|
|
58
71
|
export declare function me(): Promise<MeProfile | null>;
|
|
72
|
+
export declare function whoAmI(): Promise<Pick<MeProfile, 'userId' | 'username'> | null>;
|
|
59
73
|
export interface DeckRow {
|
|
60
74
|
deckId: string;
|
|
61
75
|
title: string | null;
|
package/dist/api.js
CHANGED
|
@@ -40,10 +40,17 @@ function firstLine(body) {
|
|
|
40
40
|
return '(empty response body)';
|
|
41
41
|
return line.length > 200 ? `${line.slice(0, 200)}...` : line;
|
|
42
42
|
}
|
|
43
|
+
const BROWSER_COVER_API_TIMEOUT_MS = 85_000;
|
|
44
|
+
const BROWSER_PLAYTEST_API_TIMEOUT_MS = 110_000;
|
|
43
45
|
export async function runBrowserJob(contentGrant, operation, signal) {
|
|
44
46
|
const data = await graphql(`mutation($contentGrant: String!, $operation: Json!) {
|
|
45
47
|
runBrowserJob(contentGrant: $contentGrant, operation: $operation)
|
|
46
|
-
}`, { contentGrant, operation }, {
|
|
48
|
+
}`, { contentGrant, operation }, {
|
|
49
|
+
timeoutMs: operation.kind === 'playtest'
|
|
50
|
+
? BROWSER_PLAYTEST_API_TIMEOUT_MS
|
|
51
|
+
: BROWSER_COVER_API_TIMEOUT_MS,
|
|
52
|
+
signal,
|
|
53
|
+
});
|
|
47
54
|
handleAPIError(data);
|
|
48
55
|
return pickData(data, 'runBrowserJob');
|
|
49
56
|
}
|
|
@@ -91,6 +98,11 @@ export async function me() {
|
|
|
91
98
|
return null;
|
|
92
99
|
}
|
|
93
100
|
}
|
|
101
|
+
export async function whoAmI() {
|
|
102
|
+
const data = await graphql(`query { me { userId username } }`);
|
|
103
|
+
handleAPIError(data);
|
|
104
|
+
return pickData(data, 'me');
|
|
105
|
+
}
|
|
94
106
|
// Everything an import-picker row shows for one deck: what it is, whose it is,
|
|
95
107
|
// what it looks like, and who it was remixed from. One fragment, so the three
|
|
96
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: {
|
package/dist/castleJson.d.ts
CHANGED
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
|
-
|
|
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
|
-
//
|
|
7
|
-
//
|
|
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
|
-
//
|
|
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;
|
package/dist/devSessionServer.js
CHANGED
|
@@ -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
|
|
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);
|
package/dist/filesChanged.js
CHANGED
|
@@ -57,9 +57,13 @@ export function installFilesChangedWatcher(opts) {
|
|
|
57
57
|
affected.add(p);
|
|
58
58
|
}
|
|
59
59
|
const affectedList = [...affected].sort();
|
|
60
|
-
|
|
61
|
-
.
|
|
62
|
-
.
|
|
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,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,
|
|
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
|
-
|
|
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
|
-
|
|
936
|
+
log(`Reverted ${alias} to its previous version.`);
|
|
887
937
|
if (!fs.existsSync(path.join(destDir, IMPORT_VERSION_FILE))) {
|
|
888
|
-
|
|
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
|
}
|