castle-web-cli 0.4.205 → 0.4.206

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.
@@ -89,6 +89,7 @@ export interface RouterPromptOpts {
89
89
  playtest?: boolean;
90
90
  askCalls?: boolean;
91
91
  editorTabs?: string[];
92
+ kits?: string[];
92
93
  paramsWrites?: string[];
93
94
  instruction: string;
94
95
  }
@@ -34,6 +34,7 @@ What the user sees beside this chat: Castle's own panels -- Play, Files, Paramet
34
34
  Hard rules:
35
35
  - You NEVER edit files or run state-changing commands. All building and fixing happens through background task agents -- always hand the longer work to them.
36
36
  - IMPORTS ARE YOURS, and they are the one exception to the rule above. Run \`castle-web list-decks --kind kits\` (also \`mine\` and \`saved\`) to see what this deck can import, and \`castle-web add-import <deckIdOrUrl>\` to add one -- both directly, not through a task. Do NOT claim you can list or import anything until you have actually run these; do not describe imports you have not looked at. \`list-decks\` prints one deck per line starting with the id \`add-import\` takes, and marks the ones this deck already has. A pasted castle.xyz deck link works in place of an id. Everything else about a deck's files still goes to task agents.
37
+ - A deck can lack what a kit provides. == kits this deck can import == (present only on a deck that runs no kit) lists each kit this platform ships: what it is for and the file types its editors open. When the user asks for one of those things -- a file type, an editor, a way of working the listing names -- and this deck's guide says it has no such thing, they are asking for that kit, whether they phrase it as a request or as a how-to question. Do not explain the absence, do not paste code that imitates it, and do not spawn a task to build a substitute: import the kit yourself in that same turn with the exact command the listing gives, and read its output. "This deck now runs" in the output means the deck switched over -- its starter content and editors are in place -- so say in one line what the deck now has, tell them to reload the Play panel (its Restart button) to see it, since it keeps running the old code until then, and handle the rest of their ask the way you would on any deck built on that kit. Any other output means the deck kept its own code: the kit is imported but not running, and switching over replaces what they built -- say that and ask which they want before anything else; on a yes, a task repoints the entry point the output names. When the deck's own guide already covers what they asked for, this rule is not in play.
37
38
  - Imported files are READ-ONLY, which is what to say when the user asks whether they can change something a kit or another import gave them (an editor tab included), or why an edit to one did not stick: the deck takes its own version of that one file -- a fork, stored beside the import and used in its place -- and that version is what runs. Forking is how their own data and code changes override an import's, and a task agent does it; the tradeoff, worth saying plainly, is that a file done this way stops picking up changes when the import itself is updated, so it stays to the few files the change actually needs. Often it does not come to a fork at all, which is the better thing to say first: a kit picks up the deck's own behaviors and systems, so new logic is usually just a new file in the deck.
38
39
  - When the user reports something broken, do NOT dig into the code to diagnose it first -- spawn a task whose job is to investigate AND fix it. That brief carries the SYMPTOM, not a cause: the user's own words for what they saw, quoted, plus where the behavior lives when the docs or the conversation name it. You have not read the code, so a mechanism you name is a guess, and a task given a guess implements the guess instead of investigating. A QUESTION is not a fix request: "why is X happening?" gets a task told explicitly to diagnose and CHANGE NOTHING, and your reply says that it will only look and report back.
39
40
  - Only read deck files when your reply itself needs them (answering a question about the deck, grounding a claim -- never make things up); never read as pre-work before spawning a task, and never read files just to learn conventions already covered by the Quick reference.${playtest ? `\n${PLAYTEST_ROUTER_RULE}` : ""}
@@ -851,6 +852,9 @@ export function buildRouterPromptParts(opts) {
851
852
  const editorTabs = opts.editorTabs?.length
852
853
  ? `\n\n== editor tabs ==\n${opts.editorTabs.map((tab) => `- ${tab}`).join("\n")}`
853
854
  : "";
855
+ const kits = opts.kits?.length
856
+ ? `\n\n== kits this deck can import ==\n${opts.kits.join("\n")}`
857
+ : "";
854
858
  const deckFiles = opts.deckTree?.trim()
855
859
  ? `\n\n== deck files ==\n${opts.deckTree.trim()}`
856
860
  : "";
@@ -876,7 +880,7 @@ export function buildRouterPromptParts(opts) {
876
880
  system: `${routerRules(opts.plan !== undefined, opts.playtest === true, opts.askCalls === true)}
877
881
 
878
882
  == deck ==
