langctl 0.3.0 → 0.5.0

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 };
+}

package/dist/index.js

@@ -11,11 +11,14 @@ import { orgInfoCommand, orgPlanCommand, orgStatsCommand } from './commands/org.
 import { projectsAddLanguageCommand, projectsCreateCommand, projectsDeleteCommand, projectsGetCommand, projectsListCommand, projectsRemoveLanguageCommand, projectsStatsCommand, projectsUpdateCommand, } from './commands/projects.js';
 import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
+import { translateCommand } from './commands/translate.js';
+import { reviewCommand } from './commands/review.js';
 import { getTeamMemberCommand, inviteTeamMemberCommand, listInvitationsCommand, listTeamCommand, removeTeamMemberCommand, revokeInvitationCommand, updateTeamRoleCommand, } from './commands/team.js';
 import { flagOverrides } from './core/config.js';
 import { CliError, ExitCode, usageError } from './core/errors.js';
 import { httpSettings } from './core/http.js';
 import { log, printJson, runtime } from './core/output.js';
+import { finishUpdateCheck, startUpdateCheck } from './core/update-check.js';
 import { VERSION } from './version.js';
 const collect = (value, previous = []) => [...previous, value];
 /** Global flags, accepted before or after the subcommand (`langctl --json pull` and `langctl pull --json`). */
@@ -27,6 +30,7 @@ function withGlobals(cmd) {
         .option('-y, --yes', 'skip confirmation prompts (required for destructive commands in CI)')
         .option('--api-key <key>', 'API key (prefer the LANGCTL_API_KEY env var)')
         .option('--api-url <url>', 'API base URL (env: LANGCTL_API_URL)')
+        .option('--profile <name>', 'use a named credentials profile (env: LANGCTL_PROFILE)')
         .option('--timeout <seconds>', 'request timeout in seconds (env: LANGCTL_TIMEOUT)')
         .option('--no-color', 'disable colors (also honors NO_COLOR)');
 }
@@ -57,13 +61,17 @@ program.hook('preAction', (_root, action) => {
         flagOverrides.apiKey = o.apiKey;
     if (typeof o.apiUrl === 'string')
         flagOverrides.apiUrl = o.apiUrl;
+    if (typeof o.profile === 'string')
+        flagOverrides.profile = o.profile;
     if (o.timeout !== undefined) {
         const s = Number(o.timeout);
         if (!Number.isFinite(s) || s <= 0)
             throw usageError('--timeout must be a positive number of seconds');
         httpSettings.timeoutMs = s * 1000;
     }
+    updateCheck = startUpdateCheck();
 });
+let updateCheck = null;
 // ── Setup & auth ────────────────────────────────────────────────
 withGlobals(program.command('init'))
     .description('set up this repository: authenticate if needed and write langctl.json')
@@ -91,10 +99,12 @@ withGlobals(program.command('pull [project]'))
     .addOption(new Option('-d, --dir <path>', 'legacy: base directory for the default layout').hideHelp())
     .option('-m, --module <name>', 'only keys from this module')
     .option('--include-drafts', 'include unpublished keys (excluded by default)')
+    .option('--include-unreviewed', 'include AI translations nobody has reviewed yet (excluded by default)')
     .addOption(new Option('--no-published-only').hideHelp())
     .option('--check', 'do not write; exit 7 if any file is out of date (for CI)')
     .option('--dry-run', 'show what would change without writing')
     .option('--require-complete', 'exit 1 if any language is missing translations')
+    .option('--strip-prefix <prefix>', 'only keys with this prefix, written without it (default: "prefix" in langctl.json)')
     .action(run((project, opts) => pullCommand(project, { ...opts, languages: opts.languages ?? opts.language })));
 withGlobals(program.command('push [project]'))
     .description('upload translation files (by default only the source language)')
@@ -104,6 +114,8 @@ withGlobals(program.command('push [project]'))
     .option('-m, --module <name>', 'assign new keys to this module')
     .option('--overwrite', 'replace existing translations (default: only add new keys/languages)')
     .option('--publish', 'publish the uploaded keys')
+    .option('--prefix <prefix>', 'add this prefix to every key (default: "prefix" in langctl.json)')
+    .option('--descriptions <file>', 'flat JSON { "key": "description" } stored with the keys (existing keys need --overwrite)')
     .option('--dry-run', 'show what would change without uploading')
     .action(run((project, opts) => pushCommand(project, opts)));
 withGlobals(program.command('export [project]'))
@@ -192,6 +204,20 @@ withGlobals(keys.command('unpublish <project> [keys...]')).description('move key
     .option('--all', 'unpublish every published key')
     .option('-m, --module <name>', 'unpublish every key in a module')
     .action(run((project, names, opts) => publishKeysCommand(project, names, opts, false)));
+// ── AI translation ──────────────────────────────────────────────
+withGlobals(program.command('translate [project]')).description('fill missing translations with AI (DeepL) from the default language')
+    .option('-t, --to <codes>', 'comma-separated target languages (default: every non-default language)')
+    .option('-k, --keys <names>', 'only these keys (comma-separated)')
+    .option('-m, --module <name>', 'only keys in a module')
+    .option('--overwrite', 'retranslate keys that already have a translation')
+    .option('--dry-run', 'show what would be translated without using any AI translations')
+    .action(run((project, opts) => translateCommand(project, opts)));
+withGlobals(program.command('review [project]')).description('list AI translations awaiting review, or approve them')
+    .option('--approve', 'approve the listed translations (asks to confirm; --yes in CI)')
+    .option('-k, --keys <names>', 'only these keys (comma-separated)')
+    .option('-l, --languages <codes>', 'only these languages (comma-separated)')
+    .option('-m, --module <name>', 'only keys in a module')
+    .action(run((project, opts) => reviewCommand(project, opts)));
 // ── Team & org ──────────────────────────────────────────────────
 const team = program.command('team').description('manage team members (needs an API key with the org:admin scope)');
 withGlobals(team.command('list')).alias('ls').description('list members').action(run(() => listTeamCommand()));
@@ -227,6 +253,7 @@ In CI (no config file needed):
 Exit codes:
   0 ok · 1 error · 2 invalid usage · 3 auth/permission · 4 not found
   5 network/API unavailable · 6 plan limit reached · 7 files out of date (--check)
+  8 partial: some strings could not be AI-translated and need a human (translate)
 
 Docs: https://langctl.com/docs`);
 // ── Run ─────────────────────────────────────────────────────────
@@ -245,6 +272,7 @@ async function main() {
     catch (err) {
         process.exitCode = handleError(err);
     }
+    await finishUpdateCheck(updateCheck);
 }
 function handleError(err) {
     if (err instanceof CommanderError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langctl",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Translation management CLI for developers: sync i18n files (JSON, Android, iOS, Flutter ARB) between your repo, CI and Langctl.",
   "main": "dist/index.js",
   "type": "module",