create-shallot 0.6.0 → 0.8.1

package/index.ts

@@ -3,26 +3,16 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
 
-export interface TemplateOptions {
-    /**
-     * dependency spec for `@dylanebert/shallot`. `"latest"` for the published `bun create shallot`
-     * scaffold; `"workspace:*"` when `bun run build` regenerates examples/templates/* in-repo.
-     */
-    shallot?: string;
-}
-
 /**
- * the project files keyed by relative path, with the project name interpolated. single source of
- * truth for both `bun create shallot <name>` and the in-repo examples/templates/starter example
- * (regenerated by `bun run build`).
+ * the project files keyed by relative path, with the project name interpolated. the single source of
+ * truth for `bun create shallot <name>`.
  *
  * the project is pure data — a `shallot.json` manifest + plugin modules + `public/`, no vite
- * boilerplate. the CLI provides every harness over it: `shallot dev` runs it standalone (`bun dev`),
- * `shallot .` opens it in the editor, `shallot build` ships it (web + native targets).
+ * boilerplate. the CLI provides every harness over it: `shallot dev` runs it standalone with hot
+ * reload, `shallot build` ships it (web + native targets). the emitted CLAUDE.md / AGENTS.md point an
+ * agent at the installed engine's contract.
  */
-export function template(name: string, opts: TemplateOptions = {}): Record<string, string> {
-    const shallot = opts.shallot ?? "latest";
-
+export function template(name: string): Record<string, string> {
     return {
         "public/icon.svg": ICON,
         ".gitignore": "node_modules/\ndist/\nbuild/\n",
@@ -33,8 +23,8 @@ export function template(name: string, opts: TemplateOptions = {}): Record<strin
                     version: "0.0.0",
                     private: true,
                     type: "module",
-                    dependencies: { "@dylanebert/shallot": shallot },
-                    devDependencies: { typescript: "^5.9.3" },
+                    dependencies: { "@dylanebert/shallot": "latest" },
+                    devDependencies: { typescript: "^7.0.2" },
                 },
                 null,
                 2,
@@ -58,18 +48,15 @@ export function template(name: string, opts: TemplateOptions = {}): Record<strin
                 2,
             ) + "\n",
         "shallot.json": MANIFEST,
+        "src/env.d.ts": ENV,
         "src/spin.ts": SPIN,
         "public/scenes/scene.scene": SCENE,
         "README.md": readme(name),
+        "AGENTS.md": agents(name),
+        "CLAUDE.md": agents(name),
     };
 }
 