879
- ${opts.deckLabel}${quickReference}${editorTabs}${deckFiles}`,
883
+ ${opts.deckLabel}${quickReference}${editorTabs}${kits}${deckFiles}`,
880
884
  user: `== conversation so far ==
881
885
  ${renderTranscript(opts.messages)}${plan}
882
886
 
package/dist/agent.js CHANGED
@@ -16,6 +16,7 @@
16
16
  import { execFileSync, spawn } from 'child_process';
17
17
  import { claudeContextEnv, quickReferenceFor } from './platformDoc.js';
18
18
  import { resolveFileTypes } from './editorConfig.js';
19
+ import { kitCatalogLines } from './kitCatalog.js';
19
20
  import { panelWritesSince } from './paramsWrites.js';
20
21
  import { IMPORTS_DIR } from './imports.js';
21
22
  import { isSameOriginUpgrade } from './wsOrigin.js';
@@ -2126,6 +2127,9 @@ async function waitBeforeTaskRetry(attempt, stopRequested, taskId) {
2126
2127
  async function runTaskAgentIn(ctx, task) {
2127
2128
  const dir = path.join(ctx.tasksDir, task.id);
2128
2129
  const relDir = path.relative(ctx.deckDir, dir);
2130
+ // Read at task start, like the router's per turn: a task the router spawns
2131
+ // right after adopting a kit must be briefed with the kit's guide.
2132
+ const deckGuide = readQuickReference(ctx.deckDir);
2129
2133
  const taskPrompt = buildTaskPrompt({
2130
2134
  deckLabel: ctx.deckLabel,
2131
2135
  taskId: task.id,
@@ -2137,7 +2141,7 @@ async function runTaskAgentIn(ctx, task) {
2137
2141
  depsSummary: ctx.depsSummary,
2138
2142
  playtest: playtestSteering(),
2139
2143
  deckTree: buildDeckTree(ctx.deckDir),
2140
- quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, 'task'),
2144
+ quickReference: quickReferenceFor(ctx.deckDir, deckGuide, 'task'),
2141
2145
  plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
2142
2146
  siblings: ctx.siblings,
2143
2147
  });
@@ -2272,7 +2276,6 @@ function startTask(ctx, task) {
2272
2276
  openrouterModel,
2273
2277
  effort,
2274
2278
  stopRequested: ctx.stopRequested,
2275
- quickReference: ctx.quickReference,
2276
2279
  playtest: ctx.playtest,
2277
2280
  depsSummary: depsSummaryFor(ctx.tasks, task),
2278
2281
  // Same visibility rule as the router's board (hide acked+finished rows),
@@ -2484,7 +2487,6 @@ function createTaskStore(opts) {
2484
2487
  children,
2485
2488
  tasks,
2486
2489
  stopRequested,
2487
- quickReference: opts.quickReference,
2488
2490
  claudeModel: opts.claudeModel,
2489
2491
  openrouterModel: opts.openrouterModel,
2490
2492
  effort: opts.effort,
@@ -3015,10 +3017,14 @@ function panelWriteWatermark(messages, selfMessageId) {
3015
3017
  // context + transcript replay (minus log lines and the in-flight reply) +
3016
3018
  // the live board + this turn's instruction.
3017
3019
  function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
3020
+ // Read per turn, not once per serve: adopting a kit mid-conversation
3021
+ // rewrites CLAUDE.md, and the next turn has to see the kit's guide.
3022
+ const deckGuide = readQuickReference(ctx.deckDir);
3018
3023
  return buildRouterPromptParts({
3019
3024
  deckLabel: ctx.deckLabel,
3020
- quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, 'router'),
3025
+ quickReference: quickReferenceFor(ctx.deckDir, deckGuide, 'router'),
3021
3026
  editorTabs: editorTabsFor(ctx.deckDir),
3027
+ kits: kitCatalogLines(ctx.deckDir),
3022
3028
  deckTree: buildDeckTree(ctx.deckDir),
3023
3029
  playtest: playtestSteering(),
3024
3030
  askCalls: askCallsEnabled(ctx.deckDir),
@@ -3647,7 +3653,6 @@ function startRouterTurn(ctx, instruction) {
3647
3653
  runRouterTurnIn({
3648
3654
  deckDir: ctx.deckDir,
3649
3655
  deckLabel: ctx.deckLabel,
3650
- quickReference: ctx.quickReference,
3651
3656
  agentDir: ctx.agentDir,
3652
3657
  children: ctx.routerChildren,
3653
3658
  log: ctx.log,
@@ -3938,7 +3943,6 @@ function makePlaytestRunner(deps) {
3938
3943
  }
3939
3944
  export function createAgentServer(opts) {
3940
3945
  const { deckDir, deckLabel } = opts;
3941
- const quickReference = readQuickReference(deckDir);
3942
3946
  const welcomeMessage = readWelcomeMessage(deckDir) || DEFAULT_WELCOME_MESSAGE;
3943
3947
  const agentDir = path.join(deckDir, '.castle', 'agent');
3944
3948
  const tasksDir = path.join(agentDir, 'tasks');
@@ -4032,7 +4036,6 @@ export function createAgentServer(opts) {
4032
4036
  deckLabel,
4033
4037
  tasksDir,
4034
4038
  children: taskChildren,
4035
- quickReference,
4036
4039
  openrouterModel: () => settings.tasksOpenrouterModel,
4037
4040
  claudeModel: () => settings.tasksClaudeModel,
4038
4041
  effort: () => settings.tasksEffort,
@@ -4049,7 +4052,6 @@ export function createAgentServer(opts) {
4049
4052
  const routerQueue = createRouterQueue({
4050
4053
  deckDir,
4051
4054
  deckLabel,
4052
- quickReference,
4053
4055
  agentDir,
4054
4056
  attachmentsDir,
4055
4057
  routerChildren,
package/dist/imports.d.ts CHANGED
@@ -6,7 +6,7 @@ export interface ImportVersion {
6
6
  }
7
7
  export declare function writeImportVersion(importDir: string, value: ImportVersion): void;
8
8
  export declare function readImportVersion(deckDir: string, alias: string): ImportVersion | null;
9
- export type ImportErrorCode = 'no-deck-ref' | 'bad-deck-ref' | 'no-such-dir' | 'self-import' | 'no-source' | 'bad-alias';
9
+ export type ImportErrorCode = 'no-deck-ref' | 'bad-deck-ref' | 'no-such-dir' | 'self-import' | 'no-source' | 'bad-alias' | 'already-imported';
10
10
  export declare class ImportError extends Error {
11
11
  code: ImportErrorCode;
12
12
  constructor(code: ImportErrorCode, message: string);
package/dist/imports.js CHANGED
@@ -5,6 +5,7 @@ import * as api from './api.js';
5
5
  import { runTar } from './save-deck.js';
6
6
  import { normalizeDeckPackageJson } from './normalize.js';
7
7
  import { getKitsDir } from './localPaths.js';
8
+ import { shippedFrameworkKit, shippedKitAlias } from './kitCatalog.js';
8
9
  import { SDK_PACKAGE } from './sdkResolve.js';
9
10
  import { writePlatformDocs } from './platformDoc.js';
10
11
  import { findImportUpdateHook, runImportUpdateHook, } from './importUpdateHook.js';
@@ -506,22 +507,23 @@ export function importedDeckIds(deckDir) {
506
507
  .map((p) => p?.deckId)
507
508
  .filter((id) => !!id));
508
509
  }
509
- // The import itself. Throws ImportError rather than exiting, because this also
510
- // runs inside the serve (from the editor's Import panel), where taking the
511
- // process down is not an option. The CLI wrapper below prints and exits.
512
- export async function addImportTo(dir, options = {}) {
513
- const targetDir = path.resolve(dir);
514
- const ref = options.deckRef?.trim();
515
- if (!ref) {
516
- throw new ImportError('no-deck-ref', 'No deck given. Pass a deck id or a castle.xyz deck link.');
510
+ async function placeShippedKit(targetDir, kit, givenAlias) {
511
+ const alias = shippedKitAlias(kit);
512
+ if (givenAlias && givenAlias.trim() !== alias) {
513
+ throw new ImportError('bad-alias', `A shipped kit is always imported as ${alias}; drop --as.`);
517
514
  }
518
- const deckId = parseDeckRef(ref);
519
- if (!deckId) {
520
- throw new ImportError('bad-deck-ref', `Not a deck id or a castle deck link: ${ref}`);
521
- }
522
- if (!fs.existsSync(targetDir)) {
523
- throw new ImportError('no-such-dir', `No such directory: ${targetDir}`);
515
+ // Add-only: the CLI's copy can be older than the one the deck updated to, and
516
+ // replacing it would pin the kit backwards under data already migrated forward.
517
+ const pins = (tryReadCastleJson(targetDir)?.imports ?? {});
518
+ if (Object.hasOwn(pins, alias) || fs.existsSync(path.join(targetDir, IMPORTS_DIR, alias))) {
519
+ throw new ImportError('already-imported', `${alias} is already imported; run \`castle-web update-import ${alias}\` to move it to the latest version.`);
524
520
  }
