castle-web-cli 0.4.242 → 0.4.244
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-prompts.js +4 -4
- package/dist/index.js +44 -3
- package/dist/platformDoc.js +1 -0
- package/dist/versionPrune.d.ts +62 -0
- package/dist/versionPrune.js +513 -0
- package/dist/versionStore.d.ts +2 -0
- package/dist/versionStore.js +64 -0
- package/dist/versions.js +6 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +2 -1
- package/kits/base/sdk/server/hub.js +5 -1
- package/kits/base/sdk/server/platformHandle.d.ts +2 -0
- package/kits/hub-game/code/client/chrome.js +3 -1
- package/kits/hub-game/code/client/hookLayer.js +8 -0
- package/kits/hub-game/code/client/padCues.js +2 -0
- package/kits/hub-game/code/client/padReadability.js +6 -1
- package/kits/hub-game/code/client/signals.js +126 -0
- package/kits/hub-game/code/client/state.js +4 -0
- package/kits/hub-game/code/server/hub.js +19 -2
- package/kits/hub-game/code/server/npcs.js +4 -0
- package/kits/hub-game/code/server/party.js +3 -0
- package/kits/hub-game/code/server/signals.js +124 -0
- package/kits/hub-game/code/systems/hub.js +21 -2
- package/kits/hub-game/docs/contract.md +65 -1
- package/kits/hub-game/package.json +1 -1
- package/kits/hub-game/scripts/test-pad-cues.mjs +6 -3
- package/kits/hub-game/scripts/test-signals.mjs +412 -0
- package/package.json +1 -1
package/dist/agent-prompts.js
CHANGED
|
@@ -118,7 +118,7 @@ ${runningTaskRules}
|
|
|
118
118
|
- Never claim the board is cleared without actually emitting the fence.
|
|
119
119
|
- Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it -- unless their words ask to go back to an earlier state, which is the version-history rule below.
|
|
120
120
|
- Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
|
|
121
|
-
- The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you run \`restore-version\` only when the user's own words ask to put the whole deck back to an earlier state ("go back", "revert it", "undo all that"): that decision is theirs, and they have made it. Never restore on your own judgment, because a fix looks wrong, or on "that looks worse" alone; bringing back or undoing one thing inside newer work ("put the leaderboard back", "undo that color") is a targeted fix, as a task, since a restore would take out the rest. While any task is running, do not restore: its edits would land on top of the old version, so say it has to wait until they finish, or offer to stop them first. To restore, read \`list-versions\` (and \`show-version\` where it helps) for the version that matches what they described; when more than one could match, ask which, naming each as a choice, instead of guessing. Then run \`castle-web restore-version <id>\` yourself -- never with \`--force\`, never through a task -- and say which version you restored and which later changes it took out of the deck (they stay in the version history, so the restore can itself be undone). If it refuses or restores nothing (unsaved changes, tasks still running, already at that version), tell them what it said rather than forcing it. No task you spawn may ever revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit or starter content -- a fix is always a targeted edit, and every task prompt you write has to be readable that way.
|
|
121
|
+
- The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you run \`restore-version\` only when the user's own words ask to put the whole deck back to an earlier state ("go back", "revert it", "undo all that"): that decision is theirs, and they have made it. Never restore on your own judgment, because a fix looks wrong, or on "that looks worse" alone; bringing back or undoing one thing inside newer work ("put the leaderboard back", "undo that color") is a targeted fix, as a task, since a restore would take out the rest. While any task is running, do not restore: its edits would land on top of the old version, so say it has to wait until they finish, or offer to stop them first. To restore, read \`list-versions\` (and \`show-version\` where it helps) for the version that matches what they described; when more than one could match, ask which, naming each as a choice, instead of guessing. Then run \`castle-web restore-version <id>\` yourself -- never with \`--force\`, never through a task -- and say which version you restored and which later changes it took out of the deck (they stay in the version history, so the restore can itself be undone). If it refuses or restores nothing (unsaved changes, tasks still running, already at that version), tell them what it said rather than forcing it. Never edit or delete anything under \`.castle/versions/\` yourself, and never ask a task to: removing versions or their blobs by hand corrupts the history and the cloud stops saving the deck. When the user asks to remove old versions, or the deck is too large to save and old versions are what is big, run \`castle-web prune-versions --keep <n> --dry-run\` yourself, tell them how many versions and how much space it would free, and once they agree run it without \`--dry-run\` (never through a task); if it refuses, tell them what it said. No task you spawn may ever revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit or starter content -- a fix is always a targeted edit, and every task prompt you write has to be readable that way.
|
|
122
122
|
|
|
123
123
|
Asking with options (the \`\`\`ask block). When you need the user to settle a few choices at once, emit ONE fenced block tagged \`ask\` containing JSON -- it renders inline in the chat as grouped options they tap and submit together (far better than stacking questions they can only half-answer). Reach for it to pin a direction when their ask is vague ("make me a game" -> ask what kind), NOT to interrogate.
|
|
124
124
|
|
|
@@ -1274,7 +1274,7 @@ phase: wiring the paddle to touch
|
|
|
1274
1274
|
}
|
|
1275
1275
|
// How a task agent records its work: a version in the deck's own store, or a
|
|
1276
1276
|
// commit when the deck is on git. The version wording is the prompt's original
|
|
1277
|
-
// text,
|
|
1277
|
+
// text, plus the rule that only prune-versions shrinks the store.
|
|
1278
1278
|
function taskSaveWording(git) {
|
|
1279
1279
|
if (!git) {
|
|
1280
1280
|
return {
|
|
@@ -1282,7 +1282,7 @@ function taskSaveWording(git) {
|
|
|
1282
1282
|
rule: '- SAVE A VERSION when your change is done, so the user can see and undo it: `castle-web save-version -m "<short description of what you changed>" <each path you touched>`. Name those paths explicitly -- a bare `save-version` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.',
|
|
1283
1283
|
listing: '`save-version -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
|
|
1284
1284
|
before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, save a version first so they can restore: `castle-web save-version -m "<what is about to change>" <those paths>`. That is on top of the end-of-task version below, not instead of it.',
|
|
1285
|
-
store: "(The version store lives there too, but you never edit it by hand -- `castle-web save-version` writes it for you.)",
|
|
1285
|
+
store: "(The version store lives there too, but you never edit or delete it by hand, not even to save space -- `castle-web save-version` writes it for you, and only `castle-web prune-versions` may shrink it.)",
|
|
1286
1286
|
};
|
|
1287
1287
|
}
|
|
1288
1288
|
return {
|
|
@@ -1290,7 +1290,7 @@ function taskSaveWording(git) {
|
|
|
1290
1290
|
rule: '- COMMIT when your change is done, so the user can see and undo it: `castle-web commit --reason task -m "<short description of what you changed>" <each path you touched>`. Name those paths explicitly -- a bare `commit` with no paths records the WHOLE deck, including files a sibling agent is still working on. One commit for the whole task, at the end; not one per file. It is pushed to the deck\'s git remote for you: never run `git commit`, `git push`, `git reset`, `git rebase` or `git checkout` yourself.',
|
|
1291
1291
|
listing: '`commit --reason task -m "<message>" <paths...>` -- as above: your own paths, named explicitly, once at the end.',
|
|
1292
1292
|
before: '- Before any change that overwrites or deletes MORE THAN ONE existing file of theirs, commit them first so they can restore: `castle-web commit --reason task -m "<what is about to change>" <those paths>`. That is on top of the end-of-task commit below, not instead of it.',
|
|
1293
|
-
store: "(The deck's history is git, in .git -- you never edit it by hand; `castle-web commit` writes it for you.)",
|
|
1293
|
+
store: "(The deck's history is git, in .git -- you never edit it by hand; `castle-web commit` writes it for you. The older version store in .castle/versions is never edited or deleted by hand either; only `castle-web prune-versions` may shrink it.)",
|
|
1294
1294
|
};
|
|
1295
1295
|
}
|
|
1296
1296
|
// Appended to claude task agents' system prompt (portable replacement for the
|
package/dist/index.js
CHANGED
|
@@ -175,7 +175,7 @@ function availableKits() {
|
|
|
175
175
|
return FALLBACK_KITS;
|
|
176
176
|
}
|
|
177
177
|
}
|
|
178
|
-
function
|
|
178
|
+
function usageText() {
|
|
179
179
|
const kits = availableKits();
|
|
180
180
|
const scaffoldKits = kits.filter((kit) => kit !== 'base' && kit !== 'real-time');
|
|
181
181
|
const initKits = [...scaffoldKits, 'none'].join(', ');
|
|
@@ -184,7 +184,7 @@ function usage() {
|
|
|
184
184
|
...kits.map((kit) => ` ${kit.padEnd(kitNameWidth)} ${KIT_DESCRIPTIONS[kit] ?? 'Scaffold kit.'}`),
|
|
185
185
|
` ${'none'.padEnd(kitNameWidth)} Minimal vite + canvas setup with the castle-web SDK and no kit.`,
|
|
186
186
|
].join('\n');
|
|
187
|
-
|
|
187
|
+
return `Usage:
|
|
188
188
|
castle-web init <dir> [--deck-id ID] [--card-id ID] [--kit NAME] [--port PORT] (kits: ${initKits}; default physics-2d)
|
|
189
189
|
castle-web init <dir> --remix <deckId> [--deck-id ID] [--card-id ID] [--port PORT] (starts from a published deck instead of a kit)
|
|
190
190
|
castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
|
|
@@ -209,6 +209,7 @@ function usage() {
|
|
|
209
209
|
castle-web list-versions [version] [--dir DIR] (defaults to the latest version)
|
|
210
210
|
castle-web show-version <version> [--dir DIR] (diffs of the files that version changed)
|
|
211
211
|
castle-web restore-version <version> [--force] [--dir DIR]
|
|
212
|
+
castle-web prune-versions --keep N [--dry-run] [--dir DIR] (keeps the newest N versions, drops the rest and their stored files, after checking the result against the cloud save's version-history rules; never hand-edit .castle/versions)
|
|
212
213
|
castle-web git init [dir] [--dir DIR] [--staging] (connects the deck to its Castle git remote: git push castle <branch>)
|
|
213
214
|
castle-web git clone <deckId|url> [dir] [--staging] (clones a deck's Castle repo; the remote is "castle")
|
|
214
215
|
castle-web git setup [--force|--remove] (lets plain git use your Castle login for git.castle.xyz; login does this)
|
|
@@ -224,9 +225,29 @@ function usage() {
|
|
|
224
225
|
Kits:
|
|
225
226
|
${kitLines}
|
|
226
227
|
|
|
227
|
-
After init, read the scaffolded deck's CLAUDE.md (also AGENTS.md) for the kit's full author guide
|
|
228
|
+
After init, read the scaffolded deck's CLAUDE.md (also AGENTS.md) for the kit's full author guide.`;
|
|
229
|
+
}
|
|
230
|
+
function usage() {
|
|
231
|
+
console.log(usageText());
|
|
228
232
|
process.exit(1);
|
|
229
233
|
}
|
|
234
|
+
// `--help` / `-h` anywhere among a command's arguments -- after a `--`, or where a flag
|
|
235
|
+
// expects its value, too. Commands parse loosely (most ignore flags they don't take, and
|
|
236
|
+
// `--` is dropped before positionals are read), so any exception lets one through to the
|
|
237
|
+
// action; a literal path or value spelled `--help` is not worth that.
|
|
238
|
+
function wantsHelp() {
|
|
239
|
+
return args.slice(1).some((arg) => arg === '--help' || arg === '-h');
|
|
240
|
+
}
|
|
241
|
+
// The usage lines for `command` (and `git <sub>`), or the whole text when it has none.
|
|
242
|
+
function helpText() {
|
|
243
|
+
const text = usageText();
|
|
244
|
+
const sub = command === 'git' ? readPositionals()[0] : undefined;
|
|
245
|
+
const prefix = sub && !sub.startsWith('-') ? `castle-web git ${sub} ` : `castle-web ${command} `;
|
|
246
|
+
const lines = text.split('\n').filter((line) => line.trimStart().startsWith(prefix));
|
|
247
|
+
if (lines.length === 0)
|
|
248
|
+
return text;
|
|
249
|
+
return `Usage:\n${lines.join('\n')}`;
|
|
250
|
+
}
|
|
230
251
|
// `git init`'s own arguments, strictly: an unknown flag is an error rather than
|
|
231
252
|
// ignored, since a typo'd `--staging` would otherwise target production.
|
|
232
253
|
function parseGitInitArgs() {
|
|
@@ -528,6 +549,17 @@ async function main() {
|
|
|
528
549
|
console.log(getCliVersion());
|
|
529
550
|
return;
|
|
530
551
|
}
|
|
552
|
+
// Also before the switch, and before any command reads its arguments: no command
|
|
553
|
+
// knows --help, and most skip an unknown flag and run -- `save-deck --help` saved
|
|
554
|
+
// the deck. Asking for help never does anything else.
|
|
555
|
+
if (command === '--help' || command === '-h' || command === 'help') {
|
|
556
|
+
console.log(usageText());
|
|
557
|
+
return;
|
|
558
|
+
}
|
|
559
|
+
if (wantsHelp()) {
|
|
560
|
+
console.log(helpText());
|
|
561
|
+
return;
|
|
562
|
+
}
|
|
531
563
|
if (VERSION_COMMANDS.has(command) && (await gitVersionCommand(command)))
|
|
532
564
|
return;
|
|
533
565
|
switch (command) {
|
|
@@ -689,6 +721,15 @@ async function main() {
|
|
|
689
721
|
restoreVersion(getFlagValue('--dir') ?? '.', target, { force: hasFlag('--force') });
|
|
690
722
|
break;
|
|
691
723
|
}
|
|
724
|
+
case 'prune-versions': {
|
|
725
|
+
const keep = Number(getFlagValue('--keep'));
|
|
726
|
+
if (!getFlagValue('--keep') || !Number.isInteger(keep) || keep < 1) {
|
|
727
|
+
console.error('Usage: castle-web prune-versions --keep N [--dry-run] (N is at least 1)');
|
|
728
|
+
process.exit(1);
|
|
729
|
+
}
|
|
730
|
+
(await import('./versionPrune.js')).pruneVersions(getFlagValue('--dir') ?? '.', { keep, dryRun: hasFlag('--dry-run') });
|
|
731
|
+
break;
|
|
732
|
+
}
|
|
692
733
|
case 'restart': {
|
|
693
734
|
const dir = findPositionalDir();
|
|
694
735
|
const servePort = getServeSocketPort(dir);
|
package/dist/platformDoc.js
CHANGED
|
@@ -59,6 +59,7 @@ export function everyDeckBullets(deckDir) {
|
|
|
59
59
|
"- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.",
|
|
60
60
|
'- If the browser console shows `[vite] failed to connect to websocket` (or a "Direct websocket connection fallback" line), ignore it. Vite HMR is deliberately off on this serve, so the line is expected and harmless: it is never why a scene is blank, a game is not running, or multiplayer is not connecting. Do not investigate or "fix" it.',
|
|
61
61
|
"- Never revert, replace, or re-scaffold the deck's scenes, scripts, or behaviors back to kit, starter, or imported content, and never delete or rewrite a whole scene to diagnose a problem -- those files are the person's own work. Fix forward with targeted edits, and treat a request to diagnose or explain as read-only unless they asked for a fix.",
|
|
62
|
+
"- **Never hand-edit, move or delete anything under `.castle/versions/`**, the deck's saved version history -- not to save space, not to fix `list-versions`. Each version is stored as a change against the one before it, so removing versions or blobs by hand corrupts the history and the cloud stops saving the deck. To shrink it, run `castle-web prune-versions --keep <n> --dry-run` to see what would go, then the same without `--dry-run`: it keeps the newest n versions, rewrites the oldest kept one so it stands on its own, and checks the result against the cloud save's version-history rules before it changes anything. Removing old versions is the person's call, so ask first.",
|
|
62
63
|
"- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe under `## Editors` in the deck's guide (its kit's `CLAUDE.md` under `imports/`). Editors under `imports/` are read-only; add or fork, don't edit.",
|
|
63
64
|
'- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. One-off or generated data stays code.',
|
|
64
65
|
"- **Put the values someone would tune while playtesting in a `PARAMS` object**: `export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08 };` near the top of the file that uses them. The Parameters panel lists every file in the deck that has one and renders their values as fields -- a number scrubs, a boolean toggles, a `'#rrggbb'` string opens a color picker -- and writes the edit back into the file. It edits every file's params in one place, so nobody has to remember which file a setting lives in, and a file that has params says so above its code with a way in. That is how a creator tunes a game on a phone without putting a cursor inside an expression. Nested one level deep (`player: { speed: 5 }`) renders as a group. **Write each value as a plain number, not as arithmetic** (`0.333`, not `1 / 3`): the panel folds arithmetic over plain numbers into a field and replaces it with the tuned literal on the first edit, so the expression you wrote does not survive the first tune. A value that NAMES something (`speed: BASE * 2`) shows read-only, as a link onto its own line in the code.",
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import * as store from './versionStore.js';
|
|
2
|
+
export declare class InvalidVersionStore extends Error {
|
|
3
|
+
}
|
|
4
|
+
/** The shape checks deck-persistence's validateVersion applies to one version object. */
|
|
5
|
+
export declare function checkVersionShape(value: unknown, id: string): store.Version;
|
|
6
|
+
/**
|
|
7
|
+
* The history rules deck-persistence's validateVersions applies, over an in-memory store:
|
|
8
|
+
* head names a version, every parent exists, there are no loops, every hash a version
|
|
9
|
+
* names has a blob, and every version's `changes` equal the diff of its manifest against
|
|
10
|
+
* its parent's (an empty manifest for a root).
|
|
11
|
+
*/
|
|
12
|
+
export declare function validateHistory(versions: ReadonlyMap<string, store.Version>, head: string | null, hasBlob: (hash: string) => boolean): void;
|
|
13
|
+
/** Every hash a set of versions needs a blob for. */
|
|
14
|
+
export declare function referencedHashes(versions: Iterable<store.Version>): Set<string>;
|
|
15
|
+
/** A version rewritten as a root: no parent, and its whole manifest as added. */
|
|
16
|
+
export declare function asRoot(version: store.Version): store.Version;
|
|
17
|
+
/**
|
|
18
|
+
* The line list-versions shows, newest first: head's later descendants (the chain a
|
|
19
|
+
* restore-version back in time left ahead of head), head, then head's ancestors. Stops at
|
|
20
|
+
* a missing parent rather than failing, so a store that already lost versions can be pruned
|
|
21
|
+
* back into shape.
|
|
22
|
+
*/
|
|
23
|
+
export declare function versionLine(versions: ReadonlyMap<string, store.Version>, head: string): store.Version[];
|
|
24
|
+
export interface PrunePlan {
|
|
25
|
+
head: string;
|
|
26
|
+
/** Kept versions as they will be on disk, keyed by id. */
|
|
27
|
+
kept: Map<string, store.Version>;
|
|
28
|
+
/** Kept versions whose file is rewritten as a root. */
|
|
29
|
+
reRooted: string[];
|
|
30
|
+
/** Versions whose file is deleted, children before parents. */
|
|
31
|
+
removed: string[];
|
|
32
|
+
/** Blob hashes deleted: nothing kept references them. */
|
|
33
|
+
removedBlobs: string[];
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Plans a prune over an in-memory store and validates the result. Pure: the caller
|
|
37
|
+
* decides whether to apply it. Throws InvalidVersionStore when the result would not be a
|
|
38
|
+
* store the cloud save accepts.
|
|
39
|
+
*/
|
|
40
|
+
export declare function planPrune(versions: ReadonlyMap<string, store.Version>, head: string | null, blobs: ReadonlySet<string>, keep: number): PrunePlan;
|
|
41
|
+
/**
|
|
42
|
+
* Validates the store on disk with the cloud save's rules, blob bytes included. Throws
|
|
43
|
+
* InvalidVersionStore naming the first problem.
|
|
44
|
+
*/
|
|
45
|
+
export declare function validateVersionStore(projectDir: string): void;
|
|
46
|
+
export interface PruneOptions {
|
|
47
|
+
keep: number;
|
|
48
|
+
dryRun?: boolean;
|
|
49
|
+
}
|
|
50
|
+
export interface PruneOutcome {
|
|
51
|
+
plan: PrunePlan;
|
|
52
|
+
bytesFreed: number;
|
|
53
|
+
applied: boolean;
|
|
54
|
+
}
|
|
55
|
+
/** Plans, validates and (unless dryRun) applies a prune. Writes nothing when it throws. */
|
|
56
|
+
/** A prune that applied and then found the store invalid: something raced it. */
|
|
57
|
+
export declare class PrunedButInvalid extends Error {
|
|
58
|
+
}
|
|
59
|
+
/** Plans, validates and (unless dryRun) applies a prune. Writes nothing when it throws
|
|
60
|
+
* InvalidVersionStore. Holds the store's lock throughout, so no save or restore interleaves. */
|
|
61
|
+
export declare function pruneVersionStore(projectDir: string, opts: PruneOptions): PruneOutcome;
|
|
62
|
+
export declare function pruneVersions(dir: string, opts: PruneOptions): void;
|