@ringozz/godot 4.7.2-661 → 4.7.2-676

package/src/bake.ts

@@ -0,0 +1,587 @@
+/**********************************************************************
+ Copyright (c) Vladimir Davidovich. All rights reserved.
+***********************************************************************/
+
+import { spawnSync } from 'node:child_process';
+import { createHash, type Hash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveEditor } from './editor.ts';
+import { packedExtensions, scannedExtensions } from './formats.ts';
+import {
+	BOOT_MANIFEST,
+	BOOT_MODULE,
+	BOOT_PCK,
+	FILES_DIR,
+	PACK_DIR,
+	PACK_DOC,
+	RELEASE,
+	descriptorOf,
+	entryId,
+	packEntries,
+	pckOf,
+	serializeDoc,
+	type Exports,
+	type PackDoc,
+	type Release,
+} from './pack.ts';
+
+// Bakes a Godot project's assets for the runtime. Two kinds of pack, both native `.pck`s (the
+// engine-converted binary resources + remap table) exported through the project's own committed
+// `export_presets.cfg`:
+//
+//  - **the boot pack**: the app's own sources (`src/`), exported with the preset, and always mounted
+//    by the runtime — a scene may load a path it assembles itself (a script named by a constant, a
+//    level chosen at run time), and only a mounted pack resolves those.
+//  - **content packs**: one per directory under `dlc/` that declares itself with a `package.json`.
+//    Each is exported on its own — the preset's `exclude_filter` is rewritten per pack, so a pack
+//    carries its own directory and nothing else — and carries the declared package fields plus the
+//    staging data the runtime needs, so it can be published and deployed apart from the app.
+//
+// A pack may reference the boot sources and the packs it declares as `dependencies`, never a sibling,
+// and the bake fails otherwise: the runtime mounts a pack by import, so a reference "upward" or
+// "sideways" is a reference that will not resolve.
+//
+// This is the bake half: everything that spawns the editor or touches the disk. What it writes is the
+// pack protocol's (`pack.ts`), which the plugin and the runtime read without any of this.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The dump's one build-time output, rewritten by every bake. */
+const DUMP = '.godot/pack-dump.json';
+
+/** The digest of every bake input, beside the packs: written by a bake that finished, read by the next. */
+const STAMP = '.stamp.json';
+
+/**
+ * Removes everything a bake derives — the import cache, the documents, the packs — and never a source.
+ * `godot clean` is the answer to the two states a bake cannot repair by itself: orphaned products left
+ * by sources that moved or were renamed, and a derived file whose import was never forced.
+ */
+export function cleanProject(cwd = process.cwd()): void {
+	rmSync(resolve(cwd, '.godot'), { recursive: true, force: true });
+	console.log('[pack] cleaned .godot');
+}
+
+/**
+ * Source the engine never imports or packs — the app's own code, sitting in the same tree as its
+ * assets. Editing it cannot change a pack, and it is the most common edit there is, so the digest
+ * skips it. The list is a deny-list on purpose: an unknown extension re-bakes (harmless) rather than
+ * going stale (a pack that silently lags its sources).
+ */
+const SOURCE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.md', '.yaml', '.yml', '.css']);
+
+export interface BuildAssetPackOptions {
+	/** The project root the bake reads and writes (default: `process.cwd()`). */
+	cwd?: string;
+	/** res:// roots whose assets the boot pack carries (default `['res://src']`). */
+	roots?: string[];
+	/** res:// root to discover content packs under (default `res://dlc`). */
+	dlc?: string;
+	/** Output directory for the packs + documents, project-relative (default {@link PACK_DIR}). */
+	out?: string;
+	/** The `export_presets.cfg` preset every pack exports with (default `Pack`). */
+	preset?: string;
+	/** Editor executable override (default: `resolveEditor()`). */
+	godot?: string;
+	/** Bake even when nothing the bake reads has changed since the last one (default: false). */
+	force?: boolean;
+}
+
+/** A content pack: a directory that declares itself with a `package.json`. */
+interface ContentPack {
+	/** The declared package name (`@tiv/packs/assets`), or the directory's own name. */
+	name: string;
+	/** Project-relative directory, no trailing slash (`dlc/assets`). */
+	dir: string;
+	/** Declared version, if any. */
+	version?: string;
+	/** Declared pack dependencies: package name → version range. */
+	dependencies: Record<string, string>;
+	/** The declared `exports` verbatim: how the pack names the entries a client may load. */
+	exports?: Exports;
+}
+
+/** A `spawnSync` runner for the editor — the bake's one injected dependency. */
+export type Run = (args: string[], env?: Record<string, string>) => void;
+
+/**
+ * Bakes the boot pack, then one pack per directory under `dlc/` that declares a `package.json`.
+ * Three editor runs per pack (import, dump, export); no project file is left changed.
+ *
+ * `run` is the seam: the editor by default, a stand-in in a test — so what a caller gets (the
+ * documents, the products beside them, the preset put back) can be asserted through this interface
+ * rather than through the helpers it is made of. Everything else is the filesystem, which `opts.cwd`
+ * can point at any root.
+ */
+export async function buildAssetPacks(opts: BuildAssetPackOptions = {}, run?: Run): Promise<void> {
+	const cwd = opts.cwd ?? process.cwd();
+	const bootRoots = opts.roots ?? ['res://src'];
+	const out = opts.out ?? PACK_DIR;
+	const preset = opts.preset ?? 'Pack';
+	const editor = opts.godot ?? (run ? null : await resolveEditor());
+	const exec = run ?? runner(editor!, cwd);
+	mkdirSync(resolve(cwd, out), { recursive: true });
+
+	const dlc = rel(opts.dlc ?? 'res://dlc');
+	const packs = discoverPacks(cwd, dlc);
+
+	const presets = resolve(cwd, 'export_presets.cfg');
+	const cfg = readFileSync(presets, 'utf8');
+
+	// Nothing the bake reads has changed since the last one that finished: an import scan, a dump and
+	// one export per pack are the whole cost of a dev server start, and none of it is worth repeating
+	// for a project nobody touched. The stamp is the digest of every input, not a timestamp of the
+	// outputs — a pack's `.pck` is rewritten on every export, so it can't answer this.
+	const stamp = resolve(cwd, out, STAMP);
+	const inputs = inputsOf({ cwd, dirs: [...bootRoots.map(rel), ...packs.map((pack) => pack.dir)], cfg, editor });
+	if (!opts.force && readStamp(stamp) === inputs) {
+		console.log(`[pack] up to date (${out})`);
+		return;
+	}
+
+	// The editor's import scan must not walk the installed dependency tree: a workspace-linked pack
+	// would be imported a second time through the link, at a depth its relative paths (a terrain
+	// `.webparray`'s layer refs) do not survive. `.gdignore` is the editor's own skip marker; the
+	// bundler never looks at it, and the sources are imported once at their real `res://` paths.
+	// A pack that declares another pack gets that link *inside itself* (`node_modules` beside its
+	// `package.json`), so each pack's tree needs the marker as well as the root one.
+	const installed = [resolve(cwd, 'node_modules'), ...packs.map((pack) => resolve(cwd, pack.dir, 'node_modules'))];
+	for (const dir of installed.filter((dir) => existsSync(dir))) writeFileSync(join(dir, '.gdignore'), '');
+	exec(['--headless', '--path', '.', '--import']);
+
+	assertScopes(bootRoots.map(rel), packs);
+	const dirOf = new Map(packs.map((pack) => [pack.name, pack.dir]));
+	const release = releaseOf(packs);
+	// Every scoped directory: the boot sources and the pack directories. A pack's export excludes all
+	// of them but its own, so no source can belong to two packs.
+	const bootDirs = bootRoots.map(rel);
+	const all = [...bootDirs, ...packs.map((pack) => pack.dir)];
+
+	// A plan's routes are relative to the converter's output root, which is where the packs live.
+	const ctx: Bake = { run: exec, cwd, cfg, preset, base: excludeFilter(cfg), all, planBase: resPath(dlc) };
+	try {
+		// **One dump for the whole project**, sliced per scope below (a loose file is staged by the pack
+		// that *owns* it, whoever needs it). One dump is also one editor run instead of one per pack.
+		const dump = runDump(ctx, [...bootRoots, ...packs.map((pack) => resPath(pack.dir))]);
+
+		if (bootDirs.length) {
+			const boot = manifestOf(dump, cwd, out, bootDirs);
+			assertRefs('the boot pack', boot.external, bootRoots);
+			exportPack(ctx, bootDirs, `${out}/${BOOT_PCK}`);
+			writeFileSync(resolve(cwd, out, BOOT_MANIFEST), serializeDoc({ needs: boot.needs, stage: boot.stage }));
+			writeFileSync(resolve(cwd, out, BOOT_MODULE), bootModule(boot));
+			console.log(`[pack] ${BOOT_PCK} over ${Object.keys(boot.needs).length} sources`);
+		}
+
+		for (const pack of packs) {
+			const version = release[pack.name].version;
+			// One directory per pack, holding exactly what its npm package holds: the `.pck`, its
+			// document, the loose products, the types and a manifest. So a bake's output and an installed
+			// pack have the same layout, and a host serves either with one static root. The version is
+			// the release's (`release.json`), not a directory's — a bake builds one per pack.
+			const dir = `${out}/${pack.name}`;
+			mkdirSync(resolve(cwd, dir), { recursive: true });
+			const own = manifestOf(dump, cwd, dir, [pack.dir]);
+			const entries = packEntries(pack.exports);
+			const allowed = [...bootRoots, ...Object.keys(pack.dependencies).map((dep) => resPath(dirOf.get(dep) ?? dep))];
+			assertRefs(pack.name, own.external, allowed);
+			exportPack(ctx, [pack.dir], `${dir}/${pckOf(pack.name)}`);
+			writeFileSync(
+				resolve(cwd, dir, PACK_DOC),
+				serializeDoc({
+					// The pack's own declaration (`name`/`version`/`dependencies`/`exports`) plus what the
+					// bake computed: the same document shape the boot pack's is, so a client reads one. The
+					// `.pck` is `<name>.pck` beside it, by convention — mounting never waits on this document.
+					name: pack.name,
+					version,
+					dependencies: pack.dependencies,
+					exports: withoutTypes(pack.exports),
+					needs: own.needs,
+					stage: own.stage,
+				}),
+			);
+			// The pack's types, beside its own `package.json` (whose `types` names them) and in its
+			// output directory: a client installs the pack by name, so the types have to travel with it.
+			const types = entries.length ? packTypes(pack.exports) : null;
+			if (types) {
+				writeFileSync(resolve(cwd, pack.dir, 'package.d.ts'), types);
+				writeFileSync(resolve(cwd, dir, 'package.d.ts'), types);
+			} else {
+				rmSync(resolve(cwd, pack.dir, 'package.d.ts'), { force: true });
+			}
+			// The output directory *is* the deployable artifact: `npm publish` of it ships the `.pck`,
+			// its document, the loose products and the types, and its declared dependencies — so a
+			// level pulls its shared pack in on install, and nothing is assembled later.
+			writeFileSync(
+				resolve(cwd, dir, 'package.json'),
+				`${JSON.stringify(
+					{
+						name: pack.name,
+						version,
+						dependencies: Object.keys(pack.dependencies).length ? pack.dependencies : undefined,
+						types: types ? './package.d.ts' : undefined,
+						files: [PACK_DOC, pckOf(pack.name), `${FILES_DIR}/**`, ...(types ? ['package.d.ts'] : [])],
+					},
+					null,
+					'\t',
+				)}\n`,
+			);
+			console.log(`[pack] ${pack.name}@${version} over ${Object.keys(own.needs).length} sources`);
+		}
+		if (packs.length) {
+			writeFileSync(resolve(cwd, out, RELEASE), serializeDoc(release));
+		} else {
+			// Nothing to release: a release document left by a previous bake would name packs this
+			// project no longer builds.
+			rmSync(resolve(cwd, out, RELEASE), { force: true });
+		}
+		// Only a bake that got this far can say the project is up to date next time.
+		writeFileSync(stamp, `${inputs}\n`);
+	} finally {
+		// The preset is scoped per pack, so it is rewritten per export and put back once.
+		writeFileSync(presets, cfg);
+	}
+}
+
+/** The bake's shared context: the runner, the project, the preset, and every scoped directory. */
+interface Bake {
+	run: Run;
+	cwd: string;
+	cfg: string;
+	preset: string;
+	base: string[];
+	all: string[];
+	/** The converter's output root, which a plan's routes are relative to. */
+	planBase: string;
+}
+
+/** Scopes the preset to `mine` and exports that scope to `pck`. */
+function exportPack(ctx: Bake, mine: string[], pck: string): void {
+	writeFileSync(resolve(ctx.cwd, 'export_presets.cfg'), withExcludes(ctx.cfg, ctx.preset, excludesFor(ctx.base, ctx.all, mine)));
+	ctx.run(['--headless', '--path', '.', '--export-pack', ctx.preset, pck]);
+}
+
+/**
+ * One scope's half of the dump, as a document's `needs`/`stage` (and the refs the bake checks). A pack's
+ * export carries its own directory and nothing else, so `needs` — what each source under `dirs` needs
+ * staged — is that scope's slice, while `stage` — the descriptor of each loose file it *owns* — is
+ * judged over the **whole project**: a level's sky lives in the shared pack and is named by nothing but
+ * the level's plan, and the owner stages it all the same. `needs` stays paths (whoever owns them),
+ * which is what lets a pack borrow another's texture without carrying its bytes. `external` is what the
+ * scope's sources leak, for the ref check.
+ */
+function manifestOf(
+	dump: Record<string, Dumped>,
+	cwd: string,
+	dir: string,
+	dirs: string[],
+): Pick<PackDoc, 'needs' | 'stage'> & { external: string[] } {
+	const roots = dirs.map((d) => resPath(d));
+	const needs: Record<string, string[]> = {};
+	const external: string[] = [];
+	for (const [source, d] of Object.entries(dump)) {
+		if (!roots.some((root) => source.startsWith(`${root}/`))) continue;
+		if (d.loose.length) needs[source] = d.loose;
+		external.push(...d.external);
+	}
+	const stage: Record<string, { path: string; import: string }> = {};
+	for (const loose of new Set(Object.values(dump).flatMap((d) => d.loose))) {
+		// Only this scope's own: a borrowed loose file is staged from the pack that owns it, so carrying
+		// a copy would make every level ship the shared textures — exactly what deploying a level on its
+		// own must not do.
+		if (!roots.some((root) => loose.startsWith(`${root}/`))) continue;
+		const abs = resolve(cwd, rel(loose));
+		if (!existsSync(`${abs}.import`)) continue;
+		const descriptor = descriptorOf(readFileSync(`${abs}.import`, 'utf8'));
+		if (!descriptor || !existsSync(resolve(cwd, rel(descriptor.path)))) continue;
+		mkdirSync(resolve(cwd, dir, FILES_DIR), { recursive: true });
+		copyFileSync(resolve(cwd, rel(descriptor.path)), resolve(cwd, dir, FILES_DIR, descriptor.path.split('/').pop()!));
+		stage[loose] = descriptor;
+	}
+	return { needs, stage, external: [...new Set(external)].sort() };
+}
+
+/** A `spawnSync` runner that throws on a non-zero editor exit. */
+function runner(editor: string, cwd: string): Run {
+	return (args, env) => {
+		const r = spawnSync(editor, args, { cwd, stdio: 'inherit', env: { ...process.env, ...env } });
+		if ((r.status ?? 1) !== 0) {
+			throw new Error(`godot-assets: \`${editor} ${args.join(' ')}\` failed (${r.status})`);
+		}
+	};
+}
+
+/** One bucket of the dump: the loose textures a source needs, and the refs that left the scan roots. */
+interface Dumped {
+	loose: string[];
+	external: string[];
+}
+
+/** Runs `dump-deps.gd` over `scope` (res:// roots): per source, its loose textures and its leaks. */
+function runDump(ctx: Bake, scope: string[]): Record<string, Dumped> {
+	copyFileSync(resolve(HERE, 'dump-deps.gd'), resolve(ctx.cwd, '.godot', 'pack-dump-deps.gd'));
+	ctx.run(['--headless', '--path', '.', '--script', 'res://.godot/pack-dump-deps.gd'], {
+		GODOT_DUMP_OUT: resPath(DUMP),
+		GODOT_DUMP_ROOTS: scope.join(','),
+		GODOT_DUMP_PLAN_BASE: ctx.planBase,
+		// The dump holds no extension lists of its own: they come from the format table, so a source
+		// cannot be walked by the dump and staged by the plugin for want of one entry.
+		GODOT_DUMP_PACKED: packedExtensions.join(','),
+		GODOT_DUMP_SCANNED: scannedExtensions.join(','),
+	});
+	const abs = resolve(ctx.cwd, DUMP);
+	if (!existsSync(abs)) throw new Error(`godot-assets: the dump wrote no ${DUMP} (see dump-deps.gd).`);
+	return JSON.parse(readFileSync(abs, 'utf8')) as Record<string, Dumped>;
+}
+
+const resPath = (rel: string) => `res://${rel.replace(/^res:\/\//, '')}`;
+const rel = (res: string) => res.replace(/^res:\/\//, '').replace(/\/+$/, '');
+
+/** Fails the bake on a reference that leaves the pack (a sibling, or a source no pack owns). */
+function assertRefs(what: string, external: string[], allowed: string[]): void {
+	const illegal = external.filter((ref) => !allowed.some((dir) => ref.startsWith(`${dir}/`)));
+	if (illegal.length) {
+		throw new Error(
+			`godot-assets: ${what} references ${illegal.length} source(s) outside itself and ${allowed.join(', ')} — a pack's refs point at the boot sources or a declared dependency:\n  ${illegal.slice(0, 10).join('\n  ')}`,
+		);
+	}
+}
+
+/**
+ * Finds the content packs under `rootAbs` (searching the subdirectory `under`, so the returned `dir`s
+ * are `rootAbs`-relative): every directory holding a `package.json`, identified by that file's `name`.
+ * Packs do not nest — a pack inside a pack could not be scoped to one export — and a directory holding
+ * one is a container, so stray files beside it belong to no pack.
+ */
+function discoverPacks(rootAbs: string, under = ''): ContentPack[] {
+	const dirs: string[] = [];
+	walk(rootAbs, under, dirs);
+	const packs: ContentPack[] = [];
+	for (const dir of dirs.sort()) {
+		const parent = packs.find((pack) => dir.startsWith(`${pack.dir}/`));
+		if (parent) throw new Error(`godot-assets: ${dir}/ is inside the pack ${parent.dir} — packs do not nest.`);
+		if (!dir) throw new Error('godot-assets: the discovery root itself declares a package.json.');
+		const pkg = JSON.parse(readFileSync(join(rootAbs, dir, 'package.json'), 'utf8')) as {
+			name?: string;
+			version?: string;
+			dependencies?: Record<string, string>;
+			exports?: Exports;
+		};
+		packs.push({
+			name: pkg.name ?? dir.split('/').pop()!,
+			dir,
+			...(pkg.version ? { version: pkg.version } : {}),
+			dependencies: pkg.dependencies ?? {},
+			// Passed through verbatim: the declaration is what a client resolves an entry against, so
+			// the bake copies it rather than restating it (a client reads it through the entry's
+			// `godot` condition).
+			exports: pkg.exports,
+		});
+	}
+	return packs;
+}
+
+/** Collects every directory (relative, `/`-separated) under `rootAbs` that holds a `package.json`. */
+function walk(rootAbs: string, dir: string, out: string[]): void {
+	const abs = dir ? join(rootAbs, dir) : rootAbs;
+	let names: string[];
+	try {
+		names = readdirSync(abs);
+	} catch {
+		return;
+	}
+	if (names.includes('package.json')) out.push(dir);
+	for (const name of names) {
+		if (name.startsWith('.') || name === 'node_modules') continue;
+		if (statSync(join(abs, name)).isDirectory()) walk(rootAbs, dir ? `${dir}/${name}` : name, out);
+	}
+}
+
+/**
+ * The release a local bake serves, in the shape `parseRelease` reads: pack name → the version it just
+ * wrote and the dependencies it declared. A deploy publishes the same graph (resolved by `bun install`
+ * into a lockfile) under one immutable name, which is the only thing that identifies a content release.
+ */
+function releaseOf(packs: ContentPack[]): Release {
+	return Object.fromEntries(
+		packs.map((pack) => [pack.name, { version: pack.version ?? '0.0.0', deps: Object.keys(pack.dependencies) }]),
+	);
+}
+
+/**
+ * The boot pack as a module the app's bundle imports (beside the packs it describes): its `.pck`
+ * mounted once, however many modules import this, and the same `needs`/`stage` — with each loose
+ * product it owns imported as a file, so its URL is the bundle's. A content pack may need one, and the
+ * boot is mounted like any other pack, so its files belong in a client's staging lookup. Only the app
+ * can name those URLs, which is why the bake renders them here.
+ */
+function bootModule({ needs, stage }: Pick<PackDoc, 'needs' | 'stage'>): string {
+	const imports: string[] = [];
+	const files: string[] = [];
+	for (const descriptor of Object.values(stage)) {
+		const name = descriptor.path.split('/').pop()!;
+		imports.push(`import file${files.length} from ${JSON.stringify(`./${FILES_DIR}/${name}`)} with { type: 'file' };`);
+		files.push(`\t${JSON.stringify(name)}: file${files.length},`);
+	}
+	return (
+		[
+			"// Generated by `godot pack`: the app's own pack, as a module (see @ringozz/godot/preload).",
+			`import bootPck from ${JSON.stringify(`./${BOOT_PCK}`)} with { type: 'file' };`,
+			`import { configurePacks, loadAssetPack } from '@ringozz/godot/load';`,
+			...imports,
+			files.length ? `const bootFiles = {\n${files.join('\n')}\n};` : 'const bootFiles = {};',
+			`configurePacks({ boot: { pck: bootPck, doc: ${JSON.stringify({ needs, stage })}, url: (file) => bootFiles[file] } });`,
+			`export const mounting = loadAssetPack(bootPck);`,
+		].join('\n') + '\n'
+	);
+}
+
+/**
+ * A pack's type surface, emitted beside the declaration that names it (`types` in its own
+ * `package.json`): one typed export per declared entry, so importing the module the plugin serves is
+ * type-checked with no generated module — `packEntries` resolves each entry, exactly as the served
+ * module's is. The bake's, not the protocol's: it writes it.
+ */
+export function packTypes(exports: Exports): string {
+	const entries = packEntries(exports);
+	const classes = [...new Set(entries.map((e) => e.cls))];
+	return [
+		"// Generated by `godot pack` from the pack's `exports` — do not edit.",
+		...classes.map((cls) => `import type { ${cls} } from '@ringozz/godot/${cls}';`),
+		'',
+		...entries.map((e) => `export declare const ${entryId(e.entry)}: Promise<${e.cls}>;`),
+		'',
+	].join('\n');
+}
+
+/**
+ * A pack's declared `exports` minus its `types` condition. The document is emitted beside the `.pck`,
+ * while the declarations a pack's `types` names stay in its source directory (the bake writes them
+ * there), so the path would not resolve from the document and nothing reads it — `packEntries` reads
+ * the `godot` condition. A subpath left with no conditions goes with it: the document says what a
+ * client may resolve.
+ */
+function withoutTypes(exports: Exports): Exports {
+	if (!exports) return exports;
+	const declared: Record<string, string | { [condition: string]: string | undefined }> = {};
+	for (const [subpath, value] of Object.entries(exports)) {
+		if (typeof value !== 'object') {
+			declared[subpath] = value;
+			continue;
+		}
+		const conditions = Object.fromEntries(Object.entries(value).filter(([condition]) => condition !== 'types'));
+		if (Object.keys(conditions).length) declared[subpath] = conditions;
+	}
+	return declared;
+}
+
+/**
+ * The bake's scopes must not overlap. Each pack's export excludes every *other* scoped directory, so a
+ * boot root that contains a pack would exclude that pack's own files from its own export — an empty
+ * pack, which shows up much later as a scene whose assets are missing. The mistake is easy to make
+ * (`--roots res://src,res://dlc` when the packs live under `dlc/`), so the bake says so instead.
+ */
+function assertScopes(bootDirs: string[], packs: ContentPack[]): void {
+	for (const pack of packs) {
+		const root = bootDirs.find((dir) => pack.dir.startsWith(`${dir}/`));
+		if (root) {
+			throw new Error(
+				`godot-assets: the boot root ${root} contains the content pack ${pack.dir} — the boot pack would carry it and the pack's own export would exclude it. Point --roots at sources only: a pack's directory is its own export.`,
+			);
+		}
+	}
+}
+
+/**
+ * A pack's `exclude_filter`: the preset's own entries plus a glob per scoped directory that is not
+ * `mine` — so the export carries this pack and nothing else.
+ */
+function excludesFor(base: string[], all: string[], mine: string[]): string[] {
+	return [...base, ...all.filter((dir) => !mine.includes(dir)).map((dir) => `${dir}/*`)];
+}
+
+/** A preset block's `exclude_filter` entries. */
+function excludeFilter(cfg: string): string[] {
+	const line = /^exclude_filter="([^"]*)"/m.exec(cfg);
+	return (line?.[1] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+/** The config with the preset named `preset`'s `exclude_filter` replaced by `exclude`. */
+function withExcludes(cfg: string, preset: string, exclude: string[]): string {
+	const at = new RegExp(`^name=${JSON.stringify(preset)}$`, 'm').exec(cfg)?.index ?? -1;
+	if (at < 0) {
+		throw new Error(`godot-assets: no "${preset}" preset in export_presets.cfg (see export_presets.example.cfg).`);
+	}
+	const line = /^exclude_filter="[^"]*"$/m.exec(cfg.slice(at));
+	if (!line) throw new Error(`godot-assets: the "${preset}" preset has no exclude_filter.`);
+	const start = at + line.index;
+	return `${cfg.slice(0, start)}exclude_filter=${JSON.stringify(exclude.join(','))}${cfg.slice(start + line[0].length)}`;
+}
+
+/**
+ * Everything a bake reads, as one digest: each resource tree's files (`path/size/mtime` — content is the
+ * editor's to read, and a checkout that only moves timestamps re-bakes, which is the safe direction),
+ * the preset, the dump script, the tool, and the editor it runs.
+ */
+function inputsOf({ cwd, dirs, cfg, editor }: {
+	cwd: string;
+	dirs: string[];
+	cfg: string;
+	editor: string | null;
+}): string {
+	const hash = createHash('sha1')
+		.update(cfg)
+		.update(readFileSync(join(HERE, 'dump-deps.gd')))
+		.update(readFileSync(join(HERE, '..', 'package.json')));
+	// The executable itself, not its `--version`: asking would spawn it, which is the cost the stamp
+	// exists to avoid.
+	hash.update(editor ? `${statSync(editor).size}:${statSync(editor).mtimeMs}` : 'injected');
+	for (const dir of dirs) digestTree(resolve(cwd, dir), '', hash);
+	return hash.digest('hex');
+}
+
+/** Feeds a tree's files into `hash`: the bake's own outputs and the app's own sources are not inputs. */
+function digestTree(abs: string, rel: string, hash: Hash): void {
+	let names: string[];
+	try {
+		names = readdirSync(abs);
+	} catch {
+		return;
+	}
+	for (const name of names.sort()) {
+		// The bake's own output beside a pack's manifest, the app's own sources, and dependencies are
+		// not inputs: editing them cannot change a pack.
+		if (name === 'node_modules' || name.startsWith('.') || name === 'package.d.ts' || SOURCE.has(extname(name))) continue;
+		const child = join(abs, name);
+		const stat = statSync(child);
+		if (stat.isDirectory()) digestTree(child, `${rel}/${name}`, hash);
+		else hash.update(`${rel}/${name}:${stat.size}:${stat.mtimeMs}\n`);
+	}
+}
+
+/** The stamp a bake left, or `null` — a stamp this can't read is a project that gets baked. */
+function readStamp(file: string): string | null {
+	try {
+		return readFileSync(file, 'utf8').trim();
+	} catch {
+		return null;
+	}
+}
+
+/** Parses `godot pack` CLI args into {@link BuildAssetPackOptions}. */
+export function parsePackArgs(args: string[]): BuildAssetPackOptions {
+	const opt = (flag: string): string | undefined => {
+		const i = args.indexOf(flag);
+		return i >= 0 ? args[i + 1] : undefined;
+	};
+	return {
+		roots: args.includes('--no-boot') ? [] : opt('--roots')?.split(',').filter(Boolean),
+		dlc: opt('--dlc'),
+		out: opt('--out'),
+		preset: opt('--preset'),
+		godot: opt('--godot'),
+		force: args.includes('--force'),
+	};
+}