bitboss-ui 3.0.0-beta.47 → 3.0.0-beta.49

package/scripts/lib/helpers-add.mjs

@@ -0,0 +1,1303 @@
+/**
+ * `bitboss-ui add <id…>` and `bitboss-ui helpers [list|diff|update]` (Q43.11):
+ * copy the Inertia helper folder into an app as files the app owns, and keep
+ * them current without ever destroying the app's own code.
+ *
+ * The rules (plans/reviews/q43-11-copy-in-2026-09-30/PLAN.md as amended by its
+ * owner rulings, and Q4-CANONICAL-HASH.md):
+ * - Only bytes bitboss-ui published may be replaced: a file is replaceable
+ *   when its bytes, or its canonical code, match the package's published list.
+ *   The lock never authorises a write.
+ * - A file the app edited is kept. It blocks only when bitboss-ui changed it
+ *   too (`conflict`) or when it was never installed by us (`foreign`).
+ * - `add` only creates and adopts; a stale file sends the user to
+ *   `helpers update`. Nothing is ever deleted, and there is no `--force`.
+ * - It never spawns a process, never loads the app's code or config, never
+ *   writes outside the helper folder except `bitboss-ui.lock.json`, and
+ *   refuses to run as a bitboss-ui other than the one the app installed.
+ *
+ * Exit codes: 0 done / nothing to do; 1 usage error, or `helpers diff` found
+ * a difference to act on; 2 refused (`add` wrote nothing; `update` wrote only
+ * the other groups); 3 a precondition failed, nothing written; 4 a write failed
+ * and was rolled back.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import {
+	chmodSync,
+	closeSync,
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	renameSync,
+	rmdirSync,
+	unlinkSync,
+	writeSync,
+} from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import {
+	canonDialect,
+	canonicalHash,
+	CANON_VERSION,
+	commentList,
+	lfHash,
+} from './helper-canon.mjs';
+import { detectPackageManager } from './mcp-config.mjs';
+
+export const LOCK_FILE = 'bitboss-ui.lock.json';
+const LOCK_VERSION = 1;
+const LOCK_MAX_BYTES = 1024 * 1024;
+const HELPERS_DIST = 'dist/ai/helpers/inertia';
+const FILE_NAME = /^[A-Za-z][A-Za-z0-9]*\.ts$/;
+const HELPER_ID = /^use[A-Za-z0-9]+$/;
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const DEVICE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const CLI = 'npx bitboss-ui';
+
+/** A refusal or failure with its exit code; `message` is complete for a human. */
+export class HelperError extends Error {
+	constructor(code, message, next = null) {
+		super(message);
+		this.code = code;
+		this.next = next;
+	}
+}
+
+const fail = (code, message, next) => {
+	throw new HelperError(code, message, next);
+};
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+
+// ---- context -------------------------------------------------------------
+
+/** Read the app's package.json, the installed manifest and the lock; refuse every precondition. */
+export function loadContext({ cwd, packageRoot, command }) {
+	let root;
+	try {
+		root = realpathSync(cwd);
+	} catch {
+		fail(3, `cannot read the current directory ${cwd}`);
+	}
+	const pkgPath = join(root, 'package.json');
+	if (!existsSync(pkgPath))
+		fail(
+			3,
+			'no package.json here. Run it from the app root (the folder with package.json).'
+		);
+	let app;
+	try {
+		app = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+	} catch (error) {
+		fail(3, `package.json does not parse: ${error.message}`);
+	}
+	const declared = new Set(
+		[
+			'dependencies',
+			'devDependencies',
+			'peerDependencies',
+			'optionalDependencies',
+		].flatMap((key) => Object.keys(app?.[key] ?? {}))
+	);
+	const pm = detectPackageManager(root);
+	const localCommand = {
+		npm: 'npm exec -- bitboss-ui',
+		pnpm: 'pnpm exec bitboss-ui',
+		yarn: 'yarn bitboss-ui',
+		bun: 'bunx --no-install bitboss-ui',
+	}[pm];
+	if (!declared.has('bitboss-ui'))
+		fail(
+			3,
+			"this package.json does not declare bitboss-ui. Run it in the app that depends on bitboss-ui (in a monorepo: that package's folder, not the root)."
+		);
+
+	// Version guard: this CLI must BE the app's installed bitboss-ui. A bare
+	// `npx` elsewhere runs whatever npm resolves (v2 is still `latest`).
+	const self = realpathSync(packageRoot);
+	const installed = findInstalled(root);
+	const ownVersion = readVersion(self);
+	if (!installed || realpathSync(installed) !== self)
+		fail(
+			3,
+			installed
+				? `this is bitboss-ui ${ownVersion} running from ${self}, but the app uses ${readVersion(realpathSync(installed))} at ${realpathSync(installed)}. Run the app's own copy: \`${localCommand} ${command}\`.`
+				: `the app has no node_modules/bitboss-ui (install its dependencies first), and this is bitboss-ui ${ownVersion} from ${self}. Then run \`${localCommand} ${command}\`.`
+		);
+	if (!declared.has('@inertiajs/vue3'))
+		fail(
+			3,
+			'this app does not declare @inertiajs/vue3. The helpers are for Inertia (Vue 3) apps.'
+		);
+	if (!existsSync(join(root, 'tsconfig.json')))
+		fail(
+			3,
+			'no tsconfig.json here. The helpers are TypeScript files; JavaScript apps are not supported.'
+		);
+
+	const manifest = loadManifest(self);
+	const lock = readLock(root);
+	return {
+		root,
+		self,
+		version: ownVersion,
+		manifest,
+		lock,
+		declared,
+		pm,
+		localCommand,
+	};
+}
+
+/** The first `node_modules/bitboss-ui` walking up from `root` (directory walk-up, like Node's resolution). */
+function findInstalled(root) {
+	let dir = root;
+	for (;;) {
+		const candidate = join(dir, 'node_modules', 'bitboss-ui');
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+function readVersion(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8')).version;
+	} catch {
+		return 'unknown';
+	}
+}
+
+/** The shipped manifest, with every file's bytes read and checked against its hash. */
+export function loadManifest(self) {
+	const base = join(self, HELPERS_DIST);
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(base, 'manifest.json'), 'utf-8'));
+	} catch {
+		fail(
+			3,
+			`this bitboss-ui ships no helper manifest (${HELPERS_DIST}/manifest.json). Upgrade bitboss-ui.`
+		);
+	}
+	const realBase = realpathSync(base);
+	const bytes = new Map();
+	for (const name of Object.keys(manifest.files ?? {})) {
+		if (!FILE_NAME.test(name))
+			fail(
+				3,
+				`the package manifest names an invalid file "${name}" (packaging bug).`
+			);
+		const path = join(base, name);
+		let text;
+		try {
+			if (!realpathSync(path).startsWith(realBase + sep))
+				fail(
+					3,
+					`${HELPERS_DIST}/${name} resolves outside the package (packaging bug).`
+				);
+			text = readFileSync(path, 'utf-8');
+		} catch (error) {
+			if (error instanceof HelperError) throw error;
+			fail(
+				3,
+				`${HELPERS_DIST}/${name} is missing from the package (packaging bug or a partial install).`
+			);
+		}
+		if (sha256(text) !== manifest.files[name].sha256)
+			fail(
+				3,
+				`${HELPERS_DIST}/${name} does not match its manifest hash (packaging bug or a partial install). Reinstall bitboss-ui.`
+			);
+		bytes.set(name, text);
+	}
+	return { ...manifest, bytes };
+}
+
+/** The parsed lock, or null when there is none. Never "treated as empty" when broken. */
+export function readLock(root) {
+	const path = join(root, LOCK_FILE);
+	let stats;
+	try {
+		stats = lstatSync(path);
+	} catch {
+		return null;
+	}
+	if (!stats.isFile())
+		fail(3, `${LOCK_FILE} is not a regular file (a link or a folder).`);
+	if (stats.size > LOCK_MAX_BYTES) fail(3, `${LOCK_FILE} is over 1 MB.`);
+	const text = readFileSync(path, 'utf-8');
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch (error) {
+		fail(
+			3,
+			`${LOCK_FILE} does not parse (${error.message}). Fix it, or delete the broken lines: files that still match a bitboss-ui version are re-adopted on the next run, edited ones are reported, nothing is lost.`
+		);
+	}
+	if (!data || typeof data !== 'object' || Array.isArray(data))
+		fail(3, `${LOCK_FILE} is not a JSON object.`);
+	if (typeof data.lockVersion === 'number' && data.lockVersion > LOCK_VERSION)
+		fail(
+			3,
+			`${LOCK_FILE} is lockVersion ${data.lockVersion}, newer than this bitboss-ui reads. Upgrade bitboss-ui.`
+		);
+	const helpers = Object.hasOwn(data, 'helpers') ? data.helpers : null;
+	const files = {};
+	if (helpers?.files && typeof helpers.files === 'object')
+		for (const [name, entry] of Object.entries(helpers.files))
+			if (FILE_NAME.test(name) && typeof entry?.sha256 === 'string')
+				files[name] = {
+					sha256: entry.sha256,
+					version: String(entry.version ?? ''),
+				};
+	return {
+		text,
+		data,
+		dir: typeof helpers?.dir === 'string' ? helpers.dir : null,
+		ids: Array.isArray(helpers?.ids)
+			? helpers.ids.filter((id) => typeof id === 'string' && HELPER_ID.test(id))
+			: [],
+		files,
+	};
+}
+
+// ---- the destination folder ----------------------------------------------
+
+/** One validator for `--dir` and the lock's `dir`, every run. */
+export function validateDir(value, { fromArgv }) {
+	if (typeof value !== 'string' || !value)
+		fail(3, 'the helper folder is empty.');
+	let dir = value;
+	if (fromArgv && process.platform === 'win32') dir = dir.replaceAll('\\', '/');
+	dir = dir.replace(/\/+$/, '');
+	const where = fromArgv ? '--dir' : `the "dir" in ${LOCK_FILE}`;
+	if (dir.startsWith('/') || /^[A-Za-z]:/.test(dir))
+		fail(3, `${where} "${value}" must be a path relative to the app root.`);
+	const segments = dir.split('/');
+	if (segments.length > 12) fail(3, `${where} "${value}" is too deep.`);
+	for (const segment of segments)
+		if (!SEGMENT.test(segment) || segment.endsWith('.') || DEVICE.test(segment))
+			fail(
+				3,
+				`${where} "${value}": "${segment}" is not allowed (letters, digits, ".", "_" and "-", no "..", no leading dot).`
+			);
+	if (['node_modules', '.git', 'vendor'].includes(segments[0]))
+		fail(3, `${where} "${value}" is inside ${segments[0]}/.`);
+	return dir;
+}
+
+/** First run: the folder from `--dir`, or the app's layout. */
+export function detectDir(root, declared) {
+	const isDir = (p) => {
+		try {
+			const s = lstatSync(join(root, p));
+			return s.isDirectory() && !s.isSymbolicLink();
+		} catch {
+			return false;
+		}
+	};
+	if (
+		isDir('resources/js') &&
+		(existsSync(join(root, 'artisan')) || declared.has('laravel-vite-plugin'))
+	)
+		return {
+			dir: 'resources/js/composables/inertia-helpers',
+			why: 'Laravel layout: resources/js',
+		};
+	if (isDir('src'))
+		return { dir: 'src/composables/inertia-helpers', why: 'src/ layout' };
+	fail(
+		3,
+		'cannot tell where the helpers go (no resources/js in a Laravel app, no src/). Pass --dir <path>, e.g. --dir resources/js/composables/inertia-helpers.'
+	);
+}
+
+/**
+ * Every existing segment of `dir` under `root` must be a real directory (no
+ * link, no junction) spelled with exactly this case. Returns the segments
+ * that do not exist yet.
+ */
+export function checkDirPath(root, dir) {
+	const segments = dir.split('/');
+	let current = root;
+	for (let i = 0; i < segments.length; i++) {
+		const segment = segments[i];
+		let names;
+		try {
+			names = readdirSync(current);
+		} catch {
+			return segments.slice(i);
+		}
+		if (!names.includes(segment)) {
+			const other = names.find(
+				(n) => n.toLowerCase() === segment.toLowerCase()
+			);
+			if (other)
+				fail(
+					3,
+					`${segments.slice(0, i).concat(other).join('/')} exists with a different case than ${segments.slice(0, i + 1).join('/')}. On a case-sensitive disk (Linux CI) that would be a second folder. Use the existing spelling.`
+				);
+			return segments.slice(i);
+		}
+		const next = join(current, segment);
+		const stats = lstatSync(next);
+		if (stats.isSymbolicLink() || !stats.isDirectory())
+			fail(
+				3,
+				`${segments.slice(0, i + 1).join('/')} is ${stats.isSymbolicLink() ? 'a link' : 'not a folder'}; bitboss-ui only writes into real folders.`
+			);
+		current = next;
+	}
+	return [];
+}
+
+// ---- canonical comparison --------------------------------------------------
+
+/** Vue's Babel and the hashes it can compare against, or why not. */
+export async function loadCanon(manifest) {
+	let babelParse;
+	try {
+		({ babelParse } = await import('vue/compiler-sfc'));
+	} catch {
+		return { available: false, reason: 'vue/compiler-sfc could not be loaded' };
+	}
+	if (typeof babelParse !== 'function')
+		return { available: false, reason: 'vue/compiler-sfc has no babelParse' };
+	const dialect = canonDialect(babelParse);
+	if (!dialect)
+		return {
+			available: false,
+			reason: "Vue's Babel builds an unknown AST shape",
+		};
+	if (manifest.canon !== CANON_VERSION)
+		return {
+			available: false,
+			reason: `the manifest is ${manifest.canon}, this CLI reads ${CANON_VERSION}`,
+		};
+	const anyFile = Object.values(manifest.files ?? {})[0];
+	if (!anyFile?.published?.[dialect])
+		return {
+			available: false,
+			reason: `the package publishes no ${dialect} hashes`,
+		};
+	return { available: true, dialect, babelParse };
+}
+
+// ---- classification -------------------------------------------------------
+
+/**
+ * The state of one helper file in the app:
+ * new | deleted | current | adopt | record | stale | edited | conflict | foreign
+ * (`reformatted` / `commentsDiffer` refine identical and stale files).
+ */
+export function classify({ root, dir, name, manifest, lock, canon }) {
+	const pkg = manifest.bytes.get(name);
+	const entry = lock?.files?.[name] ?? null;
+	const path = join(root, dir, name);
+	let stats;
+	try {
+		stats = lstatSync(path);
+	} catch {
+		return { name, state: entry ? 'deleted' : 'new', disk: null };
+	}
+	if (!stats.isFile())
+		fail(
+			3,
+			`${dir}/${name} is ${stats.isSymbolicLink() ? 'a link' : 'not a regular file'}; bitboss-ui does not write through it.`
+		);
+	const disk = readFileSync(path, 'utf-8');
+	const pkgHash = lfHash(pkg);
+	const diskHash = lfHash(disk);
+	const result = { name, disk, mode: stats.mode };
+	const identical = (extra) => {
+		const state = !entry
+			? 'adopt'
+			: entry.sha256 === pkgHash
+				? 'current'
+				: 'record';
+		return { ...result, state, ...extra };
+	};
+	if (disk === pkg || diskHash === pkgHash) return identical({});
+	const hashOf = (text) =>
+		canon.available ? canonicalHash(text, canon.babelParse) : null;
+	const diskCanon = hashOf(disk);
+	const differ = () => {
+		const a = canon.available ? commentList(disk, canon.babelParse) : null;
+		const b = canon.available ? commentList(pkg, canon.babelParse) : null;
+		return Boolean(a && b && a.join('\n\0') !== b.join('\n\0'));
+	};
+	if (diskCanon && diskCanon === hashOf(pkg))
+		return identical({ reformatted: true, commentsDiffer: differ() });
+	const published = manifest.files[name]?.published ?? {};
+	if (
+		(published.bytes ?? []).includes(diskHash) ||
+		(diskCanon && (published[canon.dialect] ?? []).includes(diskCanon))
+	)
+		return { ...result, state: 'stale', commentsDiffer: differ() };
+	if (!entry) return { ...result, state: 'foreign' };
+	return { ...result, state: entry.sha256 === pkgHash ? 'edited' : 'conflict' };
+}
+
+// ---- scope ----------------------------------------------------------------
+
+function closureOf(manifest, id) {
+	return manifest.helpers[id].closure;
+}
+
+function checkIds(manifest, ids) {
+	for (const id of ids) {
+		if (!HELPER_ID.test(id) || !Object.hasOwn(manifest.helpers, id)) {
+			const known = Object.keys(manifest.helpers).sort();
+			fail(
+				3,
+				`"${id}" is not a helper. Known: ${known.join(', ')}.`,
+				`${CLI} helpers list`
+			);
+		}
+	}
+}
+
+/** Installed helpers grouped by shared files: an update never splits a group. */
+export function connectedGroups(manifest, ids) {
+	const groups = [];
+	for (const id of ids) {
+		const files = new Set(closureOf(manifest, id));
+		const merged = { ids: new Set([id]), files };
+		for (const group of [...groups]) {
+			if ([...group.files].some((f) => files.has(f))) {
+				group.ids.forEach((g) => merged.ids.add(g));
+				group.files.forEach((f) => merged.files.add(f));
+				groups.splice(groups.indexOf(group), 1);
+			}
+		}
+		groups.push(merged);
+	}
+	return groups.map((g) => ({
+		ids: [...g.ids].sort(),
+		files: [...g.files].sort(),
+	}));
+}
+
+/** Dependencies first, so a crash never leaves a new file next to an old dependency. */
+function writeOrder(manifest, names) {
+	const order = [];
+	const seen = new Set();
+	const visit = (name) => {
+		if (seen.has(name)) return;
+		seen.add(name);
+		for (const dep of manifest.files[name]?.local ?? [])
+			if (names.has(dep)) visit(dep);
+		order.push(name);
+	};
+	[...names].sort().forEach(visit);
+	return order;
+}
+
+// ---- the write protocol ---------------------------------------------------
+
+const RETRY = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+function renameWithRetry(from, to) {
+	const deadline = Date.now() + (process.platform === 'win32' ? 3000 : 0);
+	for (;;) {
+		try {
+			renameSync(from, to);
+			return;
+		} catch (error) {
+			if (!RETRY.has(error?.code) || Date.now() >= deadline) throw error;
+			const until = Date.now() + 50;
+			while (Date.now() < until) {
+				// busy-wait: a rename blocked by an antivirus scan clears in milliseconds
+			}
+		}
+	}
+}
+
+function writeTemp(dirPath, name, text, mode) {
+	const temp = join(
+		dirPath,
+		`.${name}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+	);
+	const fd = openSync(temp, 'wx', 0o644);
+	try {
+		writeSync(fd, text);
+	} finally {
+		closeSync(fd);
+	}
+	if (mode !== undefined) chmodSync(temp, mode & 0o7777);
+	return temp;
+}
+
+function serialiseLock(lock) {
+	const files = Object.fromEntries(
+		Object.entries(lock.helpers.files).sort(([a], [b]) => a.localeCompare(b))
+	);
+	return `${JSON.stringify(
+		{
+			lockVersion: LOCK_VERSION,
+			helpers: {
+				dir: lock.helpers.dir,
+				ids: [...lock.helpers.ids].sort(),
+				files,
+			},
+		},
+		null,
+		2
+	)}\n`;
+}
+
+/**
+ * Apply `writes` (`[{ name, text, kind: 'create'|'replace', observed, mode }]`)
+ * and then the lock, all or nothing: temp files first, every target re-checked
+ * right before its rename, renames in dependency order, rollback on any failure.
+ */
+export function applyWrites({
+	root,
+	dir,
+	writes,
+	lockText,
+	previousLockText,
+	manifest,
+	testHooks = {},
+}) {
+	const dirPath = join(root, dir);
+	const createdDirs = [];
+	const temps = [];
+	const done = [];
+	try {
+		// Create the missing folders (checked segment by segment already).
+		let current = root;
+		for (const segment of dir.split('/')) {
+			current = join(current, segment);
+			if (!existsSync(current)) {
+				mkdirSync(current);
+				createdDirs.push(current);
+			}
+		}
+		const byName = new Map(writes.map((w) => [w.name, w]));
+		for (const name of writeOrder(manifest, new Set(byName.keys()))) {
+			const w = byName.get(name);
+			temps.push({ w, temp: writeTemp(dirPath, name, w.text, w.mode) });
+		}
+		for (const { w, temp } of temps) {
+			checkDirPath(root, dir);
+			const target = join(dirPath, w.name);
+			let now = null;
+			try {
+				const stats = lstatSync(target);
+				if (!stats.isFile())
+					throw new HelperError(
+						4,
+						`${dir}/${w.name} changed into a link or folder during the run`
+					);
+				now = readFileSync(target, 'utf-8');
+			} catch (error) {
+				if (error instanceof HelperError) throw error;
+			}
+			if (
+				(w.kind === 'create' && now !== null) ||
+				(w.kind === 'replace' && now !== w.observed)
+			)
+				throw new HelperError(
+					4,
+					`${dir}/${w.name} changed while bitboss-ui was running (an editor or a formatter?). Nothing was kept; run the command again.`
+				);
+			testHooks.beforeRename?.(w.name);
+			renameWithRetry(temp, target);
+			temps.splice(
+				temps.findIndex((t) => t.temp === temp),
+				1,
+				{ w, temp: null }
+			);
+			done.push(w);
+		}
+		if (lockText !== null) {
+			const lockPath = join(root, LOCK_FILE);
+			testHooks.beforeLock?.();
+			let onDisk = null;
+			try {
+				onDisk = readFileSync(lockPath, 'utf-8');
+			} catch {
+				// absent
+			}
+			if (onDisk !== previousLockText)
+				throw new HelperError(
+					4,
+					`${LOCK_FILE} changed while bitboss-ui was running (another run at the same time?). Nothing was kept; run the command again.`
+				);
+			const temp = writeTemp(root, LOCK_FILE, lockText);
+			temps.push({ w: null, temp });
+			renameWithRetry(temp, lockPath);
+		}
+	} catch (error) {
+		for (const { temp } of temps)
+			if (temp)
+				try {
+					unlinkSync(temp);
+				} catch {
+					// already gone
+				}
+		for (const w of done.reverse()) {
+			const target = join(dirPath, w.name);
+			try {
+				if (w.kind === 'create') unlinkSync(target);
+				else
+					renameWithRetry(
+						writeTemp(dirPath, w.name, w.observed, w.mode),
+						target
+					);
+			} catch {
+				// best effort: an untouched original is re-adopted by the next run
+			}
+		}
+		for (const created of createdDirs.reverse())
+			try {
+				rmdirSync(created);
+			} catch {
+				// not empty: something else lives there now
+			}
+		if (error instanceof HelperError) throw error;
+		throw new HelperError(
+			4,
+			`a write failed (${error.code ?? error.message}); everything was rolled back.`
+		);
+	}
+}
+
+// ---- diff -----------------------------------------------------------------
+
+/** A unified diff of two texts (small files: an LCS table is fine). */
+export function unifiedDiff(a, b, labelA, labelB, context = 3) {
+	const x = a.replace(/\r\n/g, '\n').split('\n');
+	const y = b.replace(/\r\n/g, '\n').split('\n');
+	if (x.length * y.length > 4_000_000)
+		return `--- ${labelA}\n+++ ${labelB}\n(files too large to diff)\n`;
+	const lcs = Array.from(
+		{ length: x.length + 1 },
+		() => new Uint32Array(y.length + 1)
+	);
+	for (let i = x.length - 1; i >= 0; i--)
+		for (let j = y.length - 1; j >= 0; j--)
+			lcs[i][j] =
+				x[i] === y[j]
+					? lcs[i + 1][j + 1] + 1
+					: Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+	const ops = [];
+	let i = 0;
+	let j = 0;
+	while (i < x.length || j < y.length) {
+		if (i < x.length && j < y.length && x[i] === y[j])
+			ops.push([' ', x[i++], j++]);
+		else if (j < y.length && (i >= x.length || lcs[i][j + 1] >= lcs[i + 1][j]))
+			ops.push(['+', y[j++]]);
+		else ops.push(['-', x[i++]]);
+	}
+	const out = [`--- ${labelA}`, `+++ ${labelB}`];
+	let k = 0;
+	while (k < ops.length) {
+		if (ops[k][0] === ' ') {
+			k++;
+			continue;
+		}
+		const start = Math.max(0, k - context);
+		let end = k;
+		while (end < ops.length) {
+			if (ops[end][0] !== ' ') {
+				end++;
+				continue;
+			}
+			let run = end;
+			while (run < ops.length && ops[run][0] === ' ') run++;
+			if (run - end > context * 2 || run === ops.length) {
+				end = Math.min(run, end + context);
+				break;
+			}
+			end = run;
+		}
+		out.push('@@');
+		for (const [op, line] of ops.slice(start, end)) out.push(`${op}${line}`);
+		k = end;
+	}
+	return `${out.join('\n')}\n`;
+}
+
+/** Terminal-safe: control characters and bidi overrides become visible escapes. */
+export function escapeForTerminal(text) {
+	return text.replace(
+		// eslint-disable-next-line no-control-regex -- matching control characters is the point
+		/[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g,
+		(c) => `\\u{${c.codePointAt(0).toString(16)}}`
+	);
+}
+
+// ---- the commands -----------------------------------------------------------
+
+function missingPackages(ctx, names) {
+	const runtime = new Set();
+	const types = new Set();
+	for (const name of names) {
+		(ctx.manifest.files[name]?.packages ?? []).forEach((p) => runtime.add(p));
+		(ctx.manifest.files[name]?.typePackages ?? []).forEach((p) => types.add(p));
+	}
+	runtime.forEach((p) => types.delete(p));
+	const missing = (set) => [...set].filter((p) => !ctx.declared.has(p)).sort();
+	const run = missing(runtime);
+	const dev = missing(types);
+	const verb = { npm: 'i', pnpm: 'add', yarn: 'add', bun: 'add' }[ctx.pm];
+	const install = [
+		...(run.length ? [`${ctx.pm} ${verb} ${run.join(' ')}`] : []),
+		...(dev.length ? [`${ctx.pm} ${verb} -D ${dev.join(' ')}`] : []),
+	];
+	return { missing: [...run, ...dev], install };
+}
+
+const STATE_WORD = {
+	new: 'create',
+	deleted: 'create',
+	current: 'identical',
+	adopt: 'adopt',
+	record: 'record',
+	stale: 'stale',
+	edited: 'keep',
+	conflict: 'conflict',
+	foreign: 'foreign',
+};
+
+function note(file) {
+	const parts = [];
+	if (file.state === 'edited') parts.push('your edit is kept');
+	if (file.state === 'conflict')
+		parts.push('you edited it, and bitboss-ui changed it since your copy');
+	if (file.state === 'foreign')
+		parts.push('a file bitboss-ui did not install, with other content');
+	if (file.state === 'stale') parts.push('an older bitboss-ui version');
+	if (file.reformatted) parts.push('reformatted');
+	if (file.commentsDiffer)
+		parts.push(
+			file.state === 'stale'
+				? 'your comments differ and would be replaced'
+				: 'your comments differ'
+		);
+	return parts.length ? `  (${parts.join('; ')})` : '';
+}
+
+/** Run one command. Returns `{ code, report, lines }`; never prints, never exits. */
+export async function runHelpers({
+	command,
+	ids = [],
+	options = {},
+	cwd,
+	packageRoot,
+	testHooks,
+}) {
+	const label = command === 'add' ? 'add' : `helpers ${command}`;
+	try {
+		const ctx = loadContext({ cwd, packageRoot, command: label });
+		const canon = await loadCanon(ctx.manifest);
+		if (command === 'list') return list(ctx, canon);
+		if (command === 'add') return add(ctx, canon, ids, options, testHooks);
+		if (command === 'diff') return diff(ctx, canon, ids);
+		if (command === 'update')
+			return update(ctx, canon, ids, options, testHooks);
+		fail(1, `unknown helpers command "${command}" (list, diff, update).`);
+	} catch (error) {
+		if (!(error instanceof HelperError)) throw error;
+		return {
+			code: error.code,
+			report: {
+				ok: false,
+				command: label,
+				error: error.message,
+				next: error.next,
+			},
+			lines: [
+				`[bitboss-ui] ${label}: ${error.message}`,
+				...(error.next ? [`  next: ${error.next}`] : []),
+			],
+			stderr: true,
+		};
+	}
+}
+
+function resolveDir(ctx, options, { required }) {
+	const fromLock = ctx.lock?.dir
+		? validateDir(ctx.lock.dir, { fromArgv: false })
+		: null;
+	if (options.dir !== undefined) {
+		const asked = validateDir(options.dir, { fromArgv: true });
+		if (fromLock && asked !== fromLock)
+			fail(
+				3,
+				`--dir ${asked} differs from the folder in ${LOCK_FILE} (${fromLock}). To move the helpers, move the folder and edit "dir" in the lock.`
+			);
+		return { dir: asked, why: fromLock ? 'from the lock' : 'from --dir' };
+	}
+	if (fromLock) return { dir: fromLock, why: 'from the lock' };
+	if (!required) return null;
+	return detectDir(ctx.root, ctx.declared);
+}
+
+function header(ctx, label, dir, dryRun, canon) {
+	return [
+		`[bitboss-ui] ${label} · bitboss-ui ${ctx.version}${dryRun ? ' · DRY RUN, nothing written' : ''}`,
+		...(dir ? [`  dir        ${dir.dir}  (${dir.why})`] : []),
+		...(canon.available
+			? []
+			: [
+					`  note       formatter-proof check unavailable: ${canon.reason}; reformatted helpers read as edited`,
+				]),
+	];
+}
+
+function fileLine(file) {
+	return `  ${STATE_WORD[file.state].padEnd(10)} ${file.name}${note(file)}`;
+}
+
+function newLock(ctx, dir, ids, files) {
+	const lock = {
+		helpers: {
+			dir,
+			ids: new Set(ctx.lock?.ids ?? []),
+			files: { ...(ctx.lock?.files ?? {}) },
+		},
+	};
+	ids.forEach((id) => lock.helpers.ids.add(id));
+	for (const file of files)
+		if (['new', 'deleted', 'adopt', 'record', 'stale'].includes(file.state))
+			lock.helpers.files[file.name] = {
+				sha256: lfHash(ctx.manifest.bytes.get(file.name)),
+				version: ctx.version,
+			};
+	const text = serialiseLock(lock);
+	const before = ctx.lock
+		? serialiseLock({
+				helpers: {
+					dir: ctx.lock.dir,
+					ids: new Set(ctx.lock.ids),
+					files: ctx.lock.files,
+				},
+			})
+		: null;
+	return text === before ? null : text;
+}
+
+function writesFor(ctx, files) {
+	return files
+		.filter((f) => ['new', 'deleted', 'stale'].includes(f.state))
+		.map((f) => ({
+			name: f.name,
+			text: ctx.manifest.bytes.get(f.name),
+			kind: f.disk === null ? 'create' : 'replace',
+			observed: f.disk,
+			mode: f.mode,
+		}));
+}
+
+function packagesLines(pkgs) {
+	if (!pkgs.missing.length) return [];
+	return [
+		`  packages   not in package.json: ${pkgs.missing.join(', ')}`,
+		...pkgs.install.map((line) => `             ${line}`),
+	];
+}
+
+function add(ctx, canon, named, options, testHooks) {
+	if (options.all && named.length)
+		fail(1, 'pass helper ids or --all, not both.');
+	const ids = options.all ? Object.keys(ctx.manifest.helpers).sort() : named;
+	if (!ids.length)
+		fail(
+			1,
+			'name at least one helper, e.g. `add useQuery`, or pass --all.',
+			`${CLI} helpers list`
+		);
+	checkIds(ctx.manifest, ids);
+	const dir = resolveDir(ctx, options, { required: true });
+	checkDirPath(ctx.root, dir.dir);
+	const names = [
+		...new Set(ids.flatMap((id) => closureOf(ctx.manifest, id))),
+	].sort();
+	const files = names.map((name) =>
+		classify({
+			root: ctx.root,
+			dir: dir.dir,
+			name,
+			manifest: ctx.manifest,
+			lock: ctx.lock,
+			canon,
+		})
+	);
+	const refused = files.filter((f) =>
+		['stale', 'conflict', 'foreign'].includes(f.state)
+	);
+	const pkgs = missingPackages(ctx, names);
+	const lines = [
+		...header(ctx, `add ${ids.join(' ')}`, dir, options.dryRun, canon),
+		...files.map(fileLine),
+	];
+	const report = {
+		ok: refused.length === 0,
+		command: 'add',
+		dryRun: Boolean(options.dryRun),
+		version: ctx.version,
+		dir: dir.dir,
+		files: files.map(({ name, state, reformatted, commentsDiffer }) => ({
+			file: name,
+			state,
+			...(reformatted ? { reformatted } : {}),
+			...(commentsDiffer ? { commentsDiffer } : {}),
+		})),
+		packages: pkgs,
+		canon: canon.available
+			? { available: true }
+			: { available: false, reason: canon.reason },
+	};
+	if (refused.length) {
+		const stale = refused.every((f) => f.state === 'stale');
+		const next = stale
+			? `${CLI} helpers update --dry-run`
+			: `${CLI} helpers diff ${refused.map((f) => f.name.replace(/\.ts$/, '')).join(' ')}`;
+		lines.push(
+			stale
+				? '[bitboss-ui] add REFUSED, nothing written: an older bitboss-ui version of these files is installed. Update them first, then add:'
+				: "[bitboss-ui] add REFUSED, nothing written. Show the user the difference between their copy and bitboss-ui's:",
+			`  ${next}`
+		);
+		return {
+			code: 2,
+			report: { ...report, refused: refused.map((f) => f.name), next },
+			lines,
+		};
+	}
+	const writes = writesFor(ctx, files);
+	const lockText = newLock(ctx, dir.dir, ids, files);
+	lines.push(...packagesLines(pkgs));
+	if (!writes.length && lockText === null) {
+		lines.push('[bitboss-ui] nothing to do.');
+		return { code: 0, report: { ...report, next: null }, lines };
+	}
+	if (!options.dryRun)
+		applyWrites({
+			root: ctx.root,
+			dir: dir.dir,
+			writes,
+			lockText,
+			previousLockText: ctx.lock?.text ?? null,
+			manifest: ctx.manifest,
+			testHooks,
+		});
+	lines.push(
+		`[bitboss-ui] ${options.dryRun ? 'would write' : 'wrote'} ${writes.length} file(s)${lockText !== null ? ` and ${LOCK_FILE}` : ''}.`,
+		...ids.map(
+			(id) =>
+				`  import { ${id} } from '@/${dir.dir.replace(/^(resources\/js|src)\//, '')}/${id}';`
+		)
+	);
+	return {
+		code: 0,
+		report: {
+			...report,
+			wrote: options.dryRun ? 0 : writes.length,
+			next: null,
+		},
+		lines,
+	};
+}
+
+function installedIds(ctx) {
+	return (ctx.lock?.ids ?? []).filter((id) =>
+		Object.hasOwn(ctx.manifest.helpers, id)
+	);
+}
+
+function update(ctx, canon, ids, options, testHooks) {
+	if (!ctx.lock?.dir) {
+		return {
+			code: 0,
+			report: {
+				ok: true,
+				command: 'helpers update',
+				installed: [],
+				next: `${CLI} add <id>`,
+			},
+			lines: [
+				`[bitboss-ui] helpers update: no helpers installed here (no ${LOCK_FILE}). Install one: ${CLI} add <id>`,
+			],
+		};
+	}
+	checkIds(ctx.manifest, ids);
+	const installed = installedIds(ctx);
+	const notInstalled = ids.filter((id) => !installed.includes(id));
+	if (notInstalled.length)
+		fail(
+			3,
+			`${notInstalled.join(', ')} ${notInstalled.length > 1 ? 'are' : 'is'} not installed here.`,
+			`${CLI} add ${notInstalled.join(' ')}`
+		);
+	const dir = resolveDir(ctx, {}, { required: true });
+	checkDirPath(ctx.root, dir.dir);
+	const groups = connectedGroups(ctx.manifest, installed).filter(
+		(g) => !ids.length || g.ids.some((id) => ids.includes(id))
+	);
+	const lines = [
+		...header(
+			ctx,
+			`helpers update${ids.length ? ` ${ids.join(' ')}` : ''}`,
+			dir,
+			options.dryRun,
+			canon
+		),
+	];
+	const applied = [];
+	const refusedGroups = [];
+	const allFiles = [];
+	for (const group of groups) {
+		const files = group.files.map((name) =>
+			classify({
+				root: ctx.root,
+				dir: dir.dir,
+				name,
+				manifest: ctx.manifest,
+				lock: ctx.lock,
+				canon,
+			})
+		);
+		allFiles.push(...files);
+		lines.push(`  group      ${group.ids.join(', ')}`);
+		lines.push(...files.map((f) => `  ${fileLine(f)}`));
+		const blocked = files.filter((f) =>
+			['conflict', 'foreign'].includes(f.state)
+		);
+		if (blocked.length) refusedGroups.push({ group, blocked });
+		else applied.push(...files);
+	}
+	const removed = Object.keys(ctx.lock.files).filter(
+		(name) => !Object.hasOwn(ctx.manifest.files, name)
+	);
+	lines.push(
+		...removed.map(
+			(name) =>
+				`  ${'removed'.padEnd(10)} ${name}  (no longer shipped; kept, never deleted)`
+		)
+	);
+	const writes = writesFor(ctx, applied);
+	const lockText = newLock(ctx, dir.dir, [], applied);
+	const pkgs = missingPackages(ctx, [...new Set(applied.map((f) => f.name))]);
+	lines.push(...packagesLines(pkgs));
+	if ((writes.length || lockText !== null) && !options.dryRun)
+		applyWrites({
+			root: ctx.root,
+			dir: dir.dir,
+			writes,
+			lockText,
+			previousLockText: ctx.lock.text,
+			manifest: ctx.manifest,
+			testHooks,
+		});
+	const next = refusedGroups.length
+		? `${CLI} helpers diff ${refusedGroups.flatMap((r) => r.blocked.map((f) => f.name.replace(/\.ts$/, ''))).join(' ')}`
+		: null;
+	if (!writes.length && lockText === null && !refusedGroups.length)
+		lines.push('[bitboss-ui] nothing to do.');
+	else
+		lines.push(
+			`[bitboss-ui] ${options.dryRun ? 'would write' : 'wrote'} ${writes.length} file(s)${lockText !== null ? ` and ${LOCK_FILE}` : ''}.`
+		);
+	if (refusedGroups.length)
+		lines.push(
+			`[bitboss-ui] REFUSED ${refusedGroups.length} group(s), left untouched: ${refusedGroups.map((r) => r.group.ids.join(', ')).join(' | ')}. Show the user the difference:`,
+			`  ${next}`
+		);
+	return {
+		code: refusedGroups.length ? 2 : 0,
+		report: {
+			ok: !refusedGroups.length,
+			command: 'helpers update',
+			dryRun: Boolean(options.dryRun),
+			version: ctx.version,
+			dir: dir.dir,
+			files: allFiles.map(({ name, state, reformatted, commentsDiffer }) => ({
+				file: name,
+				state,
+				...(reformatted ? { reformatted } : {}),
+				...(commentsDiffer ? { commentsDiffer } : {}),
+			})),
+			refused: refusedGroups.map((r) => ({
+				ids: r.group.ids,
+				files: r.blocked.map((f) => f.name),
+			})),
+			removed,
+			packages: pkgs,
+			wrote: options.dryRun ? 0 : writes.length,
+			canon: canon.available
+				? { available: true }
+				: { available: false, reason: canon.reason },
+			next,
+		},
+		lines,
+	};
+}
+
+function diff(ctx, canon, ids) {
+	checkIds(ctx.manifest, ids);
+	if (!ctx.lock?.dir && !ids.length)
+		return {
+			code: 0,
+			report: { ok: true, command: 'helpers diff', files: [], next: null },
+			lines: [
+				`[bitboss-ui] helpers diff: no helpers installed here (no ${LOCK_FILE}).`,
+			],
+		};
+	const dir = resolveDir(ctx, {}, { required: true });
+	checkDirPath(ctx.root, dir.dir);
+	const names = ids.length
+		? [...new Set(ids.flatMap((id) => closureOf(ctx.manifest, id)))].sort()
+		: Object.keys(ctx.lock.files)
+				.filter((n) => Object.hasOwn(ctx.manifest.files, n))
+				.sort();
+	const files = names.map((name) =>
+		classify({
+			root: ctx.root,
+			dir: dir.dir,
+			name,
+			manifest: ctx.manifest,
+			lock: ctx.lock,
+			canon,
+		})
+	);
+	const lines = [
+		...header(
+			ctx,
+			`helpers diff${ids.length ? ` ${ids.join(' ')}` : ''}`,
+			dir,
+			false,
+			canon
+		),
+	];
+	const report = [];
+	for (const file of files) {
+		lines.push(fileLine(file));
+		const entry = { file: file.name, state: file.state };
+		if (file.reformatted) entry.reformatted = true;
+		if (file.commentsDiffer) entry.commentsDiffer = true;
+		const show =
+			ids.length &&
+			file.disk !== null &&
+			file.disk !== ctx.manifest.bytes.get(file.name);
+		if (show) {
+			const text = unifiedDiff(
+				file.disk,
+				ctx.manifest.bytes.get(file.name),
+				`${dir.dir}/${file.name} (yours)`,
+				`${file.name} (bitboss-ui ${ctx.version})`
+			);
+			entry.diff = text;
+			if (file.reformatted)
+				lines.push(
+					`             ${file.commentsDiffer ? 'formatting and comments only' : 'formatting only'}`
+				);
+			lines.push(
+				...escapeForTerminal(text)
+					.trimEnd()
+					.split('\n')
+					.map((l) => `    ${l}`)
+			);
+		}
+		report.push(entry);
+	}
+	if (files.some((f) => f.state === 'stale' && f.commentsDiffer))
+		lines.push(
+			'[bitboss-ui] comments do not count as edits: `helpers update` replaces a stale file whole, so the comments shown above would be lost. Copy any you want to keep first.'
+		);
+	const act = files.filter((f) =>
+		[
+			'stale',
+			'conflict',
+			'foreign',
+			'deleted',
+			'new',
+			'adopt',
+			'record',
+		].includes(f.state)
+	);
+	return {
+		code: act.length ? 1 : 0,
+		report: {
+			ok: true,
+			kind: act.length ? 'difference' : 'none',
+			command: 'helpers diff',
+			version: ctx.version,
+			dir: dir.dir,
+			files: report,
+			canon: canon.available
+				? { available: true }
+				: { available: false, reason: canon.reason },
+			next: act.some((f) => f.state === 'stale')
+				? `${CLI} helpers update --dry-run`
+				: null,
+		},
+		lines,
+	};
+}
+
+function list(ctx, canon) {
+	const dir = ctx.lock?.dir ? resolveDir(ctx, {}, { required: false }) : null;
+	if (dir) checkDirPath(ctx.root, dir.dir);
+	const installed = new Set(installedIds(ctx));
+	const lines = [...header(ctx, 'helpers list', dir, false, canon)];
+	const helpers = [];
+	for (const [id, helper] of Object.entries(ctx.manifest.helpers).sort(
+		([a], [b]) => a.localeCompare(b)
+	)) {
+		let state = null;
+		if (dir && installed.has(id)) {
+			const states = helper.closure.map(
+				(name) =>
+					classify({
+						root: ctx.root,
+						dir: dir.dir,
+						name,
+						manifest: ctx.manifest,
+						lock: ctx.lock,
+						canon,
+					}).state
+			);
+			state =
+				['conflict', 'foreign', 'stale', 'deleted', 'edited'].find((s) =>
+					states.includes(s)
+				) ?? 'current';
+		}
+		helpers.push({
+			id,
+			summary: helper.summary,
+			files: helper.closure,
+			packages: [...helper.packages, ...helper.typePackages],
+			state,
+		});
+		lines.push(
+			`  ${id.padEnd(30)} ${state ? `[${state}] ` : ''}${helper.summary}`
+		);
+	}
+	lines.push(`[bitboss-ui] install one: ${CLI} add <id>`);
+	return {
+		code: 0,
+		report: {
+			ok: true,
+			command: 'helpers list',
+			version: ctx.version,
+			dir: dir?.dir ?? null,
+			testedWith: ctx.manifest.tested,
+			helpers,
+		},
+		lines,
+	};
+}
+
+/** Exposed for tests. */
+export const _internal = { writeOrder, serialiseLock };