castle-web-cli 0.4.142 → 0.4.145
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.d.ts +1 -0
- package/dist/agent-prompts.js +7 -2
- package/dist/agent.js +11 -9
- package/dist/imports.js +44 -4
- package/dist/init.d.ts +4 -0
- package/dist/init.js +63 -26
- package/dist/install.js +4 -0
- package/dist/platformDoc.d.ts +12 -0
- package/dist/platformDoc.js +236 -0
- package/dist/serve.d.ts +3 -0
- package/dist/serve.js +157 -13
- package/dist/serveSecurity.d.ts +5 -1
- package/dist/serveSecurity.js +27 -8
- package/dist/shell/assets/index-BaiRLZ8p.css +1 -0
- package/dist/shell/assets/{index-qbygvQIx.js → index-CbRAepsq.js} +68 -68
- package/dist/shell/index.html +2 -2
- package/kits/blank/CLAUDE.md +198 -0
- package/kits/blank/castle.json +8 -0
- package/kits/blank/index.html +42 -0
- package/kits/blank/package-lock.json +10 -0
- package/kits/blank/package.json +9 -0
- package/kits/physics-2d/CLAUDE.md +44 -4
- package/kits/physics-2d/behaviors/Collider.jsx +21 -0
- package/kits/physics-2d/behaviors/Draggable.jsx +9 -0
- package/kits/physics-2d/behaviors/Layout.jsx +7 -0
- package/kits/physics-2d/behaviors/RigidBody.jsx +6 -0
- package/kits/physics-2d/behaviors/Sprite.jsx +9 -4
- package/kits/physics-2d/editors/BlueprintLibrary.jsx +64 -32
- package/kits/physics-2d/editors/NewBlueprintModal.jsx +69 -0
- package/kits/physics-2d/editors/PlayOnly.jsx +1 -1
- package/kits/physics-2d/editors/SceneEditor.jsx +333 -108
- package/kits/physics-2d/editors/SelectionOverlay.jsx +6 -2
- package/kits/physics-2d/editors/behaviorRegistry.js +78 -5
- package/kits/physics-2d/engine/SceneUI.jsx +2 -2
- package/kits/physics-2d/engine/blueprint.js +212 -15
- package/kits/physics-2d/engine/editorFlags.js +50 -0
- package/kits/physics-2d/engine/files.js +9 -0
- package/kits/physics-2d/engine/liveReload.js +16 -4
- package/kits/physics-2d/engine/panelPrefs.js +78 -0
- package/kits/physics-2d/engine/panelSorting.jsx +84 -0
- package/kits/physics-2d/engine/physics/PhysicsSystem.js +5 -2
- package/kits/physics-2d/engine/physics/matterBridge.js +12 -2
- package/kits/physics-2d/engine/scene.js +94 -3
- package/kits/physics-2d/engine/ui.jsx +157 -4
- package/kits/physics-2d/engine/ui.module.css +615 -1
- package/kits/physics-2d/package-lock.json +78 -1
- package/kits/physics-2d/package.json +4 -0
- package/kits/physics-3d/CLAUDE.md +2 -3
- package/package.json +1 -1
- package/dist/commonInstructions.d.ts +0 -1
- package/dist/commonInstructions.js +0 -26
- package/dist/shell/assets/index-CcVJjnL3.css +0 -1
package/dist/agent-prompts.d.ts
CHANGED
|
@@ -73,6 +73,7 @@ export declare function applyPlanOps(fileText: string, ops: PlanOp[], sources?:
|
|
|
73
73
|
export declare function renderPlanDigest(plan: RouterPlanOpts, tasks: PromptTask[]): string;
|
|
74
74
|
export declare function planOpenQuestionLines(fileText: string): string[];
|
|
75
75
|
export declare function renderTaskPlanSlice(fileText: string, item: string | undefined, finishedWork?: PlanFinishedWork[]): string;
|
|
76
|
+
export declare const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
|
|
76
77
|
export declare function buildRouterPrompt(opts: {
|
|
77
78
|
deckLabel: string;
|
|
78
79
|
quickReference?: string;
|
package/dist/agent-prompts.js
CHANGED
|
@@ -790,6 +790,11 @@ function renderTasks(tasks, showItems) {
|
|
|
790
790
|
})
|
|
791
791
|
.join("\n");
|
|
792
792
|
}
|
|
793
|
+
// Said outright rather than left out: a router/task agent on a deck with no
|
|
794
|
+
// quick reference otherwise cannot tell "no docs exist" from "the section was
|
|
795
|
+
// not included" and burns its first turns hunting for CLAUDE.md. Exported so
|
|
796
|
+
// the platform block (platformDoc.ts) can keep the sentence after itself.
|
|
797
|
+
export const NO_DECK_DOCS = "This deck has no CLAUDE.md / AGENTS.md quick reference. There is no documentation to read -- do not search for one (CLAUDE.md, README, **/*.md, etc.).";
|
|
793
798
|
export function buildRouterPrompt(opts) {
|
|
794
799
|
// Making the ABSENCE explicit, not just omitting the section, matters: a
|
|
795
800
|
// router on a bare/greenfield deck otherwise has no way to tell "no docs
|
|
@@ -799,7 +804,7 @@ export function buildRouterPrompt(opts) {
|
|
|
799
804
|
// 8-file deck with zero markdown files).
|
|
800
805
|
const quickReference = opts.quickReference?.trim()
|
|
801
806
|
? `\n\n== how this deck works ==\n${opts.quickReference.trim()}`
|
|
802
|
-
:
|
|
807
|
+
: `\n\n== how this deck works ==\n${NO_DECK_DOCS}`;
|
|
803
808
|
const deckFiles = opts.deckTree?.trim()
|
|
804
809
|
? `\n\n== deck files ==\n${opts.deckTree.trim()}`
|
|
805
810
|
: "";
|
|
@@ -869,7 +874,7 @@ export function buildTaskPrompt(opts) {
|
|
|
869
874
|
// does if it has to discover the absence itself via a failed read/grep.
|
|
870
875
|
const quickReference = opts.quickReference?.trim()
|
|
871
876
|
? `\n\nHow this deck works (from its docs -- read the full CLAUDE.md / AGENTS.md only when you need detail beyond this):\n\n${opts.quickReference.trim()}\n`
|
|
872
|
-
:
|
|
877
|
+
: `\n\n${NO_DECK_DOCS}\n`;
|
|
873
878
|
const layout = opts.deckTree?.trim()
|
|
874
879
|
? `\n\nDeck files (snapshot at task start; parallel sibling tasks may create files named in your prompt that are absent here):\n\n${opts.deckTree.trim()}\n`
|
|
875
880
|
: "";
|
package/dist/agent.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
// runs with --mode ask (read-only at the CLI level); task agents run with
|
|
16
16
|
// --force. Claude support can slot in later behind runAgentCli.
|
|
17
17
|
import { execFileSync, spawn } from 'child_process';
|
|
18
|
+
import { quickReferenceFor } from './platformDoc.js';
|
|
18
19
|
import { IMPORTS_DIR } from './imports.js';
|
|
19
20
|
import { isSameOriginUpgrade } from './wsOrigin.js';
|
|
20
21
|
import * as fs from 'fs';
|
|
@@ -641,13 +642,11 @@ function extractDirectives(full) {
|
|
|
641
642
|
};
|
|
642
643
|
}
|
|
643
644
|
const planSessions = new Map();
|
|
644
|
-
// What a deck that says nothing gets.
|
|
645
|
-
//
|
|
646
|
-
//
|
|
647
|
-
// feature to someone outside the rollout. The cloud editor sets it per user
|
|
648
|
-
// from a feature gate; see serveOnPort in castle-www's cloudSandbox.ts.
|
|
645
|
+
// What a deck that says nothing gets. On unless the serve was explicitly told
|
|
646
|
+
// otherwise -- `CASTLE_AGENT_PLAN=off` is what the agent-qa harness uses to keep
|
|
647
|
+
// the plan doc out of scenarios that aren't testing it.
|
|
649
648
|
function planDefault() {
|
|
650
|
-
return process.env.CASTLE_AGENT_PLAN
|
|
649
|
+
return process.env.CASTLE_AGENT_PLAN !== 'off';
|
|
651
650
|
}
|
|
652
651
|
function planSession(deckDir) {
|
|
653
652
|
const existing = planSessions.get(deckDir);
|
|
@@ -1355,7 +1354,10 @@ function readClaudeSectionWithImports(deckDir, section) {
|
|
|
1355
1354
|
const text = readClaudeSection(path.join(deckDir, IMPORTS_DIR, alias), section);
|
|
1356
1355
|
if (!text)
|
|
1357
1356
|
continue;
|
|
1358
|
-
|
|
1357
|
+
// "not the entry" only distinguishes an import from the one that IS the
|
|
1358
|
+
// entry. A deck running its own code has no entry import, and every import
|
|
1359
|
+
// it has is simply an import.
|
|
1360
|
+
const role = alias === entry ? 'this deck runs on it' : entry ? 'imported, not the entry' : 'imported';
|
|
1359
1361
|
parts.push(`### from the ${alias} kit (${role})\n\n${text}`);
|
|
1360
1362
|
}
|
|
1361
1363
|
return parts.join('\n\n');
|
|
@@ -2377,7 +2379,7 @@ async function runTaskAgentIn(ctx, task) {
|
|
|
2377
2379
|
? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
|
|
2378
2380
|
: undefined),
|
|
2379
2381
|
deckContents,
|
|
2380
|
-
quickReference: ctx.quickReference,
|
|
2382
|
+
quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, ctx.backend),
|
|
2381
2383
|
plan: taskPlanOpts(ctx.deckDir, task.item, ctx.finishedWork),
|
|
2382
2384
|
siblings: ctx.siblings,
|
|
2383
2385
|
});
|
|
@@ -3103,7 +3105,7 @@ function routerTurnPrompt(ctx, instruction, selfMessageId, plan) {
|
|
|
3103
3105
|
const isSmith = ctx.backend() === 'smith';
|
|
3104
3106
|
return buildRouterPrompt({
|
|
3105
3107
|
deckLabel: ctx.deckLabel,
|
|
3106
|
-
quickReference: ctx.quickReference,
|
|
3108
|
+
quickReference: quickReferenceFor(ctx.deckDir, ctx.quickReference, ctx.backend()),
|
|
3107
3109
|
deckTree: buildDeckTree(ctx.deckDir, isSmith
|
|
3108
3110
|
? { maxEntries: DECK_TREE_SLIM_MAX_ENTRIES, perDir: DECK_TREE_SLIM_PER_DIR }
|
|
3109
3111
|
: undefined),
|
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 { writePlatformDocs } from './platformDoc.js';
|
|
8
9
|
import { ensureVisibleGlob, IMPORTS_DIR, readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
|
|
9
10
|
// Adding another deck as a dependency (`castle-web add-import`; removing one is a
|
|
10
11
|
// later command). Deliberately NOT `get-deck`: that one
|
|
@@ -185,6 +186,19 @@ function unlockImportTree(dir) {
|
|
|
185
186
|
// leaves its packages behind -- harmless (an unused package), and the honest
|
|
186
187
|
// alternative needs provenance we don't track yet: once a deck starts importing
|
|
187
188
|
// a package directly, "who added it" is no longer answerable from package.json.
|
|
189
|
+
// Never fatal: a deck whose install failed is still a deck whose files updated,
|
|
190
|
+
// so name the recovery command rather than aborting the serve.
|
|
191
|
+
async function installAddedDependencies(deckDir, added) {
|
|
192
|
+
if (added.length === 0)
|
|
193
|
+
return;
|
|
194
|
+
try {
|
|
195
|
+
const { installDeps } = await import('./install.js');
|
|
196
|
+
await installDeps(deckDir, false);
|
|
197
|
+
}
|
|
198
|
+
catch (e) {
|
|
199
|
+
console.warn(`Added ${added.length === 1 ? 'a dependency' : `${added.length} dependencies`} but installing failed -- run \`castle-web install\`. ${e instanceof Error ? e.message : String(e)}`);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
188
202
|
export function syncImportDependencies(deckDir) {
|
|
189
203
|
const deckPkgPath = path.join(deckDir, 'package.json');
|
|
190
204
|
let deckPkg;
|
|
@@ -380,6 +394,23 @@ function backupImport(deckDir, alias) {
|
|
|
380
394
|
fs.writeFileSync(path.join(dest, '.castle-import-pin.json'), JSON.stringify(pin, null, 2), 'utf-8');
|
|
381
395
|
}
|
|
382
396
|
}
|
|
397
|
+
// The docs-only kit a bare scaffold imports for its agent guide. A deck that
|
|
398
|
+
// adopts a real kit no longer has anything to say: leaving it would put two
|
|
399
|
+
// quick references in front of the agent every turn, one of them opening "No
|
|
400
|
+
// kit: nothing in this deck comes from a framework" about a deck that has one.
|
|
401
|
+
function dropBareDocsImport(deckDir, alias) {
|
|
402
|
+
const dir = path.join(deckDir, IMPORTS_DIR, alias);
|
|
403
|
+
if (fs.existsSync(dir)) {
|
|
404
|
+
unlockImportTree(dir);
|
|
405
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
406
|
+
}
|
|
407
|
+
const existing = readCastleJson(deckDir);
|
|
408
|
+
if (!existing?.imports?.[alias])
|
|
409
|
+
return;
|
|
410
|
+
const imports = { ...existing.imports };
|
|
411
|
+
delete imports[alias];
|
|
412
|
+
fs.writeFileSync(path.join(deckDir, 'castle.json'), JSON.stringify({ ...existing, imports }, null, 2) + '\n', 'utf-8');
|
|
413
|
+
}
|
|
383
414
|
async function placeImport(deckDir, alias, deckId, source, via) {
|
|
384
415
|
const destDir = path.join(deckDir, IMPORTS_DIR, alias);
|
|
385
416
|
const replaced = fs.existsSync(destDir);
|
|
@@ -493,10 +524,12 @@ export async function addImportTo(dir, options = {}) {
|
|
|
493
524
|
const declaredMain = tryReadCastleJson(importDir)?.main;
|
|
494
525
|
let adoptedMain = null;
|
|
495
526
|
if (typeof declaredMain === 'string' && declaredMain.trim()) {
|
|
496
|
-
const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme } = await import('./init.js');
|
|
527
|
+
const { isPristineBareDeck, adoptImportEntry, writeStarterScene, writeStarterTheme, retargetBareClaudeMd, BARE_DOCS_ALIAS, } = await import('./init.js');
|
|
497
528
|
if (isPristineBareDeck(targetDir)) {
|
|
498
529
|
adoptImportEntry(targetDir, alias, declaredMain.trim());
|
|
499
530
|
adoptedMain = declaredMain.trim();
|
|
531
|
+
retargetBareClaudeMd(targetDir, alias);
|
|
532
|
+
dropBareDocsImport(targetDir, BARE_DOCS_ALIAS);
|
|
500
533
|
// A kit's runtime with no scene to run is a blank screen, and the agent
|
|
501
534
|
// has nothing to edit. Give the deck the kit's own starter, same as
|
|
502
535
|
// `init --kit`. Only when the deck has no scenes -- never overwrite.
|
|
@@ -535,6 +568,9 @@ export async function addImportTo(dir, options = {}) {
|
|
|
535
568
|
console.warn(`Imported ${alias}, but installing its dependencies failed -- run \`castle-web install\`. ${e instanceof Error ? e.message : String(e)}`);
|
|
536
569
|
}
|
|
537
570
|
}
|
|
571
|
+
// The platform guide's media list names the deck's declared types, which
|
|
572
|
+
// this import may have just changed.
|
|
573
|
+
writePlatformDocs(targetDir);
|
|
538
574
|
const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
|
|
539
575
|
const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
|
|
540
576
|
return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
|
|
@@ -682,9 +718,10 @@ export async function autoUpdateImports(deckDir) {
|
|
|
682
718
|
}
|
|
683
719
|
}
|
|
684
720
|
if (updated.length > 0) {
|
|
685
|
-
|
|
721
|
+
const added = syncImportDependencies(deckDir);
|
|
722
|
+
for (const dep of added)
|
|
686
723
|
console.log(`auto-update: added dependency ${dep}`);
|
|
687
|
-
|
|
724
|
+
await installAddedDependencies(deckDir, added);
|
|
688
725
|
}
|
|
689
726
|
return updated;
|
|
690
727
|
}
|
|
@@ -711,7 +748,8 @@ export async function updateImport(dir, options = {}) {
|
|
|
711
748
|
if (options.revert) {
|
|
712
749
|
for (const alias of aliases)
|
|
713
750
|
revertImport(deckDir, alias);
|
|
714
|
-
syncImportDependencies(deckDir);
|
|
751
|
+
await installAddedDependencies(deckDir, syncImportDependencies(deckDir));
|
|
752
|
+
writePlatformDocs(deckDir);
|
|
715
753
|
return;
|
|
716
754
|
}
|
|
717
755
|
let changed = false;
|
|
@@ -749,6 +787,8 @@ export async function updateImport(dir, options = {}) {
|
|
|
749
787
|
const added = syncImportDependencies(deckDir);
|
|
750
788
|
for (const dep of added)
|
|
751
789
|
console.log(`Added dependency ${dep}`);
|
|
790
|
+
await installAddedDependencies(deckDir, added);
|
|
791
|
+
writePlatformDocs(deckDir);
|
|
752
792
|
console.log('Play the deck to check the update before saving; `--revert` puts the old version back.');
|
|
753
793
|
}
|
|
754
794
|
// Restore the copy taken when this import was last replaced.
|
package/dist/init.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
export declare const BARE_DOCS_KIT = "blank";
|
|
2
|
+
export declare const BARE_DOCS_ALIAS = "castle.blank";
|
|
1
3
|
export declare function resolveScaffoldRefs(): {
|
|
2
4
|
workspaceMode: boolean;
|
|
3
5
|
sdkRef: string;
|
|
@@ -5,11 +7,13 @@ export declare function resolveScaffoldRefs(): {
|
|
|
5
7
|
cliDistAbs: string | null;
|
|
6
8
|
sdkPathPosix: string | null;
|
|
7
9
|
};
|
|
10
|
+
export declare function ensureAgentsSymlink(projectDir: string): void;
|
|
8
11
|
export declare function isPristineBareDeck(dir: string): boolean;
|
|
9
12
|
export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
|
|
10
13
|
export declare function getCliVersion(): string;
|
|
11
14
|
export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
|
|
12
15
|
export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
|
|
16
|
+
export declare function retargetBareClaudeMd(deckDir: string, alias: string): void;
|
|
13
17
|
export declare function init(dir: string, opts?: {
|
|
14
18
|
kit?: string;
|
|
15
19
|
serve?: boolean;
|
package/dist/init.js
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import * as fs from 'fs';
|
|
2
2
|
import * as path from 'path';
|
|
3
|
-
import {
|
|
3
|
+
import { CLAUDE_MD_PLATFORM_SECTION } from './platformDoc.js';
|
|
4
4
|
import { installDeps } from './install.js';
|
|
5
5
|
import { deckMainFile, deckStarterScene } from './castleJson.js';
|
|
6
6
|
import { addImportTo, IMPORTS_DIR, lockImportTree, restoreMissingImports, syncImportDependencies, } from './imports.js';
|
|
7
7
|
import { discardParentSource, fetchParentSource, unpackParentSource, writeRemixIdentity, } from './remix.js';
|
|
8
|
-
import { getCliEntryPath, getKitsDir,
|
|
8
|
+
import { getCliEntryPath, getKitsDir, getSdkPackagePath, toPosixPath, } from './localPaths.js';
|
|
9
9
|
import { serve } from './serve.js';
|
|
10
10
|
import { createVersion } from './versions.js';
|
|
11
11
|
const INDEX_HTML = `<!DOCTYPE html>
|
|
@@ -36,13 +36,21 @@ card.appendChild(el);
|
|
|
36
36
|
// Default kit imported by `init` when no --kit is given. `none`/`bare` skip the
|
|
37
37
|
// kit and produce the minimal index.html + game.js stub above.
|
|
38
38
|
const DEFAULT_KIT = 'physics-2d';
|
|
39
|
+
// A kit-less deck still imports ONE kit: a docs-only deck holding the guide to
|
|
40
|
+
// building without a framework. It is imported rather than written into the
|
|
41
|
+
// deck's own CLAUDE.md so it behaves like every other kit's guide -- the quick
|
|
42
|
+
// reference reaches the agent every turn, the rest is read on demand, and the
|
|
43
|
+
// text ships to existing decks via `autoUpdateWhenImported` instead of waiting
|
|
44
|
+
// for whatever CLI release the deck was scaffolded by.
|
|
45
|
+
export const BARE_DOCS_KIT = 'blank';
|
|
39
46
|
// Registry version of castle-web-sdk to inject when scaffolding from a
|
|
40
47
|
// globally-installed castle-web (not from inside the workspace). Bumped
|
|
41
48
|
// alongside cli/sdk version bumps.
|
|
42
|
-
const PUBLISHED_SDK_VERSION = '0.4.
|
|
49
|
+
const PUBLISHED_SDK_VERSION = '0.4.18';
|
|
43
50
|
// The account the first-party kits are (to be) published under, so a kit
|
|
44
51
|
// imported from the CLI's copy is named the same as one fetched from the server.
|
|
45
52
|
const KIT_AUTHOR = 'castle';
|
|
53
|
+
export const BARE_DOCS_ALIAS = `${KIT_AUTHOR}.${BARE_DOCS_KIT}`;
|
|
46
54
|
// Never copied into a deck's import: build/dependency junk.
|
|
47
55
|
const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git']);
|
|
48
56
|
// The bare (`--kit none`) deck's default editor config: just the Files panel and
|
|
@@ -77,28 +85,15 @@ export function resolveScaffoldRefs() {
|
|
|
77
85
|
sdkPathPosix,
|
|
78
86
|
};
|
|
79
87
|
}
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
const repoRoot = getRepoRoot();
|
|
85
|
-
const upstream = path.join(repoRoot, 'CLAUDE.md');
|
|
86
|
-
try {
|
|
87
|
-
return fs.readFileSync(upstream, 'utf8').trimEnd() + '\n';
|
|
88
|
-
}
|
|
89
|
-
catch {
|
|
90
|
-
return `# Castle Experimental Web\n\nSee https://github.com/castle-xyz/castle-experimental-web for the agent guide.\n`;
|
|
91
|
-
}
|
|
92
|
-
}
|
|
93
|
-
// Append the cli-owned common guidance to the deck's CLAUDE.md. Runs after
|
|
94
|
-
// the kit's (or bare) CLAUDE.md is written; the AGENTS.md symlink picks the
|
|
95
|
-
// appended content up for free.
|
|
96
|
-
function appendCommonInstructions(projectDir) {
|
|
88
|
+
// Append the platform section -- the @import of the serve-written platform
|
|
89
|
+
// guide (platformDoc.ts) -- after the kit's (or bare) pointer is written. The
|
|
90
|
+
// AGENTS.md symlink picks it up for free.
|
|
91
|
+
function appendPlatformSection(projectDir) {
|
|
97
92
|
const claudePath = path.join(projectDir, 'CLAUDE.md');
|
|
98
93
|
const existing = fs.existsSync(claudePath)
|
|
99
94
|
? fs.readFileSync(claudePath, 'utf8').trimEnd() + '\n\n'
|
|
100
95
|
: '';
|
|
101
|
-
fs.writeFileSync(claudePath, existing +
|
|
96
|
+
fs.writeFileSync(claudePath, existing + CLAUDE_MD_PLATFORM_SECTION);
|
|
102
97
|
}
|
|
103
98
|
function tryMakeAgentsSymlink(agentsPath) {
|
|
104
99
|
try {
|
|
@@ -143,7 +138,7 @@ function makePackageJson(projectDir) {
|
|
|
143
138
|
}
|
|
144
139
|
// Some coding agents read AGENTS.md by convention. Symlink so they get the
|
|
145
140
|
// same guidance without a duplicate copy.
|
|
146
|
-
function ensureAgentsSymlink(projectDir) {
|
|
141
|
+
export function ensureAgentsSymlink(projectDir) {
|
|
147
142
|
const agentsPath = path.join(projectDir, 'AGENTS.md');
|
|
148
143
|
if (fs.lstatSync(agentsPath, { throwIfNoEntry: false }))
|
|
149
144
|
return;
|
|
@@ -182,11 +177,16 @@ function scaffoldBare(projectDir) {
|
|
|
182
177
|
fs.mkdirSync(projectDir, { recursive: true });
|
|
183
178
|
fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
|
|
184
179
|
fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
180
|
+
const pins = {};
|
|
181
|
+
copyKitImport(projectDir, requireKitDir(BARE_DOCS_KIT), BARE_DOCS_KIT, BARE_DOCS_ALIAS, pins, new Map());
|
|
182
|
+
writeJsonFile(path.join(projectDir, 'castle.json'), { ...BARE_CASTLE_JSON, imports: pins });
|
|
183
|
+
fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeBareClaudeMd(BARE_DOCS_ALIAS));
|
|
184
|
+
appendPlatformSection(projectDir);
|
|
188
185
|
ensureAgentsSymlink(projectDir);
|
|
189
186
|
fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
|
|
187
|
+
// The docs kit declares no dependencies, so unlike a real kit's import there
|
|
188
|
+
// is nothing to merge into package.json before the install.
|
|
189
|
+
lockImportTree(path.join(projectDir, IMPORTS_DIR, BARE_DOCS_ALIAS));
|
|
190
190
|
}
|
|
191
191
|
// Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
|
|
192
192
|
// build/dependency junk and castle.json.
|
|
@@ -295,6 +295,24 @@ export function writeStarterTheme(projectDir, kitDir) {
|
|
|
295
295
|
return;
|
|
296
296
|
fs.copyFileSync(src, dest);
|
|
297
297
|
}
|
|
298
|
+
function makeBareClaudeMd(alias) {
|
|
299
|
+
return `# Castle deck (no kit)
|
|
300
|
+
|
|
301
|
+
This deck is a normal browser project: \`index.html\` loads \`game.js\` as an ES
|
|
302
|
+
module, \`package.json\` holds its scripts and any npm package it adds, and
|
|
303
|
+
\`castle.json\` is its editor config. Nothing here comes from a framework -- there
|
|
304
|
+
is no scene, behavior, sprite, or level format unless this deck defines one, and
|
|
305
|
+
no editor other than the code editor unless this deck builds one. Everything it
|
|
306
|
+
renders, it renders itself: DOM, canvas, WebGL, React, Pixi, Three, WebAssembly,
|
|
307
|
+
whatever the web offers.
|
|
308
|
+
|
|
309
|
+
Read \`${IMPORTS_DIR}/${alias}/CLAUDE.md\` for the authoring guide: the deck's
|
|
310
|
+
file layout, the Castle SDK, and how to give a file type an editor of its own.
|
|
311
|
+
|
|
312
|
+
Do not edit anything under \`${IMPORTS_DIR}/\`: those files belong to the deck they
|
|
313
|
+
came from, and are replaced wholesale when the import is updated.
|
|
314
|
+
`;
|
|
315
|
+
}
|
|
298
316
|
function makeImportedKitClaudeMd(alias) {
|
|
299
317
|
return `# Castle deck
|
|
300
318
|
|
|
@@ -312,6 +330,24 @@ something in the kit behaves, define your own behavior of the same name in
|
|
|
312
330
|
\`behaviors/\` -- the deck's own files win over an import's.
|
|
313
331
|
`;
|
|
314
332
|
}
|
|
333
|
+
// A bare deck's CLAUDE.md points at the docs kit, which adopting a real kit is
|
|
334
|
+
// about to remove. Rewrite it to point at the kit that is now mounted -- but
|
|
335
|
+
// only while the file is still byte-for-byte what the scaffold wrote, since
|
|
336
|
+
// `isPristineBareDeck` answers for the entry point and says nothing about
|
|
337
|
+
// whatever the creator may have written here.
|
|
338
|
+
export function retargetBareClaudeMd(deckDir, alias) {
|
|
339
|
+
const claudePath = path.join(deckDir, 'CLAUDE.md');
|
|
340
|
+
const scaffolded = makeBareClaudeMd(BARE_DOCS_ALIAS).trimEnd() + '\n\n' + CLAUDE_MD_PLATFORM_SECTION;
|
|
341
|
+
try {
|
|
342
|
+
if (fs.readFileSync(claudePath, 'utf8') !== scaffolded)
|
|
343
|
+
return;
|
|
344
|
+
}
|
|
345
|
+
catch {
|
|
346
|
+
return;
|
|
347
|
+
}
|
|
348
|
+
fs.writeFileSync(claudePath, makeImportedKitClaudeMd(alias));
|
|
349
|
+
appendPlatformSection(deckDir);
|
|
350
|
+
}
|
|
315
351
|
// How the deck names the kit it was built on. `scripts/publish-kits.mjs` stamps
|
|
316
352
|
// a published kit's castle.json with the deckId it lives at and the version it
|
|
317
353
|
// was published as, and both have to be present to pin it that way: a deckId
|
|
@@ -445,7 +481,8 @@ function scaffoldFromKitImport(kit, projectDir) {
|
|
|
445
481
|
dependencies,
|
|
446
482
|
});
|
|
447
483
|
fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias));
|
|
448
|
-
|
|
484
|
+
appendPlatformSection(projectDir);
|
|
485
|
+
ensureAgentsSymlink(projectDir);
|
|
449
486
|
for (const importedAlias of copied.keys()) {
|
|
450
487
|
lockImportTree(path.join(projectDir, IMPORTS_DIR, importedAlias));
|
|
451
488
|
}
|
package/dist/install.js
CHANGED
|
@@ -2,6 +2,7 @@ import { execSync, spawn } from 'child_process';
|
|
|
2
2
|
import * as fs from 'fs';
|
|
3
3
|
import * as path from 'path';
|
|
4
4
|
import { restoreMissingImports, syncImportDependencies } from './imports.js';
|
|
5
|
+
import { writePlatformDocs } from './platformDoc.js';
|
|
5
6
|
function hasPnpm() {
|
|
6
7
|
try {
|
|
7
8
|
execSync('pnpm --version', { stdio: 'ignore' });
|
|
@@ -67,6 +68,9 @@ export async function install(dir) {
|
|
|
67
68
|
const restored = await restoreMissingImports(projectDir);
|
|
68
69
|
for (const alias of restored)
|
|
69
70
|
console.log(`Restored import ${alias}`);
|
|
71
|
+
// A fetched deck's CLAUDE.md already @imports the platform guide; write it
|
|
72
|
+
// now rather than leaving the reference dangling until the first serve.
|
|
73
|
+
writePlatformDocs(projectDir);
|
|
70
74
|
// Imports declare packages the deck has to install (see syncImportDependencies).
|
|
71
75
|
// Re-done here, not just at add-import time, so a deck fetched with get-deck --
|
|
72
76
|
// which brings castle.json's pins but not the dependency files -- still ends up
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export declare const PLATFORM_DOCS_DIR: string;
|
|
2
|
+
export declare const PLATFORM_DOC_REL: string;
|
|
3
|
+
export declare function everyDeckBullets(deckDir: string): string[];
|
|
4
|
+
export declare const PLATFORM_SECTION_HEADING = "### from the Castle platform (every deck)";
|
|
5
|
+
export declare function platformSection(deckDir: string): string;
|
|
6
|
+
export declare function quickReferenceFor(deckDir: string, quickReference: string, backend: 'claude' | 'cursor' | 'smith'): string;
|
|
7
|
+
export declare function platformGuide(deckDir: string): string;
|
|
8
|
+
export declare function writePlatformDocs(deckDir: string): void;
|
|
9
|
+
export declare const CLAUDE_MD_IMPORT_LINE: string;
|
|
10
|
+
export declare const CLAUDE_MD_PLATFORM_SECTION: string;
|
|
11
|
+
export type ClaudeMdMigration = 'absent' | 'current' | 'migrated' | 'added' | 'kept' | 'gated';
|
|
12
|
+
export declare function migrateClaudeMd(deckDir: string): ClaudeMdMigration;
|