@vampgg/cli 1.0.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,153 @@
+//#region src/config/types.d.ts
+interface FrameworkConfig {
+  /** Path to the bebop.json config file (default: "./bebop.json") */
+  bebopConfig?: string;
+  schemas: {
+    entity: string;
+    actions: string;
+    state: string;
+    tags: string;
+    /**
+     * Path for the generated bebop mutation schema (EntityDelta, MutationScope).
+     * Defaults to a `mutation.bop` sibling of the entity schema.
+     */
+    mutation?: string;
+  };
+  outFile: string;
+}
+interface BebopConfig {
+  include?: string[];
+  exclude?: string[];
+  generators?: {
+    ts?: {
+      outFile?: string;
+    };
+  };
+  watchOptions?: {
+    excludeDirectories?: string[];
+  };
+}
+//#endregion
+//#region src/config/loader.d.ts
+declare function loadBebopConfig(cwd: string, configPath?: string): BebopConfig;
+declare function loadVampConfig(cwd: string): FrameworkConfig;
+//#endregion
+//#region src/generators/parse-bop.d.ts
+interface SchemaField {
+  name: string;
+  typeId: number;
+  isArray: boolean;
+  isMap: boolean;
+  /** For scalars, the scalar type name. For definitions, the definition name. */
+  typeName: string;
+  /** For arrays, the member type name */
+  memberTypeName?: string;
+  /** For maps, the key type name */
+  keyTypeName?: string;
+  /** For maps, the value type name */
+  valueTypeName?: string;
+  /** Bebop field tag (for messages) */
+  constantValue?: number | null;
+}
+interface SchemaDefinition {
+  name: string;
+  kind: "struct" | "message" | "union" | "enum";
+  fields: SchemaField[];
+  /** For unions: branch info */
+  branches?: {
+    discriminator: number;
+    typeName: string;
+  }[];
+}
+interface ParsedSchema {
+  definitions: Map<string, SchemaDefinition>;
+}
+declare function parseSchema(bebopSchemaBytes: Uint8Array): ParsedSchema;
+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;
+//#endregion
+//#region src/generators/parse-bop-source.d.ts
+/** Recursive classification of a type token (base/array/map). */
+interface TypeClassification {
+  /** Resolved element/base type name (e.g. "guid", "Pool"). For maps this is "map". */
+  typeName: string;
+  isArray: boolean;
+  isMap: boolean;
+  /** For arrays, the member type name */
+  memberType?: string;
+  /** For maps, the key type name */
+  keyType?: string;
+  /** For maps, the value type name (raw substring) */
+  valueType?: string;
+  /** For maps, the recursive classification of the value type */
+  valueClassified?: TypeClassification;
+  /** For arrays, the recursive classification of the member type */
+  memberClassified?: TypeClassification;
+  /** True when the resolved base/member type is a bebop scalar */
+  isScalar: boolean;
+}
+interface SourceField extends TypeClassification {
+  /** Bebop field tag/index */
+  index: number;
+  name: string;
+  /** Raw type token as written (e.g. "guid", "Pool", "Tags", "guid[]", "map[guid, Foo]") */
+  rawType: string;
+}
+interface SourceMessage {
+  name: string;
+  fields: SourceField[];
+}
+/**
+ * Extract the body of `message <name> { ... }` from bebop source text.
+ * Returns null if the message is not found.
+ */
+declare function extractMessageBody(source: string, messageName: string): string | null;
+/**
+ * Parse `message <name>` field declarations from bebop source text.
+ *
+ * This is intentionally a lightweight, syntax-focused parser (no import
+ * resolution). It only understands the constrained field syntax used in
+ * generated/authored entity schemas: `<index> -> <type> <name>;`.
+ *
+ * Nested/inline message blocks inside the message body are stripped before
+ * field extraction; their fields are NOT emitted as fields of this message. A
+ * warning is logged so the user knows an inline component was ignored.
+ */
+declare function parseMessage(source: string, messageName: string): SourceMessage | null;
+/** Convenience wrapper for the `Entity` message. */
+declare function parseEntityMessage(source: string): SourceMessage;
+//#endregion
+//#region src/generators/emit-mutation-bop.d.ts
+/**
+ * Emit the bebop schema providing serializable EntityDelta + MutationScope
+ * types, derived from the Entity message.
+ *
+ * @param entity Parsed Entity message.
+ * @param entityImportPath Import path to the entity schema, relative to the
+ *   emitted file (e.g. "./entity.bop").
+ * @param userDeltas Set of `<Type>Delta` message names already reachable from
+ *   the user's schema (so they are reused verbatim, not re-synthesized).
+ * @param components Map of component name -> parsed component message, used to
+ *   synthesize a `<Type>Delta` when one is not user-supplied.
+ * @param entitySchemaPath Absolute path to the entity schema (for error text).
+ */
+declare function emitMutationSchema(entity: SourceMessage, entityImportPath: string, userDeltas?: ReadonlySet<string>, components?: ReadonlyMap<string, SourceMessage>, entitySchemaPath?: string): string;
+//#endregion
+//#region src/generators/generate-mutation-schema.d.ts
+/** Default mutation schema path: a `mutation.bop` sibling of the entity schema. */
+declare function resolveMutationPath(cwd: string, vampConfig: FrameworkConfig): string;
+/**
+ * Parse the user's entity schema and (re)generate the bebop mutation schema
+ * (EntityDelta, MutationType, MutationRecord, MutationScope) next to it.
+ *
+ * IMPORTANT: this must run BEFORE `bebopc build` so the generated schema is
+ * picked up and compiled into serializable types.
+ *
+ * @returns the absolute path of the written mutation schema.
+ */
+declare function generateMutationSchema(cwd: string, vampConfig: FrameworkConfig): string;
+//#endregion
+export { type BebopConfig, type FrameworkConfig, type ParsedSchema, type SchemaDefinition, type SchemaField, type SourceField, type SourceMessage, emitMutationSchema, extractMessageBody, generate, generateMutationSchema, loadAndParseSchema, loadBebopConfig, loadSchemaFromFile, loadVampConfig, parseEntityMessage, parseMessage, parseSchema, resolveMutationPath };

