create-shallot 0.5.1 → 0.6.0

package/index.ts

@@ -1,27 +1,85 @@
 #!/usr/bin/env bun
 
 import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { join, resolve } from "path";
-
-const name = process.argv[2];
-if (!name) {
-    console.error("Usage: bun create shallot <project-name>");
-    process.exit(1);
+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;
 }
 
-const dir = resolve(name);
-if (existsSync(dir)) {
-    console.error(`Directory "${name}" already exists`);
-    process.exit(1);
+/**
+ * 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 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).
+ */
+export function template(name: string, opts: TemplateOptions = {}): Record<string, string> {
+    const shallot = opts.shallot ?? "latest";
+
+    return {
+        "public/icon.svg": ICON,
+        ".gitignore": "node_modules/\ndist/\nbuild/\n",
+        "package.json":
+            JSON.stringify(
+                {
+                    name,
+                    version: "0.0.0",
+                    private: true,
+                    type: "module",
+                    dependencies: { "@dylanebert/shallot": shallot },
+                    devDependencies: { typescript: "^5.9.3" },
+                },
+                null,
+                2,
+            ) + "\n",
+        "tsconfig.json":
+            JSON.stringify(
+                {
+                    compilerOptions: {
+                        target: "ESNext",
+                        module: "ESNext",
+                        moduleResolution: "bundler",
+                        lib: ["ESNext", "DOM", "DOM.Iterable"],
+                        types: ["@webgpu/types"],
+                        strict: true,
+                        noEmit: true,
+                        skipLibCheck: true,
+                    },
+                    include: ["src"],
+                },
+                null,
+                2,
+            ) + "\n",
+        "shallot.json": MANIFEST,
+        "src/spin.ts": SPIN,
+        "public/scenes/scene.scene": SCENE,
+        "README.md": readme(name),
+    };
 }
 
-mkdirSync(dir, { recursive: true });
-mkdirSync(join(dir, "src"), { recursive: true });
-mkdirSync(join(dir, "public/scenes"), { recursive: true });
+/**
+ * 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)) {
+        const path = join(dir, rel);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
+}
 
-writeFileSync(
-    join(dir, "public/icon.svg"),
-    `<svg id="Shallot" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80">
+const ICON = `<svg id="Shallot" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80">
   <title>shallot icon</title>
   <defs>
     <radialGradient id="baseGradient" cx="35%" cy="30%" r="70%" fx="25%" fy="20%">
@@ -39,148 +97,74 @@ writeFileSync(
     <path d="M40,2 C44,10 66,28 66,46 C66,60 48,70 40,78 C32,70 14,60 14,46 C14,28 36,10 40,2 Z" fill="none" stroke="#6B4230" stroke-width="2"/>
   </g>
 </svg>
-`,
-);
-
-writeFileSync(
-    join(dir, ".gitignore"),
-    `node_modules/
-dist/
-build/
-`,
-);
-
-writeFileSync(
-    join(dir, "package.json"),
-    JSON.stringify(
-        {
-            name,
-            version: "0.0.0",
-            private: true,
-            type: "module",
-            scripts: {
-                dev: "vite",
-                build: "vite build",
-                preview: "vite preview",
-            },
-            dependencies: { "@dylanebert/shallot": "latest" },
-            devDependencies: { typescript: "^5.9.3", vite: "^8.0.0" },
-        },
-        null,
-        2,
-    ) + "\n",
-);
-
-writeFileSync(
-    join(dir, "tsconfig.json"),
-    JSON.stringify(
-        {
-            compilerOptions: {
-                target: "ESNext",
-                module: "ESNext",
-                moduleResolution: "bundler",
-                lib: ["ESNext", "DOM", "DOM.Iterable"],
-                types: ["@webgpu/types", "vite/client"],
-                strict: true,
-                noEmit: true,
-                skipLibCheck: true,
-            },
-            include: ["src"],
-        },
-        null,
-        2,
-    ) + "\n",
-);
-
-writeFileSync(
-    join(dir, "index.html"),
-    `<!doctype html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <link rel="icon" type="image/svg+xml" href="./icon.svg" />
-        <title>${name}</title>
-        <style>
-            * { box-sizing: border-box; margin: 0; padding: 0; }
-            body { background: #0c0a09; overflow: hidden; }
-            canvas { display: block; width: 100vw; height: 100vh; }
-        </style>
-    </head>
-    <body>
-        <canvas id="canvas"></canvas>
-        <script type="module" src="./src/main.ts"></script>
-    </body>
-</html>
-`,
-);
-
-writeFileSync(
-    join(dir, "vite.config.ts"),
-    `import { defineConfig } from "vite";
-
-export default defineConfig({
-    base: "./",
-    server: { port: 3000 },
-    build: {
-        target: "esnext",
-        outDir: "dist",
-        emptyOutDir: true,
-    },
-});
-`,
-);
-
-writeFileSync(
-    join(dir, "src/lib.ts"),
-    `import { type Config, Part, quat, type State, type System, Transform } from "@dylanebert/shallot";
-
-// A system is plain data: an \`update\` the engine runs each frame. This one spins
-// every Part around Y. It runs in the standalone app but not the editor — \`shallot .\`
-// builds in edit mode, where unannotated systems are skipped, so the cube stays put
-// and editable there. Delete it (and the plugin entry below) for a static scene.
-let angle = 0;
+`;
+
+const readme = (name: string) => `# ${name}
+
+A shallot project.
+
+## Develop
+
+\`\`\`bash
+bun install
+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.
+
+## Ship
+
+\`\`\`bash
+bunx shallot build
+\`\`\`
+
+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 MANIFEST = `{
+  "$schema": "./node_modules/@dylanebert/shallot/shallot.schema.json",
+  "scene": "scenes/scene.scene",
+  "plugins": {
+    "Orbit": true,
+    "Spin": "./src/spin"
+  }
+}
+`;
+
+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
+// \`shallot.json\` entry) for a static scene.
 const SpinSystem: System = {
     group: "simulation",
     update(state: State) {
-        angle = (angle + state.time.deltaTime * 45) % 360;
-        const q = quat(0, angle, 0);
+        // Derive the angle from elapsed time, not a module-level accumulator, so it stays
+        // correct after a hot reload or State rebuild rather than carrying stale rotation.
+        const q = quat(0, (state.time.elapsed * 45) % 360, 0);
         for (const eid of state.query([Part, Transform])) {
             Transform.rot.set(eid, q.x, q.y, q.z, q.w);
         }
     },
 };
 
-// The project definition, shared by the standalone app (src/main.ts) and the shallot
-// editor (\`shallot .\`). The default plugins (render, lit surface, orbit camera) stay
-// on; the spin plugin adds our one system. The scene lives here too, so main.ts stays
-// untouched as the project grows.
-export const config: Config = {
-    plugins: [{ name: "spin", systems: [SpinSystem] }],
-    scene: "scenes/scene.scene",
-};
-`,
-);
-
-writeFileSync(
-    join(dir, "src/main.ts"),
-    `import { run } from "@dylanebert/shallot";
-import { config } from "./lib";
-
-// One config source (src/lib.ts) drives both this standalone build and the editor. The camera
-// auto-binds to the page's <canvas>.
-const { dispose } = await run(config);
+// 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.
+const SpinPlugin: Plugin = { name: "Spin", systems: [SpinSystem] };
+export default SpinPlugin;
+`;
 
-// HMR re-runs this module — dispose the old State + RAF loop or each reload stacks another.
-if (import.meta.hot) {
-    import.meta.hot.dispose(() => dispose());
-}
-`,
-);
-
-writeFileSync(
-    join(dir, "public/scenes/scene.scene"),
-    `<scene>
+const SCENE = `<scene>
     <a ambient-light="color: 0xd0dcec; intensity: 0.5" />
     <a directional-light="direction: -0.4 -1 -0.55; color: 0xfff4e0; intensity: 1.1" />
 
@@ -190,12 +174,28 @@ writeFileSync(
     <!-- a Part is the engine's drop-in renderable: a mesh (default "cube") wearing a surface (default "default", lit) -->
     <a part transform="pos: 0 0 0" color="rgba: 0.85 0.55 0.35 1" />
 </scene>
-`,
-);
-
-console.log(`Created ${name}/`);
-console.log();
-console.log("Next steps:");
-console.log(`  cd ${name}`);
-console.log("  bun install");
-console.log("  bun dev");
+`;
+
+if (import.meta.main) {
+    const args = process.argv.slice(2);
+    const name = args.find((a) => !a.startsWith("--"));
+    if (!name) {
+        console.error("Usage: bun create shallot <project-name>");
+        process.exit(1);
+    }
+
+    const dir = resolve(name);
+    if (existsSync(dir)) {
+        console.error(`Directory "${name}" already exists`);
+        process.exit(1);
+    }
+
+    scaffold(dir, template(name));
+
+    console.log(`Created ${name}/`);
+    console.log();
+    console.log("Next steps:");
+    console.log(`  cd ${name}`);
+    console.log("  bun install");
+    console.log("  bunx shallot dev");
+}

package/package.json

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