@vttforge/cli 0.0.0 → 0.5.1

package/dist/src-CWhUNM__.mjs

@@ -0,0 +1,2443 @@
+import { createWriteStream, existsSync, readFileSync, readdirSync, statSync, watch } from "node:fs";
+import { basename, dirname, extname, join, posix, relative, resolve, sep } from "node:path";
+import { lstat, mkdir, readFile, readdir, readlink, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import * as p from "@clack/prompts";
+import { execFile, spawn } from "node:child_process";
+import { ZipArchive } from "archiver";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { promisify } from "node:util";
+//#region src/audit/manifest-rules.ts
+/**
+* Manifest-scope audit rules.
+*
+* These rules operate on the parsed contents of `system.json` and/or
+* `module.json` at the project root. They cover three v13 manifest
+* footguns from the VTTForge audit catalog:
+*
+*   VTTF-AUDIT-001 (HIGH)   — flags.hotReload shape
+*   VTTF-AUDIT-002 (MEDIUM) — deprecated gridDistance/gridUnits
+*   VTTF-AUDIT-003 (LOW)    — styles array of strings (v12 shape)
+*
+* Each rule emits zero or more `RuleResult`s. Line numbers are looked up
+* cheaply by scanning the raw JSON for the offending key — accurate
+* enough for navigation, no AST dependency.
+*/
+const MANIFEST_FILES$1 = ["system.json", "module.json"];
+/**
+* Load the manifest(s) at the project root. Returns at most two entries
+* (system + module), skipping anything that can't be parsed as a JSON
+* object. We tolerate parse errors here because that's a separate failure
+* mode the user will hit when they actually run `vite build`; the audit
+* shouldn't double-report it.
+*/
+async function loadManifests(cwd) {
+	const out = [];
+	for (const file of MANIFEST_FILES$1) {
+		const path = join(cwd, file);
+		if (!existsSync(path)) continue;
+		let raw;
+		try {
+			raw = await readFile(path, "utf8");
+		} catch {
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			continue;
+		}
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) out.push({
+			path,
+			raw,
+			parsed
+		});
+	}
+	return out;
+}
+/**
+* Find the 1-based line number of the first `"key":` occurrence in JSON
+* source. Good enough for navigation — JSON keys are usually unique at
+* the level we report on, and even when nested duplicates exist the
+* first occurrence points at the right region of the file.
+*/
+function findKeyLine(raw, key) {
+	const needle = `"${key}"`;
+	const idx = raw.indexOf(needle);
+	if (idx < 0) return void 0;
+	let line = 1;
+	for (let i = 0; i < idx; i += 1) if (raw[i] === "\n") line += 1;
+	return line;
+}
+/**
+* VTTF-AUDIT-001 (HIGH) — flags.hotReload shape.
+*
+* v12 accepted `"hotReload": ["css", "hbs", ...]` (array). v13 expects
+* `"hotReload": { "extensions": [...], "paths": [...] }` (object at the
+* root of `flags`, NOT nested under a package id). With the array shape
+* the server's chokidar watcher reads `.extensions` and gets undefined,
+* silently disabling HMR for the package.
+*/
+function ruleHotReload(manifest) {
+	const flags = manifest.parsed.flags;
+	if (!flags || typeof flags !== "object" || Array.isArray(flags)) return [];
+	const hr = flags.hotReload;
+	if (hr === void 0) return [];
+	const line = findKeyLine(manifest.raw, "hotReload");
+	if (Array.isArray(hr)) return [{
+		ruleId: "VTTF-AUDIT-001",
+		title: "flags.hotReload uses the deprecated v12 array shape",
+		severity: "HIGH",
+		filePath: manifest.path,
+		line,
+		message: "flags.hotReload is an array; v13 expects an object `{ \"extensions\": [...], \"paths\": [...] }`. With the array shape Foundry silently disables HMR for this package.",
+		remediation: "Replace the array with an object: `\"hotReload\": { \"extensions\": [\"css\", \"hbs\", \"json\"], \"paths\": [\"styles\", \"templates\", \"lang\"] }`."
+	}];
+	if (hr === null || typeof hr !== "object") return [{
+		ruleId: "VTTF-AUDIT-001",
+		title: "flags.hotReload has an invalid shape",
+		severity: "HIGH",
+		filePath: manifest.path,
+		line,
+		message: "flags.hotReload must be an object with `extensions` and `paths` arrays in v13.",
+		remediation: "Replace with `\"hotReload\": { \"extensions\": [...], \"paths\": [...] }`."
+	}];
+	const hrObj = hr;
+	if (!Array.isArray(hrObj.extensions)) return [{
+		ruleId: "VTTF-AUDIT-001",
+		title: "flags.hotReload is missing the required `extensions` key",
+		severity: "HIGH",
+		filePath: manifest.path,
+		line,
+		message: "flags.hotReload must declare an `extensions` array — Foundry has no default and the watcher silently does nothing without it.",
+		remediation: "Add `extensions`: `\"hotReload\": { \"extensions\": [\"css\", \"hbs\", \"json\"], \"paths\": [\"styles\", \"templates\", \"lang\"] }`. `paths` is optional (defaults to the package root) but recommended."
+	}];
+	return [];
+}
+/**
+* VTTF-AUDIT-002 (MEDIUM) — deprecated top-level grid fields.
+*
+* v12 used flat `gridDistance` + `gridUnits`. v13 wants
+* `grid: { type, distance, units, diagonals }`. The legacy keys still
+* work today (Foundry auto-migrates and warns) but will be removed in
+* v14 — flag them now so the project is forward-compatible.
+*/
+function ruleGridShape(manifest) {
+	const hasLegacyDistance = "gridDistance" in manifest.parsed;
+	const hasLegacyUnits = "gridUnits" in manifest.parsed;
+	if (!hasLegacyDistance && !hasLegacyUnits) return [];
+	const offendingKey = hasLegacyDistance ? "gridDistance" : "gridUnits";
+	return [{
+		ruleId: "VTTF-AUDIT-002",
+		title: "Top-level gridDistance / gridUnits are deprecated v12 fields",
+		severity: "MEDIUM",
+		filePath: manifest.path,
+		line: findKeyLine(manifest.raw, offendingKey),
+		message: "gridDistance and gridUnits at the manifest root are the v12 shape. Foundry v13 expects a structured `grid` object and emits a deprecation warning on load; the fields will be removed in v14.",
+		remediation: "Replace with `\"grid\": { \"type\": 1, \"distance\": 5, \"units\": \"ft\", \"diagonals\": 0 }` (adjust values to your system)."
+	}];
+}
+/**
+* VTTF-AUDIT-003 (LOW) — styles array of strings.
+*
+* v12 took `styles: ["styles/foo.css"]`. v13 expects `styles: [{ src,
+* layer? }]` so cascade-layer ordering can be declared in the manifest.
+* The string form still works (Foundry auto-migrates) but emits a
+* deprecation warning and loses the ability to control layer placement.
+*/
+function ruleStylesShape(manifest) {
+	const styles = manifest.parsed.styles;
+	if (!Array.isArray(styles) || styles.length === 0) return [];
+	if (!styles.some((entry) => typeof entry === "string")) return [];
+	return [{
+		ruleId: "VTTF-AUDIT-003",
+		title: "styles uses the deprecated v12 string-array shape",
+		severity: "LOW",
+		filePath: manifest.path,
+		line: findKeyLine(manifest.raw, "styles"),
+		message: "styles entries should be objects of the form `{ \"src\": \"path/to.css\", \"layer\": \"optional-layer\" }` in v13. String entries auto-migrate today but the conversion drops your control over cascade-layer placement.",
+		remediation: "Replace each string with `{ \"src\": \"<that-path>\" }`. Add a `\"layer\"` field per entry where you want explicit cascade ordering."
+	}];
+}
+/**
+* Entry point: run every manifest rule against every manifest at the
+* project root.
+*/
+async function runManifestRules(cwd) {
+	const manifests = await loadManifests(cwd);
+	const results = [];
+	for (const manifest of manifests) {
+		results.push(...ruleHotReload(manifest));
+		results.push(...ruleGridShape(manifest));
+		results.push(...ruleStylesShape(manifest));
+	}
+	return results;
+}
+//#endregion
+//#region src/audit/source-rules.ts
+/**
+* Source-tree audit rules.
+*
+* These walk `.ts` / `.tsx` / `.mjs` / `.cjs` / `.js` files under the
+* project root (excluding common build/dependency dirs) and apply regex
+* heuristics to spot four v13 footguns from the VTTForge audit catalog:
+*
+*   VTTF-AUDIT-004 (MEDIUM) — HTMLField/FilePathField missing manifest declaration
+*   VTTF-AUDIT-005 (MEDIUM) — extends TypeDataModel without prepareBaseData stub
+*   VTTF-AUDIT-006 (LOW)    — `_addDataFieldMigrations` override (wrong signature)
+*   VTTF-AUDIT-007 (MEDIUM) — manifest primary/secondaryTokenAttribute not matched
+*                             by a `value`/`max` SchemaField in source
+*
+* Regex-based on purpose: avoids pulling in a TypeScript AST dependency
+* for what amount to four pattern checks. The trade-off is occasional
+* false negatives on heavily-formatted code; the alternative would be a
+* 30MB+ runtime dep for marginal gains.
+*/
+/** Directories we never descend into — they're not user source. */
+const EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	".git",
+	".turbo",
+	".vttforge",
+	".next",
+	"coverage",
+	".vitest-cache"
+]);
+const SOURCE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".mjs",
+	".cjs",
+	".js"
+];
+function isSourceFile(name) {
+	if (name.endsWith(".d.ts") || name.endsWith(".d.mts") || name.endsWith(".d.cts")) return false;
+	return SOURCE_EXTENSIONS.some((ext) => name.endsWith(ext));
+}
+async function* walkSourceFiles(cwd) {
+	const entries = await readdir(cwd, { withFileTypes: true });
+	for (const entry of entries) {
+		if (entry.name.startsWith(".") && EXCLUDED_DIRS.has(entry.name)) continue;
+		if (entry.isDirectory()) {
+			if (EXCLUDED_DIRS.has(entry.name)) continue;
+			yield* walkSourceFiles(join(cwd, entry.name));
+		} else if (entry.isFile() && isSourceFile(entry.name)) yield join(cwd, entry.name);
+	}
+}
+/** Find the 1-based line number of the first occurrence of `needle`. */
+function lineOf(content, needle) {
+	const idx = typeof needle === "string" ? content.indexOf(needle) : content.search(needle);
+	if (idx < 0) return void 0;
+	let line = 1;
+	for (let i = 0; i < idx; i += 1) if (content[i] === "\n") line += 1;
+	return line;
+}
+/** VTTF-AUDIT-005 — `extends TypeDataModel` without a `prepareBaseData(...)` method. */
+function rule005(filePath, content) {
+	const out = [];
+	const directClasses = findDirectTypeDataModelClasses(content);
+	for (const cls of directClasses) {
+		const body = content.slice(cls.openIdx + 1, cls.endIdx);
+		if (/prepareBaseData\s*\(/.test(body)) continue;
+		out.push({
+			ruleId: "VTTF-AUDIT-005",
+			title: "TypeDataModel subclass missing prepareBaseData stub",
+			severity: "MEDIUM",
+			filePath,
+			line: cls.startLine,
+			message: `Class \`${cls.className}\` extends TypeDataModel directly but does not define prepareBaseData(). Active Effects apply between prepareBaseData and prepareDerivedData; without the hook, AE consumers see uninitialised fields.`,
+			remediation: "Add a no-op `prepareBaseData()` method (or extend `BaseTypeDataModel()` from `@vttforge/core`, which provides the stub)."
+		});
+	}
+	return out;
+}
+/**
+* Subset of `findClassRanges` that only returns classes whose `extends`
+* names `TypeDataModel` (and not via the `BaseTypeDataModel()` factory).
+* The word boundary in `\bTypeDataModel\b` keeps the factory pattern
+* out, same as the lower-level helper.
+*/
+function findDirectTypeDataModelClasses(content) {
+	const re = /class\s+(\w+)\s+extends\s+(?:[\w.]+\.)?\bTypeDataModel\b[^{]*\{/g;
+	const out = [];
+	for (const match of content.matchAll(re)) {
+		if (match.index === void 0) continue;
+		const openIdx = match.index + match[0].length - 1;
+		let depth = 0;
+		let endIdx = -1;
+		for (let i = openIdx; i < content.length; i += 1) if (content[i] === "{") depth += 1;
+		else if (content[i] === "}") {
+			depth -= 1;
+			if (depth === 0) {
+				endIdx = i;
+				break;
+			}
+		}
+		if (endIdx < 0) continue;
+		let line = 1;
+		for (let i = 0; i < match.index; i += 1) if (content[i] === "\n") line += 1;
+		out.push({
+			className: match[1] ?? "(anonymous)",
+			startLine: line,
+			openIdx,
+			endIdx
+		});
+	}
+	return out;
+}
+/** VTTF-AUDIT-006 — `_addDataFieldMigrations(` override on a TypeDataModel subclass. */
+function rule006(filePath, content) {
+	if (!/_addDataFieldMigrations\s*\(/.test(content)) return [];
+	if (!/extends\s+(?:[\w.]+\.)?(?:Base)?TypeDataModel\b/.test(content)) return [];
+	return [{
+		ruleId: "VTTF-AUDIT-006",
+		title: "Method name confused with Foundry migration API",
+		severity: "LOW",
+		filePath,
+		line: lineOf(content, /_addDataFieldMigrations\s*\(/),
+		message: "The plural `_addDataFieldMigrations` is not a real Foundry API. The canonical v13 migration hook is a static `migrateData(source)` override that calls singular `super._addDataFieldMigration(source, oldKey, newKey, apply?)` for each rename. Instance overrides named `_addDataFieldMigrations` never run.",
+		remediation: "Replace the override with `static migrateData(source) { super._addDataFieldMigration(source, \"oldKey\", \"newKey\"); return super.migrateData(source); }`."
+	}];
+}
+function findClassRanges(content) {
+	const out = [];
+	for (const match of content.matchAll(/class\s+(\w+)(?:\s+extends\s+[^{]+)?\{/g)) {
+		if (match.index === void 0) continue;
+		const openIdx = match.index + match[0].length - 1;
+		let depth = 0;
+		let endIdx = -1;
+		for (let i = openIdx; i < content.length; i += 1) if (content[i] === "{") depth += 1;
+		else if (content[i] === "}") {
+			depth -= 1;
+			if (depth === 0) {
+				endIdx = i;
+				break;
+			}
+		}
+		if (endIdx < 0) continue;
+		let line = 1;
+		for (let i = 0; i < match.index; i += 1) if (content[i] === "\n") line += 1;
+		out.push({
+			className: match[1] ?? "(anonymous)",
+			startLine: line,
+			openIdx,
+			endIdx
+		});
+	}
+	return out;
+}
+function findEnclosingClass(ranges, idx) {
+	for (let i = ranges.length - 1; i >= 0; i -= 1) {
+		const r = ranges[i];
+		if (!r) continue;
+		if (idx >= r.openIdx && idx <= r.endIdx) return r.className;
+	}
+}
+/**
+* One `<subtype>: <Class>` entry inside a dataModels object literal.
+*
+* The key is bare for a system (`character`) and quoted for a module
+* (`'my-module.vehicle'`), because the module form contains a dot.
+*/
+const SUBTYPE_ENTRY_RE = /(?:['"]([^'"]+)['"]|(\w+))\s*:\s*(\w+)/g;
+/** Map a `registerSystem({ ...DataModels })` key to the document name. */
+const REGISTER_SYSTEM_KEYS = [
+	{
+		key: "actorDataModels",
+		doc: "Actor"
+	},
+	{
+		key: "itemDataModels",
+		doc: "Item"
+	},
+	{
+		key: "activeEffectDataModels",
+		doc: "ActiveEffect"
+	},
+	{
+		key: "journalEntryPageDataModels",
+		doc: "JournalEntryPage"
+	},
+	{
+		key: "regionBehaviorDataModels",
+		doc: "RegionBehavior"
+	}
+];
+function findConfigMappings(content) {
+	const out = [];
+	for (const m of content.matchAll(/CONFIG\.(\w+)\.dataModels\.(\w+)\s*=\s*(\w+)/g)) out.push({
+		doc: m[1] ?? "",
+		subtype: m[2] ?? "",
+		className: m[3] ?? ""
+	});
+	for (const m of content.matchAll(/CONFIG\.(\w+)\.dataModels\[\s*['"]([^'"]+)['"]\s*\]\s*=\s*(\w+)/g)) out.push({
+		doc: m[1] ?? "",
+		subtype: m[2] ?? "",
+		className: m[3] ?? ""
+	});
+	for (const m of content.matchAll(/CONFIG\.(\w+)\.dataModels\s*=\s*\{([\s\S]*?)\}/g)) {
+		const doc = m[1] ?? "";
+		const body = m[2] ?? "";
+		for (const e of body.matchAll(SUBTYPE_ENTRY_RE)) out.push({
+			doc,
+			subtype: e[1] ?? e[2] ?? "",
+			className: e[3] ?? ""
+		});
+	}
+	for (const { key, doc } of REGISTER_SYSTEM_KEYS) {
+		const re = new RegExp(String.raw`\b${key}\s*:\s*\{`, "g");
+		for (const m of content.matchAll(re)) {
+			if (m.index === void 0) continue;
+			const openIdx = m.index + m[0].length - 1;
+			let depth = 0;
+			let endIdx = -1;
+			for (let i = openIdx; i < content.length; i += 1) if (content[i] === "{") depth += 1;
+			else if (content[i] === "}") {
+				depth -= 1;
+				if (depth === 0) {
+					endIdx = i;
+					break;
+				}
+			}
+			if (endIdx < 0) continue;
+			const body = content.slice(openIdx + 1, endIdx);
+			for (const pair of body.matchAll(SUBTYPE_ENTRY_RE)) out.push({
+				doc,
+				subtype: pair[1] ?? pair[2] ?? "",
+				className: pair[3] ?? ""
+			});
+		}
+	}
+	return out;
+}
+/**
+* Match `<name>: new (f|fields|foundry.data.fields).HTMLField(` or
+* `.FilePathField(`. We capture the field name, the field type, the
+* enclosing class, AND the dot-path through any enclosing SchemaField
+* wrappers — so rule 004 compares against the FULL manifest declaration
+* path (`profile.bio`), not just the leaf segment (`bio`).
+*/
+const RICH_FIELD_RE = /(\w+)\s*:\s*new\s+(?:[\w.]+\.)?(HTMLField|FilePathField)\s*\(/g;
+function findRichFields(content, classes) {
+	const out = [];
+	for (const m of content.matchAll(RICH_FIELD_RE)) {
+		if (m.index === void 0) continue;
+		let line = 1;
+		for (let i = 0; i < m.index; i += 1) if (content[i] === "\n") line += 1;
+		const fieldName = m[1] ?? "(anonymous)";
+		out.push({
+			fieldName,
+			type: m[2] ?? "HTMLField",
+			line,
+			enclosingClass: findEnclosingClass(classes, m.index),
+			schemaPath: buildSchemaPath(content, m.index, fieldName)
+		});
+	}
+	return out;
+}
+/**
+* Walk backward from a rich-field match looking for enclosing SchemaField
+* wrappers, building the dot-path up to the outermost schema.
+*
+* For `profile: new SchemaField({ bio: new HTMLField() })`, the rich-field
+* match is `bio: new HTMLField(`; walking back, we find the enclosing `{`
+* that's preceded by `profile: new ...SchemaField(`, prepend `profile`, and
+* recurse. Top-level fields (immediate children of `defineSchema()`'s
+* returned object) recurse until the enclosing `{` has no SchemaField
+* ancestor, returning just the field name.
+*/
+function buildSchemaPath(content, idx, fieldName) {
+	let depth = 0;
+	let openIdx = -1;
+	for (let i = idx - 1; i >= 0; i -= 1) {
+		const ch = content[i];
+		if (ch === "}") depth += 1;
+		else if (ch === "{") {
+			if (depth === 0) {
+				openIdx = i;
+				break;
+			}
+			depth -= 1;
+		}
+	}
+	if (openIdx < 0) return fieldName;
+	const lookbackStart = Math.max(0, openIdx - 200);
+	const m = content.slice(lookbackStart, openIdx).match(/(\w+)\s*:\s*new\s+(?:[\w.]+\.)?SchemaField\s*\(\s*$/);
+	if (!m) return fieldName;
+	const parentName = m[1] ?? "";
+	if (!parentName) return fieldName;
+	return `${buildSchemaPath(content, lookbackStart + (m.index ?? 0), parentName)}.${fieldName}`;
+}
+/**
+* Foundry's manifest convention puts TypeDataModel-driven field paths
+* under the `system.` root (`system.biography`). Source-side rich-field
+* paths from `buildSchemaPath` don't include that prefix because they
+* start from `defineSchema()`'s returned object. Strip it for matching.
+*/
+function normalizeDeclaredPath(path) {
+	return path.startsWith("system.") ? path.slice(7) : path;
+}
+/**
+* Find one subtype's declarations, accounting for the module prefix.
+*
+* A system declares `character` in the manifest and registers `character`
+* in source — the two match directly. A module declares `vehicle` but
+* Foundry registers it as `my-module.vehicle`, and that prefixed form is
+* what appears in source. Comparing the two verbatim reports every
+* correctly declared module field as missing, so fall back to the bare key
+* once the package's own prefix is stripped.
+*
+* Only this package's prefix is stripped. A subtype contributed by some
+* other module is genuinely not ours to have declared.
+*/
+function lookupSubtype(declared, doc, subtype) {
+	const direct = declared.perSubtype.get(`${doc}.${subtype}`);
+	if (direct) return direct;
+	const prefix = declared.packageId ? `${declared.packageId}.` : null;
+	if (!prefix || !subtype.startsWith(prefix)) return void 0;
+	return declared.perSubtype.get(`${doc}.${subtype.slice(prefix.length)}`);
+}
+/**
+* VTTF-AUDIT-004 — cross-check source HTMLField/FilePathField usages
+* against the manifest's documentTypes declarations.
+*
+* Subtype-aware: if the enclosing class is registered on
+* `CONFIG.<Doc>.dataModels.<subtype>`, the field must be declared in
+* THAT subtype's htmlFields / filePathFields. Otherwise — class
+* unregistered, registration spread across files, dynamic registration —
+* we fall back to the global union check (catches the common "forgot to
+* declare anything" case without false positives on advanced setups).
+*/
+function rule004(filePath, content, declared, classToSubtypes) {
+	const usages = findRichFields(content, findClassRanges(content));
+	const out = [];
+	for (const usage of usages) {
+		const declaredBucketName = usage.type === "HTMLField" ? "htmlFields" : "filePathFields";
+		const mappings = usage.enclosingClass ? classToSubtypes.get(usage.enclosingClass) ?? [] : [];
+		const sourcePath = usage.schemaPath;
+		if (mappings.length > 0) {
+			const missing = mappings.filter((mapping) => {
+				const decl = lookupSubtype(declared, mapping.doc, mapping.subtype);
+				return !(usage.type === "HTMLField" ? decl?.html : decl?.filePath)?.has(sourcePath);
+			});
+			if (missing.length > 0) {
+				const locations = missing.map((mapping) => `${mapping.doc}.${mapping.subtype}`).join(", ");
+				out.push({
+					ruleId: "VTTF-AUDIT-004",
+					title: `${usage.type} not declared in manifest documentTypes`,
+					severity: "MEDIUM",
+					filePath,
+					line: usage.line,
+					message: `\`${usage.enclosingClass}\` declares \`${sourcePath}\` as ${usage.type}, but documentTypes.${locations}.${declaredBucketName} does not list this path. The Foundry server only sanitises declared paths.`,
+					remediation: `Add \`${sourcePath}\` (or \`system.${sourcePath}\`) to documentTypes.${missing[0]?.doc}.${missing[0]?.subtype}.${declaredBucketName} in your manifest.`
+				});
+			}
+			continue;
+		}
+		if ((usage.type === "HTMLField" ? declared.globalHtml : declared.globalFilePath).has(sourcePath)) continue;
+		out.push({
+			ruleId: "VTTF-AUDIT-004",
+			title: `${usage.type} not declared in manifest documentTypes`,
+			severity: "MEDIUM",
+			filePath,
+			line: usage.line,
+			message: `Schema declares \`${sourcePath}\` as ${usage.type}, but no documentTypes.<Doc>.<subtype>.${declaredBucketName} entry lists this path. The Foundry server only sanitises declared paths.`,
+			remediation: `Add \`${sourcePath}\` (or \`system.${sourcePath}\`) to documentTypes.<Doc>.<subtype>.${declaredBucketName} in your manifest.`
+		});
+	}
+	return out;
+}
+/**
+* VTTF-AUDIT-007 — manifest's `primaryTokenAttribute` /
+* `secondaryTokenAttribute` must point at a SchemaField with `value` +
+* `max` keys. If not, Foundry's `getBarAttribute` silently degrades to
+* value-only rendering (no bar at all).
+*
+* Cross-check walks the source for every SchemaField declaration paired
+* with its full schema path (`buildSchemaPath`). The manifest path is
+* matched EXACTLY — `primaryTokenAttribute: 'health'` does not accept a
+* nested `attributes.health` SchemaField, and a nested path like
+* `attributes.hp` is resolved by finding the declaration at that exact
+* dot-path. No more "verify manually" branch; either the path resolves
+* or it doesn't.
+*/
+async function rule007(manifestPath, manifestRaw, manifestParsed, sourceFiles, classToSubtypes) {
+	if (!manifestPath || !manifestRaw || !manifestParsed) return [];
+	const actorClasses = new Set([...classToSubtypes.entries()].filter(([, mappings]) => mappings.some((m) => m.doc === "Actor")).map(([className]) => className));
+	const out = [];
+	for (const key of ["primaryTokenAttribute", "secondaryTokenAttribute"]) {
+		const value = manifestParsed[key];
+		if (typeof value !== "string" || value.length === 0) continue;
+		if (!await sourceHasValueMaxSchemaAtPath(sourceFiles, value, actorClasses)) out.push({
+			ruleId: "VTTF-AUDIT-007",
+			title: `${key} does not resolve to a {value, max} SchemaField`,
+			severity: "MEDIUM",
+			filePath: manifestPath,
+			line: lineOfInRaw(manifestRaw, key),
+			message: `Manifest ${key} is \`${value}\`, but no TypeDataModel schema in the source declares a SchemaField at this path with both \`value\` and \`max\` keys. Foundry's getBarAttribute degrades silently when the structure doesn't match.`,
+			remediation: `Define \`${value}\` as a SchemaField with \`value\` and \`max\` NumberField children in your TypeDataModel schema (matching the manifest path exactly).`
+		});
+	}
+	return out;
+}
+function lineOfInRaw(raw, key) {
+	const idx = raw.indexOf(`"${key}"`);
+	if (idx < 0) return void 0;
+	let line = 1;
+	for (let i = 0; i < idx; i += 1) if (raw[i] === "\n") line += 1;
+	return line;
+}
+/**
+* Path-aware lookup for the rule-007 cross-check. For every SchemaField
+* declaration in every source file, compute its FULL schema path via
+* `buildSchemaPath`. Match the manifest's `primaryTokenAttribute` (which
+* may be a single key like `health` or a dotted path like `attributes.hp`)
+* against the declaration's path exactly. Only declarations whose schema
+* path equals the manifest value contribute to the value+max check.
+*
+* Why exact path: an unqualified `health: new SchemaField(...)` inside
+* `attributes: new SchemaField({...})` has schema path `attributes.health`.
+* Manifest `primaryTokenAttribute: 'health'` should NOT resolve to that
+* nested declaration — Foundry walks the document path structurally and
+* would look for `health.value` at the top of `system`, not under
+* `attributes`.
+*/
+async function sourceHasValueMaxSchemaAtPath(sourceFiles, targetPath, actorClasses) {
+	for (const file of sourceFiles) {
+		let content;
+		try {
+			content = await readFile(file, "utf8");
+		} catch {
+			continue;
+		}
+		const classes = findClassRanges(content);
+		for (const decl of findAllSchemaFields(content)) {
+			if (decl.path !== targetPath) continue;
+			if (actorClasses.size > 0) {
+				const owner = classes.find((c) => decl.index > c.openIdx && decl.index < c.endIdx);
+				if (!owner || !actorClasses.has(owner.className)) continue;
+			}
+			const topKeys = extractTopLevelKeys(decl.body);
+			if (topKeys.has("value") && topKeys.has("max")) return true;
+		}
+	}
+	return false;
+}
+function findAllSchemaFields(content) {
+	const out = [];
+	for (const m of content.matchAll(/(\w+)\s*:\s*new\s+(?:[\w.]+\.)?SchemaField\s*\(\s*\{/g)) {
+		if (m.index === void 0) continue;
+		const fieldName = m[1] ?? "";
+		const openIdx = m.index + m[0].length - 1;
+		let depth = 0;
+		let endIdx = -1;
+		for (let i = openIdx; i < content.length; i += 1) if (content[i] === "{") depth += 1;
+		else if (content[i] === "}") {
+			depth -= 1;
+			if (depth === 0) {
+				endIdx = i;
+				break;
+			}
+		}
+		if (endIdx < 0) continue;
+		out.push({
+			path: buildSchemaPath(content, m.index, fieldName),
+			body: content.slice(openIdx + 1, endIdx),
+			index: m.index
+		});
+	}
+	return out;
+}
+/**
+* Extract identifier keys declared at depth 0 of an object-literal body.
+*
+* The naive `value:`/`max:` regex check matches nested constructor options
+* too — `value: new NumberField({ max: 100 })` looked to a flat regex like
+* both keys were SchemaField siblings. Walking the body byte-by-byte with
+* depth tracking + string-boundary handling correctly distinguishes
+* top-level keys from nested ones.
+*/
+function extractTopLevelKeys(body) {
+	const keys = /* @__PURE__ */ new Set();
+	let depth = 0;
+	let inString = null;
+	let escaped = false;
+	let pos = 0;
+	const idStart = /[a-zA-Z_$]/;
+	const idCont = /[\w$]/;
+	const ws = /\s/;
+	while (pos < body.length) {
+		const ch = body[pos];
+		if (ch === void 0) break;
+		if (escaped) {
+			escaped = false;
+			pos += 1;
+			continue;
+		}
+		if (inString) {
+			if (ch === "\\") escaped = true;
+			else if (ch === inString) inString = null;
+			pos += 1;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			pos += 1;
+			continue;
+		}
+		if (ch === "{" || ch === "(" || ch === "[") {
+			depth += 1;
+			pos += 1;
+			continue;
+		}
+		if (ch === "}" || ch === ")" || ch === "]") {
+			depth -= 1;
+			pos += 1;
+			continue;
+		}
+		if (depth === 0 && idStart.test(ch)) {
+			let end = pos;
+			while (end < body.length && idCont.test(body[end] ?? "")) end += 1;
+			const name = body.slice(pos, end);
+			let after = end;
+			while (after < body.length && ws.test(body[after] ?? "")) after += 1;
+			if (body[after] === ":") {
+				keys.add(name);
+				pos = after + 1;
+				continue;
+			}
+			pos = end;
+			continue;
+		}
+		pos += 1;
+	}
+	return keys;
+}
+/**
+* Load every manifest at the project root, then return:
+*   - declared.perSubtype: per `Doc.subtype` htmlFields / filePathFields sets
+*   - declared.globalHtml / globalFilePath: union across all subtypes
+*   - manifest path/raw/parsed for the manifest we found first
+*
+* Used by rules 004 and 007. The per-subtype map lets rule 004 do a strict
+* cross-check when it knows which subtype a source class is registered to;
+* the global union is the fallback when no class→subtype mapping is found.
+*/
+async function collectDeclaredRichFields(cwd) {
+	const perSubtype = /* @__PURE__ */ new Map();
+	const globalHtml = /* @__PURE__ */ new Set();
+	const globalFilePath = /* @__PURE__ */ new Set();
+	let manifestPath = null;
+	let manifestRaw = null;
+	let manifestParsed = null;
+	let packageId = null;
+	for (const file of ["system.json", "module.json"]) {
+		const p = join(cwd, file);
+		if (!existsSync(p)) continue;
+		let raw;
+		try {
+			raw = await readFile(p, "utf8");
+		} catch {
+			continue;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			continue;
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+		if (!manifestPath) {
+			manifestPath = p;
+			manifestRaw = raw;
+			manifestParsed = parsed;
+			const id = parsed.id;
+			packageId = typeof id === "string" && id.length > 0 ? id : null;
+		}
+		const docTypes = parsed.documentTypes;
+		if (!docTypes || typeof docTypes !== "object" || Array.isArray(docTypes)) continue;
+		for (const [docName, docType] of Object.entries(docTypes)) {
+			if (!docType || typeof docType !== "object" || Array.isArray(docType)) continue;
+			for (const [subName, subtype] of Object.entries(docType)) {
+				if (!subtype || typeof subtype !== "object" || Array.isArray(subtype)) continue;
+				const sub = subtype;
+				const key = `${docName}.${subName}`;
+				const entry = perSubtype.get(key) ?? {
+					html: /* @__PURE__ */ new Set(),
+					filePath: /* @__PURE__ */ new Set()
+				};
+				if (Array.isArray(sub.htmlFields)) {
+					for (const e of sub.htmlFields) if (typeof e === "string") {
+						const normalized = normalizeDeclaredPath(e);
+						entry.html.add(normalized);
+						globalHtml.add(normalized);
+					}
+				}
+				for (const declaredPath of declaredFilePathKeys(sub.filePathFields)) {
+					const normalized = normalizeDeclaredPath(declaredPath);
+					entry.filePath.add(normalized);
+					globalFilePath.add(normalized);
+				}
+				perSubtype.set(key, entry);
+			}
+		}
+	}
+	return {
+		declared: {
+			perSubtype,
+			packageId,
+			globalHtml,
+			globalFilePath
+		},
+		manifestPath,
+		manifestRaw,
+		manifestParsed
+	};
+}
+/**
+* Read the declared file-path keys off one subtype's `filePathFields`.
+*
+* The manifest shape is an object keyed by field path, whose values name
+* the permitted file categories. Older hand-written manifests sometimes
+* carry a bare array instead; that shape does not validate, but reading it
+* costs nothing and avoids reporting a field as undeclared when the author
+* plainly declared it.
+*/
+function declaredFilePathKeys(value) {
+	if (Array.isArray(value)) return value.filter((e) => typeof e === "string");
+	if (value && typeof value === "object") return Object.keys(value);
+	return [];
+}
+/**
+* Aggregate every `CONFIG.<Doc>.dataModels.<subtype> = <ClassName>`
+* mapping discovered across all source files, keyed by class name.
+* Rule 004 reads this to determine which subtype each rich-field's
+* enclosing class is registered under.
+*/
+function buildClassToSubtypes(fileContents) {
+	const map = /* @__PURE__ */ new Map();
+	for (const content of fileContents) for (const mapping of findConfigMappings(content)) {
+		if (!mapping.className) continue;
+		const existing = map.get(mapping.className) ?? [];
+		existing.push(mapping);
+		map.set(mapping.className, existing);
+	}
+	return map;
+}
+/** Entry point: gather everything once, then dispatch to the per-file rules. */
+async function runSourceRules(cwd) {
+	if (!existsSync(cwd)) return [];
+	if (!(await stat(cwd)).isDirectory()) return [];
+	const { declared, manifestPath, manifestRaw, manifestParsed } = await collectDeclaredRichFields(cwd);
+	const sourceFiles = [];
+	for await (const file of walkSourceFiles(cwd)) sourceFiles.push(file);
+	const contents = /* @__PURE__ */ new Map();
+	for (const file of sourceFiles) try {
+		contents.set(file, await readFile(file, "utf8"));
+	} catch {}
+	const classToSubtypes = buildClassToSubtypes(contents.values());
+	const results = [];
+	for (const [file, content] of contents) {
+		results.push(...rule005(file, content));
+		results.push(...rule006(file, content));
+		results.push(...rule004(file, content, declared, classToSubtypes));
+	}
+	results.push(...await rule007(manifestPath, manifestRaw, manifestParsed, sourceFiles, classToSubtypes));
+	return results;
+}
+//#endregion
+//#region src/audit/types.ts
+/** Severity rank for sorting (HIGH first). */
+const SEVERITY_RANK = {
+	HIGH: 0,
+	MEDIUM: 1,
+	LOW: 2
+};
+//#endregion
+//#region src/audit/index.ts
+/**
+* Audit orchestrator — runs every rule against a project root and
+* aggregates the findings into an `AuditReport`.
+*
+* Rule organisation:
+*   - manifest-rules.ts → VTTF-AUDIT-001, 002, 003 (manifest-only)
+*   - source-rules.ts   → VTTF-AUDIT-004, 005, 006, 007 (source walker
+*                         + cross-check with manifest where needed)
+*
+* The orchestrator stays minimal — it knows which rule sets exist, but
+* the rules themselves are responsible for their own file IO. This keeps
+* the individual rule files testable in isolation.
+*/
+var AuditTargetError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "AuditTargetError";
+	}
+};
+async function runAudit(options) {
+	const cwd = resolve(options.cwd);
+	if (!existsSync(cwd)) throw new AuditTargetError(`Audit target does not exist: ${cwd}`);
+	if (!statSync(cwd).isDirectory()) throw new AuditTargetError(`Audit target is not a directory: ${cwd}`);
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const [manifestFindings, sourceFindings] = await Promise.all([runManifestRules(cwd), runSourceRules(cwd)]);
+	const findings = [...manifestFindings, ...sourceFindings].sort(compareFindings);
+	return {
+		cwd,
+		startedAt,
+		findings,
+		counts: countBySeverity(findings)
+	};
+}
+/** Sort: HIGH first, then by ruleId for deterministic output. */
+function compareFindings(a, b) {
+	const sev = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+	if (sev !== 0) return sev;
+	if (a.ruleId !== b.ruleId) return a.ruleId.localeCompare(b.ruleId);
+	return a.filePath.localeCompare(b.filePath);
+}
+function countBySeverity(findings) {
+	const counts = {
+		HIGH: 0,
+		MEDIUM: 0,
+		LOW: 0
+	};
+	for (const f of findings) counts[f.severity] += 1;
+	return counts;
+}
+//#endregion
+//#region src/audit/reporter.ts
+/**
+* Render an `AuditReport` as JSON (machine-readable, stable schema) or
+* markdown (terminal-friendly, sectioned by severity).
+*
+* JSON output is the contract for downstream CI tooling: stable shape,
+* stable severity strings, stable ruleId namespace `VTTF-AUDIT-NNN`. The
+* markdown variant exists so a human running `vttforge audit` in a
+* scrollback gets immediate signal without piping through `jq`.
+*/
+function formatReport(report, format) {
+	return format === "json" ? formatJson(report) : formatMarkdown(report);
+}
+function formatJson(report) {
+	return `${JSON.stringify(report, null, 2)}\n`;
+}
+function formatMarkdown(report) {
+	const { findings, counts, cwd } = report;
+	const lines = [];
+	lines.push("# vttforge audit report");
+	lines.push("");
+	lines.push(`- cwd: \`${cwd}\``);
+	lines.push(`- started: ${report.startedAt}`);
+	lines.push(`- findings: ${findings.length} (${counts.HIGH} HIGH · ${counts.MEDIUM} MEDIUM · ${counts.LOW} LOW)`);
+	lines.push("");
+	if (findings.length === 0) {
+		lines.push("No issues found. The system / module looks healthy against the v13 catalog.");
+		lines.push("");
+		return lines.join("\n");
+	}
+	for (const severity of [
+		"HIGH",
+		"MEDIUM",
+		"LOW"
+	]) {
+		const bucket = findings.filter((f) => f.severity === severity);
+		if (bucket.length === 0) continue;
+		lines.push(`## ${severity} (${bucket.length})`);
+		lines.push("");
+		for (const finding of bucket) {
+			lines.push(formatFinding(finding, cwd));
+			lines.push("");
+		}
+	}
+	return lines.join("\n");
+}
+function formatFinding(finding, cwd) {
+	const location = formatLocation(finding, cwd);
+	const lines = [];
+	lines.push(`### \`${finding.ruleId}\` — ${finding.title}`);
+	lines.push("");
+	lines.push(`- file: ${location}`);
+	lines.push(`- message: ${finding.message}`);
+	if (finding.remediation) lines.push(`- fix: ${finding.remediation}`);
+	return lines.join("\n");
+}
+function formatLocation(finding, cwd) {
+	const rel = relativizeIfBelow(finding.filePath, cwd);
+	return finding.line !== void 0 ? `\`${rel}:${finding.line}\`` : `\`${rel}\``;
+}
+/**
+* Show paths relative to `cwd` when they live underneath it (cleaner reports),
+* fall back to the absolute path otherwise so we don't lie about where the
+* file actually is.
+*/
+function relativizeIfBelow(filePath, cwd) {
+	const rel = relative(cwd, filePath);
+	if (rel === "" || rel.startsWith("..") || rel.startsWith("/")) return filePath;
+	return rel;
+}
+//#endregion
+//#region src/commands/audit.ts
+/**
+* `vttforge audit` — scan a system/module project against the VTTForge
+* audit catalog (seven v13 manifest + code footguns).
+*
+* The seven rules (VTTF-AUDIT-001 through 007) live in
+* `audit/manifest-rules.ts` or `audit/source-rules.ts`; this file is the
+* CLI surface that orchestrates them and prints the report.
+*
+* Exit codes:
+*   0 — clean run, or only MEDIUM/LOW findings (informational)
+*   1 — at least one HIGH finding (or any finding in `--strict` mode)
+*/
+async function runAuditCommand(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const format = options.format ?? "markdown";
+	const strict = options.strict === true;
+	const write = options.write ?? ((chunk) => {
+		process.stdout.write(chunk);
+	});
+	const report = await runAudit({ cwd });
+	write(formatReport(report, format));
+	return {
+		report,
+		exitCode: report.counts.HIGH > 0 || strict && (report.counts.MEDIUM > 0 || report.counts.LOW > 0) ? 1 : 0
+	};
+}
+//#endregion
+//#region src/manifest.ts
+/**
+* Read a built manifest (`dist/system.json` or `dist/module.json`).
+*
+* The vite plugin emits the manifest into `dist/` during build, so the CLI
+* commands that come after a build (dev's initial symlink, build's release
+* zip) read from there rather than walking source. This file is intentionally
+* tiny — we extract just the fields the CLI cares about and surface the
+* rest as `raw` for any consumer that wants more.
+*/
+const MANIFEST_FILES = [{
+	file: "system.json",
+	type: "system"
+}, {
+	file: "module.json",
+	type: "module"
+}];
+const MANIFEST_ID_RE = /^[a-z][a-z0-9._-]*$/;
+const MANIFEST_VERSION_RE = /^[0-9A-Za-z._+-]+$/;
+/**
+* Locate and parse the Foundry manifest inside the given dist directory.
+* Prefers `system.json`, falls back to `module.json` (a single dist can't
+* be both — the vite plugin emits exactly one based on the project type).
+*
+* Throws if neither file exists, required fields are missing/non-string,
+* or the id/version contain characters that would let downstream `join()`
+* calls escape their intended directory.
+*/
+async function readManifest(distDir) {
+	for (const { file, type } of MANIFEST_FILES) {
+		const path = join(distDir, file);
+		if (!existsSync(path)) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(await readFile(path, "utf8"));
+		} catch (err) {
+			throw new Error(`Failed to parse ${path}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`Manifest at ${path} is not a JSON object.`);
+		const raw = parsed;
+		const id = raw.id;
+		const version = raw.version;
+		if (typeof id !== "string" || id.length === 0) throw new Error(`Manifest at ${path} is missing a non-empty "id" field.`);
+		if (!MANIFEST_ID_RE.test(id)) throw new Error(`Manifest at ${path} has an invalid "id" (${JSON.stringify(id)}). Foundry package ids must match ${MANIFEST_ID_RE} — lowercase letters, digits, dashes, dots, underscores; must start with a letter.`);
+		if (typeof version !== "string" || version.length === 0) throw new Error(`Manifest at ${path} is missing a non-empty "version" field.`);
+		if (!MANIFEST_VERSION_RE.test(version)) throw new Error(`Manifest at ${path} has an invalid "version" (${JSON.stringify(version)}). Use a semver-ish string with letters, digits, dots, dashes, plus, or underscore.`);
+		return {
+			id,
+			version,
+			type,
+			raw
+		};
+	}
+	throw new Error(`No Foundry manifest found in ${distDir}. Expected system.json or module.json — did you run \`vite build\` first?`);
+}
+//#endregion
+//#region src/package-manager.ts
+/**
+* Detect which package manager invoked the CLI so we can run the right
+* `install` command after scaffolding.
+*
+* Strategy: read `npm_config_user_agent`, which pnpm/npm/bun/yarn all set when
+* they spawn a child process (including `pnpm dlx`, `pnpm create`, etc.).
+* Falls back to `pnpm` because that's the VTTForge house default and the
+* most common Foundry-developer choice — but any concrete signal in the
+* environment wins over the default.
+*/
+function detectPackageManager(env = process.env) {
+	const ua = env.npm_config_user_agent;
+	if (typeof ua === "string" && ua.length > 0) {
+		if (ua.startsWith("pnpm")) return "pnpm";
+		if (ua.startsWith("bun")) return "bun";
+		if (ua.startsWith("yarn")) return "yarn";
+		if (ua.startsWith("npm")) return "npm";
+	}
+	return "pnpm";
+}
+function installCommand(pm) {
+	return `${pm} install`;
+}
+/**
+* Detect a project's package manager by looking at which lockfile it
+* ships. `dev` and `build` need this — by the time the user runs
+* `vttforge dev`, npm_config_user_agent reflects whatever shell launched
+* the binary (often nothing in a global install), not how the project
+* was bootstrapped. The lockfile is the project's own contract.
+*
+* Falls back to {@link detectPackageManager} for fresh checkouts that
+* haven't been installed yet.
+*/
+function detectProjectPackageManager(cwd, env = process.env) {
+	if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+	if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb"))) return "bun";
+	if (existsSync(join(cwd, "package-lock.json")) || existsSync(join(cwd, "npm-shrinkwrap.json"))) return "npm";
+	return detectPackageManager(env);
+}
+/**
+* Argument vector to invoke `vite` (or any other locally-installed CLI)
+* via the project's package manager. We always shell out through `<pm>
+* exec` so the call works regardless of the linker's choices — Yarn 4
+* Plug'n'Play, pnpm's symlinked layout, npm's flattened node_modules,
+* Bun's symlinked node_modules. Each manager exposes a uniform "run a
+* locally-resolved binary in the project's dependency graph" command.
+*/
+function execInvocation(pm, bin) {
+	switch (pm) {
+		case "pnpm": return ["pnpm", ["exec", bin]];
+		case "yarn": return ["yarn", [
+			"exec",
+			"--",
+			bin
+		]];
+		case "bun": return ["bun", ["x", bin]];
+		case "npm": return ["npx", ["--no-install", bin]];
+	}
+}
+//#endregion
+//#region src/vite-runner.ts
+/**
+* Spawn the user's project-local `vite` through their package manager.
+*
+* We deliberately go through `<pm> exec vite` instead of probing a
+* `node_modules/vite/bin/vite.js` path: Yarn 4 Plug'n'Play stores
+* dependencies in `.yarn/cache/` rather than `node_modules/`, and even
+* within npm/pnpm projects PNP-style linkers may not materialize the
+* binary on disk. The package-manager command always resolves the
+* locally-installed vite correctly regardless of linker.
+*/
+var ViteNotInstalledError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ViteNotInstalledError";
+	}
+};
+/** Spawn args for invoking the user's vite (e.g. `["pnpm", ["exec", "vite"]]`). */
+function resolveViteInvocation(cwd) {
+	if (!existsSync(join(cwd, "package.json"))) throw new ViteNotInstalledError(`No package.json found at ${cwd}. Run \`vttforge dev\` / \`vttforge build\` from inside a scaffolded project.`);
+	return execInvocation(detectProjectPackageManager(cwd), "vite");
+}
+/** Run `vite build` once and wait for it to exit. Throws on non-zero exit. */
+async function runViteBuildOnce(cwd) {
+	const [bin, baseArgs] = resolveViteInvocation(cwd);
+	await new Promise((resolveBuild, rejectBuild) => {
+		const child = spawn(bin, [...baseArgs, "build"], {
+			cwd,
+			stdio: "inherit",
+			env: process.env,
+			shell: false
+		});
+		child.on("error", (err) => {
+			if (err.code === "ENOENT") rejectBuild(/* @__PURE__ */ new Error(`Could not invoke "${bin}". Is the project's package manager installed and on PATH?`));
+			else rejectBuild(err);
+		});
+		child.on("exit", (code) => {
+			if (code === 0) resolveBuild();
+			else rejectBuild(/* @__PURE__ */ new Error(`vite build exited with code ${code ?? "unknown"}`));
+		});
+	});
+}
+/**
+* Spawn `vite build --watch` and return the child process. The caller is
+* responsible for waiting on it and tearing it down (the dev command kills
+* it on SIGINT).
+*/
+function spawnViteWatch(cwd) {
+	const [bin, baseArgs] = resolveViteInvocation(cwd);
+	return spawn(bin, [
+		...baseArgs,
+		"build",
+		"--watch"
+	], {
+		cwd,
+		stdio: "inherit",
+		env: process.env,
+		shell: false
+	});
+}
+//#endregion
+//#region src/zip.ts
+/**
+* Emit a foundryvtt.com-compatible release zip.
+*
+* foundryvtt.com expects the package contents at the zip root (no wrapper
+* folder), so `unzip release.zip` produces `system.json`, `scripts/`, etc.
+* directly. The vite build output already matches that layout, so we feed
+* `dist/` straight into archiver with `false` as the second arg to disable
+* the wrap-with-source-dir-name default.
+*
+* Optional extras (LICENSE / README / CHANGELOG) ride along when present at
+* the project root and not already inside `dist/`. We never duplicate.
+*/
+async function emitZip(opts) {
+	const { sourceDir, outFile, extras = [], extrasFrom } = opts;
+	if (!existsSync(sourceDir)) throw new Error(`emitZip: sourceDir does not exist: ${sourceDir}`);
+	if (extras.length > 0 && !extrasFrom) throw new Error("emitZip: extrasFrom is required when extras are provided.");
+	await new Promise((resolveZip, rejectZip) => {
+		const output = createWriteStream(outFile);
+		const archive = new ZipArchive({ zlib: { level: 9 } });
+		output.on("close", () => resolveZip());
+		output.on("error", rejectZip);
+		archive.on("error", rejectZip);
+		archive.on("warning", (err) => {
+			if (err.code !== "ENOENT") rejectZip(err);
+		});
+		archive.pipe(output);
+		archive.directory(sourceDir, false);
+		if (extrasFrom) for (const name of extras) {
+			const srcPath = join(extrasFrom, name);
+			if (!existsSync(srcPath)) continue;
+			const distPath = join(sourceDir, name);
+			if (existsSync(distPath)) continue;
+			archive.file(srcPath, { name });
+		}
+		archive.finalize().catch(rejectZip);
+	});
+	return {
+		outFile,
+		byteSize: (await stat(outFile)).size
+	};
+}
+//#endregion
+//#region src/commands/build.ts
+/**
+* `vttforge build` — emit a foundryvtt.com-ready release zip.
+*
+* Flow:
+*   1. Clean dist/
+*   2. Run `vite build` (production mode)
+*   3. Read the resulting manifest → id + version
+*   4. Zip dist/ + LICENSE/README/CHANGELOG (if present) into
+*      `<cwd>/<id>-<version>.zip` with contents at the zip root
+*
+* The release workflows shipped by the templates upload this zip to a
+* GitHub release; the manifest URL points at `releases/latest/download/`
+* so Foundry's auto-update catches new versions.
+*/
+/** Files we copy into the zip at root when they exist at project root. */
+const RELEASE_ZIP_EXTRAS = [
+	"LICENSE",
+	"README.md",
+	"CHANGELOG.md"
+];
+/** Format a byte count as `12 B`, `4.3 KB`, or `1.2 MB`. */
+function formatBytes(n) {
+	if (!Number.isFinite(n) || n < 0) return `${n} B`;
+	const units = [
+		"B",
+		"KB",
+		"MB"
+	];
+	let v = n;
+	let unitIndex = 0;
+	while (v >= 1024 && unitIndex < units.length - 1) {
+		v /= 1024;
+		unitIndex += 1;
+	}
+	return `${v.toFixed(v >= 10 || unitIndex === 0 ? 0 : 1)} ${units[unitIndex]}`;
+}
+/**
+* Internal building block exposed for tests: assumes dist/ is already
+* populated (vite has run, manifest is present) and just emits the zip.
+*/
+async function emitReleaseZip(opts) {
+	const cwd = resolve(opts.cwd);
+	const distDir = join(cwd, "dist");
+	const manifest = await readManifest(distDir);
+	const zipName = `${manifest.id}-${manifest.version}.zip`;
+	const zipFile = join(cwd, zipName);
+	const { byteSize } = await emitZip({
+		sourceDir: distDir,
+		outFile: zipFile,
+		extras: RELEASE_ZIP_EXTRAS,
+		extrasFrom: cwd
+	});
+	return {
+		zipFile,
+		byteSize,
+		manifest
+	};
+}
+async function runBuild(options = {}) {
+	const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
+	p.intro("🜲 vttforge build — release zip");
+	const distDir = join(cwd, "dist");
+	await rm(distDir, {
+		recursive: true,
+		force: true
+	});
+	const buildSpinner = p.spinner();
+	buildSpinner.start("vite build (production)");
+	try {
+		await runViteBuildOnce(cwd);
+		buildSpinner.stop("Build complete");
+	} catch (err) {
+		buildSpinner.stop("Build failed");
+		throw err;
+	}
+	const { zipFile, byteSize } = await emitReleaseZip({ cwd });
+	p.note(`${zipFile}\n${formatBytes(byteSize)}`, "Release artifact");
+	p.outro(`Upload this zip to your release. The release workflow shipped with the template handles tag→GitHub Release → foundryvtt.com manifest update.`);
+}
+//#endregion
+//#region src/symlink.ts
+/**
+* Cross-platform symlink helpers for `vttforge dev`.
+*
+* The dev loop drops a symlink from Foundry's `Data/<systems|modules>/<id>/`
+* back to the project's `dist/` so Foundry serves freshly-built files as
+* vite writes them. The win32 path matters: with `type: 'junction'` the
+* operation works on standard Windows shells without Developer Mode, while
+* `type: 'dir'` requires admin. We never silently fall back to copying —
+* Foundry's HMR relies on live file mutation, and a copy snapshot defeats
+* the loop. If the symlink fails, we surface the platform-specific fix.
+*/
+/**
+* Read a symlink target. Returns the absolute path the link points at, or
+* `null` if `path` doesn't exist or isn't a symlink. Relative symlink
+* targets are resolved against the link's own directory (matches the
+* semantics callers expect when comparing to a known absolute source).
+*/
+async function readLinkTarget(path) {
+	try {
+		if (!(await lstat(path)).isSymbolicLink()) return null;
+		const target = await readlink(path);
+		return resolve(dirname(path), target);
+	} catch {
+		return null;
+	}
+}
+/**
+* Create a symlink at `target` pointing to `source`. Win32 uses `'junction'`
+* so the call succeeds without elevation; everywhere else uses `'dir'`.
+*
+* Idempotency:
+*   - target already points to source → no-op
+*   - target points elsewhere → throws unless `options.overwrite`
+*   - target is a real file/dir → throws unconditionally
+*/
+async function createLink(target, source, options = {}) {
+	const absSource = resolve(source);
+	const absTarget = resolve(target);
+	let info;
+	try {
+		info = await lstat(absTarget);
+	} catch (err) {
+		if (err.code === "ENOENT") info = null;
+		else throw err;
+	}
+	if (info?.isSymbolicLink()) {
+		const existing = await readLinkTarget(absTarget);
+		if (existing === absSource) return;
+		if (!options.overwrite) throw new Error(`Symlink already exists at ${absTarget} pointing to ${existing}. Pass { overwrite: true } or remove it manually.`);
+		await unlink(absTarget);
+	} else if (info) {
+		const kind = info.isDirectory() ? "directory" : "file";
+		throw new Error(`Refusing to overwrite ${absTarget}: path exists as a ${kind}, not a symlink.`);
+	}
+	await mkdir(dirname(absTarget), { recursive: true });
+	const linkType = process.platform === "win32" ? "junction" : "dir";
+	try {
+		await symlink(absSource, absTarget, linkType);
+	} catch (err) {
+		if (err.code === "EPERM" && process.platform === "win32") throw new Error(`Could not create symlink at ${absTarget}: permission denied. On Windows, enable Developer Mode (Settings → Update & Security → For Developers) or relaunch the terminal as administrator.`);
+		throw err;
+	}
+}
+/**
+* Remove a symlink at `path`. No-ops when the path doesn't exist. Throws
+* when the path exists but isn't a symlink — we never unlink real files
+* or directories.
+*/
+async function removeLink(path) {
+	let info;
+	try {
+		info = await lstat(path);
+	} catch (err) {
+		if (err.code === "ENOENT") return;
+		throw err;
+	}
+	if (!info.isSymbolicLink()) {
+		const kind = info.isDirectory() ? "directory" : "file";
+		throw new Error(`Refusing to remove ${path}: it is a ${kind}, not a symlink.`);
+	}
+	await unlink(path);
+}
+//#endregion
+//#region src/dev-module-install.ts
+/**
+* Put `@vttforge/dev-module` where Foundry will find it.
+*
+* Foundry loads a module from a directory under `Data/modules/<id>/` holding
+* `module.json` and the files it names. The published package already has
+* exactly that shape, so the install is a link to the package root — no copy
+* to keep in step, and a `pnpm update` is picked up on the next reload.
+*
+* A container is the other case: it cannot follow a host symlink, so the
+* compose file mounts the same directory instead. `vttforge dev` prints the
+* mount rather than editing anyone's compose file for them.
+*/
+const DEV_MODULE_ID = "vttforge-dev";
+/**
+* Find the installed package directory.
+*
+* Resolved from the consumer's project so their `node_modules` answers,
+* falling back to this CLI's own resolution — which is what makes it work
+* inside this repository, where the package is a workspace link.
+*/
+function resolveDevModuleDir(cwd) {
+	const candidates = [join(cwd, "node_modules", "@vttforge", "dev-module"), join(dirname(fileURLToPath(import.meta.url)), "..", "..", "dev-module")];
+	for (const dir of candidates) if (existsSync(join(dir, "module.json"))) return dir;
+	return null;
+}
+async function installDevModule(modulesDir, packageDir) {
+	const target = join(modulesDir, DEV_MODULE_ID);
+	if (await readLinkTarget(target) === packageDir) return {
+		target,
+		source: packageDir,
+		changed: false
+	};
+	await createLink(target, packageDir, { overwrite: true });
+	return {
+		target,
+		source: packageDir,
+		changed: true
+	};
+}
+/** The compose line a containerised Foundry needs, ready to paste. */
+function composeMountLine(packageDir) {
+	return `- ${packageDir}:/data/Data/modules/${DEV_MODULE_ID}:ro`;
+}
+//#endregion
+//#region src/dev-server.ts
+/**
+* A one-way WebSocket server: `vttforge dev` pushes, the dev module listens.
+*
+* Hand-written rather than pulled from a package. The CLI ships to every
+* consumer, so each dependency is one they install too, and what is needed
+* here is a narrow slice of RFC 6455: accept the upgrade, send unmasked text
+* frames, notice when a client goes away. No client payloads are read, no
+* compression, no extensions.
+*/
+/** Fixed GUID from RFC 6455 §1.3, concatenated with the client key. */
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+/** Frame lengths above these switch to a wider length field. */
+const LEN_16_BIT = 126;
+const LEN_64_BIT = 65536;
+/** Opcode 0x8 — the client is closing. */
+const OPCODE_CLOSE = 8;
+/**
+* Compute the handshake response header.
+*
+* Exported because it is the one part of the handshake with a published test
+* vector, and a wrong value fails as a silent non-connection.
+*/
+function acceptKey(clientKey) {
+	return createHash("sha1").update(clientKey + WS_GUID).digest("base64");
+}
+/**
+* Encode one text frame, server to client.
+*
+* Server frames are never masked. The payload length picks one of three
+* widths, and getting the boundary wrong corrupts the stream rather than
+* failing loudly — hence the explicit constants and the tests around them.
+*/
+function encodeTextFrame(message) {
+	const payload = Buffer.from(message, "utf8");
+	const len = payload.length;
+	let header;
+	if (len < LEN_16_BIT) header = Buffer.from([129, len]);
+	else if (len < LEN_64_BIT) {
+		header = Buffer.alloc(4);
+		header[0] = 129;
+		header[1] = LEN_16_BIT;
+		header.writeUInt16BE(len, 2);
+	} else {
+		header = Buffer.alloc(10);
+		header[0] = 129;
+		header[1] = 127;
+		header.writeBigUInt64BE(BigInt(len), 2);
+	}
+	return Buffer.concat([header, payload]);
+}
+/** Is this inbound frame a close? That is the only opcode worth reading. */
+function isCloseFrame(chunk) {
+	const first = chunk.at(0);
+	return first !== void 0 && (first & 15) === OPCODE_CLOSE;
+}
+async function startDevServer(options) {
+	const sockets = /* @__PURE__ */ new Set();
+	const server = createServer((_req, res) => {
+		res.writeHead(426, { "Content-Type": "text/plain" });
+		res.end("This port speaks WebSocket only — it is the vttforge dev bridge.\n");
+	});
+	server.on("upgrade", (req, socket) => {
+		const key = req.headers["sec-websocket-key"];
+		if (typeof key !== "string") {
+			socket.destroy();
+			return;
+		}
+		socket.write([
+			"HTTP/1.1 101 Switching Protocols",
+			"Upgrade: websocket",
+			"Connection: Upgrade",
+			`Sec-WebSocket-Accept: ${acceptKey(key)}`,
+			"\r\n"
+		].join("\r\n"));
+		if ("setNoDelay" in socket && typeof socket.setNoDelay === "function") socket.setNoDelay(true);
+		sockets.add(socket);
+		const drop = () => {
+			sockets.delete(socket);
+			socket.destroy();
+		};
+		socket.on("data", (chunk) => {
+			if (isCloseFrame(chunk)) drop();
+		});
+		socket.on("close", () => sockets.delete(socket));
+		socket.on("error", drop);
+	});
+	await new Promise((resolveStart, rejectStart) => {
+		server.once("error", rejectStart);
+		server.listen(options.port, options.host ?? "127.0.0.1", () => {
+			server.removeListener("error", rejectStart);
+			resolveStart();
+		});
+	});
+	const address = server.address();
+	return {
+		broadcast: (message) => {
+			const frame = encodeTextFrame(message);
+			for (const socket of sockets) try {
+				socket.write(frame);
+			} catch {
+				sockets.delete(socket);
+			}
+		},
+		clientCount: () => sockets.size,
+		close: async () => {
+			for (const socket of sockets) socket.destroy();
+			sockets.clear();
+			await new Promise((resolveClose) => server.close(() => resolveClose()));
+		},
+		port: typeof address === "object" && address ? address.port : options.port
+	};
+}
+//#endregion
+//#region src/dev-watcher.ts
+/**
+* Watch the build output and turn each change into a reload payload.
+*
+* Watching `dist/` rather than hooking into Vite is deliberate: Vite rebuilds
+* into that directory whatever its internals look like, so this stays correct
+* across bundler versions and gives the served path directly — `dist/` is what
+* Foundry mounts, so a file's position inside it is its position under
+* `/systems/<id>/`.
+*/
+/** What the dev module knows how to apply without a page reload. */
+const RELOADABLE = /* @__PURE__ */ new Set([
+	"css",
+	"hbs",
+	"html",
+	"json"
+]);
+/**
+* Editors save in bursts — write, rename, truncate — and a burst should be
+* one reload, not four.
+*/
+const DEBOUNCE_MS = 40;
+/**
+* The path Foundry serves this file at.
+*
+* Always POSIX separators — it becomes a URL, and a Windows backslash would
+* not match the `<link>` the browser rendered.
+*/
+function servedPath(relative, packageId, packageType) {
+	const normalized = relative.split(sep).join(posix.sep);
+	return posix.join(`${packageType}s`, packageId, normalized);
+}
+/** Extension without the dot, lowercased. Empty when there is none. */
+function reloadableExtension(relative) {
+	const ext = extname(relative).replace(".", "").toLowerCase();
+	return RELOADABLE.has(ext) ? ext : null;
+}
+const digest = (content) => createHash("sha1").update(content).digest("hex");
+/**
+* Record what every reloadable file already contains.
+*
+* Vite rewrites its whole output on each build, so without a baseline the
+* first rebuild after startup looks like every file changed at once.
+*
+* Read synchronously and before the watcher exists, on purpose. Doing it
+* asynchronously races the very first change: the walk can pick up a file
+* written a moment ago and then the change event finds a matching hash and
+* drops a real edit. The output tree is small; correctness is worth the wait.
+*/
+function seedDigests(distDir) {
+	const seen = /* @__PURE__ */ new Map();
+	const walk = (dir, prefix) => {
+		let items;
+		try {
+			items = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const item of items) {
+			const rel = prefix ? `${prefix}/${item.name}` : item.name;
+			if (item.isDirectory()) {
+				walk(join(dir, item.name), rel);
+				continue;
+			}
+			if (!reloadableExtension(rel)) continue;
+			try {
+				seen.set(rel, digest(readFileSync(join(distDir, rel), "utf8")));
+			} catch {}
+		}
+	};
+	walk(distDir, "");
+	return seen;
+}
+function watchDist(options) {
+	const debounceMs = options.debounceMs ?? DEBOUNCE_MS;
+	const pending = /* @__PURE__ */ new Map();
+	/**
+	* Last content seen per file.
+	*
+	* A rebuild rewrites every output file, changed or not, so the filesystem
+	* event alone says "the bundler ran", not "the developer edited this".
+	* Comparing content is what makes a reload mean the second thing — and it
+	* matters: a language file rewritten untouched would redraw every open
+	* window, undoing the scoped re-render on the file that did change.
+	*/
+	const digests = seedDigests(options.distDir);
+	const send = async (relative) => {
+		const extension = reloadableExtension(relative);
+		if (!extension) return;
+		let content;
+		try {
+			content = await readFile(join(options.distDir, relative), "utf8");
+		} catch {
+			return;
+		}
+		const hash = digest(content);
+		if (digests.get(relative) === hash) return;
+		digests.set(relative, hash);
+		options.onPayload(JSON.stringify({
+			packageType: options.packageType,
+			packageId: options.packageId,
+			content,
+			path: servedPath(relative, options.packageId, options.packageType),
+			extension
+		}));
+	};
+	if (!existsSync(options.distDir)) {
+		options.onError?.(`Cannot watch ${options.distDir} — the directory does not exist.`);
+		return { close: () => void 0 };
+	}
+	let watcher;
+	try {
+		watcher = watch(options.distDir, { recursive: true }, (_event, filename) => {
+			if (!filename) return;
+			const relative = filename.toString();
+			clearTimeout(pending.get(relative));
+			pending.set(relative, setTimeout(() => {
+				pending.delete(relative);
+				send(relative);
+			}, debounceMs));
+		});
+	} catch (err) {
+		options.onError?.(err instanceof Error ? err.message : String(err));
+		return { close: () => void 0 };
+	}
+	watcher.on("error", (err) => {
+		options.onError?.(err instanceof Error ? err.message : String(err));
+	});
+	return { close: () => {
+		for (const timer of pending.values()) clearTimeout(timer);
+		pending.clear();
+		watcher.close();
+	} };
+}
+//#endregion
+//#region src/foundry-data-dir.ts
+/**
+* Foundry user-data directory discovery + persistence.
+*
+* Foundry stores worlds, systems, and modules under a single user-data
+* directory (`Data/` lives at its root). `vttforge dev` needs to know where
+* that is so it can symlink the built `dist/` into `Data/systems/<id>/` or
+* `Data/modules/<id>/` and let Foundry pick it up.
+*
+* Precedence (top wins):
+*   1. Explicit `--data-dir` flag passed to the command
+*   2. `FOUNDRY_DATA_DIR` env var (useful in Docker/CI)
+*   3. `<project>/.vttforge/config.json :: foundryDataDir`
+*   4. OS default + interactive prompt that saves to (3) for next time
+*
+* The OS-default detection treats `XDG_DATA_HOME` (Linux) and `%LOCALAPPDATA%`
+* (Windows) as part of the OS convention, not as Foundry-specific overrides.
+*
+* Everything here is pure — `platform`, `env`, and `home` flow through
+* options so tests can drive every branch without monkey-patching globals.
+*/
+/**
+* Return the OS-default Foundry user-data directory, or `null` on unknown
+* platforms / missing platform-specific env vars. Does NOT check existence —
+* callers prompt the user when the suggested path doesn't resolve.
+*/
+function autoDetectFoundryDataDir(platform = process.platform, env = process.env, home = homedir()) {
+	switch (platform) {
+		case "darwin": return join(home, "Library", "Application Support", "FoundryVTT");
+		case "linux": {
+			const xdg = env.XDG_DATA_HOME;
+			if (typeof xdg === "string" && xdg.length > 0) return join(xdg, "FoundryVTT");
+			return join(home, ".local", "share", "FoundryVTT");
+		}
+		case "win32": {
+			const localAppData = env.LOCALAPPDATA;
+			if (typeof localAppData === "string" && localAppData.length > 0) return join(localAppData, "FoundryVTT");
+			return null;
+		}
+		default: return null;
+	}
+}
+/**
+* Heuristic: a path looks like a Foundry user-data root if it contains a
+* `Data/` subdirectory (canonical Foundry layout) OR if it already contains
+* `systems/` or `modules/` (the path is already the Data folder itself).
+*/
+function looksLikeFoundryDataDir(path) {
+	if (!existsSync(path)) return false;
+	return existsSync(join(path, "Data")) || existsSync(join(path, "systems")) || existsSync(join(path, "modules"));
+}
+const CONFIG_DIR = ".vttforge";
+const CONFIG_FILE = "config.json";
+/** Absolute path to the project-local config file (whether or not it exists). */
+function configPath(cwd) {
+	return join(resolve(cwd), CONFIG_DIR, CONFIG_FILE);
+}
+/** Load `<cwd>/.vttforge/config.json` if it exists and is valid JSON. */
+async function loadConfig(cwd) {
+	const path = configPath(cwd);
+	if (!existsSync(path)) return null;
+	try {
+		const raw = await readFile(path, "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** Persist `<cwd>/.vttforge/config.json`. Creates the `.vttforge/` dir as needed. */
+async function saveConfig(cwd, config) {
+	const path = configPath(cwd);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+/**
+* Heuristic: is `path` already Foundry's `Data/` folder (vs. its parent)?
+* We treat the path as Data when:
+*   - basename is "Data" (case-insensitive — macOS/Windows file systems
+*     are case-insensitive by default), OR
+*   - any of `systems/`, `modules/`, `worlds/` exists inside (proof that
+*     Foundry has previously written package folders here).
+*
+* Used by `foundryPackagesDir` so users can supply EITHER the user-data
+* root OR the `Data/` folder directly without us double-nesting `Data/Data`.
+*/
+function isFoundryDataFolder(path) {
+	if (basename(path).toLowerCase() === "data") return true;
+	return existsSync(join(path, "systems")) || existsSync(join(path, "modules")) || existsSync(join(path, "worlds"));
+}
+/**
+* Resolve the packages directory (`Data/systems/` or `Data/modules/`) under
+* the given Foundry user-data root. Accepts the path Foundry itself runs
+* with (the user-data folder, which contains `Data/`) OR the `Data/` folder
+* directly — both are common in muscle memory.
+*
+* The returned path is not guaranteed to exist yet; callers `mkdir -p` it
+* before creating the symlink.
+*/
+function foundryPackagesDir(dataRoot, type) {
+	const subFolder = type === "system" ? "systems" : "modules";
+	if (isFoundryDataFolder(dataRoot)) return join(dataRoot, subFolder);
+	return join(dataRoot, "Data", subFolder);
+}
+/**
+* Expand `~` / `~/` prefixes to the user's home directory. Shells do this
+* automatically; Node's `path.resolve` does NOT, so a user who types the
+* prompt's own example `~/Library/Application Support/FoundryVTT` would
+* end up with a symlink under `<cwd>/~/Library/...` if we skipped this.
+*/
+function expandTilde(p, home) {
+	if (p === "~") return home;
+	if (p.startsWith("~/") || p.startsWith("~\\")) return join(home, p.slice(2));
+	return p;
+}
+/**
+* Walk the precedence chain and return the chosen Foundry user-data path.
+* Saves the user's choice to the project config on first interactive run so
+* subsequent invocations skip the prompt.
+*/
+async function resolveFoundryDataDir(opts) {
+	const { cwd, override, prompt } = opts;
+	const env = opts.env ?? process.env;
+	const platform = opts.platform ?? process.platform;
+	const home = opts.home ?? homedir();
+	if (typeof override === "string" && override.length > 0) return resolve(expandTilde(override, home));
+	const envValue = env.FOUNDRY_DATA_DIR;
+	if (typeof envValue === "string" && envValue.length > 0) return resolve(expandTilde(envValue, home));
+	const config = await loadConfig(cwd);
+	if (config?.foundryDataDir && existsSync(config.foundryDataDir)) return config.foundryDataDir;
+	const detected = autoDetectFoundryDataDir(platform, env, home);
+	if (prompt) {
+		const choice = await prompt(detected);
+		if (!choice) throw new Error("No Foundry data directory selected — aborting.");
+		const chosen = resolve(expandTilde(choice, home));
+		await saveConfig(cwd, {
+			...config,
+			foundryDataDir: chosen
+		});
+		return chosen;
+	}
+	if (detected && existsSync(detected)) return detected;
+	throw new Error("Foundry data directory not configured. Set FOUNDRY_DATA_DIR, pass --data-dir, or run `vttforge dev` interactively to save the path to .vttforge/config.json.");
+}
+/**
+* Stand up the hot reload bridge: install the companion module, open the
+* socket, watch the build output.
+*
+* Every failure here returns null rather than throwing. A busy port or a
+* missing companion package should cost the developer hot reload, not the
+* dev loop — the build and the symlink are the load-bearing parts, and they
+* already succeeded by the time this runs.
+*/
+async function startHotReloadBridge(opts) {
+	const packageDir = resolveDevModuleDir(opts.cwd);
+	if (!packageDir) {
+		p.note("Could not find @vttforge/dev-module. Install it to reload saves in place:\n  pnpm add -D @vttforge/dev-module", "Hot reload unavailable");
+		return null;
+	}
+	let server;
+	try {
+		server = await startDevServer({ port: opts.port });
+	} catch {
+		p.note(`Port ${opts.port} is in use — another \`vttforge dev\` is probably running.\nPass --hmr-port to use a different one.`, "Hot reload unavailable");
+		return null;
+	}
+	const modulesDir = foundryPackagesDir(opts.dataRoot, "module");
+	try {
+		const install = await installDevModule(modulesDir, packageDir);
+		p.note([
+			`Companion module linked → ${install.target}`,
+			"Enable \"VTTForge Dev\" in the world, once.",
+			"",
+			"Foundry in a container cannot follow that link. Mount it instead:",
+			`  ${composeMountLine(packageDir)}`
+		].join("\n"), "Hot reload");
+	} catch (err) {
+		await server.close();
+		p.note(`Could not install the companion module: ${err instanceof Error ? err.message : String(err)}`, "Hot reload unavailable");
+		return null;
+	}
+	const watcher = watchDist({
+		distDir: opts.distDir,
+		packageId: opts.manifest.id,
+		packageType: opts.manifest.type,
+		onPayload: (frame) => server.broadcast(frame),
+		onError: (message) => p.note(message, "Watch error")
+	});
+	return { close: async () => {
+		watcher.close();
+		await server.close();
+	} };
+}
+/**
+* Compose a clack prompt that resolves to a Foundry user-data path or
+* `null` if the user cancels. Suitable for passing to
+* `resolveFoundryDataDir`.
+*/
+function createDataDirPrompt() {
+	return async (autoDetected) => {
+		p.note(autoDetected ? `Detected Foundry user-data directory:\n  ${autoDetected}` : "Could not auto-detect a Foundry user-data directory on this OS — please type the path.", "First-run setup");
+		if (autoDetected) {
+			const useDetected = await p.confirm({
+				message: "Use detected directory?",
+				initialValue: true
+			});
+			if (p.isCancel(useDetected)) return null;
+			if (useDetected === true) return autoDetected;
+		}
+		const custom = await p.text({
+			message: "Foundry user-data directory (the folder that contains Data/, e.g. ~/Library/Application Support/FoundryVTT)",
+			placeholder: autoDetected ?? "/path/to/FoundryVTT",
+			validate: (value) => {
+				if (!value || value.trim().length === 0) return "A path is required";
+			}
+		});
+		if (p.isCancel(custom)) return null;
+		return String(custom).trim();
+	};
+}
+/**
+* Install signal handlers that fire once. We use `process.once` so a second
+* Ctrl-C while cleanup is in flight propagates as a hard exit instead of
+* being swallowed (the user gave up on graceful shutdown — let them).
+*/
+function installSignalHandlers(cleanup) {
+	let invoked = false;
+	const handler = () => {
+		if (invoked) return;
+		invoked = true;
+		cleanup();
+	};
+	process.once("SIGINT", handler);
+	process.once("SIGTERM", handler);
+	return () => {
+		process.removeListener("SIGINT", handler);
+		process.removeListener("SIGTERM", handler);
+	};
+}
+async function runDev(options = {}) {
+	const cwd = options.cwd ? resolve(options.cwd) : process.cwd();
+	p.intro("🜲 vttforge dev — symlink + watch");
+	if (!existsSync(join(cwd, "package.json"))) {
+		p.cancel(`No package.json at ${cwd}. Run \`vttforge dev\` from inside a scaffolded project.`);
+		throw new Error("Missing package.json");
+	}
+	const buildSpinner = p.spinner();
+	buildSpinner.start("vite build (initial)");
+	try {
+		await runViteBuildOnce(cwd);
+		buildSpinner.stop("Initial build complete");
+	} catch (err) {
+		buildSpinner.stop("Initial build failed");
+		throw err;
+	}
+	const distDir = join(cwd, "dist");
+	const manifest = await readManifest(distDir);
+	const interactive = Boolean(process.stdout.isTTY);
+	const dataRoot = await resolveFoundryDataDir({
+		cwd,
+		override: options.dataDir,
+		prompt: interactive ? createDataDirPrompt() : void 0
+	});
+	const packagesDir = foundryPackagesDir(dataRoot, manifest.type);
+	const target = join(packagesDir, manifest.id);
+	const existingTarget = await readLinkTarget(target);
+	if (existingTarget && existingTarget !== distDir) p.note(`Replacing stale symlink:\n  ${target}\n  was: ${existingTarget}\n  now: ${distDir}`, "Symlink");
+	await createLink(target, distDir, { overwrite: true });
+	p.note(`Linked dist/ → ${target}\nFoundry serves the package under /${manifest.type}s/${manifest.id}/.`, "Symlinked");
+	const bridge = await startHotReloadBridge({
+		cwd,
+		distDir,
+		dataRoot,
+		manifest,
+		port: options.hmrPort ?? 31313
+	});
+	p.note(`${bridge ? "Saves apply in place — no page refresh." : "Hot reload is off; saves need a page refresh."}\nCtrl-C to stop.`, "Watching");
+	const watcher = spawnViteWatch(cwd);
+	await new Promise((resolveDev) => {
+		const cleanup = async () => {
+			try {
+				await cleanupDevSymlink({
+					target,
+					expectedSource: distDir
+				});
+			} catch {}
+			await bridge?.close();
+			if (!watcher.killed) watcher.kill("SIGINT");
+			uninstall();
+			resolveDev();
+		};
+		const uninstall = installSignalHandlers(cleanup);
+		watcher.on("exit", (code) => {
+			if (code !== 0 && code !== null) console.error(`\nvite watcher exited with code ${code}.`);
+		});
+	});
+	p.outro("Stopped. Symlink cleaned up.");
+}
+/**
+* Internal building block exposed for tests: given an already-built `dist/`
+* (vite has run, manifest is present) and a resolved Foundry data dir,
+* create the symlink and return the target path + manifest. Skips the
+* vite spawn and the signal-loop, so tests can drive the orchestration
+* deterministically.
+*/
+async function setupDevSymlink(opts) {
+	const cwd = resolve(opts.cwd);
+	const distDir = join(cwd, "dist");
+	const manifest = await readManifest(distDir);
+	const packagesDir = foundryPackagesDir(opts.dataRoot, manifest.type);
+	const target = join(packagesDir, manifest.id);
+	await createLink(target, distDir, { overwrite: true });
+	return {
+		target,
+		manifest
+	};
+}
+/**
+* Tear down a dev symlink iff it still points at the expected source.
+* Refuses to remove a symlink that another `vttforge dev` session (or a
+* manual `ln -s`) has since redirected — that link doesn't belong to us
+* and removing it would silently disconnect their setup.
+*/
+async function cleanupDevSymlink(opts) {
+	if (await readLinkTarget(opts.target) === opts.expectedSource) await removeLink(opts.target);
+}
+//#endregion
+//#region src/git.ts
+/**
+* Git helpers for the init scaffolder. Optional: every step degrades to a
+* warning, never throws. The scaffold completes even if git is missing or
+* the user has no global git config — the user can still `git init`
+* themselves later.
+*/
+const execFileAsync = promisify(execFile);
+/**
+* Read `git config user.name` to pre-fill the author prompt. Returns
+* `undefined` if git is missing or the value is unset.
+*/
+async function readGitAuthorName() {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"config",
+			"--get",
+			"user.name"
+		]);
+		const value = stdout.trim();
+		return value.length > 0 ? value : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Initialize a fresh git repository in `cwd`, run an initial commit. Errors
+* are swallowed and converted to a return value so the caller can decide
+* whether to warn or move on.
+*/
+async function initGitRepo(cwd) {
+	try {
+		await execFileAsync("git", ["init", "--initial-branch=main"], { cwd });
+		await execFileAsync("git", ["add", "."], { cwd });
+		await execFileAsync("git", [
+			"commit",
+			"-m",
+			"chore: initial scaffold from @vttforge/cli"
+		], { cwd });
+		return { ok: true };
+	} catch (err) {
+		return {
+			ok: false,
+			reason: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/scaffold.ts
+/**
+* Template copy with `{{var}}` placeholder substitution.
+*
+* Templates live under `packages/cli/templates/<variant>/` and are shipped
+* inside the published tarball (see the `files` array in package.json).
+* Each file is read, substituted, and written to the destination directory
+* preserving the relative path. Directories are created lazily on first
+* write.
+*
+* We intentionally avoid Handlebars or any other template engine — the
+* substitution surface is small (a flat string-to-string map), and bundling
+* a dependency for ten lines of regex would be wasteful in a tool whose
+* value is being fast to invoke.
+*/
+const PLACEHOLDER_RE = /\{\{(\w+)\}\}/g;
+/**
+* Replace `{{NAME}}` placeholders in `content` using the `vars` map.
+* Unknown placeholders are passed through unchanged so partially-templated
+* files (e.g. a snippet that contains `{{handlebarsLikeSyntax}}` as literal
+* content) still scaffold without surprises.
+*/
+function substitute(content, vars) {
+	const lookup = vars;
+	return content.replace(PLACEHOLDER_RE, (match, key) => Object.hasOwn(lookup, key) ? lookup[key] ?? match : match);
+}
+/**
+* Walk `dir` recursively and yield every file path relative to `dir`.
+*/
+async function* walkRelative(dir, base = dir) {
+	const entries = await readdir(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) yield* walkRelative(full, base);
+		else if (entry.isFile()) yield relative(base, full);
+	}
+}
+/**
+* Files that should be substituted as text. Binary assets (.png, .ico, …)
+* bypass substitution and are copied byte-for-byte. The list of binary
+* extensions is intentionally small — extend if we add real binary assets
+* to templates.
+*/
+const BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".ico",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf"
+]);
+function isBinaryPath(path) {
+	const dotIndex = path.lastIndexOf(".");
+	if (dotIndex < 0) return false;
+	return BINARY_EXTENSIONS.has(path.slice(dotIndex).toLowerCase());
+}
+/**
+* Files whose source name in the template is rewritten at scaffold time so
+* npm packaging doesn't strip or rename them. npm transforms `.gitignore`
+* into `.npmignore` on publish, so templates ship `_gitignore` and the
+* scaffolder writes `.gitignore` into the generated project.
+*/
+const SCAFFOLD_PATH_RENAMES = /* @__PURE__ */ new Map([["_gitignore", ".gitignore"]]);
+function rewriteDestRelPath(relPath) {
+	const base = relPath.split("/").pop() ?? relPath;
+	const replacement = SCAFFOLD_PATH_RENAMES.get(base);
+	if (replacement === void 0) return relPath;
+	return relPath.slice(0, relPath.length - base.length) + replacement;
+}
+async function scaffold({ templateDir, destDir, vars }) {
+	if (!existsSync(templateDir)) throw new Error(`[vttforge] template directory does not exist: ${templateDir}`);
+	if (!(await stat(templateDir)).isDirectory()) throw new Error(`[vttforge] template path is not a directory: ${templateDir}`);
+	await mkdir(destDir, { recursive: true });
+	for await (const relPath of walkRelative(templateDir)) {
+		const srcPath = join(templateDir, relPath);
+		const substituted = substitute(relPath, vars);
+		const destPath = join(destDir, rewriteDestRelPath(substituted));
+		await mkdir(dirname(destPath), { recursive: true });
+		if (isBinaryPath(srcPath)) {
+			const bytes = await readFile(srcPath);
+			await writeFile(destPath, bytes);
+			continue;
+		}
+		const content = await readFile(srcPath, "utf8");
+		await writeFile(destPath, substitute(content, vars), "utf8");
+	}
+}
+/**
+* Resolve the templates directory relative to this module's file URL. tsdown
+* emits `dist/scaffold.mjs`, so `import.meta.url` points there at runtime;
+* we walk up two segments to land at the package root, then descend into
+* `templates/`.
+*/
+function templatesRoot() {
+	const here = fileURLToPath(import.meta.url);
+	return resolve(here, "..", "..", "templates");
+}
+//#endregion
+//#region src/commands/init.ts
+/**
+* `vttforge init` — interactive scaffolder.
+*
+* Honors CLI flags first, prompts for everything missing, then copies the
+* matching template into the destination directory. Optionally `git init`s
+* and runs the detected package manager's install command at the end.
+*/
+const PACKAGE_ID_RE = /^[a-z][a-z0-9-]*$/;
+const UNSAFE_METADATA_CHARS_RE = /["\\\r\n\t]/;
+function validateMetadata(value) {
+	if (!value) return void 0;
+	if (UNSAFE_METADATA_CHARS_RE.test(value)) return "Avoid backslashes, double quotes, and line breaks — they break the generated manifest.";
+	if (value.includes("*/")) return "Avoid `*/` — it closes block comments in the generated source headers.";
+}
+function validateRequiredMetadata(value) {
+	if (!value || value.trim().length === 0) return "Required — Foundry rejects packages with a blank title.";
+	return validateMetadata(value);
+}
+function validatePackageId(value) {
+	if (!PACKAGE_ID_RE.test(value ?? "")) return "Package id must start with a letter and contain only lowercase letters, digits, dashes";
+}
+/**
+* Thrown when the scaffolder cannot continue — bad input, an existing
+* destination, a cancelled prompt, etc. `runInit` propagates these instead
+* of calling `process.exit`, so library consumers (tests, other CLIs) can
+* catch and recover. The `vttforge` bin wraps `runInit` in a top-level
+* handler that prints the message and exits with code 1.
+*/
+var ScaffoldError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ScaffoldError";
+	}
+};
+function isCancelled(value) {
+	return p.isCancel(value);
+}
+function bail(message) {
+	p.cancel(message);
+	throw new ScaffoldError(message);
+}
+function slugify(input) {
+	return input.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
+}
+function localePrefix(id) {
+	return id.toUpperCase().replace(/-/g, "_");
+}
+function titleCase(input) {
+	return input.split(/[-_\s]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+/**
+* Whether we may ask the user anything at all.
+*
+* Clack reads from stdin. With no terminal attached there is nothing to read,
+* and the prompt simply hangs — so a run that cannot ask has to be told every
+* answer up front, or be given `--yes` and take the defaults.
+*/
+function canPrompt(yes) {
+	return yes !== true && Boolean(process.stdin.isTTY);
+}
+function templateVariantFor(type, lang) {
+	return `${type}-${lang}`;
+}
+async function runInit(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const interactive = canPrompt(options.yes);
+	p.intro("🜲 vttforge init — scaffold a Foundry v13+ system or module");
+	let name = options.name?.trim();
+	if (!name && !interactive) bail("A directory name is required when running without prompts. Pass it as the first argument: `vttforge init my-module --yes`.");
+	if (!name) {
+		const answer = await p.text({
+			message: "Directory name (also the default manifest id)",
+			placeholder: "my-system",
+			validate: (value) => {
+				const trimmed = value?.trim() ?? "";
+				if (trimmed.length === 0) return "Name is required";
+				if (!PACKAGE_ID_RE.test(trimmed)) return "Use only lowercase letters, digits, and dashes (no spaces, slashes, dots).";
+			}
+		});
+		if (isCancelled(answer)) bail("Scaffold cancelled.");
+		name = String(answer).trim();
+	} else if (!PACKAGE_ID_RE.test(name)) bail(`Invalid name "${name}": use only lowercase letters, digits, and dashes (no spaces, slashes, dots).`);
+	const dest = resolve(cwd, name);
+	if (existsSync(dest)) bail(`Directory already exists: ${dest}`);
+	let type = options.type;
+	if (type !== "system" && type !== "module" && !interactive) type = "system";
+	if (type !== "system" && type !== "module") {
+		const answer = await p.select({
+			message: "What are you building?",
+			options: [{
+				value: "system",
+				label: "system — defines the game rules (Actor/Item types, sheets)"
+			}, {
+				value: "module",
+				label: "module — extends an existing system or adds cross-system features"
+			}],
+			initialValue: "system"
+		});
+		if (isCancelled(answer)) bail("Scaffold cancelled.");
+		type = answer;
+	}
+	let lang = options.lang;
+	if (lang !== "ts" && lang !== "js" && !interactive) lang = "ts";
+	if (lang !== "ts" && lang !== "js") {
+		const answer = await p.select({
+			message: "Language",
+			options: [{
+				value: "ts",
+				label: "TypeScript"
+			}, {
+				value: "js",
+				label: "JavaScript (.mjs)"
+			}],
+			initialValue: "ts"
+		});
+		if (isCancelled(answer)) bail("Scaffold cancelled.");
+		lang = answer;
+	}
+	/**
+	* Resolve one metadata field: an explicit flag wins, otherwise ask, and
+	* when asking is impossible take the default.
+	*/
+	const resolveField = async (provided, fallback, ask, validate) => {
+		if (provided !== void 0) {
+			const trimmed = provided.trim();
+			const failure = validate(trimmed);
+			if (failure !== void 0) bail(`${failure} (got ${JSON.stringify(provided)})`);
+			return trimmed;
+		}
+		if (!interactive) return fallback;
+		const answer = await ask();
+		if (isCancelled(answer)) bail("Scaffold cancelled.");
+		const value = String(answer).trim();
+		return value.length > 0 ? value : fallback;
+	};
+	const defaultId = slugify(name);
+	const id = await resolveField(options.id, defaultId, () => p.text({
+		message: "Package id (used as the folder Foundry serves under /<systems|modules>/<id>/)",
+		initialValue: defaultId,
+		validate: validatePackageId
+	}), validatePackageId);
+	const title = await resolveField(options.title, titleCase(id), () => p.text({
+		message: "Title (human-readable, shown in Foundry setup screens)",
+		initialValue: titleCase(id),
+		validate: validateRequiredMetadata
+	}), validateRequiredMetadata);
+	const defaultDescription = `A Foundry v13+ ${type} built with VTTForge`;
+	const description = await resolveField(options.description, defaultDescription, () => p.text({
+		message: "One-line description",
+		placeholder: defaultDescription,
+		initialValue: defaultDescription,
+		validate: validateMetadata
+	}), validateMetadata);
+	const rawDetectedAuthor = await readGitAuthorName();
+	const detectedAuthor = rawDetectedAuthor && validateMetadata(rawDetectedAuthor) === void 0 ? rawDetectedAuthor : void 0;
+	const author = await resolveField(options.author, detectedAuthor ?? "Anonymous", () => p.text({
+		message: "Author name (used in the manifest)",
+		placeholder: detectedAuthor ?? "Your Name",
+		initialValue: detectedAuthor ?? "",
+		validate: validateMetadata
+	}), validateMetadata);
+	const license = await resolveField(options.license, "MIT", () => p.select({
+		message: "License",
+		options: [
+			{
+				value: "MIT",
+				label: "MIT (recommended for Foundry community packages)"
+			},
+			{
+				value: "Apache-2.0",
+				label: "Apache-2.0"
+			},
+			{
+				value: "GPL-3.0-or-later",
+				label: "GPL-3.0-or-later"
+			},
+			{
+				value: "UNLICENSED",
+				label: "UNLICENSED (private use only)"
+			}
+		],
+		initialValue: "MIT"
+	}), validateRequiredMetadata);
+	const foundryMinVersion = "13";
+	const foundryVerifiedVersion = "13.341";
+	const templateVariant = templateVariantFor(type, lang);
+	const templateDir = resolve(templatesRoot(), templateVariant);
+	if (!existsSync(templateDir)) bail(`Template "${templateVariant}" not found at ${templateDir}`);
+	const vars = {
+		ID: id,
+		TITLE: title,
+		DESCRIPTION: description,
+		AUTHOR: author,
+		LICENSE: license,
+		FOUNDRY_MIN_VERSION: foundryMinVersion,
+		FOUNDRY_VERIFIED_VERSION: foundryVerifiedVersion,
+		LOCALE_PREFIX: localePrefix(id),
+		YEAR: String((/* @__PURE__ */ new Date()).getFullYear())
+	};
+	const scaffoldSpinner = p.spinner();
+	scaffoldSpinner.start(`Scaffolding ${templateVariant} into ${name}/`);
+	try {
+		await scaffold({
+			templateDir,
+			destDir: dest,
+			vars
+		});
+		scaffoldSpinner.stop(`Scaffold written to ${dest}`);
+	} catch (err) {
+		scaffoldSpinner.stop("Scaffold failed.");
+		throw err;
+	}
+	const pm = detectPackageManager();
+	let shouldInstall = !options.noInstall;
+	if (shouldInstall && interactive) {
+		const confirm = await p.confirm({
+			message: `Install dependencies now with ${pm}?`,
+			initialValue: true
+		});
+		if (isCancelled(confirm)) bail("Scaffold cancelled at install prompt (your scaffold is intact).");
+		shouldInstall = confirm === true;
+	}
+	if (shouldInstall) {
+		const installSpinner = p.spinner();
+		installSpinner.start(`Running ${installCommand(pm)}`);
+		try {
+			await runInstall(pm, dest);
+			installSpinner.stop(`Dependencies installed (${pm}).`);
+		} catch (err) {
+			installSpinner.stop(`Install failed: ${err instanceof Error ? err.message : String(err)}`);
+			p.note(`Run \`${installCommand(pm)}\` inside ${name}/ to retry.`, "Continuing without install.");
+		}
+	}
+	if (!options.noGit) {
+		const gitSpinner = p.spinner();
+		gitSpinner.start("Initializing git repository");
+		const gitResult = await initGitRepo(dest);
+		if (gitResult.ok) gitSpinner.stop("Git initialized (branch: main, initial commit landed).");
+		else gitSpinner.stop(`Skipped git init: ${gitResult.reason ?? "unknown error"}`);
+	}
+	const nextSteps = [
+		`cd ${name}`,
+		!shouldInstall ? installCommand(pm) : null,
+		`${pm} run build`,
+		"Symlink dist/ into your Foundry Data/<systems|modules>/<id>/ (or use the dev compose mount)"
+	].filter((line) => line !== null).map((line, idx) => `  ${idx + 1}. ${line}`).join("\n");
+	p.note(nextSteps, "Next steps");
+	p.outro("Have fun building.");
+}
+function runInstall(pm, cwd) {
+	return new Promise((resolveInstall, rejectInstall) => {
+		const child = spawn(pm, ["install"], {
+			cwd,
+			stdio: "inherit",
+			env: process.env
+		});
+		child.on("error", rejectInstall);
+		child.on("exit", (code) => {
+			if (code === 0) resolveInstall();
+			else rejectInstall(/* @__PURE__ */ new Error(`${pm} install exited with code ${code}`));
+		});
+	});
+}
+//#endregion
+//#region src/index.ts
+const VTTFORGE_CLI_VERSION = "0.1.0";
+//#endregion
+export { installCommand as A, ViteNotInstalledError as C, detectPackageManager as D, spawnViteWatch as E, SEVERITY_RANK as F, runSourceRules as I, runManifestRules as L, runAuditCommand as M, formatReport as N, detectProjectPackageManager as O, runAudit as P, emitZip as S, runViteBuildOnce as T, createLink as _, substitute as a, emitReleaseZip as b, runDev as c, configPath as d, foundryPackagesDir as f, saveConfig as g, resolveFoundryDataDir as h, scaffold as i, readManifest as j, execInvocation as k, setupDevSymlink as l, looksLikeFoundryDataDir as m, ScaffoldError as n, templatesRoot as o, loadConfig as p, runInit as r, cleanupDevSymlink as s, VTTFORGE_CLI_VERSION as t, autoDetectFoundryDataDir as u, readLinkTarget as v, resolveViteInvocation as w, runBuild as x, removeLink as y };
+
+//# sourceMappingURL=src-CWhUNM__.mjs.map