package/dist/index.mjs

@@ -0,0 +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";
+export { emitMutationSchema, extractMessageBody, generate, generateMutationSchema, loadAndParseSchema, loadBebopConfig, loadSchemaFromFile, loadVampConfig, parseEntityMessage, parseMessage, parseSchema, resolveMutationPath };

package/dist/vamp.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/vamp.mjs

@@ -0,0 +1,279 @@
+#!/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 { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { defineCommand, runMain } from "citty";
+import { execSync } from "node:child_process";
+//#region src/commands/generate.ts
+/**
+* Build a watch-mode scheduler that runs `run` on each change, never dropping a
+* change saved while a run is in flight: a mid-run change sets a pending flag
+* that triggers exactly one follow-up after the current run completes.
+*
+* Extracted (and exported) so the pending-rerun semantics can be unit-tested
+* without invoking the real generator (plan 21 §4d / Case E).
+*/
+function createWatchScheduler(run, debounce, onComplete) {
+	let isRunning = false;
+	let pending = false;
+	const runOnce = () => {
+		isRunning = true;
+		const ok = run();
+		isRunning = false;
+		onComplete?.(ok);
+		if (pending) {
+			pending = false;
+			debounce(runOnce);
+		}
+	};
+	const onChange = () => {
+		if (isRunning) {
+			pending = true;
+			return;
+		}
+		debounce(runOnce);
+	};
+	return { onChange };
+}
+const generateCommand = defineCommand({
+	meta: {
+		name: "generate",
+		description: "Run bebopc build, then emit game.generated.ts with component map, delta types, helpers, and factory"
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Working directory",
+			default: process.cwd()
+		},
+		"skip-bebopc": {
+			type: "boolean",
+			description: "Skip running bebopc build",
+			default: false
+		},
+		watch: {
+			type: "boolean",
+			description: "Watch schema files for changes and regenerate on change",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const cwd = args.cwd;
+		const vampConfig = loadVampConfig(cwd);
+		const bebopConfig = loadBebopConfig(cwd, vampConfig.bebopConfig);
+		const runGenerate = () => {
+			console.log("Generating mutation schema...");
+			const mutationPath = generateMutationSchema(cwd, vampConfig);
+			console.log(`Generated ${mutationPath}`);
+			const bebopTsPath = resolve(cwd, bebopConfig.generators?.ts?.outFile ?? "./src/bebop.ts");
+			if (!args["skip-bebopc"]) {
+				try {
+					execSync("npx --no-install bebopc --version", {
+						cwd,
+						stdio: "pipe"
+					});
+				} catch {
+					console.error("bebopc not found. Install it (e.g. `pnpm add -D bebop-tools`) before running `vamp generate`.");
+					return false;
+				}
+				console.log("Running bebopc build...");
+				try {
+					execSync("npx --no-install bebopc build", {
+						cwd,
+						stdio: "inherit"
+					});
+				} catch (err) {
+					console.error("bebopc build failed:");
+					const e = err;
+					if (e.stderr?.length) console.error(e.stderr.toString());
+					return false;
+				}
+				if (!existsSync(bebopTsPath)) {
+					console.error(`bebopc build did not produce ${bebopTsPath}`);
+					return false;
+				}
+			}
+			console.log("Generating ECS types...");
+			const outPath = generate(cwd, bebopConfig, vampConfig);
+			console.log(`Generated ${outPath}`);
+			return true;
+		};
+		if (!args.watch) {
+			if (!runGenerate()) process.exit(1);
+			return;
+		}
+		const chokidar = await import("chokidar");
+		const schemaPaths = [
+			resolve(cwd, vampConfig.schemas.entity),
+			resolve(cwd, vampConfig.schemas.actions),
+			resolve(cwd, vampConfig.schemas.state),
+			resolve(cwd, vampConfig.schemas.tags)
+		];
+		let debounceTimer = null;
+		const debounce = (fn) => {
+			if (debounceTimer) clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(fn, 100);
+		};
+		const scheduler = createWatchScheduler(runGenerate, debounce, (ok) => {
+			if (ok) console.log("Watching for changes...");
+		});
+		const watcher = chokidar.watch(schemaPaths, { persistent: true });
+		watcher.on("change", (path) => {
+			console.log(`\nSchema changed: ${path}`);
+			scheduler.onChange();
+		});
+		console.log("Watching for changes...");
+		if (!runGenerate()) {
+			await watcher.close();
+			process.exit(1);
+		}
+	}
+});
+//#endregion
+//#region src/templates/entity.bop.ts
+/**
+* Entity schema template. `__POOL_IMPORT__` is replaced at scaffold time with a
+* path to `@vampgg/utils/schema/pool.bop` resolved via Node module resolution, so
+* it is correct for the actual (hoisted or pnpm) `node_modules` layout.
+*/
+const entityTemplate = `import "__POOL_IMPORT__"
+import "./tags.bop"
+
+message Entity {
+\t1 -> string id;
+\t2 -> string sk;
+\t3 -> Tags[] tags;
+\t4 -> string parent;
+\t5 -> string[] children;
+\t6 -> Pool health;
+}
+`;
+/** Fallback import path used when `@vampgg/utils` cannot be resolved at init time. */
+const POOL_IMPORT_PLACEHOLDER = "__POOL_IMPORT__";
+const POOL_IMPORT_FALLBACK = "../node_modules/@vampgg/utils/schema/pool.bop";
+//#endregion
+//#region src/templates/actions.bop.ts
+const actionsTemplate = `union Actions {
+\t1 -> message Attack {
+\t\t1 -> guid source;
+\t\t2 -> guid target;
+\t\t3 -> uint32 damage;
+\t}
+}
+`;
+//#endregion
+//#region src/templates/state.bop.ts
+const stateTemplate = `message State {
+\t1 -> string ns;
+}
+`;
+//#endregion
+//#region src/templates/tags.bop.ts
+const tagsTemplate = `enum Tags {
+  Default = 1;
+}
+`;
+//#endregion
+//#region src/commands/init.ts
+/**
+* Resolve a bebop import path (relative to `schemaDir`) for
+* `@vampgg/utils/schema/pool.bop` using Node module resolution, so the scaffolded
+* import is correct under hoisted or pnpm `node_modules` layouts. Falls back to
+* a literal path (with a warning) when resolution fails.
+*
+* `resolve` is injectable so the fallback branch can be tested deterministically
+* (Node resolution from a temp dir is environment-dependent — it may still find
+* a `@vampgg/utils` in an ancestor `node_modules`).
+*/
+function resolvePoolImport(cwd, schemaDir, resolveImport = resolveBebopImport) {
+	const resolved = resolveImport("@vampgg/utils/schema/pool.bop", cwd);
+	if (!resolved) {
+		console.warn("Warning: could not resolve '@vampgg/utils/schema/pool.bop'. Scaffolding a literal import path that may not resolve under your node_modules layout — fix the import in schema/entity.bop if `bebopc build` fails.");
+		return POOL_IMPORT_FALLBACK;
+	}
+	const rel = relative(schemaDir, resolved).split("\\").join("/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+//#endregion
+//#region src/vamp.ts
+runMain(defineCommand({
+	meta: {
+		name: "vamp",
+		description: "ECS code generator for @vampgg"
+	},
+	subCommands: {
+		generate: generateCommand,
+		init: defineCommand({
+			meta: {
+				name: "init",
+				description: "Scaffold schema/ dir, template .bop files, and create bebop.json + vamp.json"
+			},
+			args: { cwd: {
+				type: "string",
+				description: "Working directory",
+				default: process.cwd()
+			} },
+			run({ args }) {
+				const cwd = args.cwd;
+				const schemaDir = resolve(cwd, "schema");
+				mkdirSync(schemaDir, { recursive: true });
+				console.log("Created schema/");
+				const poolImport = resolvePoolImport(cwd, schemaDir);
+				const files = [
+					{
+						path: "schema/entity.bop",
+						content: entityTemplate.replace(POOL_IMPORT_PLACEHOLDER, poolImport)
+					},
+					{
+						path: "schema/actions.bop",
+						content: actionsTemplate
+					},
+					{
+						path: "schema/state.bop",
+						content: stateTemplate
+					},
+					{
+						path: "schema/tags.bop",
+						content: tagsTemplate
+					}
+				];
+				for (const file of files) {
+					const fullPath = resolve(cwd, file.path);
+					if (existsSync(fullPath)) console.log(`Skipping ${file.path} (already exists)`);
+					else {
+						writeFileSync(fullPath, file.content, "utf-8");
+						console.log(`Created ${file.path}`);
+					}
+				}
+				const bebopConfigPath = resolve(cwd, "bebop.json");
+				if (existsSync(bebopConfigPath)) console.log("Skipping bebop.json (already exists)");
+				else {
+					writeFileSync(bebopConfigPath, JSON.stringify({
+						include: ["schema/**/*.bop"],
+						generators: { ts: { outFile: "./src/bebop.ts" } }
+					}, null, 2) + "\n", "utf-8");
+					console.log("Created bebop.json");
+				}
+				const vampConfigPath = resolve(cwd, "vamp.json");
+				if (existsSync(vampConfigPath)) console.log("Skipping vamp.json (already exists)");
+				else {
+					writeFileSync(vampConfigPath, JSON.stringify({
+						schemas: {
+							entity: "schema/entity.bop",
+							actions: "schema/actions.bop",
+							state: "schema/state.bop",
+							tags: "schema/tags.bop"
+						},
+						outFile: "./src/game.generated.ts"
+					}, null, 2) + "\n", "utf-8");
+					console.log("Created vamp.json");
+				}
+			}
+		})
+	}
+})).catch((err) => {
+	console.error(err);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@vampgg/cli",
+  "version": "1.0.0-beta.1",
+  "description": "ECS code generator CLI for @vampgg",
+  "homepage": "https://github.com/sammccord/vamp/tree/main/tools/cli#readme",
+  "bugs": {
+    "url": "https://github.com/sammccord/vamp/issues"
+  },
+  "license": "MIT",
+  "author": "Sam McCord <sam.mccord@protonmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sammccord/vamp.git",
+    "directory": "tools/cli"
+  },
+  "bin": {
+    "vamp": "./dist/vamp.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./vamp": "./dist/vamp.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "bebop": "3.2.3",
+    "chokidar": "^3.6.0",
+    "citty": "^0.1.6",
+    "jsonc-parser": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "bebop-tools": "^3.2.3",
+    "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"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit",
+    "codegen:typecheck-fixtures": "vp test --run roundtrip"
+  }
+}