-/**
- * the committed in-repo template under examples/templates/<dir>. the source of truth for what
- * `bun run build` regenerates and `bun check` gates for staleness.
- */
-export const TEMPLATES: { dir: string }[] = [{ dir: "starter" }];
-
 /** write a template file map under dir, creating parent directories as needed. */
 export function scaffold(dir: string, files: Record<string, string>): void {
     for (const [rel, content] of Object.entries(files)) {
@@ -111,8 +98,8 @@ bunx shallot dev
 \`\`\`
 
 \`bun install\` fetches the engine. \`bunx shallot dev\` runs the project with hot
-reload; \`bunx shallot\` opens it in the editor. Edit \`src/spin.ts\` (a plugin) and
-\`shallot.json\` (the manifest: scene + plugin enablement) in your IDE.
+reload. Edit \`src/spin.ts\` (a plugin) and \`shallot.json\` (the manifest: scene +
+plugin enablement) in your IDE.
 
 ## Ship
 
@@ -124,11 +111,54 @@ Builds a web bundle to \`dist/\`. For native targets:
 \`bunx shallot build --target windows|mac|linux\` (add \`--release\` for an optimized build).
 `;
 
-// The project manifest: the editor (\`shallot .\`) and a shipped build both read it. \`scene\`
-// is the scene to open; \`plugins\` is enablement — "Orbit": true turns on the orbit camera the
-// scene uses, and "Spin": "./src/spin" declares our own plugin by its module path. The default
-// plugins (render, lit surface) are on unless you set one false. Toggle these in the editor's
-// plugin menu and it rewrites this file, so the editor and a build always agree on what loads.
+const agents = (name: string) => `# ${name}
+
+A WebGPU game built on \`@dylanebert/shallot\`.
+
+## Layout
+
+- \`shallot.json\` — the manifest: which scene to open + which plugins to enable
+- \`public/scenes/*.scene\` — the world as declarative XML (each \`<a>\` is an entity, each attribute a component)
+- \`src/*.ts\` — your plugins (a plugin is data: components + systems)
+
+## Build, run, verify
+
+\`\`\`bash
+bunx tsc --noEmit                                # typecheck — run after every change
+bunx shallot dev                                 # run with hot reload while you work
+bunx shallot build [--target windows|mac|linux]  # ship it (web bundle, or a native app)
+bunx shallot verify                              # prove it: boot headless, check it renders, exit 0/nonzero
+\`\`\`
+
+\`shallot verify\` is the verification step — a self-terminating gate that boots the project in a real
+headless browser, waits for a settled frame, and exits nonzero on failure. Nothing left running. \`--json\`
+emits the full result; \`--screenshot <path>\` saves a frame. It drives Playwright, an optional one-time
+install: \`bun add -d playwright && bunx playwright install chromium\` (exit code 3 names this command if
+it's missing). By default it checks the scene rendered; to assert your own pass/fail (entity poses,
+physics state) install \`window.__harness\` via \`installHarness\` from \`@dylanebert/shallot/harness\` — in a
+manifest project like this one, from a plugin's \`initialize(state)\` hook (the engine's AGENTS.md has the
+worked example).
+
+## Engine reference
+
+The engine is the documentation. Read \`node_modules/@dylanebert/shallot/AGENTS.md\` for the full
+contract (ECS, plugins, scenes, GPU, UI, and the \`shallot verify\` harness), and every public export
+carries JSDoc. The examples index lives at \`node_modules/@dylanebert/shallot/examples/AGENTS.md\` — grep
+it for the problem you have, then read that recipe's source, before writing a pattern from scratch.
+\`bunx shallot recipe <name> [dir]\` copies a recipe out of the installed package into a runnable project
+(bare: lists them).
+
+## Conventions
+
+Data-oriented, ECS, declarative. Add components and systems, not methods — a \`Jump\` marker plus a
+system, never \`player.jump()\`. Scenes declare; code transforms. One source of truth: every value has
+one authoritative home; derive, don't duplicate.
+`;
+
+// The project manifest: `shallot dev` and a shipped `shallot build` both read it. `scene` is the scene
+// to open; `plugins` is enablement — "Orbit": true turns on the orbit camera the scene uses, and
+// "Spin": "./src/spin" declares our own plugin by its module path. The default plugins (render, lit
+// surface) are on unless you set one false.
 const MANIFEST = `{
   "$schema": "./node_modules/@dylanebert/shallot/shallot.schema.json",
   "scene": "scenes/scene.scene",
@@ -139,12 +169,16 @@ const MANIFEST = `{
 }
 `;
 
+// Ambient types + the tsconfig anchor. `include: ["src"]` needs at least one matching file, so this
+// keeps `bunx tsc --noEmit` green (no TS18003) even when spin.ts is deleted for a static scene. It's
+// infrastructure, not demo content — don't delete it.
+const ENV = `/// <reference types="@webgpu/types" />
+`;
+
 const SPIN = `import { type Plugin, type State, type System, Part, quat, Transform } from "@dylanebert/shallot";
 
-// A plugin is plain data: components + systems the engine runs. This system spins every Part
-// around Y. It runs when the project plays (the editor's preview, or a shipped build) but not
-// while you edit — the editor (\`bunx shallot\`) builds in edit mode, where unannotated systems
-// are skipped, so the cube stays put and editable there. Delete this file (and its
+// A plugin is plain data: components + systems the engine runs. This system spins every Part around Y.
+// It runs in the "simulation" group, which plays when the project runs. Delete this file (and its
 // \`shallot.json\` entry) for a static scene.
 const SpinSystem: System = {
     group: "simulation",
@@ -159,7 +193,7 @@ const SpinSystem: System = {
 };
 
 // The default export is the plugin — \`shallot.json\` references this file by path and imports
-// its default. The name ("Spin") is how the plugin menu lists it.
+// its default. The name ("Spin") is how the manifest lists it.
 const SpinPlugin: Plugin = { name: "Spin", systems: [SpinSystem] };
 export default SpinPlugin;
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-shallot",
-    "version": "0.6.0",
+    "version": "0.8.1",
     "type": "module",
     "bin": "./index.ts",
     "files": ["index.ts"],