langctl 0.4.0 → 0.5.0

package/dist/commands/review.js

@@ -1,8 +1,9 @@
 import chalk from 'chalk';
+import { loadProjectConfig, resolvePrefix, withPrefix } from '../core/config.js';
 import { usageError } from '../core/errors.js';
 import { getSession } from '../core/http.js';
 import { log, printJson, runtime, spinner, table } from '../core/output.js';
-import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
+import { assertLanguages, getProject, listAllKeys, projectSlugFrom } from '../core/project.js';
 import { confirm } from '../core/prompts.js';
 const split = (v) => (v ? v.split(',').map(s => s.trim()).filter(Boolean) : undefined);
 /**
@@ -12,19 +13,28 @@ const split = (v) => (v ? v.split(',').map(s => s.trim()).filter(Boolean) : unde
 export async function reviewCommand(projectArg, opts) {
     const session = await getSession();
     const project = await getProject(session, projectSlugFrom(projectArg));
-    const keys = split(opts.keys);
+    const prefix = resolvePrefix(undefined, loadProjectConfig()?.config ?? {});
     const languages = split(opts.languages);
     if (languages)
         assertLanguages(project, languages);
     const spin = spinner('Fetching AI translations awaiting review…');
     let list;
+    let inModule;
     try {
-        list = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/review`);
+        list = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/review`, { module: opts.module });
+        // The review list may not carry modules (older API): resolve the module's keys separately
+        if (opts.module && !list.items.every(i => i.module !== undefined)) {
+            inModule = new Set((await listAllKeys(session, project, { module: opts.module })).map(k => k.id));
+        }
     }
     finally {
         spin.stop();
     }
-    const items = list.items.filter(i => (!keys || keys.includes(i.key)) && (!languages || languages.includes(i.language)));
+    // With "prefix" in langctl.json, --keys may name keys with or without it
+    const known = new Set(list.items.map(i => i.key));
+    const keys = split(opts.keys)?.map(k => withPrefix(k, prefix, known));
+    const items = list.items.filter(i => (!keys || keys.includes(i.key)) && (!languages || languages.includes(i.language))
+        && (!opts.module || (inModule ? inModule.has(i.keyId) : i.module === opts.module)));
     if (keys) {
         const unknown = keys.filter(k => !list.items.some(i => i.key === k));
         if (unknown.length)
@@ -38,7 +48,7 @@ export async function reviewCommand(projectArg, opts) {
             return;
         }
         table(items.map(i => [i.key, i.language, i.text.length > 60 ? `${i.text.slice(0, 57)}…` : i.text]), ['key', 'lang', 'AI translation']);
-        log.info(chalk.dim(`${items.length} awaiting review — left out of "langctl pull" until approved. Approve with "langctl review ${project.slug} --approve" (narrow with --keys / --languages), or edit them in the web app.`));
+        log.info(chalk.dim(`${items.length} awaiting review — left out of "langctl pull" until approved. Approve with "langctl review ${project.slug} --approve" (narrow with --module / --keys / --languages), or edit them in the web app.`));
         return;
     }
     if (!items.length) {

package/dist/commands/translate.js

@@ -1,19 +1,39 @@
 import chalk from 'chalk';
-import { usageError } from '../core/errors.js';
+import { loadProjectConfig, resolvePrefix, withPrefix } from '../core/config.js';
+import { CliError, ExitCode, usageError } from '../core/errors.js';
 import { getSession } from '../core/http.js';
-import { log, printJson, runtime, spinner, table } from '../core/output.js';
+import { log, printJson, progress, runtime, spinner, table } from '../core/output.js';
 import { assertLanguages, getProject, listAllKeys, projectSlugFrom } from '../core/project.js';
-/** The API translates at most 50 strings per request. */
-const BATCH = 50;
+/** Strings per request (API maximum). Servers before API 2026-10 accept at most LEGACY_BATCH. */
+export const BATCH = 100;
+const LEGACY_BATCH = 50;
+/** Requests in flight at once */
+export const CONCURRENCY = 3;
+/** Per-key saves in flight at once on servers without `save: true` */
+export const SAVE_CONCURRENCY = 6;
 const isBlank = (v) => !v || !v.trim();
