@vampgg/cli 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -2,15 +2,147 @@
 
 ECS code generator CLI for @vampgg. Parses Bebop (`.bop`) schemas and emits the
 TypeScript ECS components, factories, deltas, and mutation schemas used by a
-`@vampgg` game.
+`@vampgg` game. The binary is `vamp`.
 
-## Usage
+```bash
+pnpm add -D @vampgg/cli bebop-tools
+```
+
+> **Prerequisite:** `generate` shells out to `bebopc` (from `bebop-tools`). It must
+> be resolvable via `npx bebopc`, or `vamp generate` exits with a clear error. Use
+> `--skip-bebopc` if you regenerate `src/bebop.ts` separately.
+
+## Commands
+
+### `vamp init [--cwd <dir>]`
+
+Scaffolds a new game's schema: creates `schema/` with template `.bop` files
+(`entity.bop`, `actions.bop`, `state.bop`, `tags.bop`) plus `bebop.json` (the
+`bebopc` config) and `vamp.json` (the codegen config). Existing files are left
+untouched, so it's safe to re-run.
+
+### `vamp generate [--cwd <dir>] [--skip-bebopc] [--watch]`
+
+The codegen pipeline: emit `mutation.bop` (the `EntityDelta` / `MutationScope` wire
+types) from your `Entity` message → run `bebopc build` (→ `src/bebop.ts`, skip with
+`--skip-bebopc`) → emit the generated TypeScript.
 
 ```bash
-vamp init        # scaffold schema/ and a vamp.json config
-vamp generate    # parse the .bop schemas and (re)generate TypeScript output
+vamp generate            # one-shot regenerate
+vamp generate --watch    # re-run on schema changes (debounced; never drops a change)
+```
+
+## Generated output
+
+`vamp generate` runs `bebopc` (which writes `src/bebop.ts`) and then emits **three**
+TypeScript files from a single `vamp.json` `outFile` (default `./src/game.generated.ts`):
+
+| File                       | Depends on                                      | Import it from              |
+| -------------------------- | ----------------------------------------------- | --------------------------- |
+| `game.core.generated.ts`   | `@vampgg/ecs` only                              | anywhere (node, web, tests) |
+| `game.worker.generated.ts` | `@vampgg/worker` (imports `cloudflare:workers`) | a Cloudflare Worker only    |
+| `game.generated.ts`        | re-exports both (barrel)                        | Worker code / convenience   |
+
+The `game.core.generated.ts` file (component map, `EntityDelta`, `materialize/merge/accumulateDelta`,
+`createECSOptions`, the `createGame*` system factories) carries **no** Worker
+dependency — import it directly from non-Worker packages to keep `cloudflare:workers`
+out of your dependency graph. `game.worker.generated.ts` holds the `GameECS` durable
+object, runtime, and interest broadcast. The barrel keeps existing `./game.generated`
+imports working. Override the two part-file paths with `coreOutFile` / `workerOutFile`
+in `vamp.json`.
+
+### `env` (durable-object bindings type)
+
+The generated `GameECS` exposes an overridable `Env` generic that defaults to
+`Cloudflare.Env` (the `wrangler types` bindings interface). For a non-Worker package
+that has no wrangler types, set `env` in `vamp.json`:
+
+```jsonc
+{
+  "outFile": "./src/game.generated.ts",
+  "env": "unknown", // or "{}", or a locally-declared bindings type
+}
 ```
 
