@kumikijs/cli 0.1.0

package/README.md

@@ -0,0 +1,24 @@
+# @kumikijs/cli
+
+The `kumiki` command — build, check, and AI-edit (list/view/add/replace/remove/rename/fix) Kumiki sources. Part of [Kumiki](https://github.com/kage1020/Kumiki), an AI-first web framework language.
+
+## Install
+
+```sh
+npm i -g @kumikijs/cli
+# or run without installing
+npx @kumikijs/cli --help
+```
+
+## Usage
+
+```sh
+kumiki build <input.kumiki> <outdir>   # compile to a runnable app
+kumiki check <input.kumiki>            # type-check and report diagnostics
+```
+
+Run `kumiki` with no arguments to see the full command list (list / view / add / replace / remove / rename / fix / smoke / run).
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { Def, KumikiError, Program } from "@kumikijs/compiler";
+import { Scenario, ScenarioReport, SmokeReport } from "@kumikijs/runtime";
+
+//#region src/store.d.ts
+type DefRange = {
+  /** 1-based start line in the source file. */startLine: number; /** 1-based end line, inclusive. */
+  endLine: number;
+};
+type DefEntry = {
+  layer: string;
+  name: string;
+  def: Def;
+  range: DefRange;
+};
+type Store = {
+  source: string;
+  lines: string[];
+  program: Program;
+  defs: DefEntry[];
+  byQName: Map<string, DefEntry>;
+};
+declare function load(path: string): Store;
+declare function viewDef(store: Store, qname: string): string | null;
+declare function viewWithDeps(store: Store, qname: string): string;
+/**
+ * Return qnames that the definition at `qname` references. The match is
+ * textual (identifier token in the source range) and intentionally over-
+ * inclusive: any identifier that names another definition is considered a
+ * dependency.
+ */
+declare function directDeps(store: Store, qname: string): string[];
+type RefSite = {
+  qname: string;
+  layer: string;
+  name: string;
+  line: number;
+};
+declare function findReferences(store: Store, targetQname: string): RefSite[];
+declare function listDefs(store: Store, layer?: string): DefEntry[];
+//#endregion
+//#region src/fix.d.ts
+type AutoPatch = {
+  code: string;
+  message: string; /** Free-form description of the fix to be applied. */
+  description: string;
+  apply: (text: string) => string;
+};
+declare function planFixes(store: Store, errors: KumikiError[]): AutoPatch[];
+declare function fixCmd(path: string, apply: boolean, onlyCode?: string): void;
+//#endregion
+//#region src/mutate.d.ts
+declare function addDef(path: string, layer: string, name: string, body: string): void;
+declare function replaceDef(path: string, qname: string, body: string): void;
+declare function removeDef(path: string, qname: string, cascade: boolean): void;
+declare function renameDef(path: string, qname: string, newName: string): void;
+//#endregion
+//#region src/smoke.d.ts
+/** Compile + mount + exercise a Kumiki source string; return the smoke report. */
+declare function smokeSource(source: string): Promise<SmokeReport>;
+declare function smokeFile(path: string): Promise<SmokeReport>;
+/** CLI entry: print a human-readable report and exit non-zero on failure. */
+declare function smokeCmd(path: string): Promise<void>;
+/** Compile + mount + drive a scenario; return the structured trace. */
+declare function runScenarioSource(source: string, scenario: Scenario): Promise<ScenarioReport>;
+/** CLI entry: run a scenario JSON file against a .kumiki file; print the trace. */
+declare function runCmd(kumikiPath: string, scenarioPath: string): Promise<void>;
+//#endregion
+export { type AutoPatch, type Store, addDef, directDeps, findReferences, fixCmd, listDefs, load, planFixes, removeDef, renameDef, replaceDef, runCmd, runScenarioSource, smokeCmd, smokeFile, smokeSource, viewDef, viewWithDeps };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { _ as viewWithDeps, a as smokeSource, c as renameDef, d as planFixes, f as directDeps, g as viewDef, h as load, i as smokeFile, l as replaceDef, m as listDefs, n as runScenarioSource, o as addDef, p as findReferences, r as smokeCmd, s as removeDef, t as runCmd, u as fixCmd } from "./smoke-CY4f_tnY.js";
+export { addDef, directDeps, findReferences, fixCmd, listDefs, load, planFixes, removeDef, renameDef, replaceDef, runCmd, runScenarioSource, smokeCmd, smokeFile, smokeSource, viewDef, viewWithDeps };

package/dist/kumiki.d.ts

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

package/dist/kumiki.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { _ as viewWithDeps, c as renameDef, g as viewDef, h as load, l as replaceDef, m as listDefs, o as addDef, p as findReferences, r as smokeCmd, s as removeDef, t as runCmd, u as fixCmd } from "./smoke-CY4f_tnY.js";
+import { createRequire } from "node:module";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { check, compile } from "@kumikijs/compiler";
+import { resolve } from "node:path";
+//#region src/kumiki.ts
+const require = createRequire(import.meta.url);
+function usage() {
+	console.error("Usage:");
+	console.error("  kumiki build <input.kumiki> <outdir>");
+	console.error("  kumiki list <input.kumiki> [layer]");
+	console.error("  kumiki view <input.kumiki> <qname> [--with-deps]");
+	console.error("  kumiki refs <input.kumiki> <qname>");
+	console.error("  kumiki check <input.kumiki> [--strict-a11y]");
+	console.error("  kumiki smoke <input.kumiki>");
+	console.error("  kumiki run <input.kumiki> <scenario.json>");
+	process.exit(2);
+}
+function buildCmd(inputArg, outdirArg) {
+	const inputPath = resolve(process.cwd(), inputArg);
+	const outdir = resolve(process.cwd(), outdirArg);
+	const result = compile(readFileSync(inputPath, "utf8"), { runtimeSpecifier: "./runtime.js" });
+	if (result.kind === "fail") {
+		for (const err of result.errors) console.error(`${err.code} ${err.kind} at ${err.pos.line}:${err.pos.col}: ${err.message}`);
+		process.exit(1);
+	}
+	mkdirSync(outdir, { recursive: true });
+	writeFileSync(resolve(outdir, "app.js"), result.js);
+	writeFileSync(resolve(outdir, "runtime.js"), buildRuntimeBundle());
+	writeFileSync(resolve(outdir, "index.html"), buildHtml());
+	console.log(`Wrote ${outdir}/index.html, app.js, runtime.js`);
+}
+function listCmd(inputArg, layer) {
+	const entries = listDefs(load(resolve(process.cwd(), inputArg)), layer);
+	for (const e of entries) console.log(`${e.layer.padEnd(8)} ${e.name}  (${e.range.startLine}-${e.range.endLine})`);
+}
+function viewCmd(inputArg, qname, withDeps) {
+	const store = load(resolve(process.cwd(), inputArg));
+	const out = withDeps ? viewWithDeps(store, qname) : viewDef(store, qname);
+	if (out === null) {
+		console.error(`Definition "${qname}" not found`);
+		process.exit(1);
+	}
+	console.log(out);
+}
+function refsCmd(inputArg, qname) {
+	const refs = findReferences(load(resolve(process.cwd(), inputArg)), qname);
+	if (refs.length === 0) {
+		console.log(`(no references to ${qname})`);
+		return;
+	}
+	for (const r of refs) console.log(`${r.qname}  ${inputArg}:${r.line}`);
+}
+function checkCmd(inputArg, strictA11y) {
+	const errors = check(load(resolve(process.cwd(), inputArg)).program, { strictA11y });
+	if (errors.length === 0) {
+		console.log("ok");
+		return;
+	}
+	for (const err of errors) console.error(`${err.code} ${err.kind} at ${err.pos.line}:${err.pos.col}: ${err.message}`);
+	process.exit(1);
+}
+async function main(argv) {
+	const cmd = argv[2];
+	if (!cmd) usage();
+	switch (cmd) {
+		case "build": {
+			const input = argv[3];
+			const out = argv[4];
+			if (!input || !out) usage();
+			buildCmd(input, out);
+			return;
+		}
+		case "list": {
+			const input = argv[3];
+			if (!input) usage();
+			listCmd(input, argv[4]);
+			return;
+		}
+		case "view": {
+			const input = argv[3];
+			const qname = argv[4];
+			if (!input || !qname) usage();
+			viewCmd(input, qname, argv.includes("--with-deps"));
+			return;
+		}
+		case "refs": {
+			const input = argv[3];
+			const qname = argv[4];
+			if (!input || !qname) usage();
+			refsCmd(input, qname);
+			return;
+		}
+		case "check": {
+			const input = argv[3];
+			if (!input) usage();
+			checkCmd(input, argv.includes("--strict-a11y"));
+			return;
+		}
+		case "smoke": {
+			const input = argv[3];
+			if (!input) usage();
+			await smokeCmd(resolve(process.cwd(), input));
+			return;
+		}
+		case "run": {
+			const input = argv[3];
+			const scenario = argv[4];
+			if (!input || !scenario) usage();
+			await runCmd(resolve(process.cwd(), input), resolve(process.cwd(), scenario));
+			return;
+		}
+		case "add": {
+			const [, , , file, layer, name, ...rest] = argv;
+			if (!file || !layer || !name || rest.length === 0) {
+				console.error("Usage: kumiki add <file> <layer> <name> <body>");
+				process.exit(2);
+			}
+			const body = rest.join(" ");
+			try {
+				addDef(resolve(process.cwd(), file), layer, name, body);
+				console.log(`added ${layer}.${name}`);
+			} catch (e) {
+				console.error(String(e));
+				process.exit(1);
+			}
+			return;
+		}
+		case "replace": {
+			const [, , , file, qname, ...rest] = argv;
+			if (!file || !qname || rest.length === 0) {
+				console.error("Usage: kumiki replace <file> <qname> <body>");
+				process.exit(2);
+			}
+			const body = rest.join(" ");
+			try {
+				replaceDef(resolve(process.cwd(), file), qname, body);
+				console.log(`replaced ${qname}`);
+			} catch (e) {
+				console.error(String(e));
+				process.exit(1);
+			}
+			return;
+		}
+		case "remove": {
+			const [, , , file, qname] = argv;
+			if (!file || !qname) {
+				console.error("Usage: kumiki remove <file> <qname> [--cascade]");
+				process.exit(2);
+			}
+			try {
+				removeDef(resolve(process.cwd(), file), qname, argv.includes("--cascade"));
+				console.log(`removed ${qname}`);
+			} catch (e) {
+				console.error(String(e));
+				process.exit(1);
+			}
+			return;
+		}
+		case "rename": {
+			const [, , , file, qname, newName] = argv;
+			if (!file || !qname || !newName) {
+				console.error("Usage: kumiki rename <file> <qname> <new-name>");
+				process.exit(2);
+			}
+			try {
+				renameDef(resolve(process.cwd(), file), qname, newName);
+				console.log(`renamed ${qname} -> ${newName}`);
+			} catch (e) {
+				console.error(String(e));
+				process.exit(1);
+			}
+			return;
+		}
+		case "fix": {
+			const file = argv[3];
+			if (!file) {
+				console.error("Usage: kumiki fix <file> [--apply] [<code>]");
+				process.exit(2);
+			}
+			const apply = argv.includes("--apply");
+			const code = argv.find((a, i) => i > 3 && a !== "--apply");
+			fixCmd(resolve(process.cwd(), file), apply, code);
+			return;
+		}
+		default: usage();
+	}
+}
+function buildRuntimeBundle() {
+	return readFileSync(require.resolve("@kumikijs/runtime/bundle"), "utf8");
+}
+function buildHtml() {
+	return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Kumiki App</title>
+  <style>
+    body { font-family: system-ui, sans-serif; margin: 0; padding: 24px; background: #fafafa; color: #1a1a1a; }
+    button { padding: 6px 12px; font-size: 16px; cursor: pointer; }
+    h1 { margin: 0 0 12px; }
+  </style>
+</head>
+<body>
+  <base href="/">
+  <div id="root"></div>
+  <script type="module" src="/app.js"><\/script>
+</body>
+</html>
+`;
+}
+main(process.argv).catch((e) => {
+	console.error(String(e));
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/smoke-CY4f_tnY.js

@@ -0,0 +1,530 @@
+import { appendFileSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { check, compile, lex, parse } from "@kumikijs/compiler";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { nodeRuntimeBundleReader } from "@kumikijs/compiler/node";
+import { runScenario, smoke } from "@kumikijs/runtime";
+import { JSDOM } from "jsdom";
+//#region src/store.ts
+const LAYER_OF = {
+	TypeDef: "type",
+	SlotDef: "slot",
+	EffectDef: "effect",
+	ReducerDef: "reducer",
+	TileDef: "tile",
+	FnDef: "fn",
+	AppDef: "app",
+	ThemeDef: "theme"
+};
+function load(path) {
+	const source = readFileSync(path, "utf8");
+	const lines = source.split(/\r?\n/);
+	const tokens = lex(source);
+	const program = parse(tokens);
+	const defs = buildEntries(program, lines, tokens);
+	const byQName = /* @__PURE__ */ new Map();
+	for (const e of defs) byQName.set(`${e.layer}.${e.name}`, e);
+	return {
+		source,
+		lines,
+		program,
+		defs,
+		byQName
+	};
+}
+function buildEntries(program, lines, tokens) {
+	const out = [];
+	for (let i = 0; i < program.defs.length; i++) {
+		const d = program.defs[i];
+		const layer = LAYER_OF[d.kind] ?? "?";
+		const name = "name" in d ? d.name : "_";
+		const start = d.pos?.line ?? 1;
+		const next = program.defs[i + 1];
+		const nextStart = next && next.pos?.line;
+		const endLine = nextStart ? nextStart - 1 : lines.length;
+		out.push({
+			layer,
+			name,
+			def: d,
+			range: {
+				startLine: start,
+				endLine
+			}
+		});
+	}
+	for (const e of out) {
+		let end = e.range.endLine;
+		while (end > e.range.startLine) {
+			const line = lines[end - 1] ?? "";
+			if (line.trim() === "" || line.trim().startsWith("#")) end--;
+			else break;
+		}
+		e.range.endLine = end;
+	}
+	return out;
+}
+function viewDef(store, qname) {
+	const e = store.byQName.get(qname);
+	if (!e) return null;
+	return store.lines.slice(e.range.startLine - 1, e.range.endLine).join("\n");
+}
+function viewWithDeps(store, qname) {
+	const seen = /* @__PURE__ */ new Set();
+	const order = [];
+	const visit = (q) => {
+		if (seen.has(q)) return;
+		seen.add(q);
+		const refs = directDeps(store, q);
+		for (const r of refs) visit(r);
+		order.push(q);
+	};
+	visit(qname);
+	return order.map((q) => viewDef(store, q)).filter((s) => s !== null).join("\n\n");
+}
+/**
+* Return qnames that the definition at `qname` references. The match is
+* textual (identifier token in the source range) and intentionally over-
+* inclusive: any identifier that names another definition is considered a
+* dependency.
+*/
+function directDeps(store, qname) {
+	const e = store.byQName.get(qname);
+	if (!e) return [];
+	const body = store.lines.slice(e.range.startLine - 1, e.range.endLine).join("\n");
+	const refs = /* @__PURE__ */ new Set();
+	const idents = body.matchAll(/[a-zA-Z_][a-zA-Z0-9_-]*/g);
+	for (const m of idents) {
+		const tok = m[0];
+		if (!tok || tok === e.name) continue;
+		for (const other of store.defs) {
+			if (other === e) continue;
+			if (other.name === tok) refs.add(`${other.layer}.${other.name}`);
+		}
+	}
+	return Array.from(refs).sort();
+}
+function findReferences(store, targetQname) {
+	const target = store.byQName.get(targetQname);
+	if (!target) return [];
+	const out = [];
+	const targetName = target.name;
+	for (const e of store.defs) {
+		if (e === target) continue;
+		for (let ln = e.range.startLine; ln <= e.range.endLine; ln++) {
+			const cleaned = (store.lines[ln - 1] ?? "").replace(/"(?:[^"\\]|\\.)*"/g, "\"\"").replace(/#.*$/, "");
+			if (new RegExp(`(^|[^a-zA-Z0-9_-])${escapeRegExp$1(targetName)}(?![a-zA-Z0-9_-])`).test(cleaned)) out.push({
+				qname: `${e.layer}.${e.name}`,
+				layer: e.layer,
+				name: e.name,
+				line: ln
+			});
+		}
+	}
+	return out;
+}
+function escapeRegExp$1(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function listDefs(store, layer) {
+	if (layer) return store.defs.filter((e) => e.layer === layer);
+	return store.defs;
+}
+//#endregion
+//#region src/fix.ts
+function levenshtein(a, b) {
+	const m = a.length;
+	const n = b.length;
+	let prev = Array.from({ length: n + 1 }, (_, j) => j);
+	for (let i = 1; i <= m; i++) {
+		const curr = [i, ...new Array(n).fill(0)];
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+		}
+		prev = curr;
+	}
+	return prev[n] ?? 0;
+}
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function suggestName(store, missing) {
+	const all = listDefs(store).map((e) => e.name);
+	let best = null;
+	let bestScore = Number.POSITIVE_INFINITY;
+	for (const cand of all) {
+		const d = levenshtein(missing, cand);
+		if (d < bestScore) {
+			bestScore = d;
+			best = cand;
+		}
+	}
+	if (best === null) return null;
+	if (bestScore <= 2 || bestScore <= Math.ceil(missing.length * .25)) return best;
+	return null;
+}
+function planFixes(store, errors) {
+	const patches = [];
+	for (const err of errors) {
+		if (err.code === "E0103" || err.code === "E0105" || err.code === "E0102" || err.code === "E0104") {
+			const match = /"([^"]+)"/.exec(err.message);
+			if (!match) continue;
+			const missing = match[1];
+			const suggested = suggestName(store, missing);
+			if (!suggested) continue;
+			patches.push({
+				code: err.code,
+				message: err.message,
+				description: `replace "${missing}" with "${suggested}" at ${err.pos.line}:${err.pos.col}`,
+				apply: (text) => {
+					const lines = text.split(/\r?\n/);
+					const idx = err.pos.line - 1;
+					const line = lines[idx] ?? "";
+					const re = new RegExp(`\\b${escapeRegex(missing)}\\b`);
+					lines[idx] = line.replace(re, suggested);
+					return lines.join("\n");
+				}
+			});
+		}
+		if (err.code === "E0001") patches.push({
+			code: err.code,
+			message: err.message,
+			description: `add "/404" -> NotFound to app.routes (you must define a NotFound tile)`,
+			apply: (text) => {
+				return `\ntile NotFound = page(heading("404"))\n` + text.replace(/(routes\s*=\s*\{)([^}]*)(\})/, (_m, open, body, close) => {
+					if (body.includes("\"/404\"")) return `${open}${body}${close}`;
+					const trimmed = body.trimEnd();
+					return `${open}${body}${trimmed.endsWith(",") || trimmed.endsWith("{") ? "" : ","} "/404" -> NotFound ${close}`;
+				});
+			}
+		});
+	}
+	return patches;
+}
+function fixCmd(path, apply, onlyCode) {
+	const store = load(path);
+	const errors = check(store.program);
+	if (errors.length === 0) {
+		console.log("no errors");
+		return;
+	}
+	let patches = planFixes(store, errors);
+	if (onlyCode) patches = patches.filter((p) => p.code === onlyCode);
+	if (patches.length === 0) {
+		console.log("(no auto-patches available)");
+		for (const e of errors) console.error(`${e.code} ${e.message}`);
+		return;
+	}
+	if (!apply) {
+		for (const p of patches) {
+			console.log(`${p.code} ${p.message}`);
+			console.log(`  fix: ${p.description}`);
+		}
+		return;
+	}
+	let text = readFileSync(path, "utf8");
+	for (const p of patches) text = p.apply(text);
+	writeFileSync(path, text);
+	try {
+		const after = check(parse(lex(text)));
+		if (after.length === 0) console.log(`applied ${patches.length} fix(es) — file now clean`);
+		else console.log(`applied ${patches.length} fix(es) — ${after.length} error(s) remain`);
+	} catch (e) {
+		console.error(`fixes broke the file: ${String(e)}`);
+	}
+}
+//#endregion
+//#region src/mutate.ts
+const ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function ulid() {
+	let s = "op_";
+	for (let i = 0; i < 16; i++) s += ULID_ALPHABET[Math.floor(Math.random() * 32)];
+	return s;
+}
+function logOp(path, op) {
+	const enriched = {
+		...op,
+		opId: ulid(),
+		ts: Date.now()
+	};
+	appendFileSync(`${path}.kumiki-ops.jsonl`, `${JSON.stringify(enriched)}\n`);
+}
+/**
+* Validate that after the write the file still parses and typechecks.
+* Returns the error list (empty array = success).
+*/
+function validate(path) {
+	try {
+		const errors = check(parse(lex(readFileSync(path, "utf8"))));
+		if (errors.length > 0) return {
+			ok: false,
+			message: `Validation failed: ${errors.slice(0, 3).map((e) => `${e.code} ${e.message}`).join("; ")}`
+		};
+		return { ok: true };
+	} catch (e) {
+		return {
+			ok: false,
+			message: `Parse/lex failed: ${String(e)}`
+		};
+	}
+}
+function addDef(path, layer, name, body) {
+	const src = readFileSync(path, "utf8");
+	const inserted = assemble(layer, name, body);
+	writeFileSync(path, src.endsWith("\n") ? `${src}\n${inserted}\n` : `${src}\n\n${inserted}\n`);
+	const v = validate(path);
+	if (!v.ok) {
+		writeFileSync(path, src);
+		throw new Error(`add rejected: ${v.message}`);
+	}
+	logOp(path, {
+		op: "add",
+		layer,
+		name,
+		body
+	});
+}
+function replaceDef(path, qname, body) {
+	const store = load(path);
+	const entry = store.byQName.get(qname);
+	if (!entry) throw new Error(`Definition "${qname}" not found`);
+	const before = store.lines.slice(0, entry.range.startLine - 1);
+	const after = store.lines.slice(entry.range.endLine);
+	const inserted = assemble(entry.layer, entry.name, body).split(/\r?\n/);
+	const next = [
+		...before,
+		...inserted,
+		...after
+	].join("\n");
+	const original = store.source;
+	writeFileSync(path, next);
+	const v = validate(path);
+	if (!v.ok) {
+		writeFileSync(path, original);
+		throw new Error(`replace rejected: ${v.message}`);
+	}
+	logOp(path, {
+		op: "replace",
+		layer: entry.layer,
+		name: entry.name,
+		body
+	});
+}
+function removeDef(path, qname, cascade) {
+	const store = load(path);
+	const entry = store.byQName.get(qname);
+	if (!entry) throw new Error(`Definition "${qname}" not found`);
+	const refs = findReferences(store, qname);
+	if (refs.length > 0 && !cascade) {
+		const summary = refs.slice(0, 5).map((r) => `${r.qname}:${r.line}`).join(", ");
+		throw new Error(`Cannot remove ${qname}: ${refs.length} references (${summary}). Re-run with --cascade.`);
+	}
+	const toRemove = new Set([qname]);
+	if (cascade) {
+		let frontier = [qname];
+		while (frontier.length > 0) {
+			const next = [];
+			for (const q of frontier) for (const r of findReferences(store, q)) if (!toRemove.has(r.qname)) {
+				toRemove.add(r.qname);
+				next.push(r.qname);
+			}
+			frontier = next;
+		}
+	}
+	const removalEntries = [...toRemove].map((q) => store.byQName.get(q)).filter((e) => !!e).sort((a, b) => b.range.startLine - a.range.startLine);
+	let lines = store.lines.slice();
+	for (const e of removalEntries) lines = [...lines.slice(0, e.range.startLine - 1), ...lines.slice(e.range.endLine)];
+	const next = lines.join("\n");
+	const original = store.source;
+	writeFileSync(path, next);
+	const v = validate(path);
+	if (!v.ok) {
+		writeFileSync(path, original);
+		throw new Error(`remove rejected: ${v.message}`);
+	}
+	logOp(path, {
+		op: "remove",
+		layer: entry.layer,
+		name: entry.name,
+		cascade
+	});
+}
+function renameDef(path, qname, newName) {
+	const store = load(path);
+	const entry = store.byQName.get(qname);
+	if (!entry) throw new Error(`Definition "${qname}" not found`);
+	const old = entry.name;
+	const re = new RegExp(`\\b${escapeRegExp(old)}\\b`, "g");
+	const next = store.lines.map((line) => {
+		let result = "";
+		let i = 0;
+		while (i < line.length) {
+			const ch = line[i];
+			if (ch === "#") {
+				result += line.slice(i);
+				break;
+			}
+			if (ch === "\"") {
+				const start = i;
+				i++;
+				while (i < line.length && line[i] !== "\"") {
+					if (line[i] === "\\") i++;
+					i++;
+				}
+				i++;
+				result += line.slice(start, i);
+				continue;
+			}
+			result += ch;
+			i++;
+		}
+		const codePart = result;
+		const tail = line.slice(codePart.length);
+		return codePart.replace(re, newName) + tail;
+	}).join("\n");
+	const original = store.source;
+	writeFileSync(path, next);
+	const v = validate(path);
+	if (!v.ok) {
+		writeFileSync(path, original);
+		throw new Error(`rename rejected: ${v.message}`);
+	}
+	logOp(path, {
+		op: "rename",
+		layer: entry.layer,
+		name: old,
+		newName
+	});
+}
+function escapeRegExp(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function assemble(layer, name, body) {
+	switch (layer) {
+		case "type": return `type ${name} = ${body}`;
+		case "slot": return `slot ${name} : ${body}`;
+		case "effect": return `effect ${name} ${body}`;
+		case "reducer": return `reducer ${name} ${body}`;
+		case "tile": return `tile ${name} = ${body}`;
+		case "fn": return `fn ${name}${body.startsWith("(") ? "" : " "}${body}`;
+		case "app": return `app ${name}\n${body}`;
+		case "theme": return `theme ${name} = ${body}`;
+		default: throw new Error(`Unknown layer "${layer}"`);
+	}
+}
+//#endregion
+//#region src/smoke.ts
+let domReady = false;
+function ensureDom() {
+	if (domReady) return;
+	const dom = new JSDOM("<!doctype html><html><body></body></html>", { url: "http://localhost/" });
+	const g = globalThis;
+	const w = dom.window;
+	for (const key of [
+		"window",
+		"document",
+		"navigator",
+		"location",
+		"history",
+		"localStorage",
+		"sessionStorage",
+		"HTMLElement",
+		"HTMLInputElement",
+		"HTMLSelectElement",
+		"HTMLTextAreaElement",
+		"Element",
+		"Node",
+		"Event",
+		"MouseEvent",
+		"CustomEvent",
+		"KeyboardEvent",
+		"CSS",
+		"getComputedStyle"
+	]) {
+		if (w[key] === void 0) continue;
+		try {
+			g[key] = w[key];
+		} catch {
+			Object.defineProperty(g, key, {
+				value: w[key],
+				configurable: true,
+				writable: true
+			});
+		}
+	}
+	domReady = true;
+}
+async function loadApp(source) {
+	const result = compile(source, {
+		runtimeSpecifier: "ignored",
+		bundle: true,
+		readRuntimeBundle: nodeRuntimeBundleReader
+	});
+	if (result.kind !== "ok") throw new Error(`compile failed:\n${result.errors.map((e) => `${e.code} ${e.message}`).join("\n")}`);
+	const patched = result.js.replace(/mount\(App, document\.getElementById\("root"\)\);?/, "");
+	const file = join(mkdtempSync(join(tmpdir(), "kumiki-smoke-")), "app.mjs");
+	writeFileSync(file, patched);
+	await import(pathToFileURL(file).href);
+	const app = globalThis.__kumikiApp;
+	if (!app) throw new Error("compiled module did not expose __kumikiApp");
+	return app;
+}
+/** Compile + mount + exercise a Kumiki source string; return the smoke report. */
+async function smokeSource(source) {
+	ensureDom();
+	const app = await loadApp(source);
+	const doc = globalThis.document;
+	const root = doc.createElement("div");
+	doc.body.appendChild(root);
+	try {
+		return await smoke(app, root, { settleMs: 20 });
+	} finally {
+		root.remove();
+	}
+}
+async function smokeFile(path) {
+	return smokeSource(readFileSync(path, "utf8"));
+}
+/** CLI entry: print a human-readable report and exit non-zero on failure. */
+async function smokeCmd(path) {
+	const report = await smokeFile(path);
+	if (report.ok) {
+		console.log(`ok — mounted, rendered, ${report.interactions} interaction(s), no runtime errors`);
+		return;
+	}
+	console.error(`runtime smoke failed (mounted=${report.mounted}, rendered=${report.rendered}, interactions=${report.interactions}):`);
+	for (const i of report.issues) console.error(`  [${i.phase}] ${i.message}${i.trigger ? ` (on ${i.trigger})` : ""}`);
+	process.exit(1);
+}
+/** Compile + mount + drive a scenario; return the structured trace. */
+async function runScenarioSource(source, scenario) {
+	ensureDom();
+	const app = await loadApp(source);
+	const doc = globalThis.document;
+	const root = doc.createElement("div");
+	doc.body.appendChild(root);
+	try {
+		return await runScenario(app, root, scenario, { settleMs: 20 });
+	} finally {
+		root.remove();
+	}
+}
+/** CLI entry: run a scenario JSON file against a .kumiki file; print the trace. */
+async function runCmd(kumikiPath, scenarioPath) {
+	const scenario = JSON.parse(readFileSync(scenarioPath, "utf8"));
+	const report = await runScenarioSource(readFileSync(kumikiPath, "utf8"), scenario);
+	for (let i = 0; i < report.steps.length; i++) {
+		const s = report.steps[i];
+		if (!s) continue;
+		const head = `step ${i}${s.label ? ` (${s.label})` : ""}${s.action ? `: ${s.action}` : ""}`;
+		const status = s.errors.length === 0 && s.failures.length === 0 ? "ok" : "FAIL";
+		console.log(`[${status}] ${head}`);
+		for (const e of s.errors) console.log(`    error: ${e}`);
+		for (const f of s.failures) console.log(`    assert: ${f}`);
+	}
+	console.log(report.ok ? "\nscenario passed" : "\nscenario FAILED");
+	if (!report.ok) process.exit(1);
+}
+//#endregion
+export { viewWithDeps as _, smokeSource as a, renameDef as c, planFixes as d, directDeps as f, viewDef as g, load as h, smokeFile as i, replaceDef as l, listDefs as m, runScenarioSource as n, addDef as o, findReferences as p, smokeCmd as r, removeDef as s, runCmd as t, fixCmd as u };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kumikijs/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Kumiki CLI — build, check, and AI-edit (list/view/add/replace/remove/rename/fix) Kumiki sources.",
+  "license": "Apache-2.0",
+  "author": "kage1020",
+  "homepage": "https://github.com/kage1020/Kumiki/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kage1020/Kumiki.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/kage1020/Kumiki/issues",
+  "keywords": [
+    "kumiki",
+    "ai-first",
+    "cli",
+    "compiler",
+    "codegen"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "kumiki": "./dist/kumiki.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./kumiki": "./src/kumiki.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./kumiki": "./dist/kumiki.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "biome check src test",
+    "kumiki": "tsx src/kumiki.ts"
+  },
+  "dependencies": {
+    "@kumikijs/compiler": "workspace:*",
+    "@kumikijs/runtime": "workspace:*",
+    "jsdom": "catalog:"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}