@x18n/cli 0.0.14 → 0.1.0

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 import { a as out, c as runPlan, d as useColor, f as wireDiagnostics, i as openWorkspace, l as singleProject, n as displayPath, o as printJson, r as exitCodeOf, s as readInput, t as cwd, u as stdinArg } from "./context-j5IMF1tl.mjs";
 import { createRequire } from "node:module";
-import { PluginFileSchema, errors, isJsonObject, isX18nError, parseMessageBatch, placeholderProblems, renderPrompt, toErrorInfo, toWireRange, validate } from "@x18n/core";
+import { PluginFileSchema, errors, isJsonObject, isX18nError, parseMessageBatch, placeholderProblems, renderExplanation, renderPrompt, toErrorInfo, toWireRange, validate } from "@x18n/core";
 import process from "node:process";
 import { styleText } from "node:util";
 import cac from "cac";
@@ -15,7 +15,7 @@ import { existsSync } from "node:fs";
 import { namespaceFromPath } from "@x18n/builtins/finders";
 import { parse, stringify } from "yaml";
 //#region package.json
-var version = "0.0.14";
+var version = "0.1.0";
 //#endregion
 //#region src/commands/change.ts
 async function project(options) {
@@ -104,13 +104,13 @@ async function format(options) {
 }
 //#endregion
 //#region src/commands/check.ts
-function list(value) {
+function list$1(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);
+	const locales = list$1(options.locale);
+	const only = list$1(options.only);
+	const skip = list$1(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"
@@ -138,14 +138,14 @@ function reportInputs(workspace, options) {
 function needsHistory(loaded, options) {
 	const setting = loaded.project.config.checks["stale-translation"];
 	const level = typeof setting === "string" ? setting : setting?.[0];
-	const only = list(options.only);
-	return level !== "off" && (only.length === 0 || only.includes("stale-translation")) && !list(options.skip).includes("stale-translation");
+	const only = list$1(options.only);
+	return level !== "off" && (only.length === 0 || only.includes("stale-translation")) && !list$1(options.skip).includes("stale-translation");
 }
 async function report(workspace, options) {
 	const inputs = reportInputs(workspace, options);
-	const reporterIds = list(options.reporter);
+	const reporterIds = list$1(options.reporter);
 	const ids = reporterIds.length ? reporterIds : [options.json ? "json" : "pretty"];
-	const outputs = list(options.output);
+	const outputs = list$1(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()) {
@@ -201,7 +201,7 @@ async function readPlan(file) {
 	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) {
+async function review$1(candidates, root) {
 	const rl = createInterface({
 		input: process.stdin,
 		output: process.stderr
@@ -258,7 +258,7 @@ async function extract(files, options) {
 		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;
+	const chosen = interactive ? await review$1(candidates, loaded.root) : candidates;
 	if (chosen.length === 0) {
 		out("Nothing to extract.");
 		return;
@@ -368,6 +368,39 @@ function locate(loaded, path, start, end) {
 		column: range.column
 	};
 }
+async function search(query, options) {
+	const workspace = await openWorkspace(options);
+	const projects = workspace.projects.map((loaded) => {
+		const { project } = loaded;
+		const { items, total, nextCursor } = page(project.search(String(query), { exact: options.exact }), options);
+		return {
+			name: loaded.name,
+			total,
+			nextCursor,
+			matches: items.map((m) => ({
+				key: m.key,
+				locale: m.locale,
+				value: m.value,
+				usages: project.usages({ key: m.key }).map((u) => ({
+					possible: u.possible,
+					...locate(loaded, u.usage.path, u.usage.range.start, u.usage.range.end)
+				}))
+			}))
+		};
+	});
+	if (options.json) {
+		printJson("search", { projects });
+		return;
+	}
+	for (const p of projects) {
+		if (workspace.projects.length > 1) out(`# ${p.name}`);
+		for (const m of p.matches) {
+			out(`${m.key}  ${m.locale}  ${JSON.stringify(m.value)}`);
+			for (const u of m.usages) out(`  ${u.file}:${u.line}:${u.column}${u.possible ? " (possible)" : ""}`);
+		}
+		if (p.nextCursor) out(`… ${p.total - Number(p.nextCursor)} more (--cursor ${p.nextCursor})`);
+	}
+}
 async function get(input, options) {
 	const workspace = await openWorkspace(options);
 	const projects = workspace.projects.flatMap((loaded) => {
@@ -390,7 +423,8 @@ async function get(input, options) {
 				raw: u.usage.raw,
 				...locate(loaded, u.usage.path, u.usage.range.start, u.usage.range.end)
 			})),
-			diagnostics: wireDiagnostics(loaded, info.diagnostics)
+			diagnostics: wireDiagnostics(loaded, info.diagnostics),
+			reviews: info.reviews
 		}];
 	});
 	if (options.json) {
@@ -405,6 +439,7 @@ async function get(input, options) {
 		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}`);
+		for (const thread of p.reviews) out(`  review ${thread.locale}: ${thread.state ?? "resolved"}, ${thread.comments.length} comment${thread.comments.length === 1 ? "" : "s"}`);
 	}
 }
 async function usages(input, options) {
@@ -458,25 +493,7 @@ async function doctor(options) {
 		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.name} ${err.why}`).join("\n")}`);
-		out("config origins:");
-		for (const [key, origin] of Object.entries(e.config.origins)) out(`  ${key}: ${origin}`);
-	}
+	for (const e of projects) out(renderExplanation(e, e.configFile));
 }
 //#endregion
 //#region src/commands/migrate.ts
@@ -526,10 +543,94 @@ async function prompt(kind, options) {
 	else out(renderPrompt(data));
 }
 //#endregion
+//#region src/commands/review.ts
+const commentTypes = {
+	"comment": "comment",
+	"approve": "approve",
+	"request-change": "request-change",
+	"suggest": "suggestion"
+};
+/** `Ada <ada@example.com>`, `Ada` or `ada@example.com`. */
+function parseAuthor(input) {
+	const text = input.trim();
+	const open = text.lastIndexOf("<");
+	if (open >= 0 && text.endsWith(">")) {
+		const name = text.slice(0, open).trim();
+		return {
+			...name && { name },
+			email: text.slice(open + 1, -1).trim()
+		};
+	}
+	return text.includes("@") ? { email: text } : { name: text };
+}
+function required(value, flag) {
+	if (value === void 0 || value === "") throw errors.X18N4008({ reason: `pass ${flag}` });
+	return String(value);
+}
+async function list(target, options) {
+	const workspace = await openWorkspace(options);
+	const locale = options.locale === void 0 ? void 0 : String([options.locale].flat()[0]);
+	const projects = workspace.projects.map(({ name, project }) => ({
+		name,
+		threads: project.reviews({
+			key: target === void 0 ? void 0 : project.parseKey(target),
+			locale,
+			open: options.open
+		})
+	}));
+	if (options.json) {
+		printJson("review list", { projects });
+		return;
+	}
+	const threads = projects.flatMap((p) => p.threads);
+	if (threads.length === 0) out(options.open ? "No open reviews." : "No reviews.");
+	for (const thread of threads) {
+		out(`${thread.key}  ${thread.locale}${thread.state ? `  ${thread.state.replace("-", " ")}` : ""}`);
+		for (const c of thread.comments) {
+			const flags = [c.resolved && "resolved", c.stale && "stale"].filter(Boolean).join(", ");
+			out(`  ${c.id}  ${c.type.padEnd(14)} ${c.author?.name ?? c.author?.email ?? "-"}  ${c.time.slice(0, 10)}${flags ? `  (${flags})` : ""}`);
+			if (c.text) out(`    ${c.text}`);
+			if (c.suggestion !== void 0) out(`    suggests ${JSON.stringify(c.suggestion)}`);
+		}
+	}
+}
+/** `x18n review <action> [target]`: list, comment, approve, request-change, suggest, resolve, apply-suggestion, mark-fresh. */
+async function review(action, target, options) {
+	if (action === "list") return list(target, options);
+	const loaded = singleProject(await openWorkspace(options));
+	const { project } = loaded;
+	const locales = options.locale === void 0 ? void 0 : [options.locale].flat().map(String);
+	let op;
+	const type = commentTypes[action];
+	if (type) {
+		const locale = locales?.[0];
+		if (locale === void 0) throw errors.X18N4008({ reason: "pass --locale <locale>" });
+		op = {
+			type: "review",
+			key: project.parseKey(required(target, "<key>")),
+			locale,
+			review: type,
+			text: type === "request-change" ? required(options.text, "--text <text>") : options.text === void 0 ? void 0 : String(options.text),
+			suggestion: type === "suggestion" ? required(options.value, "--value <value>") : void 0,
+			author: options.author === void 0 ? await project.reviewAuthor() : parseAuthor(options.author)
+		};
+	} else if (action === "resolve" || action === "apply-suggestion") op = {
+		type: action === "resolve" ? "resolve-review" : "apply-suggestion",
+		id: required(target, "<id>")
+	};
+	else if (action === "mark-fresh") op = {
+		type: "mark-fresh",
+		key: project.parseKey(required(target, "<key>")),
+		locales
+	};
+	else throw errors.X18N4008({ reason: `unknown review action "${action}" (list, comment, approve, request-change, suggest, resolve, apply-suggestion, mark-fresh)` });
+	await runPlan(`review ${action}`, loaded, project.plan([op]), options);
+}
+//#endregion
 //#region src/commands/setup.ts
 async function schema(name, options) {
 	const which = name ?? "config";
-	if (which !== "config" && which !== "plugin") throw errors.X18N0001({ issue: `unknown schema "${which}" (config, plugin)` });
+	if (which !== "config" && which !== "plugin" && which !== "reviews") throw errors.X18N0001({ issue: `unknown schema "${which}" (config, plugin, reviews)` });
 	const require = createRequire(import.meta.url);
 	const text = await readFile(require.resolve(`@x18n/core/schema/${which}.json`), "utf8");
 	if (options.json) printJson("schema", {
@@ -676,10 +777,11 @@ function createCli() {
 	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");
+		if (!options.json) process.stdout.write("\nCommands: check, keys, search, 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("search <query>", "Find keys by their value in any locale, with their usages").option("--exact", "Only values containing the query, instead of a fuzzy match").option("--limit <n>", "Page size").option("--cursor <cursor>", "Start of the page").action(run("search", search));
 	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));
@@ -693,12 +795,13 @@ function createCli() {
 	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").option("--stale", "Also translate stale translations (needs git history)").action(run("prompt", prompt));
+	cli.command("review <action> [target]", "Reviews: `list [key]`, `comment|approve|request-change|suggest <key>`, `resolve|apply-suggestion <id>`, `mark-fresh <key>`").option("--locale <locale>", "Locale of the message (repeatable for mark-fresh)").option("--text <text>", "Comment text").option("--value <value>", "Suggested value (suggest)").option("--author <author>", "Author as `Name <email>` (default: review.author, then git user)").option("--open", "Only unresolved reviews (list)").option("--dry-run", "Print the plan instead of writing").action(run("review", review));
 	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("schema [name]", "Print a JSON Schema: config (default), plugin or reviews").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);

package/dist/presets.d.mts

@@ -10,7 +10,6 @@ import { flutterTranslate } from "@x18n/builtins/presets/flutter-translate";
 import { general } from "@x18n/builtins/presets/general";
 import { globalize } from "@x18n/builtins/presets/globalize";
 import { gravityUiI18n } from "@x18n/builtins/presets/gravity-ui-i18n";
-import { i18nJs } from "@x18n/builtins/presets/i18n-js";
 import { i18nTag } from "@x18n/builtins/presets/i18n-tag";
 import { i18next } from "@x18n/builtins/presets/i18next";
 import { i18nextShopify } from "@x18n/builtins/presets/i18next-shopify";
@@ -32,6 +31,7 @@ import { polyglot } from "@x18n/builtins/presets/polyglot";
 import { pythonGettext } from "@x18n/builtins/presets/python-gettext";
 import { reactI18next } from "@x18n/builtins/presets/react-i18next";
 import { reactIntl } from "@x18n/builtins/presets/react-intl";
+import { rubyI18nJs } from "@x18n/builtins/presets/ruby-i18n-js";
 import { railsLazyKey, rubyRails } from "@x18n/builtins/presets/ruby-rails";
 import { solidPrimitivesI18n } from "@x18n/builtins/presets/solid-primitives-i18n";
 import { svelteI18n } from "@x18n/builtins/presets/svelte-i18n";
@@ -41,4 +41,4 @@ import { typesafeI18n } from "@x18n/builtins/presets/typesafe-i18n";
 import { ui5 } from "@x18n/builtins/presets/ui5";
 import { vscodeExtension } from "@x18n/builtins/presets/vscode-extension";
 import { vueI18n } from "@x18n/builtins/presets/vue-i18n";
-export { cargoI18n, chromeExtension, dotnetResx, easyLocalization, emberIntl, fluentReact, fluentVue, flutter, flutterTranslate, general, globalize, gravityUiI18n, i18nJs, i18nTag, i18next, i18nextShopify, i18nice, jekyll, laravel, laravelVueI18n, lingui, nextInternational, nextIntl, nextTranslate, ngxTranslate, nuxtI18n, nuxtI18nMicro, paraglide, phpGettext, phpJoomla, polyglot, pythonGettext, railsLazyKey, reactI18next, reactIntl, rubyRails, solidPrimitivesI18n, svelteI18n, svelteI18next, transloco, typesafeI18n, ui5, vscodeExtension, vueI18n };
+export { cargoI18n, chromeExtension, dotnetResx, easyLocalization, emberIntl, fluentReact, fluentVue, flutter, flutterTranslate, general, globalize, gravityUiI18n, i18nTag, i18next, i18nextShopify, i18nice, jekyll, laravel, laravelVueI18n, lingui, nextInternational, nextIntl, nextTranslate, ngxTranslate, nuxtI18n, nuxtI18nMicro, paraglide, phpGettext, phpJoomla, polyglot, pythonGettext, railsLazyKey, reactI18next, reactIntl, rubyI18nJs, rubyRails, solidPrimitivesI18n, svelteI18n, svelteI18next, transloco, typesafeI18n, ui5, vscodeExtension, vueI18n };

package/dist/presets.mjs

@@ -10,7 +10,6 @@ import { flutterTranslate } from "@x18n/builtins/presets/flutter-translate";
 import { general } from "@x18n/builtins/presets/general";
 import { globalize } from "@x18n/builtins/presets/globalize";
 import { gravityUiI18n } from "@x18n/builtins/presets/gravity-ui-i18n";
-import { i18nJs } from "@x18n/builtins/presets/i18n-js";
 import { i18nTag } from "@x18n/builtins/presets/i18n-tag";
 import { i18next } from "@x18n/builtins/presets/i18next";
 import { i18nextShopify } from "@x18n/builtins/presets/i18next-shopify";
@@ -32,6 +31,7 @@ import { polyglot } from "@x18n/builtins/presets/polyglot";
 import { pythonGettext } from "@x18n/builtins/presets/python-gettext";
 import { reactI18next } from "@x18n/builtins/presets/react-i18next";
 import { reactIntl } from "@x18n/builtins/presets/react-intl";
+import { rubyI18nJs } from "@x18n/builtins/presets/ruby-i18n-js";
 import { railsLazyKey, rubyRails } from "@x18n/builtins/presets/ruby-rails";
 import { solidPrimitivesI18n } from "@x18n/builtins/presets/solid-primitives-i18n";
 import { svelteI18n } from "@x18n/builtins/presets/svelte-i18n";
@@ -41,4 +41,4 @@ import { typesafeI18n } from "@x18n/builtins/presets/typesafe-i18n";
 import { ui5 } from "@x18n/builtins/presets/ui5";
 import { vscodeExtension } from "@x18n/builtins/presets/vscode-extension";
 import { vueI18n } from "@x18n/builtins/presets/vue-i18n";
-export { cargoI18n, chromeExtension, dotnetResx, easyLocalization, emberIntl, fluentReact, fluentVue, flutter, flutterTranslate, general, globalize, gravityUiI18n, i18nJs, i18nTag, i18next, i18nextShopify, i18nice, jekyll, laravel, laravelVueI18n, lingui, nextInternational, nextIntl, nextTranslate, ngxTranslate, nuxtI18n, nuxtI18nMicro, paraglide, phpGettext, phpJoomla, polyglot, pythonGettext, railsLazyKey, reactI18next, reactIntl, rubyRails, solidPrimitivesI18n, svelteI18n, svelteI18next, transloco, typesafeI18n, ui5, vscodeExtension, vueI18n };
+export { cargoI18n, chromeExtension, dotnetResx, easyLocalization, emberIntl, fluentReact, fluentVue, flutter, flutterTranslate, general, globalize, gravityUiI18n, i18nTag, i18next, i18nextShopify, i18nice, jekyll, laravel, laravelVueI18n, lingui, nextInternational, nextIntl, nextTranslate, ngxTranslate, nuxtI18n, nuxtI18nMicro, paraglide, phpGettext, phpJoomla, polyglot, pythonGettext, railsLazyKey, reactI18next, reactIntl, rubyI18nJs, rubyRails, solidPrimitivesI18n, svelteI18n, svelteI18next, transloco, typesafeI18n, ui5, vscodeExtension, vueI18n };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x18n/cli",
   "type": "module",
-  "version": "0.0.14",
+  "version": "0.1.0",
   "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.14",
-    "@x18n/core": "0.0.14",
-    "@x18n/node": "0.0.14",
-    "@x18n/ui": "0.0.14",
+    "@x18n/builtins": "0.1.0",
+    "@x18n/core": "0.1.0",
+    "@x18n/node": "0.1.0",
+    "@x18n/ui": "0.1.0",
     "cac": "^7.1.0",
     "devframe": "^1.2.6",
     "nostics": "^1.3.0",

package/skills/x18n/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: x18n
+description: Manage a project's translations with x18n (`@x18n/cli`). Use when the task touches locale files or translation keys - adding, renaming or deleting keys, finding the key behind a text shown in the app, finding missing or unused keys, translating missing messages, reviewing translations, extracting hard-coded strings, keeping a glossary of terms.
+---
+
+# x18n
+
+x18n reads a project's i18n setup (locale files, translate calls in code) and changes it safely. Work through the `x18n` CLI from `@x18n/cli`: it keeps formatting, key style, file choice and placeholders correct, and every command prints a stable JSON envelope with `--json`.
+
+## Decisions belong to the user
+
+You do the legwork; the user makes the **decisions** that shape the product. Before you act on one of these, stop and ask, with your recommendation and the facts you found:
+
+- the source locale, and which locales the project supports
+- key naming and structure: namespaces, nesting, the style of new keys
+- a glossary term and its translation per locale, and terms that must stay untranslated (brand and product names)
+- tone and formality per locale (German *du* or *Sie*, French *tu* or *vous*)
+- deleting keys that look unused, since keys built at runtime look unused too
+- renames that touch many files or move keys between namespaces
+
+Batch the questions into one message. Routine work needs no question: adding a key you use, translating a missing message, fixing a placeholder.
+
+## Rules
+
+- Change locale files through `x18n set`, `x18n apply`, `x18n rename` and `x18n delete`. The config file (`x18n.config.ts`) is the one i18n file you edit by hand.
+- Check a key before you use it in code: `x18n get <key> --json`. Reuse an existing key with the same meaning: `x18n search "<text>" --json` finds keys whose value already says it.
+- Keep every placeholder of the source message (`{name}`, `{{count}}`, `%{name}`, `:name`, `%s`, `@:key`).
+- Pass `--json` and read the envelope `{ "x18n": 2, "command", "data", "diagnostics", "errors" }`.
+- Run renames and deletes with `--dry-run` first, and read the plan.
+- Write every key as a full string literal. Do not build keys at runtime (see below).
+
+## Avoid composed keys
+
+Do not build a key from parts, such as `` t(`foo.bar.${name}`) `` or `t('foo.bar.' + name)`. x18n and the compiler cannot see the full key, so:
+
+- `x18n keys --unused` reports the key as unused, and `x18n delete` can remove a message that the code needs
+- `x18n rename` does not update the usage
+- `x18n check` cannot find a missing message until the user hits it at runtime
+- translators cannot see the full key in context
+
+Write each key out in full and map the value to it:
+
+```ts
+// Avoid
+t(`status.${status}`)
+
+// Prefer: a lookup of full literal keys
+const labels = {
+  active: t('status.active'),
+  paused: t('status.paused'),
+} as const
+labels[status]
+```
+
+```ts
+// Avoid
+t(`plans.${plan}.title`)
+
+// Prefer: a switch, or a record of functions when the call must be lazy
+const planTitle = {
+  free: () => t('plans.free.title'),
+  pro: () => t('plans.pro.title'),
+}
+planTitle[plan]()
+```
+
+When the variable part is only a word inside a sentence, use a placeholder instead of a key part: `t('greeting', { name })` with the message `Hello, {name}`. When the text differs by count, use the library's plural syntax, not `t(count === 1 ? 'item.one' : 'item.many')`.
+
+If the user's code already composes keys, do not rewrite it unasked. Tell the user which keys are affected, and treat those keys as used when you clean up.
+
+## Set up and check
+
+- To set up x18n, or migrate from i18n-ally, use the `x18n-setup` skill.
+- To run `x18n check` and fix what it reports, use the `x18n-check` skill.
+
+Commands below use `x18n`; without the dev dependency, run them as `npx @x18n/cli <command>`.
+
+## Glossary (terms table)
+
+The `glossary` in the config is the project's terms table. Translate prompts include it, and the `glossary` check reports messages that translate a term differently.
+
+```ts
+// x18n.config.ts
+import { defineConfig } from '@x18n/core'
+
+export default defineConfig({
+  glossary: [
+    {
+      term: 'Workspace',
+      translations: { de: 'Arbeitsbereich', fr: 'Espace de travail' }
+    },
+    { term: 'x18n', doNotTranslate: true },
+    {
+      term: 'Save',
+      translations: { de: 'Speichern' },
+      note: 'The button label, not "rescue"'
+    },
+  ],
+  checks: { glossary: 'warning' },
+})
+```
+
+Maintain it while you work:
+
+- Before you translate, read the current entries: `x18n doctor --json` lists them under `config.glossary`.
+- When you meet a term that recurs across messages or has a product meaning, propose an entry to the user, with a translation for each locale.
+- Add the entries the user approves, then run `x18n check --only glossary --json` and fix the messages it reports.
+
+## Loops
+
+### Find the key behind a text
+
+When the user names a text they see in the app, and not a key, search the values:
+
+```sh
+x18n search "Sign in" --json
+x18n search "Anmelden" --exact --json
+```
+
+The search covers every locale and ignores case. It is fuzzy by default, and values that contain the query rank first. `--exact` keeps only those. Each match in `data.projects[].matches` has `key`, `locale`, `value` and `usages` (`file`, `line`, `column`), so you can open the code that shows the text.
+
+### Add a key while coding
+
+```sh
+x18n search "Settings" --exact --json
+x18n get settings.title --json
+x18n set settings.title --value "Settings" --json
+x18n keys --missing de --json --limit 50
+```
+
+Reuse a key that `x18n search` finds with the same meaning. `x18n set` without `--locale` writes the source locale. Then use the key in code, for example `t('settings.title')`.
+
+### Translate missing messages
+
+```sh
+x18n prompt translate --to de --limit 50
+```
+
+Follow the prompt. It holds the rules, the glossary, examples of existing translations and the code around each usage. Write `{ "de": { "<key>": "<translation>" } }` to a file, then:
+
+```sh
+x18n apply translations.json --json
+x18n check --only placeholder-mismatch,invalid-syntax,glossary --locale de --json
+```
+
+`x18n apply` refuses values whose placeholders differ from the source and lists them in `data.rejected`. Fix them and apply again. When the prompt reports more keys, continue with `x18n prompt translate --to de --cursor <nextCursor>`.
+
+### Review translations
+
+```sh
+x18n prompt review --locale de --limit 50
+```
+
+Do not change values yourself. For each wrong translation, leave a review for a human to accept, then list what you reviewed:
+
+```sh
+x18n review suggest <key> --locale de --value <better text> --text <why> --json
+x18n review request-change <key> --locale de --text <why> --json
+```
+
+Keep every placeholder in a suggested value. `x18n review list --locale de --open --json` shows the open reviews. Only when the user asks, apply one with `x18n review apply-suggestion <id> --json`. When reviews are off (`review.enabled: false`, error X18N5003), fix values with `x18n set <key> --locale de --value <text> --json` instead.
+
+### Clean up
+
+```sh
+x18n keys --unused --json
+x18n delete old.key --dry-run --json
+```
+
+Show the user the unused keys and delete only the ones they confirm: `x18n delete old.key --json`.
+
+### Rename keys
+
+```sh
+x18n rename home.title home.heading --dry-run --json
+x18n rename home.title home.heading --json
+x18n rename pages screens --json
+```
+
+A rename updates every locale and every usage in code. Renaming a parent (`pages`) moves every key under it. A rename onto an existing key is refused (exit code 1).
+
+### Extract hard-coded strings
+
+```sh
+x18n extract --list --json
+x18n extract --plan extract-plan.json
+x18n extract --apply extract-plan.json --json
+```
+
+Edit the keys in the plan file before you apply it. The proposed keys follow the project's style; ask the user when there is none yet.
+
+Tests, fixtures, mocks, stories, configs and type declarations are never scanned, in any language (`*.test.ts`, `*_test.go`, `test_*.py`, `*_spec.rb`, `*Test.java`, `vite.config.ts`, `tests/`, `spec/`, `e2e/`, ...). To keep strings that are not UI text out of the plan, drop them from the plan file, or add a control comment to the code:
+
+| Comment | Skips |
+| --- | --- |
+| `x18n-ignore-file` | the whole file, wherever the comment is |
+| `x18n-ignore-start` ... `x18n-ignore-end` | everything between them (to the end of the file when unclosed) |
+| `x18n-ignore` | strings on its line and on the next line |
+
+Use any comment syntax: `// x18n-ignore-file`, `<!-- x18n-ignore -->`. For strings that recur across files, use `extract.ignore` in the config instead.
+
+## Output
+
+Exit codes:
+
+- `0` success
+- `1` `x18n check` found errors, or `x18n apply` rejected values
+- `2` usage or config error
+- `3` a decision is needed: re-run with `--yes` to accept the defaults
+- `4` files changed during the command: run it again
+
+List commands take `--limit` and return `nextCursor`; pass it as `--cursor` to get the next page: `x18n keys --json --limit 100 --cursor 100`.
+
+When `x18n status --json` lists several projects (a monorepo), pass `--project <name>` to write commands.

package/skills/x18n-check/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: x18n-check
+description: Run `x18n check` and fix what it reports - missing keys and translations, placeholder mismatches, invalid message syntax, unused keys, glossary violations. Use when the user asks to check, lint or fix translations, when `x18n check` fails locally or in CI, or before opening a PR that touches locale files or translation keys.
+---
+
+# Check and fix translations
+
+`x18n check` reports broken, untranslated and unused messages, like `tsc --noEmit` for i18n. Run it, fix the routine problems, and bring the rest to the user. Change locale files only through the `x18n` CLI (`set`, `apply`, `rename`, `delete`), never by hand. The `x18n` skill covers those commands.
+
+If the project has no x18n setup yet, use the `x18n-setup` skill first.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- deleting keys reported as unused, since keys built at runtime look unused too
+- a glossary term and its translation per locale
+- changing the severity of a check in the `checks` map of the config, such as `'unused-key': 'error'` or `glossary: 'warning'`
+- making warnings fail CI with `--strict` or `--max-warnings <n>`
+
+## Loop
+
+1. Run `x18n check --json`. Read `data.projects[].summary` for the counts and `diagnostics` for the problems. Group the diagnostics by `code` and `severity`. **Done when** you know the count per check, errors first.
+2. Fix the errors, check by check, with the table below. Re-run only that check to confirm: `x18n check --only placeholder-mismatch --json`. **Done when** the summary shows no errors, or each remaining error waits on a user decision.
+3. Fix the warnings you can fix without a decision, such as missing translations. **Done when** the remaining warnings each need a decision.
+4. Ask the user about the remaining diagnostics in one message: list them by check, with your recommendation for each. Apply what they decide.
+5. Run `x18n check --json` again and report the result. **Done when** `x18n check` exits with code 0, or every remaining diagnostic is one the user chose to keep.
+
+## Fixes per check
+
+| Check (`code`) | Fix |
+| --- | --- |
+| `missing-key` | A usage names a key the source locale lacks. If it is a typo, fix the usage to an existing key (`x18n keys` lists them). Else add it: `x18n set <key> --value <text> --json`. |
+| `missing-translation`, `empty-translation` | Translate: `x18n prompt translate --to <locale> --limit 50`, write the result to a file, then `x18n apply <file> --json`. Follow `nextCursor` when the prompt reports more keys. |
+| `placeholder-mismatch` | Rewrite the target value with every placeholder of the source: `x18n set <key> --locale <locale> --value <text> --json`. |
+| `invalid-syntax` | Fix the message syntax (ICU braces, linked messages) with `x18n set`. When a linked message does not exist, fix the link or add that key. |
+| `key-conflict` | A key is both a message and a parent, or is defined twice in one locale. Ask which one to keep, then `x18n rename` or `x18n delete` with `--dry-run` first. |
+| `unused-key` | Show the list from `x18n keys --unused --json` and delete only the keys the user confirms: `x18n delete <key> --dry-run --json`, then without `--dry-run`. Keys built at runtime go in `usage.keysInUse` in the config instead. |
+| `redundant-translation` | The message repeats what its fallback locale (`localeFallbacks`) already says. Delete it with `x18n delete <key> --locale <locale> --dry-run` first, then without `--dry-run`. |
+| `glossary` | Rewrite the message with the term from the glossary (`x18n doctor --json` lists it under `config.glossary`), with `x18n set`. |
+| `locale-code-conflict`, `dynamic-key`, `key-style`, `identical-to-source`, `hard-string` | Report them. Fix only when the user asks; `hard-string` is fixed with `x18n extract`, or silenced with an `x18n-ignore` control comment when the string is not UI text. |
+
+After a batch of fixes, check only what you touched: `x18n check --only placeholder-mismatch,invalid-syntax,glossary --locale de --json`.
+
+## CI
+
+`x18n check` exits with code 1 on errors, so CI fails on broken keys without more setup. Warnings do not fail it unless the project uses `--strict` or `--max-warnings <n>`. For pull request annotations, use `x18n check --reporter github --reporter pretty`. Change none of this without asking.

package/skills/x18n-setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: x18n-setup
+description: Set up x18n (`@x18n/cli`) in a project, or migrate it from i18n-ally. Use when a project has no x18n config yet, when x18n detects the wrong locale files or library, when the user asks to add, install or configure x18n, or when `.vscode/settings.json` has `i18n-ally.*` settings.
+---
+
+# Set up x18n
+
+x18n reads a project's i18n setup (locale files, translate calls in code) and often needs no config. Set it up by checking what it detects, and write a config only when detection needs help.
+
+## Decisions belong to the user
+
+Before you act on one of these, stop and ask, with your recommendation and the facts you found. Batch the questions into one message.
+
+- the source locale, and which locales the project supports
+- the config format: `x18n.config.ts`, or YAML for projects without Node.js tooling
+- what an i18n-ally migration drops (see the reference below)
+- adding `x18n check` to CI or to a git hook
+
+## Steps
+
+1. Run `npx @x18n/cli doctor` in the project root. Without a config, x18n uses the project's i18n-ally settings if it has any, and detects the i18n library and the locale files. Check the detected presets, the locale files and the source locale. **Done when** the doctor output names the library the project uses and lists every locale file.
+2. If the project has i18n-ally settings (`i18n-ally.*` keys in `.vscode/settings.json`), follow [references/migrate-i18n-ally.md](references/migrate-i18n-ally.md) instead of step 3.
+3. If detection is wrong or incomplete, run `x18n init` to write `x18n.config.ts`, then fix `resources`, `sourceLocale` or `presets` in it. `x18n init --format yml` writes YAML. **Done when** `x18n doctor` shows the right result.
+4. Install the CLI as a dev dependency with the project's package manager (`pnpm add -D @x18n/cli`), and add a script such as `"i18n:check": "x18n check"`. Ask the user before you add it to CI.
+5. Run `x18n check --json` and report the summary to the user: errors and warnings per check (`code` of each diagnostic) and coverage per locale. Do not fix anything in this skill. **Done when** the user has the counts and knows that the `x18n-check` skill fixes them.
+
+Without the dev dependency, run commands as `npx @x18n/cli <command>`. In a monorepo, `x18n status --json` lists every project; pass `--project <name>` to pick one.

package/skills/x18n-setup/references/migrate-i18n-ally.md

@@ -0,0 +1,49 @@
+# Migrate from i18n-ally
+
+Use this when a project has i18n-ally settings: `i18n-ally.*`, legacy `vue-i18n-ally.*` or i18n-ally-next `i18n-ally-next.*` keys in `.vscode/settings.json` or a `*.code-workspace` file, or a `.vscode/i18n-ally-custom-framework.yml` (i18n-ally-next: `i18n-ally-next-custom-framework.yml`). `x18n migrate i18n-ally` converts them. It never deletes i18n-ally files.
+
+## Steps
+
+1. Record the baseline before you change anything: `npx @x18n/cli status --json` and `npx @x18n/cli keys --unused --json`. x18n already reads the i18n-ally settings without a config, so this is what the project gets today. **Done when** you have the locale list, the key count and the unused keys.
+2. Preview the migration: `x18n migrate i18n-ally --dry-run`. It prints the files it would write and notes about settings it dropped. **Done when** you have read every note.
+3. Ask the user about each **decision** the notes raise, in one message. The usual ones:
+   - `translate.*` settings (machine translation engines) are dropped. x18n writes translate prompts instead (`x18n prompt translate --to <locale>`).
+   - `languageTagSystem` is dropped: x18n uses locale codes exactly as they appear in file names.
+   - A custom framework with `monopoly: true` turns the built-in presets off (`presets: []`).
+   - Executed JS/TS locale files become read-only (`execute: true`).
+   - Reviews are converted to `.x18n/reviews.yml`; key descriptions and `review.removeCommentOnResolved` are dropped.
+   - The config format: `x18n.config.ts` by default, or `--format yml` / `--format json` for projects without Node.js tooling.
+4. Write the files: `x18n migrate i18n-ally --json` (add `--format yml` if the user chose YAML; `--force` replaces an existing x18n config). It writes:
+   - `x18n.config.ts` (or `.yml`, `.json`) from the project settings
+   - `.x18n/custom.x18n-plugin.yml`, when there are custom regexes, a custom framework, refactor templates or `localeCountryMap` flags
+   - editor settings in `.vscode/settings.json`: `x18n.displayLocale`, `x18n.annotationInPlace`, `x18n.annotations`, `x18n.annotationMaxLength`, `x18n.showFlags`
+   - `.x18n/reviews.yml`, when `.vscode/i18n-ally-reviews.yml` or `.vscode/i18n-ally-next-reviews.yml` exists
+
+   **Done when** the command exits with code 0 and `data.files` lists the files above that apply.
+5. Verify: run `x18n doctor --json`, `x18n status --json` and `x18n keys --unused --json`, and compare them with the baseline of step 1. The locales and keys must match. The unused keys may shrink, because `keysInUse` and the derived-key rules now apply. **Done when** every difference is explained to the user.
+6. Clean up, after the user agrees: the command's `data.removable` lists the i18n-ally settings that x18n no longer needs. Remove them from `.vscode/settings.json`, delete the custom framework file if listed, and suggest the VS Code extension `antfu.x18n` in place of `lokalise.i18n-ally` or `lydanne.i18n-ally-next`.
+
+In VS Code, the extension offers the same migration when it finds i18n-ally settings and no x18n config: the command **x18n: Migrate from i18n-ally** previews the files and writes them on confirmation.
+
+## What maps where
+
+| i18n-ally | x18n |
+| --- | --- |
+| `localesPaths`, `pathMatcher`, `dirStructure`, `namespace` | `resources[].pattern`, with the same `{locale}`, `{namespace}`, `{namespaces}`, `{ext}` tokens |
+| `enabledFrameworks` | `presets`: every i18n-ally framework has a preset (`vue` → `vue-i18n`, `react` → `react-intl`, `ember` → `ember-intl`, `chrome-ext` → `chrome-extension`); `general` and `custom` are dropped |
+| `sourceLanguage` | `sourceLocale` |
+| `displayLanguage` | VS Code setting `x18n.displayLocale` |
+| `ignoredLocales` | `ignoreLocales` |
+| `keystyle`, `disablePathParsing` | `keyStyle` (`disablePathParsing` becomes `flat`) |
+| `defaultNamespace` | `namespace.default` |
+| `enabledParsers`, `parsers.extendFileExtensions` | `formats` |
+| `keysInUse`, `usage.derivedKeyRules`, `usage.scanningIgnore` | `usage.keysInUse`, `usage.derivedKeys`, `usage.exclude` |
+| `regex.usageMatch`, `regex.usageMatchAppend` | `scanners.regex` in the generated YAML plugin |
+| `refactor.templates` | `extract.templates` |
+| `extract.*` | `extract.*`, same meaning |
+| `sortKeys`, `sortCompare`, `indent`, `tabStyle`, `keepFulfilled` | `write.sort`, `write.indent`, `write.keepFilled` |
+| `annotations`, `annotationInPlace`, `annotationInPlaceFullMatch`, `annotationMaxLength`, `showFlags`, `theme.annotation*` | VS Code settings with the same names under `x18n.*` |
+| `localeCountryMap` | `localeInfo` flags in the generated YAML plugin |
+| custom framework `languageIds`, `usageMatchRegex`, `scopeRangeRegex`, `refactorTemplates`, `monopoly` | the generated YAML plugin: `scanners.regex`, `scopes.regex`, `extract.templates`; `monopoly` sets `presets: []` |
+
+The full map is on the docs page <https://x18n.antfu.dev/migration>.