+### tsconfig / tooling
+
+- **`moduleResolution`**: `nodenext` **or** `bundler` both work — the generated
+  relative imports carry explicit `.js` extensions.
+- **`verbatimModuleSyntax`**: leave it **off**. The `bebopc`-generated `src/bebop.ts`
+  emits a value-style import of the `BebopRecord` type, which `verbatimModuleSyntax`
+  rejects. (The `@vampgg/cli`-generated files are themselves compatible; the constraint
+  is bebopc's output.)
+- **Formatter / linter**: the generated files are overwritten on every run, so add them
+  to your ignore globs, e.g. `src/bebop.ts` and `src/*.generated.ts`.
+
+## Configuration
+
+`vamp.json` (`FrameworkConfig`) points the generator at your schema files and output:
+
+```jsonc
+{
+  "schemas": {
+    "entity": "schema/entity.bop",
+    "actions": "schema/actions.bop",
+    "state": "schema/state.bop",
+    "tags": "schema/tags.bop",
+    // "mutation": "schema/mutation.bop"   // optional; auto-emitted otherwise
+  },
+  "outFile": "./src/game.generated.ts",
+  // optional: "coreOutFile", "workerOutFile", "bebopConfig", "env"
+}
+```
+
+`bebop.json` — the `bebopc` config `init` writes alongside it:
+
+```jsonc
+{
+  "include": ["schema/**/*.bop"],
+  "generators": { "ts": { "outFile": "./src/bebop.ts" } },
+}
+```
+
+See `examples/basic/vamp.json` for a complete config.
+
+## End-to-end workflow
+
+```bash
+vamp init                 # scaffold schema/ + configs
+# edit schema/*.bop to define your entity, actions, state, tags
+vamp generate             # emit src/bebop.ts + the generated TypeScript
+```
+
+Then import the generated symbols to wire the world — see
+[`@vampgg/worker`](../../packages/worker) for the Durable Object entry and
+[`examples/basic/`](../../examples/basic) for the full stack (schema → generated
+options → systems → worker → Solid client).
+
+## Programmatic API
+
+The generator is usable as a library (`@vampgg/cli`):
+
+```ts
+import { loadVampConfig, loadBebopConfig, generate, generateMutationSchema } from "@vampgg/cli";
+
+const vampConfig = loadVampConfig(cwd);
+const bebopConfig = loadBebopConfig(cwd, vampConfig.bebopConfig);
+generateMutationSchema(cwd, vampConfig); // emit mutation.bop
+const { core, worker, barrel } = generate(cwd, bebopConfig, vampConfig); // emit the TS files
+```
+
+Also exported: `parseSchema` / `loadSchemaFromFile` / `loadAndParseSchema`,
+`emitMutationSchema`, `resolveMutationPath`, and the `FrameworkConfig` /
+`BebopConfig` / `ParsedSchema` types.
+
+## Performance
+
+`vamp generate` emits the framework's fast path — the archetype-graph ECS, additive
+CRDT deltas, and interest-routed broadcast that the full-stack benchmark measures
+(server frames over 1,024 entities, ~100 µs single-`act` round-trips, 0%-loss
+fan-out to dozens of observers, ~18k entities per Durable Object). See
+[`@vampgg/worker`](../../packages/worker#performance) for the numbers and how to
+reproduce them (`cd examples/basic && pnpm bench`).
+
 ## Development
 
 ```bash

package/dist/{generate-mutation-schema-DPVvPX4h.mjs → generate-mutation-schema-g3hIkmuv.mjs}

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse, printParseErrorCode } from "jsonc-parser";
 import { BinarySchema } from "bebop";
 //#region src/config/loader.ts
@@ -350,16 +350,18 @@ export function createECSOptions(createId: () => string): ECSOptions<Entity, Ent
 }
 //#endregion
 //#region src/generators/emit-classes.ts
-function emitClasses(tagsType = "number") {
+function emitClasses(tagsType = "number", env = "Cloudflare.Env") {
 	return `/**
  * App-typed {@link ECSDurableObject}: this schema's \`Actions\`/\`Tags\`/\`Entity\`/
- * \`EntityDelta\` are baked in, leaving \`UserSession\`/\`Context\`/\`UpdateArguments\`
- * open. Subclass this as your game's durable object.
+ * \`EntityDelta\` are baked in, leaving \`UserSession\`/\`Context\`/\`UpdateArguments\`/\`Env\`
+ * open (\`Env\` defaults to \`${env}\`, configurable via the \`env\` field in vamp.json).
+ * Subclass this as your game's durable object.
  */
 export class GameECS<
     UserSession extends {} = {},
     Context extends {} = {},
     UpdateArguments extends Array<unknown> = [],
+    Env = ${env},
   > extends ECSDurableObject<
     UserSession,
     Context,
@@ -368,7 +370,7 @@ export class GameECS<
     ${tagsType},
     Entity,
     EntityDelta,
-    Cloudflare.Env
+    Env
   > {}
 
 /** App-typed {@link ECSStorage} over this schema's {@link Entity}. */
@@ -598,6 +600,30 @@ export function createGameBehavior<
 }
 //#endregion
 //#region src/generators/codegen.ts
+const AUTOGEN_HEADER = `// This file is auto-generated by @vampgg/cli. Do not edit manually.`;
+/**
+* Derive a `.core`/`.worker` sibling path from the barrel `outFile`
+* (`./src/game.generated.ts` → `./src/game.core.generated.ts`). Falls back to
+* inserting the part before a plain `.ts`, or appending it, for atypical names.
+*/
+function derivePartPath(outFile, part) {
+	if (outFile.endsWith(".generated.ts")) return `${outFile.slice(0, -13)}.${part}.generated.ts`;
+	if (outFile.endsWith(".ts")) return `${outFile.slice(0, -3)}.${part}.ts`;
+	return `${outFile}.${part}.ts`;
+}
+/**
+* Build the relative ESM specifier that imports `toFile` from `fromFile`, with a
+* `.js` extension (nodenext-compatible; maps back to the `.ts` source).
+*/
+function relativeImport(fromFile, toFile) {
+	let rel = relative(dirname(fromFile), toFile).split("\\").join("/");
+	rel = rel.replace(/\.ts$/, ".js");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function writeGenerated(path, sections) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, sections.join("\n"), "utf-8");
+}
 function generate(cwd, config, vampConfig) {
 	const schema = loadAndParseSchema(resolve(cwd, config.generators?.ts?.outFile ?? "./src/bebop.ts"));
 	const entityDef = schema.definitions.get("Entity");
@@ -606,17 +632,17 @@ function generate(cwd, config, vampConfig) {
 	if (!schema.definitions.get("State")) throw new Error("No 'State' definition found in schema");
 	if (!schema.definitions.get("Tags")) throw new Error("No 'Tags' definition found in schema");
 	const bebopImportTypes = collectBebopImportTypes(entityDef, schema);
-	const bebopImport = "./bebop";
+	const bebopImport = "./bebop.js";
 	const helperImports = emitHelperImports(entityDef, schema);
-	const output = [
-		`// This file is auto-generated by @vampgg/cli. Do not edit manually.`,
-		`import type { ECSOptions, MutationBatch, EntitySystem, ArchetypeSystem, Behavior, System, Query, QueryBuilder } from "@vampgg/ecs";`,
+	const barrelPath = resolve(cwd, vampConfig.outFile);
+	const corePath = resolve(cwd, vampConfig.coreOutFile ?? derivePartPath(vampConfig.outFile, "core"));
+	const workerPath = resolve(cwd, vampConfig.workerOutFile ?? derivePartPath(vampConfig.outFile, "worker"));
+	const coreSections = [
+		AUTOGEN_HEADER,
+		`import type { ECSOptions, EntitySystem, ArchetypeSystem, Behavior, System, Query, QueryBuilder } from "@vampgg/ecs";`,
 		`import { createEntitySystem, createArchetypeSystem, createBehavior } from "@vampgg/ecs";`,
 		...helperImports ? [helperImports] : [],
-		`import { defineECSRuntime, ECSDurableObject, ECSStorage, type ECSRuntimeConfiguration, type RPCContext } from "@vampgg/worker";`,
-		`import { createInterestBroadcast, type InterestBroadcastConfig } from "@vampgg/worker/interest";`,
 		`import type { Entity, Actions, Tags${bebopImportTypes} } from "${bebopImport}";`,
-		`import { MutationScope, type MutationRecord } from "${bebopImport}";`,
 		"",
 		emitComponents(entityDef),
 		"",
@@ -626,21 +652,47 @@ function generate(cwd, config, vampConfig) {
 		"",
 		emitFactory(),
 		"",
-		emitClasses("Tags"),
+		emitSystems(),
+		""
+	];
+	const coreFromWorker = relativeImport(workerPath, corePath);
+	const workerSections = [
+		AUTOGEN_HEADER,
+		`import type { MutationBatch } from "@vampgg/ecs";`,
+		`import { defineECSRuntime, ECSDurableObject, ECSStorage, type ECSRuntimeConfiguration, type RPCContext } from "@vampgg/worker";`,
+		`import { createInterestBroadcast, type InterestBroadcastConfig } from "@vampgg/worker/interest";`,
+		`import type { Entity, Actions, Tags } from "${bebopImport}";`,
+		`import { MutationScope, type MutationRecord } from "${bebopImport}";`,
+		`import type { EntityDelta } from "${coreFromWorker}";`,
+		"",
+		emitClasses("Tags", vampConfig.env),
 		"",
 		emitGameContext(),
 		"",
 		emitRuntime(),
 		"",
-		emitSystems(),
-		"",
 		emitInterest(),
 		""
-	].join("\n");
-	const outPath = resolve(cwd, vampConfig.outFile);
-	mkdirSync(dirname(outPath), { recursive: true });
-	writeFileSync(outPath, output, "utf-8");
-	return outPath;
+	];
+	const coreFromBarrel = relativeImport(barrelPath, corePath);
+	const workerFromBarrel = relativeImport(barrelPath, workerPath);
+	const barrelSections = [
+		AUTOGEN_HEADER,
+		`// Barrel over the generated ECS surface. Import the pure core file directly`,
+		`// (\`${coreFromBarrel}\`) from non-Worker code to avoid pulling in @vampgg/worker`,
+		`// and its \`cloudflare:workers\` import.`,
+		`export * from "${coreFromBarrel}";`,
+		`export * from "${workerFromBarrel}";`,
+		""
+	];
+	writeGenerated(corePath, coreSections);
+	writeGenerated(workerPath, workerSections);
+	writeGenerated(barrelPath, barrelSections);
+	return {
+		barrel: barrelPath,
+		core: corePath,
+		worker: workerPath
+	};
 }
 /** Candidate custom type names a field references (base, array member, or map value). */
 function candidateTypeNames(field) {
@@ -953,6 +1005,22 @@ function emitMutationSchema(entity, entityImportPath, userDeltas = /* @__PURE__
 //#endregion
 //#region src/generators/resolve-imports.ts
 /**
+* Resolve a package specifier to its *symlinked* `node_modules` path rather than
+* the realpath. `require.resolve` runs `fs.realpathSync` on its result, which under
+* pnpm points into the version-pinned `.pnpm/<pkg>@<version>/…` store — a path that
+* breaks the moment the version bumps. Walking the module search dirs and joining
+* the specifier keeps the stable `node_modules/<pkg>/<subpath>` symlink instead.
+*/
+function resolveStablePath(req, specifier) {
+	const searchDirs = req.resolve.paths(specifier);
+	if (!searchDirs) return null;
+	for (const dir of searchDirs) {
+		const candidate = join(dir, specifier);
+		if (existsSync(candidate)) return candidate;
+	}
+	return null;
+}
+/**
 * Extract the import paths from a bebop source file. Bebop imports look like
 * `import "../relative/path.bop"` or `import "@scope/pkg/schema/foo.bop"`.
 */
@@ -979,6 +1047,8 @@ function resolveBebopImport(specifier, fromDir) {
 		return existsSync(abs) ? abs : null;
 	}
 	const req = createRequire(resolve(fromDir, "noop.js"));
+	const stable = resolveStablePath(req, specifier);
+	if (stable) return stable;
 	try {
 		const direct = req.resolve(specifier);
 		if (existsSync(direct)) return direct;

package/dist/index.d.mts

@@ -14,6 +14,25 @@ interface FrameworkConfig {
     mutation?: string;
   };
   outFile: string;
+  /**
+   * Override path for the generated **pure** ECS file (components, deltas, helpers,
+   * factory, systems — depends only on `@vampgg/ecs`). Defaults to a sibling of
+   * `outFile` with `.core.generated.ts` in place of `.generated.ts`.
+   */
+  coreOutFile?: string;
+  /**
+   * Override path for the generated **worker** file (the `GameECS` durable object,
+   * runtime, and interest broadcast — depends on `@vampgg/worker`). Defaults to a
+   * sibling of `outFile` with `.worker.generated.ts` in place of `.generated.ts`.
+   */
+  workerOutFile?: string;
+  /**
+   * TypeScript type used as the default `Env` generic of the generated `GameECS`
+   * durable object. Defaults to `"Cloudflare.Env"` (the wrangler-generated bindings
+   * type). Set to `"unknown"`, `"{}"`, or a locally-declared type for non-Worker
+   * packages that lack wrangler types.
+   */
+  env?: string;
 }
 interface BebopConfig {
   include?: string[];
@@ -67,7 +86,16 @@ declare function loadSchemaFromFile(bebopTsPath: string): Uint8Array;
 declare function loadAndParseSchema(bebopTsPath: string): ParsedSchema;
 //#endregion
 //#region src/generators/codegen.d.ts
-declare function generate(cwd: string, config: BebopConfig, vampConfig: FrameworkConfig): string;
+/** Absolute paths of the three files `generate` writes. */
+interface GeneratedPaths {
+  /** Backward-compatible barrel re-exporting `core` + `worker`. */
+  barrel: string;
+  /** Pure ECS file (`@vampgg/ecs` only) — safe to import from non-Worker code. */
+  core: string;
+  /** Worker runtime file (`@vampgg/worker`, imports `cloudflare:workers`). */
+  worker: string;
+}
+declare function generate(cwd: string, config: BebopConfig, vampConfig: FrameworkConfig): GeneratedPaths;
 //#endregion
 //#region src/generators/parse-bop-source.d.ts
 /** Recursive classification of a type token (base/array/map). */

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as extractMessageBody, c as generate, d as parseSchema, f as loadBebopConfig, i as emitMutationSchema, l as loadAndParseSchema, n as resolveMutationPath, o as parseEntityMessage, p as loadVampConfig, s as parseMessage, t as generateMutationSchema, u as loadSchemaFromFile } from "./generate-mutation-schema-DPVvPX4h.mjs";
+import { a as extractMessageBody, c as generate, d as parseSchema, f as loadBebopConfig, i as emitMutationSchema, l as loadAndParseSchema, n as resolveMutationPath, o as parseEntityMessage, p as loadVampConfig, s as parseMessage, t as generateMutationSchema, u as loadSchemaFromFile } from "./generate-mutation-schema-g3hIkmuv.mjs";
 export { emitMutationSchema, extractMessageBody, generate, generateMutationSchema, loadAndParseSchema, loadBebopConfig, loadSchemaFromFile, loadVampConfig, parseEntityMessage, parseMessage, parseSchema, resolveMutationPath };

package/dist/vamp.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as generate, f as loadBebopConfig, p as loadVampConfig, r as resolveBebopImport, t as generateMutationSchema } from "./generate-mutation-schema-DPVvPX4h.mjs";
+import { c as generate, f as loadBebopConfig, p as loadVampConfig, r as resolveBebopImport, t as generateMutationSchema } from "./generate-mutation-schema-g3hIkmuv.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { defineCommand, runMain } from "citty";
@@ -94,8 +94,10 @@ const generateCommand = defineCommand({
 				}
 			}
 			console.log("Generating ECS types...");
-			const outPath = generate(cwd, bebopConfig, vampConfig);
-			console.log(`Generated ${outPath}`);
+			const { core, worker, barrel } = generate(cwd, bebopConfig, vampConfig);
+			console.log(`Generated ${core}`);
+			console.log(`Generated ${worker}`);
+			console.log(`Generated ${barrel}`);
 			return true;
 		};
 		if (!args.watch) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vampgg/cli",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.3",
   "description": "ECS code generator CLI for @vampgg",
   "homepage": "https://github.com/sammccord/vamp/tree/main/tools/cli#readme",
   "bugs": {
@@ -40,9 +40,9 @@
     "typescript": "^5",
     "vite-plus": "^0.1.24",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
-    "@vampgg/ecs": "1.0.0-beta.1",
-    "@vampgg/utils": "1.0.0-beta.1",
-    "@vampgg/worker": "1.0.0-beta.1"
+    "@vampgg/utils": "1.0.0-beta.2",
+    "@vampgg/ecs": "1.0.0-beta.2",
+    "@vampgg/worker": "1.0.0-beta.2"
   },
   "scripts": {
     "build": "vp pack",