@x18n/cli 0.0.2 → 0.0.3

package/dist/cli.d.mts

@@ -0,0 +1,4 @@
+import { CAC } from "cac";
+//#region src/cli.d.ts
+export declare function createCli(): CAC;
+//#endregion

package/dist/cli.mjs

@@ -0,0 +1,689 @@
+import { a as openWorkspace, c as readInput, d as stdinArg, f as useColor, i as exitCodeOf, l as runPlan, n as displayPath, o as out, p as wireDiagnostics, r as errorInfo, s as printJson, t as cwd, u as singleProject } from "./context-Za_ea1Nk.mjs";
+import { createRequire } from "node:module";
+import { PluginFileSchema, X18nError, isJsonObject, parseMessageBatch, placeholderProblems, renderPrompt, toWireRange, validate } from "@x18n/core";
+import process from "node:process";
+import cac from "cac";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { configFileNames, findConfigFile, loadWorkspace, migrateI18nAlly } from "@x18n/node";
+import { extractItems, findCandidates, toPlanFile } from "@x18n/builtins/extractors";
+import { existsSync } from "node:fs";
+import { namespaceFromPath } from "@x18n/builtins/finders";
+import { parse, stringify } from "yaml";
+//#region package.json
+var version = "0.0.3";
+//#endregion
+//#region src/commands/change.ts
+async function project(options) {
+	return singleProject(await openWorkspace(options));
+}
+async function set(key, options) {
+	if (options.value === void 0) throw new X18nError("X18N4008", "pass --value <text> (or --value - to read stdin)");
+	const loaded = await project(options);
+	const value = options.value === "\0stdin" ? (await readInput(stdinArg)).replace(/\r?\n$/, "") : String(options.value);
+	const locale = options.locale ?? loaded.project.sourceLocale;
+	await runPlan("set", loaded, loaded.project.plan([{
+		type: "set",
+		key: loaded.project.parseKey(key),
+		locale,
+		value
+	}]), options);
+}
+async function apply(source, options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	let data;
+	try {
+		data = JSON.parse(await readInput(source));
+	} catch (error) {
+		throw new X18nError("X18N4008", `${source} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const ops = parseMessageBatch(p, data);
+	const rejected = placeholderProblems(p, ops);
+	if (rejected.length > 0 && !options.force) {
+		if (options.json) {
+			printJson("apply", {
+				applied: false,
+				rejected
+			}, [], [new X18nError("X18N4007", `${rejected.length} values`).toJSON()]);
+			return 1;
+		}
+		for (const r of rejected) out(`rejected ${r.locale} ${r.key}: ${[r.missing.length ? `missing ${r.missing.join(", ")}` : "", r.extra.length ? `unexpected ${r.extra.join(", ")}` : ""].filter(Boolean).join("; ")}`);
+		out(`${rejected.length} values have placeholder problems; nothing was written. Fix them or pass --force.`);
+		return 1;
+	}
+	await runPlan("apply", loaded, p.plan(ops), options);
+	return 0;
+}
+async function rename(from, to, options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	const op = {
+		type: "rename",
+		from: p.parseKey(from),
+		to: p.parseKey(to),
+		usages: options.usages !== false
+	};
+	await runPlan("rename", loaded, p.plan([op]), options);
+}
+async function remove(key, options) {
+	const loaded = await project(options);
+	const locales = options.locale === void 0 ? "all" : [options.locale].flat();
+	await runPlan("delete", loaded, loaded.project.plan([{
+		type: "delete",
+		key: loaded.project.parseKey(key),
+		locales
+	}]), options);
+}
+async function fill(options) {
+	const loaded = await project(options);
+	const p = loaded.project;
+	const targets = options.locale === void 0 ? p.locales.filter((l) => l !== p.sourceLocale) : [options.locale].flat();
+	const ops = [];
+	for (const locale of targets) for (const key of p.keys({ missing: locale })) {
+		if (p.message(key, locale) !== void 0) continue;
+		ops.push({
+			type: "set",
+			key,
+			locale,
+			value: options.copySource ? p.message(key, p.sourceLocale)?.value ?? "" : ""
+		});
+	}
+	await runPlan("fill", loaded, p.plan(ops), options);
+}
+async function format(options) {
+	const loaded = await project(options);
+	await runPlan("format", loaded, loaded.project.plan([{ type: "format" }]), options);
+}
+//#endregion
+//#region src/commands/check.ts
+function list(value) {
+	return value === void 0 ? [] : [value].flat().flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean);
+}
+function filterDiagnostics(diagnostics, options) {
+	const locales = list(options.locale);
+	const only = list(options.only);
+	const skip = list(options.skip);
+	return diagnostics.filter((d) => locales.length === 0 || d.locale === void 0 || locales.includes(d.locale) || d.code === "missing-translation" && locales.some((l) => d.message.includes(l))).filter((d) => only.length === 0 || only.includes(d.code)).filter((d) => !skip.includes(d.code)).map((d) => options.strict && d.severity === "warning" ? {
+		...d,
+		severity: "error"
+	} : d);
+}
+function reportInputs(workspace, options) {
+	return workspace.projects.map((loaded) => {
+		const analysis = loaded.project.analyze();
+		const diagnostics = filterDiagnostics(analysis.diagnostics, options);
+		return {
+			project: loaded.name,
+			text: (path) => loaded.project.text(path),
+			diagnostics,
+			coverage: analysis.coverage,
+			summary: {
+				errors: diagnostics.filter((d) => d.severity === "error").length,
+				warnings: diagnostics.filter((d) => d.severity === "warning").length,
+				infos: diagnostics.filter((d) => d.severity === "info" || d.severity === "hint").length,
+				files: new Set(diagnostics.flatMap((d) => d.location ? [d.location.path] : [])).size
+			}
+		};
+	});
+}
+async function report(workspace, options) {
+	const inputs = reportInputs(workspace, options);
+	const reporterIds = list(options.reporter);
+	const ids = reporterIds.length ? reporterIds : [options.json ? "json" : "pretty"];
+	const outputs = list(options.output);
+	const available = workspace.projects[0]?.project.reporters ?? /* @__PURE__ */ new Map();
+	const roots = new Map(workspace.projects.map((p) => [p.name, p.root]));
+	for (const [i, id] of ids.entries()) {
+		const reporter = available.get(id);
+		if (!reporter) throw new X18nError("X18N0001", `unknown reporter "${id}" (${[...available.keys()].join(", ")})`);
+		const text = await reporter.report(inputs, {
+			color: !outputs[i] && useColor(options) && id === "pretty",
+			displayPath: (path, project) => displayPath(roots.get(project) ?? "", path)
+		});
+		if (outputs[i]) await writeFile(outputs[i], text);
+		else if (text) process.stdout.write(text);
+	}
+	const errors = inputs.reduce((sum, input) => sum + input.summary.errors, 0);
+	const warnings = inputs.reduce((sum, input) => sum + input.summary.warnings, 0);
+	const tooManyWarnings = options.maxWarnings !== void 0 && warnings > Number(options.maxWarnings);
+	return errors > 0 || tooManyWarnings ? 1 : 0;
+}
+async function check(options) {
+	const workspace = await openWorkspace(options);
+	const code = await report(workspace, options);
+	if (!options.watch) return code;
+	const rerun = async () => {
+		if (process.stdout.isTTY) process.stdout.write("\x1Bc");
+		out(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] File change detected. Checking...\n`);
+		await report(workspace, options);
+	};
+	for (const loaded of workspace.projects) {
+		loaded.project.watch();
+		loaded.project.onChange(() => void rerun());
+	}
+	out("\nWatching for file changes.");
+	return new Promise(() => {});
+}
+//#endregion
+//#region src/commands/extract.ts
+function isPlanItem(value) {
+	if (!isJsonObject(value) || !isJsonObject(value.range)) return false;
+	return [
+		"path",
+		"original",
+		"key",
+		"value",
+		"replacement"
+	].every((field) => typeof value[field] === "string") && typeof value.range.start === "number" && typeof value.range.end === "number" && Array.isArray(value.imports) && value.imports.every((line) => typeof line === "string");
+}
+async function readPlan(file) {
+	const data = JSON.parse(await readFile(file, "utf8"));
+	if (!isJsonObject(data) || !Array.isArray(data.items) || !data.items.every(isPlanItem)) throw new X18nError("X18N4008", `${file} is not an extraction plan`);
+	return data.items;
+}
+/** One question per string in a TTY: extract with the proposed key, a typed key, or skip. */
+async function review(candidates, root) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	const picked = [];
+	try {
+		for (const candidate of candidates) {
+			process.stderr.write(`\n${displayPath(root, candidate.path)}:${candidate.line}  ${JSON.stringify(candidate.text)}\n  → ${candidate.replacement}\n`);
+			const reply = (await rl.question(`Extract as "${candidate.key}"? [Y/n/key/q] `)).trim();
+			if (reply === "q") break;
+			if (reply === "n") continue;
+			picked.push(reply && reply !== "y" ? {
+				...candidate,
+				key: reply,
+				replacement: candidate.replacement.replace(candidate.key, reply)
+			} : candidate);
+		}
+	} finally {
+		rl.close();
+	}
+	return picked;
+}
+async function extract(files, options) {
+	const loaded = singleProject(await openWorkspace(options));
+	const { project } = loaded;
+	if (options.apply) {
+		const items = extractItems(project, await readPlan(options.apply));
+		await runPlan("extract", loaded, project.plan([{
+			type: "extract",
+			items
+		}]), options);
+		return;
+	}
+	const candidates = findCandidates(project, { files });
+	if (options.plan) {
+		await writeFile(options.plan, `${JSON.stringify(toPlanFile(project, candidates), null, 2)}\n`);
+		if (options.json) printJson("extract", {
+			plan: options.plan,
+			items: candidates.length
+		});
+		else out(`Wrote ${candidates.length} strings to ${options.plan}. Edit keys and replacements, then run \`x18n extract --apply ${options.plan}\`.`);
+		return;
+	}
+	const interactive = !options.list && !options.yes && !options.json && process.stdin.isTTY;
+	if (options.list || !interactive && !options.yes) {
+		if (options.json) {
+			printJson("extract", { items: candidates.map((c) => ({
+				...c,
+				file: displayPath(loaded.root, c.path)
+			})) });
+			return;
+		}
+		for (const c of candidates) out(`${displayPath(loaded.root, c.path)}:${c.line}\t${c.kind}\t${JSON.stringify(c.text)}\t→ ${c.key}${c.reused ? " (existing)" : ""}`);
+		out(`${candidates.length} strings. Apply with \`x18n extract --yes\`, or review with \`x18n extract --plan plan.json\`.`);
+		return;
+	}
+	const chosen = interactive ? await review(candidates, loaded.root) : candidates;
+	if (chosen.length === 0) {
+		out("Nothing to extract.");
+		return;
+	}
+	await runPlan("extract", loaded, project.plan([{
+		type: "extract",
+		items: extractItems(project, chosen)
+	}]), options);
+}
+//#endregion
+//#region src/commands/look.ts
+function percent(coverage) {
+	return coverage.total === 0 ? 100 : Math.floor(coverage.translated / coverage.total * 1e3) / 10;
+}
+function summaryOf(loaded) {
+	const diagnostics = loaded.project.analyze().diagnostics;
+	return {
+		errors: diagnostics.filter((d) => d.severity === "error").length,
+		warnings: diagnostics.filter((d) => d.severity === "warning").length,
+		infos: diagnostics.filter((d) => d.severity === "info" || d.severity === "hint").length
+	};
+}
+function statusData(loaded) {
+	const { project } = loaded;
+	return {
+		name: loaded.name,
+		root: displayPath(loaded.root, ""),
+		sourceLocale: project.sourceLocale,
+		locales: project.analyze().coverage.map((c) => ({
+			locale: c.locale,
+			total: c.total,
+			translated: c.translated,
+			missing: c.missing.length,
+			empty: c.empty.length,
+			percent: percent(c)
+		})),
+		resources: project.resources.length,
+		keys: project.keys().length,
+		usages: project.usages().length,
+		summary: summaryOf(loaded)
+	};
+}
+async function status(options) {
+	const workspace = await openWorkspace(options);
+	if (options.json) {
+		printJson("status", { projects: workspace.projects.map(statusData) });
+		return;
+	}
+	for (const loaded of workspace.projects) {
+		const { project } = loaded;
+		const summary = summaryOf(loaded);
+		out(`${loaded.name} (${displayPath(loaded.root, "")})`);
+		out(`  ${project.resources.length} resources, ${project.keys().length} keys, ${project.usages().length} usages`);
+		for (const c of project.analyze().coverage) {
+			const label = `${c.locale}${c.locale === project.sourceLocale ? " (source)" : ""}`;
+			out(`  ${label.padEnd(16)} ${String(percent(c)).padStart(5)}%  ${c.translated}/${c.total}${c.missing.length ? `, ${c.missing.length} missing` : ""}${c.empty.length ? `, ${c.empty.length} empty` : ""}`);
+		}
+		out(`  ${summary.errors} errors, ${summary.warnings} warnings`);
+	}
+}
+/** One page of a list: `--limit` items from `--cursor`, plus the cursor of the next page. */
+function page(items, options) {
+	const start = Number(options.cursor ?? 0) || 0;
+	const end = options.limit ? start + Number(options.limit) : items.length;
+	return {
+		items: items.slice(start, end),
+		total: items.length,
+		nextCursor: end < items.length ? String(end) : void 0
+	};
+}
+async function keys(glob, options) {
+	const workspace = await openWorkspace(options);
+	const projects = workspace.projects.map((loaded) => {
+		const { project } = loaded;
+		const { items, total, nextCursor } = page(project.keys({
+			glob,
+			missing: options.missing,
+			unused: options.unused,
+			namespace: options.namespace
+		}), options);
+		const values = (key) => Object.fromEntries(project.locales.map((locale) => [locale, project.message(key, locale)?.value]));
+		return {
+			name: loaded.name,
+			total,
+			nextCursor,
+			keys: items.map((key) => options.values ? {
+				key,
+				values: values(key)
+			} : { key })
+		};
+	});
+	if (options.json) {
+		printJson("keys", { projects });
+		return;
+	}
+	for (const p of projects) {
+		if (workspace.projects.length > 1) out(`# ${p.name}`);
+		for (const item of p.keys) out("values" in item ? `${item.key}\t${JSON.stringify(item.values)}` : item.key);
+		if (p.nextCursor) out(`… ${p.total - Number(p.nextCursor)} more (--cursor ${p.nextCursor})`);
+	}
+}
+function locate(loaded, path, start, end) {
+	const range = toWireRange(loaded.project.text(path), start, end);
+	return {
+		file: displayPath(loaded.root, path),
+		line: range.line,
+		column: range.column
+	};
+}
+async function get(input, options) {
+	const workspace = await openWorkspace(options);
+	const projects = workspace.projects.flatMap((loaded) => {
+		const { project } = loaded;
+		const info = project.get(project.parseKey(input));
+		if (!info) return [];
+		const resourceOf = (id) => project.resources.find((r) => r.id === id)?.path ?? id;
+		return [{
+			name: loaded.name,
+			key: info.key,
+			namespace: info.namespace,
+			messages: info.messages.map((m) => ({
+				locale: m.locale,
+				value: m.value,
+				...locate(loaded, resourceOf(m.resource), m.range?.key.start ?? 0, m.range?.key.end ?? 0)
+			})),
+			missing: info.missing,
+			usages: info.usages.map((u) => ({
+				possible: u.possible,
+				raw: u.usage.raw,
+				...locate(loaded, u.usage.path, u.usage.range.start, u.usage.range.end)
+			})),
+			diagnostics: wireDiagnostics(loaded, info.diagnostics)
+		}];
+	});
+	if (options.json) {
+		printJson("get", { projects });
+		return;
+	}
+	if (projects.length === 0) out(`"${input}" is not defined.`);
+	for (const p of projects) {
+		out(`${p.key}${workspace.projects.length > 1 ? ` (${p.name})` : ""}`);
+		for (const m of p.messages) out(`  ${m.locale.padEnd(8)} ${JSON.stringify(m.value)}  ${m.file}:${m.line}:${m.column}`);
+		if (p.missing.length) out(`  missing in ${p.missing.join(", ")}`);
+		out(`  ${p.usages.length} usages`);
+		for (const u of p.usages) out(`    ${u.file}:${u.line}:${u.column}${u.possible ? " (possible)" : ""}`);
+		for (const d of p.diagnostics) out(`  ${d.severity} ${d.code}: ${d.message}`);
+	}
+}
+async function usages(input, options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => {
+		const { project } = loaded;
+		const { items, total, nextCursor } = page(project.usages({
+			key: input === void 0 ? void 0 : project.parseKey(input),
+			path: options.file
+		}), options);
+		return {
+			name: loaded.name,
+			total,
+			nextCursor,
+			usages: items.map((m) => ({
+				key: m.usage.key,
+				raw: m.usage.raw,
+				possible: m.possible,
+				dynamic: m.usage.dynamic,
+				...locate(loaded, m.usage.path, m.usage.range.start, m.usage.range.end)
+			}))
+		};
+	});
+	if (options.json) {
+		printJson("usages", { projects });
+		return;
+	}
+	for (const p of projects) for (const u of p.usages) out(`${u.file}:${u.line}:${u.column}\t${u.key ?? u.raw}${u.possible ? " (possible)" : ""}`);
+}
+async function locales(options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => ({
+		name: loaded.name,
+		sourceLocale: loaded.project.sourceLocale,
+		locales: loaded.project.locales.map((code) => ({
+			...loaded.project.localeInfo(code),
+			resources: loaded.project.resources.filter((r) => r.locale === code).map((r) => displayPath(loaded.root, r.path))
+		}))
+	}));
+	if (options.json) {
+		printJson("locales", { projects });
+		return;
+	}
+	for (const p of projects) for (const l of p.locales) out(`${l.code.padEnd(10)} ${(l.displayName ?? "").padEnd(28)} ${l.resources.join(", ")}`);
+}
+async function doctor(options) {
+	const projects = (await openWorkspace(options)).projects.map((loaded) => ({
+		...loaded.project.explain(),
+		root: displayPath(loaded.root, ""),
+		configFile: loaded.configFile && displayPath(loaded.configFile, "")
+	}));
+	if (options.json) {
+		printJson("doctor", { projects });
+		return;
+	}
+	for (const e of projects) {
+		out(`# ${e.name} (${e.root})`);
+		out(`config: ${e.configFile ?? "none (detection only)"}`);
+		out(`presets:`);
+		const applied = e.presets.filter((p) => p.reason === "detected" || p.reason === "listed");
+		for (const p of applied) out(`  ✓ ${p.name} (${p.reason})`);
+		if (applied.length === 0) out("  none");
+		if (e.presets.length > applied.length) out(`  ${e.presets.length - applied.length} others not applied (--json lists them)`);
+		out("finders:");
+		for (const f of e.finders) out(`  ${f.id}: ${f.resources.length} resources${f.resources.length ? `\n    ${f.resources.slice(0, 20).join("\n    ")}` : ""}`);
+		out("formats:");
+		for (const f of e.formats.filter((f) => f.resources > 0)) out(`  ${f.id} (${f.extensions.join(", ")}): ${f.resources} resources`);
+		out("scanners:");
+		for (const s of e.scanners) out(`  ${s.id} (${s.extensions.join(", ") || "none"}): ${s.files} files`);
+		if (e.conflicts.length) out(`conflicts:\n${e.conflicts.map((c) => `  .${c.extension}: ${c.winner} wins over ${c.loser}`).join("\n")}`);
+		if (e.errors.length) out(`errors:\n${e.errors.map((err) => `  ${err.code} ${err.message}`).join("\n")}`);
+		out("config origins:");
+		for (const [key, origin] of Object.entries(e.config.origins)) out(`  ${key}: ${origin}`);
+	}
+}
+//#endregion
+//#region src/commands/migrate.ts
+async function migrate(source, options) {
+	if (source !== "i18n-ally") throw new X18nError("X18N0001", `unknown migration source "${source}" (i18n-ally)`);
+	const root = resolve(options.root ?? cwd());
+	const result = await migrateI18nAlly(root, { format: options.format });
+	const existing = findConfigFile(root);
+	if (existing && !options.force && !options.dryRun && result.files.length > 0) throw new X18nError("X18N0001", `${existing} already exists (pass --force to replace it)`);
+	if (!options.dryRun) for (const file of result.files) {
+		const path = join(root, file.path);
+		await mkdir(dirname(path), { recursive: true });
+		if (file.path === ".x18n/reviews.yml" && existsSync(path)) continue;
+		await writeFile(path, file.content);
+	}
+	if (options.json) {
+		printJson("migrate", {
+			...result,
+			written: !options.dryRun
+		});
+		return;
+	}
+	for (const file of result.files) out(options.dryRun ? `--- ${file.path}\n${file.content}` : `wrote ${file.path}`);
+	for (const note of result.notes) out(`note: ${note}`);
+	if (result.removable.length) out(`These i18n-ally settings can be removed now:\n${result.removable.map((key) => `  ${key}`).join("\n")}`);
+}
+//#endregion
+//#region src/commands/prompt.ts
+async function prompt(kind, options) {
+	if (kind !== "translate" && kind !== "review") throw new X18nError("X18N0001", `unknown prompt "${kind}" (translate, review)`);
+	const locale = kind === "translate" ? options.to : options.locale ?? options.to;
+	if (!locale) throw new X18nError("X18N0001", kind === "translate" ? "pass --to <locale>" : "pass --locale <locale>");
+	const { project } = singleProject(await openWorkspace(options));
+	const data = project.prompt(kind, locale, {
+		keys: options.keys,
+		namespace: options.namespace,
+		limit: options.limit === void 0 ? void 0 : Number(options.limit),
+		cursor: options.cursor,
+		context: options.context
+	});
+	if (options.json || options.format === "json") printJson(`prompt ${kind}`, data);
+	else out(renderPrompt(data));
+}
+//#endregion
+//#region src/commands/setup.ts
+async function schema(name, options) {
+	const which = name ?? "config";
+	if (which !== "config" && which !== "plugin") throw new X18nError("X18N0001", `unknown schema "${which}" (config, plugin)`);
+	const require = createRequire(import.meta.url);
+	const text = await readFile(require.resolve(`@x18n/core/schema/${which}.json`), "utf8");
+	if (options.json) printJson("schema", {
+		name: which,
+		schema: JSON.parse(text)
+	});
+	else out(text);
+}
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The folders and file name that name `namespace`, in the style of `namespace.fromPath`. */
+function namespaceSpan(parts, namespace, fromPath) {
+	for (let start = 0; start < parts.length; start++) for (let end = start + 1; end <= parts.length; end++) if (namespaceFromPath(parts.slice(start, end).join("/"), fromPath) === namespace) return {
+		start,
+		end
+	};
+}
+/** The resource pattern that matches a found file: `public/locales/en/common.json` → `public/locales/{locale}/{namespaces}.{ext}`. */
+function patternOf(resource, fromPath) {
+	const parts = resource.path.replace(/\.[^./]+$/, "").split("/");
+	const span = resource.namespace === void 0 ? void 0 : namespaceSpan(parts, resource.namespace, fromPath);
+	if (span) parts.splice(span.start, span.end - span.start, "{namespaces}");
+	return `${parts.join("/")}.{ext}`.replace(new RegExp(`(^|[/._-])${escapeRegExp(resource.locale)}(?=[/._-])`), "$1{locale}");
+}
+async function init(options) {
+	const root = resolve(options.root ?? cwd());
+	const existing = findConfigFile(root);
+	if (existing && !options.force) throw new X18nError("X18N0001", `${existing} already exists (pass --force to replace it)`);
+	const { project } = (await loadWorkspace({
+		cwd: root,
+		cache: false
+	})).projects[0];
+	const detected = project.explain().presets.filter((p) => p.reason === "detected" && p.name !== "general").map((p) => p.name);
+	const resources = [...new Set(project.resources.filter((r) => !r.block).map((r) => patternOf(r, project.config.namespace.fromPath)))];
+	const config = {
+		sourceLocale: project.sourceLocale,
+		resources: resources.map((pattern) => ({ pattern }))
+	};
+	const format = options.format ?? "ts";
+	let file;
+	let content;
+	if (format === "yml" || format === "yaml") {
+		file = join(root, "x18n.config.yml");
+		content = `# yaml-language-server: $schema=https://x18n.antfu.dev/schema/config.json\n${stringify(config)}`;
+	} else if (format === "json") {
+		file = join(root, "x18n.config.json");
+		content = `${JSON.stringify({
+			$schema: "https://x18n.antfu.dev/schema/config.json",
+			...config
+		}, null, 2)}\n`;
+	} else {
+		file = join(root, "x18n.config.ts");
+		const body = JSON.stringify(config, null, 2).replace(/"(\w+)":/g, "$1:").replace(/"/g, "'");
+		content = `import { defineConfig } from '@x18n/core'\n\n// Detected presets: ${detected.join(", ") || "none"}. They apply automatically.\nexport default defineConfig(${body})\n`;
+	}
+	if (!configFileNames.some((name) => file.endsWith(name))) throw new X18nError("X18N0001", `unknown format "${format}" (ts, yml, json)`);
+	await writeFile(file, content);
+	if (options.json) printJson("init", {
+		file,
+		presets: detected,
+		config
+	});
+	else out(`Wrote ${file}\nDetected presets: ${detected.join(", ") || "none"}\nLocales: ${project.locales.join(", ")}`);
+}
+const literal = (value) => JSON.stringify(value, null, 2).replace(/"([a-z_$][\w$]*)":/gi, "$1:");
+/** The TS plugin equivalent of a YAML plugin, using the same built-in factories. */
+function ejectPlugin(data) {
+	const lines = [];
+	const configLines = [];
+	if (data.config) configLines.push(`    Object.assign(config, ${literal(data.config).replace(/\n/g, "\n    ")})`);
+	if (data.scanners?.calls || data.scanners?.regex) {
+		configLines.push(`    config.usage = {`, `      ...config.usage,`);
+		if (data.scanners.calls) configLines.push(`      calls: [...config.usage.calls, ...${literal(data.scanners.calls).replace(/\n/g, "\n      ")}],`);
+		if (data.scanners.regex) configLines.push(`      regex: [...config.usage.regex, ...${literal(data.scanners.regex).replace(/\n/g, "\n      ")}],`);
+		configLines.push(`    }`);
+	}
+	const fields = [`  name: ${literal(data.name)},`];
+	if (configLines.length) fields.push(`  config(config) {`, ...configLines, `  },`);
+	if (data.derivedKeys) fields.push(`  derivedKeys: ${literal(data.derivedKeys)},`);
+	if (data.placeholders) fields.push(`  placeholders: ${literal(data.placeholders)}.map(placeholderFromShape),`);
+	if (data.normalizeKey) {
+		const rules = data.normalizeKey.map((rule) => `.replace(new RegExp(${literal(rule.replace.pattern)}, 'g'), ${literal(rule.replace.with)})`).join("");
+		fields.push(`  normalizeKey: raw => raw${rules},`);
+	}
+	if (data.localeInfo) fields.push(`  localeInfo: code => (${literal(data.localeInfo)} as Record<string, { flag?: string, displayName?: string }>)[code],`);
+	const imports = ["definePlugin", ...data.detect ? ["definePreset"] : []];
+	lines.push(`import { ${imports.join(", ")} } from '@x18n/core'`);
+	if (data.placeholders) lines.push(`import { placeholderFromShape } from '@x18n/builtins/placeholders'`);
+	if (data.scopes) lines.push(`import { regexScopes } from '@x18n/builtins/scanners'`);
+	lines.push("", `const plugin = definePlugin({`, ...fields, `})`, "");
+	const plugins = `[plugin${data.scopes ? `, regexScopes(${literal(data.scopes.regex)})` : ""}]`;
+	if (data.detect) {
+		const any = data.detect.dependencies?.any;
+		lines.push(`export default definePreset({`, `  name: ${literal(data.name)},`, ...data.exclusive ? [`  exclusive: true,`] : [], `  detect: ctx => ${any ? `ctx.hasAnyDependency(${literal(any)})` : "true"},`, `  plugins: ${plugins},`, `})`);
+	} else lines.push(data.scopes ? `export default ${plugins}` : "export default plugin");
+	return `${lines.join("\n")}\n`;
+}
+async function eject(file, options) {
+	const path = resolve(cwd(), file);
+	if (!existsSync(path)) throw new X18nError("X18N1001", path);
+	const result = validate(PluginFileSchema, parse(await readFile(path, "utf8")));
+	if (!result.success) throw new X18nError("X18N1004", result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+	const code = ejectPlugin(result.output);
+	if (options.json) printJson("plugin eject", {
+		file: path,
+		code
+	});
+	else out(code);
+}
+//#endregion
+//#region src/cli.ts
+const uiCommands = () => import("./ui-Bp3xyqr_.mjs");
+/** Runs a command and turns errors into the JSON envelope or a printed hint, with the matching exit code. */
+function run(command, action) {
+	return async (...args) => {
+		const options = args.at(-1);
+		try {
+			const code = await action(...args);
+			process.exitCode = code ?? 0;
+		} catch (error) {
+			const info = errorInfo(error);
+			if (options.json) printJson(command, null, [], [info]);
+			else {
+				process.stderr.write(`error ${info.code}: ${info.message}\n`);
+				if (info.hint) process.stderr.write(`  ${info.hint}\n`);
+				if (!(error instanceof Error && "code" in error) && error instanceof Error && process.env.DEBUG) process.stderr.write(`${error.stack}\n`);
+			}
+			process.exitCode = exitCodeOf(error);
+		}
+	};
+}
+function createCli() {
+	const cli = cac("x18n");
+	cli.option("--root <dir>", "Project root (default: nearest config upward from the cwd)").option("--config <file>", "Explicit config file").option("--project <name>", "Pick one project in a monorepo").option("--json", "Print the JSON contract instead of human output").option("--no-cache", "Ignore the persistent cache").option("--yes", "Accept default answers for decisions");
+	cli.command("", "Show the status and the main commands").action(run("status", async (options) => {
+		await status(options);
+		if (!options.json) process.stdout.write("\nCommands: check, keys, get, usages, set, apply, rename, delete, fill, prompt translate, ui. Run `x18n --help` for all.\n");
+	}));
+	cli.command("status", "Locales with coverage, resources, keys and diagnostics").action(run("status", status));
+	cli.command("keys [glob]", "List keys").option("--missing <locale>", "Only keys missing or empty in a locale").option("--unused", "Only keys without usages").option("--namespace <ns>", "Only keys of a namespace").option("--values", "Include the value per locale").option("--limit <n>", "Page size").option("--cursor <cursor>", "Start of the page (from `nextCursor`)").action(run("keys", keys));
+	cli.command("get <key>", "Values, resources, usages and diagnostics of one key").action(run("get", get));
+	cli.command("usages [key]", "Usages of a key, or all usages").option("--file <path>", "Only usages in a file").option("--limit <n>", "Page size").option("--cursor <cursor>", "Start of the page").action(run("usages", usages));
+	cli.command("locales", "Locale codes as found, with display names and resources").action(run("locales", locales));
+	cli.command("doctor", "How the project was understood: presets, finders, formats, scanners, config origins").action(run("doctor", doctor));
+	cli.command("check", "Report invalid, untranslated and unused keys, like `tsc --noEmit`").option("--watch", "Re-check on change").option("--strict", "Turn every warning into an error").option("--locale <locale>", "Only report for these locales (repeatable)").option("--only <checks>", "Only these check ids (comma separated)").option("--skip <checks>", "Skip these check ids (comma separated)").option("--max-warnings <n>", "Fail when there are more warnings").option("--reporter <id>", "pretty, json, markdown, github or sarif (repeatable)").option("--output <file>", "Write the matching reporter output to a file (repeatable)").action(run("check", check));
+	cli.command("set <key>", "Set one value").option("--locale <locale>", "Locale (default: source locale)").option("--value <value>", "The value; `-` reads stdin").option("--dry-run", "Print the plan instead of writing").action(run("set", set));
+	cli.command("apply <file>", "Batch set from JSON `{ \"<locale>\": { \"<key>\": \"<value>\" } }`; `-` reads stdin").option("--force", "Write values with placeholder problems").option("--dry-run", "Print the plan instead of writing").action(run("apply", apply));
+	cli.command("rename <from> <to>", "Rename a key (or every key under a parent) in all locales and usages").option("--no-usages", "Keep code unchanged").option("--dry-run", "Print the plan instead of writing").action(run("rename", rename));
+	cli.command("delete <key>", "Delete a key (or every key under a parent) in all locales").option("--locale <locale>", "Only in these locales (repeatable)").option("--dry-run", "Print the plan instead of writing").action(run("delete", remove));
+	cli.command("fill", "Add missing keys with empty values").option("--locale <locale>", "Only these locales (repeatable)").option("--copy-source", "Use the source value instead of an empty string").option("--dry-run", "Print the plan instead of writing").action(run("fill", fill));
+	cli.command("format", "Re-write resources with the configured sort and indent").option("--dry-run", "Print the plan instead of writing").action(run("format", format));
+	cli.command("extract [...files]", "Find hard-coded strings and turn them into keys").option("--list", "Print candidates and proposed keys").option("--plan <file>", "Write the extraction plan to a file to edit").option("--apply <file>", "Apply an (edited) extraction plan").option("--dry-run", "Print the plan instead of writing").action(run("extract", extract));
+	cli.command("prompt <kind>", "Print a prompt for an agent or LLM: `prompt translate --to <locale>` or `prompt review --locale <locale>`").option("--to <locale>", "Target locale (translate)").option("--locale <locale>", "Locale to review").option("--keys <glob>", "Only keys matching a glob").option("--namespace <ns>", "Only keys of a namespace").option("--limit <n>", "Messages per prompt (default 50)").option("--cursor <cursor>", "Continue from `nextCursor`").option("--format <format>", "markdown (default) or json").option("--no-context", "Leave out code around usages").action(run("prompt", prompt));
+	cli.command("ui", "Start the UI: browse and edit messages in the browser, with HTTP MCP at /__mcp").option("--port <port>", "Port (default: a free one from 9999)").option("--host <host>", "Bind host (default: localhost)").option("--no-open", "Do not open the browser").option("--no-auth", "Skip authentication (CI and e2e only)").action(run("ui", async (options) => (await uiCommands()).ui(options)));
+	cli.command("build", "Write a static, read-only report of the UI").option("--out-dir <dir>", "Output directory (default: .x18n/report)").action(run("build", async (options) => (await uiCommands()).build(options)));
+	cli.command("mcp", "Serve the MCP tools over stdio").action(run("mcp", async (options) => (await uiCommands()).mcp(options)));
+	cli.command("init", "Detect the setup and write x18n.config.ts").option("--format <format>", "ts (default), yml or json").option("--force", "Replace an existing config").action(run("init", init));
+	cli.command("migrate <source>", "Convert i18n-ally settings: `migrate i18n-ally`").option("--format <format>", "ts (default), yml or json").option("--dry-run", "Print the files instead of writing").option("--force", "Replace an existing config").action(run("migrate", migrate));
+	cli.command("schema [name]", "Print a JSON Schema: config (default) or plugin").action(run("schema", schema));
+	cli.command("plugin <action> <file>", "Plugin tools: `plugin eject <file.yml>` prints the TS equivalent").action(run("plugin eject", async (action, file, options) => {
+		if (action !== "eject") throw new Error(`unknown plugin action "${action}"`);
+		await eject(file, options);
+	}));
+	cli.help();
+	cli.version(version);
+	return cli;
+}
+process.stdout.on("error", (error) => {
+	if (error.code === "EPIPE") process.exit(0);
+	throw error;
+});
+const argv = process.argv.map((arg) => arg === "-" ? stdinArg : arg);
+try {
+	createCli().parse(argv);
+} catch (error) {
+	process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 2;
+}
+//#endregion
+export { createCli };

package/dist/context-Za_ea1Nk.mjs

@@ -0,0 +1,148 @@
+import { X18nError, applyTextEdits, envelope, isX18nError, toWireDiagnostic } from "@x18n/core";
+import process from "node:process";
+import { Buffer } from "node:buffer";
+import { readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadWorkspace, stderrLogger } from "@x18n/node";
+//#region src/context.ts
+const cwd = () => process.cwd();
+function useColor(options) {
+	if (options.json || process.env.NO_COLOR) return false;
+	if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0") return true;
+	return process.stdout.isTTY === true;
+}
+async function openWorkspace(options) {
+	return loadWorkspace({
+		cwd: options.root ?? cwd(),
+		configFile: options.config,
+		upward: options.root === void 0,
+		project: options.project,
+		cache: options.cache !== false,
+		logger: stderrLogger
+	});
+}
+/** Write commands work on one project; a monorepo needs `--project`. */
+function singleProject(workspace) {
+	if (workspace.projects.length !== 1) throw new X18nError("X18N0003", `pick one with --project (${workspace.projects.map((p) => p.name).join(", ")})`);
+	return workspace.projects[0];
+}
+function displayPath(root, path) {
+	return relative(cwd(), join(root, path)).replace(/\\/g, "/") || ".";
+}
+function out(text) {
+	process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+function printJson(command, data, diagnostics = [], errors = []) {
+	const value = envelope(command, data, diagnostics, errors);
+	out(JSON.stringify(value, null, 2));
+}
+function wireDiagnostics(loaded, diagnostics) {
+	return diagnostics.map((d) => toWireDiagnostic(loaded.name, d, (path) => loaded.project.text(path)));
+}
+/** Exit code for an error: 2 usage or config, 3 decision needed, 4 stale plan, 1 otherwise. */
+function exitCodeOf(error) {
+	if (!isX18nError(error)) return 2;
+	if (error.code === "X18N4003") return 3;
+	if (error.code === "X18N4004") return 4;
+	return /^X18N[01]/.test(error.code) ? 2 : 1;
+}
+function errorInfo(error) {
+	if (isX18nError(error)) return error.toJSON();
+	return {
+		code: "X18N0002",
+		message: error instanceof Error ? error.message : String(error),
+		hint: "",
+		docs: ""
+	};
+}
+/** Stands for a lone `-` argument (stdin). */
+const stdinArg = "\0stdin";
+async function readInput(source) {
+	if (source !== "-" && source !== "\0stdin") return readFile(source, "utf8");
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Answers for the plan's decisions: defaults with `--yes`, a prompt in a TTY, else an error. */
+async function answer(plan, options) {
+	const answers = {};
+	if (plan.decisions.length === 0) return answers;
+	if (options.yes) {
+		for (const decision of plan.decisions) answers[decision.id] = decision.default;
+		return answers;
+	}
+	if (options.json || !process.stdin.isTTY) throw new X18nError("X18N4003", plan.decisions.map((d) => `${d.message} (${d.options.map((o) => o.id).join(" | ")})`).join(" "), plan.decisions.map((d) => d.id));
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		for (const decision of plan.decisions) {
+			process.stderr.write(`${decision.message}\n${decision.options.map((o, i) => `  ${i + 1}) ${o.label}`).join("\n")}\n`);
+			const reply = await rl.question(`Choose [1]: `);
+			const option = decision.options[Number(reply || "1") - 1] ?? decision.options[0];
+			answers[decision.id] = option.id;
+		}
+	} finally {
+		rl.close();
+	}
+	return answers;
+}
+/** Changes as a small line diff, for `--dry-run` and the summary after a write. */
+function formatPlan(project, root, plan) {
+	const lines = [];
+	for (const change of plan.changes) {
+		const path = displayPath(root, change.path);
+		if (change.type === "create") {
+			lines.push(`create ${path}`, ...change.content.split("\n").filter(Boolean).map((line) => `+ ${line}`));
+			continue;
+		}
+		if (change.type === "delete") {
+			lines.push(`delete ${path}`);
+			continue;
+		}
+		const before = project.text(change.path) ?? "";
+		const after = applyTextEdits(before, change.edits);
+		const a = before.split("\n");
+		const b = after.split("\n");
+		let start = 0;
+		while (start < a.length && start < b.length && a[start] === b[start]) start++;
+		let endA = a.length;
+		let endB = b.length;
+		while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+			endA--;
+			endB--;
+		}
+		lines.push(`edit ${path}`, ...a.slice(start, endA).map((line) => `- ${line}`), ...b.slice(start, endB).map((line) => `+ ${line}`));
+	}
+	for (const warning of plan.warnings) lines.push(`warning: ${warning}`);
+	return lines.length ? lines.join("\n") : "No changes.";
+}
+function planData(root, plan, applied) {
+	return {
+		applied,
+		keys: plan.keys,
+		warnings: plan.warnings,
+		decisions: plan.decisions,
+		changes: plan.changes.map((change) => ({
+			...change,
+			file: displayPath(root, change.path)
+		}))
+	};
+}
+/** Plans, asks, then applies (or prints with `--dry-run`). */
+async function runPlan(command, loaded, plan, options) {
+	if (options.dryRun) {
+		if (options.json) printJson(command, planData(loaded.root, plan, false));
+		else out(formatPlan(loaded.project, loaded.root, plan));
+		return;
+	}
+	const answers = await answer(plan, options);
+	const preview = formatPlan(loaded.project, loaded.root, plan);
+	await loaded.project.apply(plan, { answers });
+	if (options.json) printJson(command, planData(loaded.root, plan, true));
+	else out(preview);
+}
+//#endregion
+export { openWorkspace as a, readInput as c, stdinArg as d, useColor as f, exitCodeOf as i, runPlan as l, displayPath as n, out as o, wireDiagnostics as p, errorInfo as r, printJson as s, cwd as t, singleProject as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { Check, Format, LocaleFinder, Plugin, Preset, Reporter, Scanner, UserConfig, defineConfig, definePlugin, definePreset } from "@x18n/core";
+export { type Check, type Format, type LocaleFinder, type Plugin, type Preset, type Reporter, type Scanner, type UserConfig, defineConfig, definePlugin, definePreset };

package/dist/index.mjs

@@ -0,0 +1 @@
+export { defineConfig, definePlugin, definePreset } from "@x18n/core";

package/dist/presets.d.mts

@@ -0,0 +1 @@
+export * from "@x18n/builtins/presets";

package/dist/presets.mjs

@@ -0,0 +1,2 @@
+export * from "@x18n/builtins/presets";
+export {};

package/dist/ui-Bp3xyqr_.mjs

@@ -0,0 +1,74 @@
+import { a as openWorkspace, o as out, s as printJson, t as cwd } from "./context-Za_ea1Nk.mjs";
+import process from "node:process";
+import { join, resolve } from "node:path";
+import { createX18nDevframe } from "@x18n/ui";
+import { createBuild } from "devframe/adapters/build";
+import { createDevServer } from "devframe/adapters/dev";
+import { createMcpServer } from "devframe/adapters/mcp";
+import { buildOtpAuthUrl, getTempAuthCodeInfo } from "devframe/node/auth";
+import { randomToken } from "devframe/utils/crypto-token";
+import { launchEditor } from "devframe/utils/launch-editor";
+//#region src/commands/ui.ts
+/** Starts the UI dev server and keeps running until interrupted. */
+async function ui(options) {
+	const workspace = await openWorkspace(options);
+	workspace.projects.forEach((p) => p.project.watch());
+	const editor = process.env.LAUNCH_EDITOR || process.env.VISUAL || process.env.EDITOR;
+	const definition = createX18nDevframe(workspace.projects, { openInEditor: editor ? async ({ project, path, line, column }) => launchEditor(`${join(project.root, path)}:${line}:${column}`, editor) : void 0 });
+	const mcpToken = randomToken();
+	const auth = options.auth !== false;
+	if (!auth) process.stderr.write("warning: --no-auth lets anything that reaches the port edit your files. Use it only in CI and e2e tests.\n");
+	const server = await createDevServer(definition, {
+		host: options.host ?? "localhost",
+		...options.port === void 0 ? {} : { port: Number(options.port) },
+		auth,
+		openBrowser: options.open !== false,
+		mcp: { authorization: mcpToken }
+	});
+	const url = `${server.origin}/`;
+	const code = auth ? getTempAuthCodeInfo().code : void 0;
+	const mcp = {
+		url: `${url}__mcp`,
+		token: mcpToken
+	};
+	if (options.json) printJson("ui", {
+		url,
+		code,
+		link: code && buildOtpAuthUrl(url, code),
+		mcp
+	});
+	else {
+		out(`x18n UI at ${url}`);
+		if (code) out(`  auth code  ${code}\n  or open    ${buildOtpAuthUrl(url, code)}`);
+		out(`  MCP        ${mcp.url}\n  MCP token  Authorization: Bearer ${mcp.token}`);
+	}
+	const stop = () => {
+		server.close().finally(() => process.exit(0));
+	};
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+}
+async function build(options) {
+	const workspace = await openWorkspace(options);
+	const outDir = resolve(cwd(), options.outDir ?? ".x18n/report");
+	const log = console.log;
+	console.log = console.error;
+	try {
+		await createBuild(createX18nDevframe(workspace.projects), { outDir });
+	} finally {
+		console.log = log;
+	}
+	if (options.json) printJson("build", { outDir });
+	else out(`Wrote the report to ${outDir}`);
+}
+/** MCP over stdio: stdout is the transport, so nothing else may print there. */
+async function mcp(options) {
+	const workspace = await openWorkspace(options);
+	workspace.projects.forEach((p) => p.project.watch());
+	await createMcpServer(createX18nDevframe(workspace.projects), {
+		transport: "stdio",
+		serverName: "x18n"
+	});
+}
+//#endregion
+export { build, mcp, ui };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Manage and view i18n files of any project, for humans and agents",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -38,10 +38,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@x18n/builtins": "0.0.2",
-    "@x18n/core": "0.0.2",
-    "@x18n/node": "0.0.2",
-    "@x18n/ui": "0.0.2",
+    "@x18n/builtins": "0.0.3",
+    "@x18n/core": "0.0.3",
+    "@x18n/node": "0.0.3",
+    "@x18n/ui": "0.0.3",
     "cac": "^7.1.0",
     "devframe": "^1.2.5",
     "yaml": "^2.9.1"