+/** Run `fn` over `items` with at most `limit` running at a time. */
+export async function pool(items, limit, fn) {
+    let i = 0;
+    const worker = async () => {
+        while (i < items.length)
+            await fn(items[i++]);
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
 /**
  * Fill missing translations with AI (DeepL) from the project's default language.
  * Counts against the plan's monthly AI translations unless the org uses its own DeepL key.
+ *
+ * Strings the provider can't translate are reported per key and never fail the rest: the
+ * command finishes, lists them, and exits 8 (partial) so CI can tell "needs a human" apart
+ * from usage (2) and network/API (5) errors.
  */
 export async function translateCommand(projectArg, opts) {
     const session = await getSession();
     const project = await getProject(session, projectSlugFrom(projectArg));
     const source = project.defaultLanguage;
+    const prefix = resolvePrefix(undefined, loadProjectConfig()?.config ?? {});
     const targets = opts.to
         ? opts.to.split(',').map(s => s.trim()).filter(Boolean)
         : project.languages.filter(l => l !== source);
@@ -31,8 +51,10 @@ export async function translateCommand(projectArg, opts) {
         spin.stop();
     }
     if (opts.keys) {
-        const wanted = new Set(opts.keys.split(',').map(s => s.trim()).filter(Boolean));
-        const unknown = [...wanted].filter(k => !keys.some(key => key.key === k));
+        const known = new Set(keys.map(k => k.key));
+        // With "prefix" in langctl.json, keys may be named with or without it
+        const wanted = new Set(opts.keys.split(',').map(s => s.trim()).filter(Boolean).map(k => withPrefix(k, prefix, known)));
+        const unknown = [...wanted].filter(k => !known.has(k));
         if (unknown.length)
             throw usageError(`Key${unknown.length > 1 ? 's' : ''} not found: ${unknown.join(', ')}`);
         keys = keys.filter(k => wanted.has(k.key));
@@ -54,46 +76,182 @@ export async function translateCommand(projectArg, opts) {
         if (total === 0)
             log.success('Nothing to translate.');
         else
-            log.info(`Dry run: ${total} translation(s) would use ${total} AI translation(s). Run without --dry-run to translate.`);
+            log.info(`Dry run: ${total} translation(s) would use up to ${total} AI translation(s). Run without --dry-run to translate.`);
         return;
     }
-    const done = [];
-    let usage;
-    let provider;
-    const progress = spinner(`Translating 0/${total}…`);
+    const outcome = await runTranslation(session, project, source, plan, Boolean(opts.overwrite));
+    report(project, plan.filter(p => p.keys.length).map(p => p.lang), total, outcome);
+}
+export async function runTranslation(session, project, source, plan, overwrite) {
+    const total = plan.reduce((n, p) => n + p.keys.length, 0);
+    const out = { done: [], failed: [] };
+    let batchSize = BATCH;
+    const queue = plan.flatMap(({ lang, keys }) => chunk(keys, batchSize).map(k => ({ lang, keys: k })));
+    const bar = progress('Translating', total);
+    const tick = () => bar.update(out.done.length + out.failed.length);
+    const keyPath = (key, lang) => `/orgs/${session.orgId}/projects/${project.id}/keys/${key.id}/translations/${encodeURIComponent(lang)}`;
+    const succeed = (lang, key, text, copied) => {
+        out.done.push({ language: lang, key: key.key, text, ...(copied ? { copied: true } : {}) });
+        bar.out(`${chalk.dim(lang)}  ${key.key}  ${text}${copied ? chalk.dim('  (copied unchanged)') : ''}`);
+    };
+    const fail = (lang, key, error) => out.failed.push({ language: lang, key: key.key, sourceText: key.translations[source], error });
+    const runJob = async (job) => {
+        let res;
+        try {
+            res = await session.api.post(`/orgs/${session.orgId}/translate/bulk`, {
+                items: job.keys.map(k => ({ text: k.translations[source], keyId: k.id })),
+                sourceLang: source,
+                targetLang: job.lang,
+                projectId: project.id,
+                save: true,
+                overwrite,
+            });
+        }
+        catch (err) {
+            // Servers before the 100-item limit reject the batch as invalid: retry it in halves
+            if (err instanceof CliError && err.status === 400 && job.keys.length > LEGACY_BATCH) {
+                batchSize = LEGACY_BATCH;
+                queue.unshift(...chunk(job.keys, LEGACY_BATCH).map(k => ({ lang: job.lang, keys: k })));
+                return;
+            }
+            throw err;
+        }
+        out.provider = res.provider ?? out.provider;
+        out.usage = res.usage ?? out.usage;
+        const serverSaved = typeof res.saved === 'number';
+        out.savedBy ?? (out.savedBy = serverSaved ? 'server' : 'client');
+        const byId = new Map((res.results ?? []).filter(r => r.keyId).map(r => [r.keyId, r]));
+        const failedById = new Map((res.failed ?? []).filter(f => f.keyId).map(f => [f.keyId, f]));
+        const toSave = [];
+        job.keys.forEach((key, j) => {
+            const r = byId.get(key.id) ?? (byId.size ? undefined : res.results?.[j]);
+            const text = r?.translatedText;
+            if (typeof text !== 'string' || text === '') {
+                fail(job.lang, key, r?.error ?? failedById.get(key.id)?.error ?? (r ? 'empty_result' : 'missing_result'));
+            }
+            else if (serverSaved) {
+                if (r.saved === false)
+                    fail(job.lang, key, 'not_saved');
+                else
+                    succeed(job.lang, key, text, Boolean(r.copied));
+            }
+            else {
+                toSave.push({ key, text, copied: Boolean(r.copied) });
+            }
+        });
+        tick();
+        // Older servers: save each translation ourselves, a few at a time
+        let fatal;
+        await pool(toSave, SAVE_CONCURRENCY, async ({ key, text, copied }) => {
+            if (fatal) {
+                fail(job.lang, key, 'not_saved');
+                return;
+            }
+            try {
+                await session.api.patch(keyPath(key, job.lang), { value: text });
+                succeed(job.lang, key, text, copied);
+            }
+            catch (err) {
+                if (err instanceof CliError && (err.exitCode === ExitCode.Auth || err.exitCode === ExitCode.Limit))
+                    fatal = err;
+                fail(job.lang, key, `not saved: ${err.message}`);
+            }
+            tick();
+        });
+        if (fatal)
+            throw fatal;
+    };
     try {
-        for (const { lang, keys: todo } of plan) {
-            for (let i = 0; i < todo.length; i += BATCH) {
-                const batch = todo.slice(i, i + BATCH);
-                const res = await session.api.post(`/orgs/${session.orgId}/translate/bulk`, {
-                    items: batch.map(k => ({ text: k.translations[source], keyId: k.id })),
-                    sourceLang: source,
-                    targetLang: lang,
-                    projectId: project.id,
-                });
-                usage = res.usage;
-                provider = res.provider;
-                for (const [j, key] of batch.entries()) {
-                    const text = res.results[j]?.translatedText;
-                    if (!text)
-                        continue;
-                    await session.api.patch(`/orgs/${session.orgId}/projects/${project.id}/keys/${key.id}/translations/${encodeURIComponent(lang)}`, { value: text });
-                    done.push({ language: lang, key: key.key, text });
-                    progress.text = `Translating ${done.length}/${total}…`;
+        const worker = async () => {
+            while (queue.length && !out.fatal) {
+                const job = queue.shift();
+                if (job.keys.length > batchSize) {
+                    queue.unshift(...chunk(job.keys, batchSize).map(k => ({ lang: job.lang, keys: k })));
+                    continue;
+                }
+                try {
+                    await runJob(job);
+                }
+                catch (err) {
+                    // Stop starting new batches; batches already in flight finish and are reported
+                    out.fatal ?? (out.fatal = asUpstreamError(err));
                 }
             }
-        }
+        };
+        await Promise.all(Array.from({ length: CONCURRENCY }, worker));
     }
     finally {
-        progress.stop();
+        bar.stop();
     }
-    if (runtime.json)
-        return printJson({ source, translated: done, provider, usage });
-    for (const d of done)
-        log.out(`${chalk.dim(d.language)}  ${d.key}  ${d.text}`);
-    const quota = provider === 'org'
+    return out;
+}
+/** The API (not the user) failed: never report that as "invalid usage" (exit 2). */
+function asUpstreamError(err) {
+    if (!(err instanceof CliError))
+        return new CliError(err?.message ?? String(err), ExitCode.Error);
+    if (err.exitCode !== ExitCode.Usage)
+        return err;
+    const code = err.status !== undefined && err.status >= 500 ? ExitCode.Network : ExitCode.Error;
+    return new CliError(err.message, code, err.hint, err.status);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+function report(project, languages, total, o) {
+    const copied = o.done.filter(d => d.copied).length;
+    const translated = o.done.length - copied;
+    const notAttempted = total - o.done.length - o.failed.length;
+    const exitCode = o.fatal ? o.fatal.exitCode : o.failed.length ? ExitCode.Partial : ExitCode.Ok;
+    if (runtime.json) {
+        printJson({
+            project: project.slug,
+            source: project.defaultLanguage,
+            total,
+            translated: o.done,
+            failed: o.failed,
+            counts: { translated, copied, failed: o.failed.length, notAttempted },
+            provider: o.provider,
+            usage: o.usage,
+            exitCode,
+            ...(o.fatal ? { error: { message: o.fatal.message, exitCode: o.fatal.exitCode, hint: o.fatal.hint ?? null, status: o.fatal.status ?? null } } : {}),
+        });
+    }
+    // Summary and failures go to stderr, so they aren't lost when stdout is piped to a file
+    const quota = o.provider === 'org'
         ? 'using your own DeepL key'
-        : usage?.limit != null ? `${usage.used}/${usage.limit} AI translations used this month` : `${usage?.used ?? done.length} AI translations used this month`;
-    log.success(`Translated ${done.length} string(s) into ${plan.filter(p => p.keys.length).map(p => p.lang).join(', ')} (${quota}).`);
-    log.info(chalk.dim(`AI translations are held back from "langctl pull" until reviewed. Check them with "langctl review ${project.slug}", then approve with --approve (or edit them in the web app).`));
+        : o.usage?.limit != null ? `${o.usage.used}/${o.usage.limit} AI translations used this month` : o.usage ? `${o.usage.used} AI translations used this month` : '';
+    const summary = `Translated ${translated}, copied ${copied} unchanged, failed ${o.failed.length}` +
+        (notAttempted > 0 ? `, not attempted ${notAttempted}` : '') +
+        ` (${languages.join(', ')}${quota ? `; ${quota}` : ''}).`;
+    if (!runtime.json) {
+        if (o.failed.length || o.fatal)
+            process.stderr.write(`${chalk.yellow('✖')} ${summary}\n`);
+        else
+            log.success(summary);
+    }
+    if (o.failed.length && !runtime.json) {
+        process.stderr.write(`${chalk.yellow('Needs a human translation:')}\n`);
+        for (const f of o.failed) {
+            process.stderr.write(`  ${chalk.dim(f.language)}  ${f.key}  ${JSON.stringify(f.sourceText)}  ${chalk.dim(`(${f.error})`)}\n`);
+        }
+    }
+    if (o.done.length) {
+        log.info(chalk.dim(`AI translations are held back from "langctl pull" until reviewed. Check them with "langctl review ${project.slug}", then approve with --approve (or edit them in the web app).`));
+    }
+    if (o.fatal) {
+        if (runtime.json) {
+            process.exitCode = o.fatal.exitCode;
+            return;
+        }
+        throw o.fatal;
+    }
+    if (o.failed.length) {
+        const hint = `Add these in the web app or with "langctl keys translate ${project.slug} <key> -l <lang> -t <text>", then re-run (only missing strings are translated).`;
+        if (!runtime.json)
+            log.error(`${o.failed.length} string(s) could not be translated automatically.`, hint);
+        process.exitCode = ExitCode.Partial;
+    }
 }

package/dist/core/config.js

@@ -6,8 +6,27 @@ export const DEFAULT_API_URL = 'https://api.langctl.com/api/v1';
 export function configDir() {
     return process.env.LANGCTL_CONFIG_DIR ? resolve(process.env.LANGCTL_CONFIG_DIR) : join(homedir(), '.langctl');
 }
+// ── Profiles ───────────────────────────────────────────────────
+//
+// The default profile is ~/.langctl/config.json (unchanged since 0.2). Named profiles live in
+// ~/.langctl/profiles/<name>.json and are selected with --profile <name> or LANGCTL_PROFILE.
+const PROFILE_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/** The active profile name, or null for the default profile. */
+export function activeProfile() {
+    const raw = (flagOverrides.profile ?? process.env.LANGCTL_PROFILE ?? '').trim();
+    if (!raw || raw === 'default')
+        return null;
+    if (!PROFILE_RE.test(raw)) {
+        throw usageError(`Invalid profile name "${raw}".`, 'Use letters, digits, ".", "_" or "-" (e.g. --profile client-a).');
+    }
+    return raw;
+}
+export function profileLabel() {
+    return activeProfile() ?? 'default';
+}
 export function configPath() {
-    return join(configDir(), 'config.json');
+    const profile = activeProfile();
+    return profile ? join(configDir(), 'profiles', `${profile}.json`) : join(configDir(), 'config.json');
 }
 export function readUserConfig() {
     const path = configPath();
@@ -87,7 +106,7 @@ export function maskApiKey(key) {
 }
 // ── Project config (langctl.json) ──────────────────────────────
 export const PROJECT_CONFIG_FILE = 'langctl.json';
-const KNOWN_KEYS = new Set(['$schema', 'project', 'format', 'output', 'languages', 'sourceLanguage', 'includeDrafts', 'module']);
+const KNOWN_KEYS = new Set(['$schema', 'project', 'format', 'output', 'languages', 'sourceLanguage', 'includeDrafts', 'module', 'prefix']);
 /** Find langctl.json in the current directory or the nearest parent. */
 export function loadProjectConfig(cwd = process.cwd()) {
     let dir = resolve(cwd);
@@ -105,6 +124,9 @@ export function loadProjectConfig(cwd = process.cwd()) {
             if (unknown.length) {
                 throw usageError(`${candidate} has unknown field(s): ${unknown.join(', ')}`, `Allowed: ${[...KNOWN_KEYS].filter(k => k !== '$schema').join(', ')}`);
             }
+            if (config.prefix !== undefined && (typeof config.prefix !== 'string' || !config.prefix.trim())) {
+                throw usageError(`${candidate}: "prefix" must be a non-empty string, e.g. "dashboard."`);
+            }
             if (config.languages !== undefined && !Array.isArray(config.languages)) {
                 throw usageError(`${candidate}: "languages" must be an array of language codes`);
             }
@@ -125,6 +147,30 @@ export function writeProjectConfig(path, config) {
         ...(config.sourceLanguage ? { sourceLanguage: config.sourceLanguage } : {}),
         ...(config.includeDrafts ? { includeDrafts: true } : {}),
         ...(config.module ? { module: config.module } : {}),
+        ...(config.prefix ? { prefix: config.prefix } : {}),
     };
     writeFileSync(path, JSON.stringify(ordered, null, 2) + '\n');
 }
+// ── Key prefixes ───────────────────────────────────────────────
+/** "dashboard" → "dashboard."; prefixes that already end in a separator are kept as given. */
+export function normalizePrefix(prefix) {
+    const p = prefix?.trim();
+    if (!p)
+        return undefined;
+    return /[.:_/-]$/.test(p) ? p : `${p}.`;
+}
+/** The prefix in effect: the flag, else langctl.json's "prefix". */
+export function resolvePrefix(flag, cfg) {
+    return normalizePrefix(flag ?? cfg.prefix);
+}
+/**
+ * Map key names typed by a user to the names stored in langctl: with a prefix configured,
+ * "common.save" and "dashboard.common.save" both mean "dashboard.common.save".
+ */
+export function withPrefix(name, prefix, known) {
+    if (!prefix || name.startsWith(prefix))
+        return name;
+    if (known && known.has(name) && !known.has(prefix + name))
+        return name;
+    return prefix + name;
+}

package/dist/core/errors.js

@@ -10,6 +10,8 @@ export const ExitCode = {
     Network: 5,
     Limit: 6,
     Drift: 7,
+    /** Partial success: some strings could not be translated and need a human (e.g. `translate`) */
+    Partial: 8,
 };
 export class CliError extends Error {
     constructor(message, exitCode = ExitCode.Error, hint, status) {
@@ -22,9 +24,16 @@ export class CliError extends Error {
 }
 export const usageError = (message, hint) => new CliError(message, ExitCode.Usage, hint);
 export const notFoundError = (message, hint) => new CliError(message, ExitCode.NotFound, hint);
+/** Shown when the API no longer knows a path this CLI calls — almost always an outdated CLI. */
+export const UPGRADE_HINT = 'This version of langctl may be too old for the Langctl API. Upgrade with: npm i -g langctl@latest';
+/** Fastify's default 404 for an unknown route: "Route GET:/api/v1/… not found". */
+export const isMissingRoute = (status, message) => status === 410 || (status === 404 && /^Route [A-Z]+:\S+ not found$/i.test(message ?? ''));
 /** Map an HTTP error response from the API to a CliError with the right exit code and a useful hint. */
 export function httpError(status, serverMessage, method, path) {
     const msg = serverMessage || `HTTP ${status}`;
+    if (isMissingRoute(status, serverMessage)) {
+        return new CliError(`The Langctl API does not support ${method} ${path} (${status}).`, status === 410 ? ExitCode.Error : ExitCode.NotFound, UPGRADE_HINT, status);
+    }
     if (status === 401) {
         return new CliError('Your API key is invalid or has been revoked.', ExitCode.Auth, 'Create a new key at https://app.langctl.com/organization/api-keys and run "langctl auth --stdin", or set LANGCTL_API_KEY.', status);
     }

package/dist/core/http.js

@@ -110,7 +110,9 @@ export class ApiClient {
             }
             if (!res.ok) {
                 const d = data;
-                throw httpError(res.status, d?.error || d?.message, method, url.pathname);
+                // Fastify's own 404 ("Route GET:/… not found") is in `message`; ours are in `error`
+                const routeMessage = typeof d?.message === 'string' && /^Route /.test(d.message) ? d.message : undefined;
+                throw httpError(res.status, routeMessage || d?.error || d?.message, method, url.pathname);
             }
             return { status: res.status, data: data, etag: res.headers.get('etag'), notModified: false };
         }
@@ -137,6 +139,10 @@ export async function validateKey(api, apiKey) {
     return res.valid && res.organizationId ? { organizationId: res.organizationId, scopes: res.scopes ?? [] } : null;
 }
 let cached = null;
+/** Forget the cached session (tests; switching keys within one process). */
+export function resetSession() {
+    cached = null;
+}
 export async function getSession() {
     if (cached)
         return cached;

package/dist/core/output.js

@@ -81,6 +81,43 @@ export function spinner(text) {
         },
     };
 }
+/**
+ * Counter for long operations: "Translating 312/889…". At a terminal it is a spinner line; in CI
+ * and pipes (where a spinner is invisible) it prints a plain stderr line every ~10%.
+ */
+export function progress(label, total) {
+    const text = (n) => `${label} ${n}/${total}…`;
+    if (isInteractive() && !runtime.quiet && !runtime.verbose) {
+        const spin = spinner(text(0));
+        return {
+            update(n) { spin.text = text(n); },
+            out(line) {
+                if (runtime.json)
+                    return;
+                process.stderr.write('\r\x1b[2K');
+                process.stdout.write(line + '\n');
+            },
+            stop() { spin.stop(); },
+        };
+    }
+    const step = Math.max(1, Math.ceil(total / 10));
+    let next = step;
+    let last = -1;
+    return {
+        update(n) {
+            if (runtime.quiet || runtime.json || total < 1 || n === last)
+                return;
+            if (n >= next || n === total) {
+                process.stderr.write(text(n) + '\n');
+                last = n;
+                while (next <= n)
+                    next += step;
+            }
+        },
+        out(line) { log.out(line); },
+        stop() { },
+    };
+}
 /** Minimal aligned table for human output. */
 export function table(rows, header) {
     const all = header ? [header, ...rows] : rows;

package/dist/core/update-check.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { configDir } from './config.js';
+import { detectCi, runtime } from './output.js';
+import { VERSION } from '../version.js';
+/**
+ * "A newer langctl is available" notice. At most one registry lookup per 24 hours (timestamp in
+ * ~/.langctl/update-check.json), never blocks a command for more than ~1.5s, and is off in
+ * --json / --quiet / CI unless LANGCTL_UPDATE_CHECK=1. LANGCTL_UPDATE_CHECK=0 turns it off.
+ */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const UPDATE_CHECK_TIMEOUT_MS = 1500;
+const REGISTRY_URL = 'https://registry.npmjs.org/langctl/latest';
+function statePath() {
+    return join(configDir(), 'update-check.json');
+}
+function readState() {
+    try {
+        return JSON.parse(readFileSync(statePath(), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(state) {
+    try {
+        mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+        writeFileSync(statePath(), JSON.stringify(state) + '\n', { mode: 0o600 });
+    }
+    catch { /* read-only home: never fail a command over this */ }
+}
+export function updateCheckEnabled() {
+    const flag = String(process.env.LANGCTL_UPDATE_CHECK ?? '').toLowerCase();
+    if (['0', 'false', 'no', 'off'].includes(flag))
+        return false;
+    if (['1', 'true', 'yes', 'on'].includes(flag))
+        return true;
+    return !runtime.json && !runtime.quiet && !detectCi();
+}
+/** Compare x.y.z versions (pre-release tags ignored). */
+export function isNewer(latest, current) {
+    const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map(n => Number(n) || 0);
+    const [a, b] = [parse(latest), parse(current)];
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    }
+    return false;
+}
+export function updateMessage(latest, current = VERSION) {
+    return `langctl ${latest} is available (you have ${current}): npm i -g langctl@latest`;
+}
+/**
+ * Start the check (call early, runs alongside the command). Resolves to the notice to print,
+ * or null. Never rejects.
+ */
+export function startUpdateCheck(now = Date.now()) {
+    if (!updateCheckEnabled())
+        return Promise.resolve(null);
+    const state = readState();
+    if (state.checkedAt && now - state.checkedAt < UPDATE_CHECK_INTERVAL_MS)
+        return Promise.resolve(null);
+    // Record the attempt up front, so being offline doesn't mean a lookup on every run
+    writeState({ ...state, checkedAt: now });
+    return (async () => {
+        try {
+            const res = await fetch(REGISTRY_URL, {
+                headers: { Accept: 'application/json' },
+                signal: AbortSignal.timeout(UPDATE_CHECK_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return null;
+            const latest = (await res.json()).version;
+            if (typeof latest !== 'string')
+                return null;
+            writeState({ checkedAt: now, latest });
+            return isNewer(latest, VERSION) ? updateMessage(latest) : null;
+        }
+        catch {
+            return null;
+        }
+    })();
+}
+/** Wait (bounded) for the check and print the notice to stderr. */
+export async function finishUpdateCheck(pending) {
+    if (!pending)
+        return;
+    const timeout = new Promise(r => setTimeout(() => r(null), UPDATE_CHECK_TIMEOUT_MS).unref());
+    const message = await Promise.race([pending, timeout]);
+    if (message)
+        process.stderr.write(`${chalk.yellow('update:')} ${message}\n`);
+}

package/dist/formats/index.js

@@ -283,3 +283,42 @@ export function expandTemplate(template, lang, defaultLang) {
 export function templateHasLanguage(template) {
     return /\{(lang|lang_|android)\}/.test(template);
 }
+// ── Rich JSON input ({ "key": { "value": "…", "description": "…" } }) ──
+const RICH_FIELDS = new Set(['value', 'description']);
+const isRichValue = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+    && typeof v.value === 'string'
+    && Object.keys(v).every(k => RICH_FIELDS.has(k))
+    && ['undefined', 'string'].includes(typeof v.description);
+/**
+ * Read a flat JSON file whose values carry descriptions: { "home.title": { "value": "Welcome", "description": "…" } }.
+ * Returns null for anything else (plain or nested JSON), so callers fall back to the normal parser.
+ * Only files where every object value has this exact shape count as rich.
+ */
+export function parseRichJson(content) {
+    let data;
+    try {
+        data = JSON.parse(content.replace(/^/, ''));
+    }
+    catch {
+        return null;
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const values = Object.values(data);
+    const objects = values.filter(v => typeof v !== 'string');
+    if (objects.length === 0 || !objects.every(isRichValue))
+        return null;
+    const translations = {};
+    const descriptions = {};
+    for (const [key, v] of Object.entries(data)) {
+        if (typeof v === 'string') {
+            translations[key] = v;
+            continue;
+        }
+        const rich = v;
+        translations[key] = rich.value;
+        if (rich.description?.trim())
+            descriptions[key] = rich.description;
+    }
+    return { translations, descriptions };
+}