521
+ const { importShippedKit } = await import('./init.js');
522
+ const placed = importShippedKit(targetDir, kit);
523
+ clearStatusCache(targetDir);
524
+ return placed;
525
+ }
526
+ async function placeFetchedImport(targetDir, deckId, givenAlias) {
525
527
  if (readCastleJson(targetDir)?.deckId === deckId) {
526
528
  throw new ImportError('self-import', `Deck ${deckId} is this deck -- a deck can't import itself.`);
527
529
  }
@@ -533,8 +535,8 @@ export async function addImportTo(dir, options = {}) {
533
535
  throw new ImportError('no-source', `No source archive on the server for deck ${deckId}. ` +
534
536
  'Its owner needs to run `castle-web save-deck` before it can be imported.');
535
537
  }
536
- const given = options.alias ? slugifyGivenAlias(options.alias) : '';
537
- if (options.alias && !given) {
538
+ const given = givenAlias ? slugifyGivenAlias(givenAlias) : '';
539
+ if (givenAlias && !given) {
538
540
  throw new ImportError('bad-alias', 'Could not derive a usable name; pick one with letters or digits.');
539
541
  }
540
542
  // An explicit `--as` is the caller's call, collision and all. A derived one
@@ -542,6 +544,35 @@ export async function addImportTo(dir, options = {}) {
542
544
  const alias = given || availableAlias(targetDir, qualifiedAlias(meta, deckId), deckId);
543
545
  const { replaced } = await placeImport(targetDir, alias, deckId, source);
544
546
  const transitive = await addTransitiveImports(targetDir, alias, importedDeckIds(targetDir));
547
+ return { deckId, alias, replaced, transitive };
548
+ }
549
+ // The import itself. Throws ImportError rather than exiting, because this also
550
+ // runs inside the serve (from the editor's Import panel), where taking the
551
+ // process down is not an option. The CLI wrapper below prints and exits.
552
+ export async function addImportTo(dir, options = {}) {
553
+ const targetDir = path.resolve(dir);
554
+ const ref = options.deckRef?.trim();
555
+ if (!ref) {
556
+ throw new ImportError('no-deck-ref', 'No deck given. Pass a deck id or a castle.xyz deck link.');
557
+ }
558
+ if (!fs.existsSync(targetDir)) {
559
+ throw new ImportError('no-such-dir', `No such directory: ${targetDir}`);
560
+ }
561
+ // Before parseDeckRef: a kit's name is id-shaped, so the other order would
562
+ // send `physics-2d` to the server as a deck id.
563
+ const kit = shippedFrameworkKit(ref);
564
+ const deckId = kit ? null : parseDeckRef(ref);
565
+ let placed;
566
+ if (kit) {
567
+ placed = await placeShippedKit(targetDir, kit, options.alias);
568
+ }
569
+ else if (deckId) {
570
+ placed = await placeFetchedImport(targetDir, deckId, options.alias);
571
+ }
572
+ else {
573
+ throw new ImportError('bad-deck-ref', `Not a deck id or a castle deck link: ${ref}`);
574
+ }
575
+ const { alias, replaced, transitive } = placed;
545
576
  const dependencies = syncImportDependencies(targetDir);
546
577
  // A kit declares its entry module (castle.json `main`). Importing one into a
547
578
  // deck that is still the untouched `--kit none` scaffold means "start from this
@@ -552,9 +583,10 @@ export async function addImportTo(dir, options = {}) {
552
583
  const declaredMain = tryReadCastleJson(importDir)?.main;
553
584
  let adoptedMain = null;
554
585
  if (typeof declaredMain === 'string' && declaredMain.trim()) {
555
- const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, } = await import('./init.js');
586
+ const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, adoptKitConfig, } = await import('./init.js');
556
587
  if (isPristineBareDeck(targetDir)) {
557
588
  adoptImportEntry(targetDir, alias, declaredMain.trim());
589
+ adoptKitConfig(targetDir, importDir, alias);
558
590
  adoptedMain = declaredMain.trim();
559
591
  retargetBareClaudeMd(targetDir, alias);
560
592
  // A kit's runtime with no scene to run is a blank screen, and the agent
@@ -600,7 +632,15 @@ export async function addImportTo(dir, options = {}) {
600
632
  writePlatformDocs(targetDir);
601
633
  const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
602
634
  const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
603
- return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
635
+ return {
636
+ deckId: placed.deckId,
637
+ alias,
638
+ replaced,
639
+ transitive,
640
+ dependencies,
641
+ adoptedMain,
642
+ offersMain,
643
+ };
604
644
  }
605
645
  export async function addImport(dir, options = {}) {
606
646
  let result;
@@ -612,7 +652,7 @@ export async function addImport(dir, options = {}) {
612
652
  throw err;
613
653
  console.error(err.message);
614
654
  if (err.code === 'no-deck-ref') {
615
- console.error('Usage: castle-web add-import <deckId|url> [dir] [--as ALIAS]');
655
+ console.error('Usage: castle-web add-import <deckId|url|kit> [dir] [--as ALIAS]');
616
656
  }
617
657
  process.exit(1);
618
658
  }
package/dist/index.js CHANGED
@@ -143,7 +143,7 @@ function usage() {
143
143
  castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private]
144
144
  castle-web get-deck [dir] [--deck-id ID] [--force] (replaces the source if the deck is already there)
145
145
  castle-web list-decks [dir] [--kind mine|saved|kits] (decks this one could import; ids are what add-import takes)
146
- castle-web add-import <deckId|url> [dir] [--as ALIAS] (adds another deck as a read-only dependency in imports/)
146
+ castle-web add-import <deckId|url|kit> [dir] [--as ALIAS] (adds another deck, or a kit this CLI ships, as a read-only dependency in imports/)
147
147
  castle-web fork-import-file <imports/...> [dir] (this deck's own version of one imported file)
148
148
  castle-web revert-import-file <imports/...> [dir]
149
149
  castle-web update-import [alias] [dir] [--check] [--revert] (re-fetches imports; no alias means all)
@@ -243,8 +243,9 @@ async function main() {
243
243
  break;
244
244
  }
245
245
  case 'add-import': {
246
- // The deck -- an id or the link to its page -- is the first positional;
247
- // the importing deck's dir is an optional second, defaulting to the cwd.
246
+ // The deck -- an id, the link to its page, or a shipped kit's name -- is the
247
+ // first positional; the importing deck's dir is an optional second,
248
+ // defaulting to the cwd.
248
249
  const positionals = readPositionals();
249
250
  await addImport(positionals[1] ?? '.', {
250
251
  deckRef: getFlagValue('--deck-id') ?? positionals[0],
package/dist/init.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export declare const BASE_KIT = "base";
2
- export declare const BASE_ALIAS = "castle.base";
2
+ export declare const BASE_ALIAS: string;
3
3
  export declare function resolveScaffoldRefs(): {
4
4
  workspaceMode: boolean;
5
5
  sdkRef: string;
@@ -14,6 +14,14 @@ export declare function getCliVersion(): string;
14
14
  export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
15
15
  export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
16
16
  export declare function retargetBareClaudeMd(deckDir: string, alias: string): void;
17
+ export interface ShippedKitImport {
18
+ alias: string;
19
+ deckId: string;
20
+ replaced: false;
21
+ transitive: string[];
22
+ }
23
+ export declare function importShippedKit(deckDir: string, kit: string): ShippedKitImport;
24
+ export declare function adoptKitConfig(deckDir: string, kitDir: string, alias: string): void;
17
25
  export declare function init(dir: string, opts?: {
18
26
  kit?: string;
19
27
  serve?: boolean;
package/dist/init.js CHANGED
@@ -5,6 +5,7 @@ import { installDeps } from './install.js';
5
5
  import { deckMainFile, deckStarterScene, STARTER_THEME_FILES } from './castleJson.js';
6
6
  import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, writeImportVersion, } from './imports.js';
7
7
  import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
8
+ import { kitFromAlias, shippedKitAlias } from './kitCatalog.js';
8
9
  import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
9
10
  import { SDK_PACKAGE } from './sdkResolve.js';
10
11
  import { serve } from './serve.js';
@@ -12,15 +13,12 @@ import { createVersion } from './versions.js';
12
13
  // Default kit imported by `init` when no --kit is given. `none`/`bare` skips the
13
14
  // framework and produces the minimal index.html + game.js stub below.
14
15
  const DEFAULT_KIT = 'physics-2d';
15
- // The account the first-party kits are (to be) published under, so a kit
16
- // imported from the CLI's copy is named the same as one fetched from the server.
17
- const KIT_AUTHOR = 'castle';
18
16
  // EVERY deck imports this one, kit or not. It carries the SDK (which resolves
19
17
  // out of it -- see sdkResolve.ts), the editor host a deck with no kit mounts
20
18
  // its editors through, and the authoring guide every deck is written against.
21
19
  // A framework kit imports it too, so a kit deck has it as well.
22
20
  export const BASE_KIT = 'base';
23
- export const BASE_ALIAS = `${KIT_AUTHOR}.${BASE_KIT}`;
21
+ export const BASE_ALIAS = shippedKitAlias(BASE_KIT);
24
22
  const INDEX_HTML = `<!DOCTYPE html>
25
23
  <html>
26
24
  <head>
@@ -501,9 +499,7 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
501
499
  for (const [depAlias, depPin] of Object.entries(kitPins)) {
502
500
  if (copied.has(depAlias) || pins[depAlias])
503
501
  continue;
504
- const depKit = depAlias.startsWith(`${KIT_AUTHOR}.`)
505
- ? depAlias.slice(KIT_AUTHOR.length + 1)
506
- : depAlias;
502
+ const depKit = kitFromAlias(depAlias);
507
503
  const depKitDir = path.join(getKitsDir(), depKit);
508
504
  if (fs.existsSync(depKitDir) && fs.statSync(depKitDir).isDirectory()) {
509
505
  copyKitImport(projectDir, depKitDir, depKit, depAlias, pins, copied);
@@ -513,6 +509,28 @@ function copyKitImport(projectDir, kitDir, kit, alias, pins, copied) {
513
509
  }
514
510
  }
515
511
  }
512
+ // `add-import <kit>`: the same copy `init --kit` makes, into an existing deck
513
+ // that does not have the kit yet (the caller refuses one that does). Kits the
514
+ // deck already pins are left as they are, which is what keeps a bare deck's
515
+ // base import from being copied over itself.
516
+ export function importShippedKit(deckDir, kit) {
517
+ const alias = shippedKitAlias(kit);
518
+ const configPath = path.join(deckDir, 'castle.json');
519
+ const pins = { ...(readJsonFile(configPath)?.imports ?? {}) };
520
+ const copied = new Map();
521
+ copyKitImport(deckDir, path.join(getKitsDir(), kit), kit, alias, pins, copied);
522
+ const pin = pins[alias];
523
+ writeJsonFile(configPath, { ...readJsonFile(configPath), imports: pins });
524
+ for (const copiedAlias of copied.keys()) {
525
+ lockImportTree(path.join(deckDir, IMPORTS_DIR, copiedAlias));
526
+ }
527
+ return {
528
+ alias,
529
+ deckId: typeof pin.deckId === 'string' ? pin.deckId : kit,
530
+ replaced: false,
531
+ transitive: [...copied.keys()].filter((a) => a !== alias),
532
+ };
533
+ }
516
534
  // The kit's server block, with `main` pointed at the copy under `imports/`. The
517
535
  // kit names its own file, which is right when the kit itself is served and wrong
518
536
  // in a deck, where that file only exists inside the import.
@@ -527,6 +545,29 @@ function serverForDeck(server, kitDir, alias) {
527
545
  }
528
546
  return { ...block, main: `${IMPORTS_DIR}/${alias}/${main}` };
529
547
  }
548
+ // The deck's own castle.json takes the kit's editor config (panel layout, file
549
+ // filters) as a starting point -- it is the deck's to edit from here -- and the
550
+ // kit's server block. Every other key the deck already has is kept. Shared by
551
+ // `init --kit` and `add-import` adopting a kit onto a bare deck, so the two
552
+ // cannot write different decks.
553
+ //
554
+ // `fileTypes` is deliberately NOT copied. It is the kit's own vocabulary, and
555
+ // the deck resolves it live from every import's castle.json (see
556
+ // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
557
+ // reaches the deck like any other, and a kit imported LATER contributes its
558
+ // types too, which a copy taken at scaffold time never could.
559
+ export function adoptKitConfig(deckDir, kitDir, alias) {
560
+ const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
561
+ const configPath = path.join(deckDir, 'castle.json');
562
+ const { editor, server, ...rest } = readJsonFile(configPath) ?? {};
563
+ const nextEditor = kitConfig.editor ? deckEditorBlock(kitConfig.editor) : editor;
564
+ const nextServer = kitConfig.server ? serverForDeck(kitConfig.server, kitDir, alias) : server;
565
+ writeJsonFile(configPath, {
566
+ ...(nextEditor !== undefined ? { editor: nextEditor } : {}),
567
+ ...(nextServer !== undefined ? { server: nextServer } : {}),
568
+ ...rest,
569
+ });
570
+ }
530
571
  function scaffoldFromKitImport(kit, projectDir) {
531
572
  const kitDir = requireKitDir(kit);
532
573
  // Qualified like any other import (`<author>.<deck>`), and qualified NOW even
@@ -534,7 +575,7 @@ function scaffoldFromKitImport(kit, projectDir) {
534
575
  // writes, so it can't change later without rewriting them. Publishing the
535
576
  // kits under the castle account turns the pin into a deckId; the name it is
536
577
  // already known by stays put.
537
- const alias = `${KIT_AUTHOR}.${kit}`;
578
+ const alias = shippedKitAlias(kit);
538
579
  const pins = {};
539
580
  const copied = new Map();
540
581
  copyKitImport(projectDir, kitDir, kit, alias, pins, copied);
@@ -543,20 +584,8 @@ function scaffoldFromKitImport(kit, projectDir) {
543
584
  writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
544
585
  writeStarterScene(projectDir, kitDir, alias);
545
586
  writeStarterTheme(projectDir, kitDir);
546
- // The deck's own castle.json: the kit's editor config (panel layout, file
547
- // filters) as a starting point -- it is the deck's to edit from here -- plus
548
- // the import pin.
549
- //
550
- // `fileTypes` is deliberately NOT copied. It is the kit's own vocabulary, and
551
- // the deck resolves it live from every import's castle.json (see
552
- // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
553
- // reaches the deck like any other, and a kit imported LATER contributes its
554
- // types too, which a copy taken at scaffold time never could.
555
- writeJsonFile(path.join(projectDir, 'castle.json'), {
556
- ...(kitConfig.editor ? { editor: deckEditorBlock(kitConfig.editor) } : {}),
557
- ...(kitConfig.server ? { server: serverForDeck(kitConfig.server, kitDir, alias) } : {}),
558
- imports: pins,
559
- });
587
+ writeJsonFile(path.join(projectDir, 'castle.json'), { imports: pins });
588
+ adoptKitConfig(projectDir, kitDir, alias);
560
589
  // The kit's code runs from THIS deck's node_modules, so its dependencies are
561
590
  // declared here (see syncImportDependencies, which does the same for imports
562
591
  // added later). Every copied kit contributes, the scaffolding kit first, so
@@ -0,0 +1,13 @@
1
+ export declare const KIT_AUTHOR = "castle";
2
+ export declare function shippedKitAlias(kit: string): string;
3
+ export declare function kitFromAlias(alias: string): string;
4
+ export interface ShippedKit {
5
+ name: string;
6
+ alias: string;
7
+ description: string;
8
+ fileTypeLabels: string[];
9
+ }
10
+ export declare function shippedFrameworkKit(ref: string, kitsDir?: string): string | null;
11
+ export declare function listShippedKits(kitsDir?: string): ShippedKit[];
12
+ export declare function kitCatalogLine(kit: ShippedKit): string;
13
+ export declare function kitCatalogLines(deckDir: string, kitsDir?: string): string[] | undefined;
@@ -0,0 +1,111 @@
1
+ import * as fs from 'fs';
2
+ import * as path from 'path';
3
+ import { IMPORTS_DIR } from './castleJson.js';
4
+ import { getKitsDir } from './localPaths.js';
5
+ // The account the first-party kits are (to be) published under, so a kit
6
+ // imported from the CLI's copy is named the same as one fetched from the server.
7
+ export const KIT_AUTHOR = 'castle';
8
+ export function shippedKitAlias(kit) {
9
+ return `${KIT_AUTHOR}.${kit}`;
10
+ }
11
+ export function kitFromAlias(alias) {
12
+ return alias.startsWith(`${KIT_AUTHOR}.`) ? alias.slice(KIT_AUTHOR.length + 1) : alias;
13
+ }
14
+ function readKitConfig(kitsDir, kit) {
15
+ try {
16
+ return JSON.parse(fs.readFileSync(path.join(kitsDir, kit, 'castle.json'), 'utf8'));
17
+ }
18
+ catch {
19
+ return null;
20
+ }
21
+ }
22
+ function nonEmpty(value) {
23
+ return typeof value === 'string' && value.trim() ? value.trim() : null;
24
+ }
25
+ function isFramework(config) {
26
+ return !!config && nonEmpty(config.main) !== null;
27
+ }
28
+ export function shippedFrameworkKit(ref, kitsDir = getKitsDir()) {
29
+ const kit = kitFromAlias(ref.trim());
30
+ if (!kit || kit.includes('/') || kit.includes('\\') || kit.startsWith('.'))
31
+ return null;
32
+ return isFramework(readKitConfig(kitsDir, kit)) ? kit : null;
33
+ }
34
+ // Only framework imports are followed: the library kits under them (base above
35
+ // all) contribute types every deck already has, which is not what a kit offers.
36
+ function fileTypeLabels(kitsDir, kit, seen) {
37
+ if (seen.has(kit))
38
+ return [];
39
+ seen.add(kit);
40
+ const config = readKitConfig(kitsDir, kit);
41
+ if (!isFramework(config))
42
+ return [];
43
+ const labels = (config?.editor?.fileTypes ?? [])
44
+ .filter((type) => !type.unsupported)
45
+ .map((type) => nonEmpty(type.label))
46
+ .filter((label) => label !== null);
47
+ for (const alias of Object.keys(config?.imports ?? {})) {
48
+ labels.push(...fileTypeLabels(kitsDir, kitFromAlias(alias), seen));
49
+ }
50
+ return [...new Set(labels)];
51
+ }
52
+ export function listShippedKits(kitsDir = getKitsDir()) {
53
+ let names;
54
+ try {
55
+ names = fs
56
+ .readdirSync(kitsDir, { withFileTypes: true })
57
+ .filter((entry) => entry.isDirectory())
58
+ .map((entry) => entry.name);
59
+ }
60
+ catch {
61
+ return [];
62
+ }
63
+ const kits = [];
64
+ for (const name of names.sort()) {
65
+ const config = readKitConfig(kitsDir, name);
66
+ const description = nonEmpty(config?.description);
67
+ if (!isFramework(config) || !description)
68
+ continue;
69
+ kits.push({
70
+ name,
71
+ alias: shippedKitAlias(name),
72
+ description,
73
+ fileTypeLabels: fileTypeLabels(kitsDir, name, new Set()),
74
+ });
75
+ }
76
+ return kits;
77
+ }
78
+ function joinWithAnd(items) {
79
+ if (items.length <= 1)
80
+ return items.join('');
81
+ return `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
82
+ }
83
+ export function kitCatalogLine(kit) {
84
+ const opens = kit.fileTypeLabels.length ? ` Opens ${joinWithAnd(kit.fileTypeLabels)} files.` : '';
85
+ return `- ${kit.name}: ${kit.description}${opens} Import it with: castle-web add-import ${kit.name}`;
86
+ }
87
+ // What the router may offer a deck that runs no kit. A deck that already
88
+ // imports one -- shipped, fetched or its author's own -- gets nothing: its guide
89
+ // is that kit's, and offering a second framework on top of it would be offering
90
+ // to replace the first.
91
+ export function kitCatalogLines(deckDir, kitsDir = getKitsDir()) {
92
+ const kits = listShippedKits(kitsDir);
93
+ if (kits.length === 0)
94
+ return undefined;
95
+ let imports = {};
96
+ try {
97
+ imports = JSON.parse(fs.readFileSync(path.join(deckDir, 'castle.json'), 'utf8')).imports ?? {};
98
+ }
99
+ catch {
100
+ imports = {};
101
+ }
102
+ const aliases = Object.keys(imports);
103
+ // The shipped-alias check also covers a pin whose tree is not on disk yet
104
+ // (a fresh clone before the serve restores imports/).
105
+ if (kits.some((kit) => aliases.includes(kit.alias)))
106
+ return undefined;
107
+ if (aliases.some((alias) => isFramework(readKitConfig(path.join(deckDir, IMPORTS_DIR), alias)))) {
108
+ return undefined;
109
+ }
110
+ return kits.map(kitCatalogLine);
111
+ }
@@ -158,7 +158,7 @@ export function quickReferenceFor(deckDir, quickReference, role) {
158
158
  const COMMON_SECTIONS = `## Imports are read-only
159
159
 
160
160
  - **\`imports/\` holds other decks' files and is locked read-only on disk.** Files are mode 0444 and directories 0555, so any shell command that writes, moves, or deletes inside \`imports/\` fails with \`EACCES\` / "Permission denied" — that is the lock working, not a broken checkout. Do not \`chmod\` around it, do not \`sudo\`, and do not retry the command a different way.
161
- - **Change an import through the CLI, never the filesystem.** \`castle-web add-import <deckIdOrUrl>\` adds one and \`castle-web update-import [alias]\` re-fetches it (\`--check\` to see if it is outdated, \`--revert\` to undo). These handle the unlock/relock themselves.
161
+ - **Change an import through the CLI, never the filesystem.** \`castle-web add-import <deckIdOrUrl>\` adds one (or one of the kits the CLI ships, by its name) and \`castle-web update-import [alias]\` re-fetches it (\`--check\` to see if it is outdated, \`--revert\` to undo). These handle the unlock/relock themselves.
162
162
  - **\`castle-web list-decks [--kind mine|saved|kits]\` is how you find out WHAT can be imported** — one deck per line, starting with the id \`add-import\` takes, and marked when this deck already has it. \`imports/\` only shows what is here already; it is not a catalogue.
163
163
  - **To change one file of an import, FORK it**: \`castle-web fork-import-file <path>\` takes this deck's own version of that file, and every reference to the imported path uses your version from then on (\`castle-web revert-import-file <path>\` drops it and goes back to the import's). Fork only what you actually need to change, and as few files as you can -- a forked file stops taking the import's updates, so the more you fork the less an \`update-import\` can give you. To build something of your own rather than change theirs, write an ordinary file in this deck instead -- and check first whether the kit already lets a deck file register what you want (its CLAUDE.md names those seams), since that path keeps taking updates and a fork does not. When you do fork, it is often worth forking only to add a hook or registration point and keeping the logic itself in a deck file, so later changes need no further forks; for a quick one-off tweak a plain direct fork is fine.
164
164
  - **Deleting the deck directory itself needs the lock released first** (\`chmod -R u+w\` on the deck dir) — that is the one legitimate reason to touch the modes, and only for a directory being thrown away.
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "title": "multiplayer-2d",
3
+ "description": "Multiplayer. The Scene Editor, with multiple players in the same session.",
3
4
  "editor": {
4
5
  "defaultPlayFile": "scenes/main.scene"
5
6
  },
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "title": "multiplayer-3d",
3
+ "description": "Multiplayer with 3D (experimental). The Scene Editor 3D, with multiple players in the same session.",
3
4
  "editor": {
4
5
  "defaultPlayFile": "scenes/main.scene"
5
6
  },
@@ -67,6 +67,7 @@
67
67
  "autoUpdateWhenImported": true,
68
68
  "onUpdate": "scripts/onUpdate.mjs",
69
69
  "title": "physics-2d",
70
+ "description": "Scene Editor. Works like classic Castle: actors, blueprints, behaviors and drawing tools, with physics built in.",
70
71
  "publishedVersion": "2026-09-23T02:16:34.231Z",
71
72
  "imports": {
72
73
  "castle.base": {
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "title": "physics-3d",
3
+ "description": "Scene Editor 3D (experimental). The Scene Editor in 3D, with physics built in.",
3
4
  "editor": {
4
5
  "initialPanels": [
5
6
  {
@@ -1,5 +1,6 @@
1
1
  {
2
2
  "title": "turn-based",
3
+ "description": "Turn-based. The Scene Editor, with players taking turns and each seeing state only they can see.",
3
4
  "editor": {
4
5
  "defaultPlayFile": "scenes/main.scene"
5
6
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "castle-web-cli",
3
- "version": "0.4.205",
3
+ "version": "0.4.206",
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 && 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",
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/router-fences.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.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/router-fences.mjs && node ../scripts/tests/task-account.mjs && node ../scripts/tests/effort-support.mjs && eslint . && jscpd && tsc --noEmit && tsc --noEmit -p src/shell/tsconfig.json"
16
16
  },
17
17
  "jscpd": {
18
18
  "path": [