langctl 0.2.0 → 0.4.0

package/dist/commands/pull.js

@@ -1,139 +1,96 @@
 import chalk from 'chalk';
-import ora from 'ora';
-import { writeFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
-import { isAuthenticated } from '../auth.js';
-import { getApiClient } from '../api.js';
-import { config } from '../config.js';
-import { exportTranslations } from '../exporters/index.js';
-/**
- * Get platform-specific output directory
- */
-function getPlatformDirectory(format) {
-    const platformDirs = {
-        'json': 'i18n',
-        'json-nested': 'i18n',
-        'ios': 'ios',
-        'android': 'android',
-        'flutter': 'flutter'
-    };
-    return platformDirs[format] || 'i18n';
-}
-export async function pullCommand(projectIdentifier, options) {
-    // Check authentication
-    if (!isAuthenticated()) {
-        console.log(chalk.red('✗ Not authenticated. Please run "langctl auth <api-key>" first.\n'));
-        process.exitCode = 1;
-        return;
+import { relative, resolve } from 'path';
+import { loadProjectConfig } from '../core/config.js';
+import { CliError, ExitCode, usageError } from '../core/errors.js';
+import { syncFile } from '../core/files.js';
+import { getSession } from '../core/http.js';
+import { log, printJson, runtime, spinner } from '../core/output.js';
+import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
+import { expandTemplate, getFormat, templateHasLanguage } from '../formats/index.js';
+export async function pullCommand(projectArg, opts) {
+    const loaded = loadProjectConfig();
+    const cfg = loaded?.config ?? {};
+    const slug = projectSlugFrom(projectArg);
+    const format = getFormat(opts.format ?? cfg.format);
+    // Paths from flags are relative to the cwd; paths from langctl.json are relative to that file
+    let template;
+    if (opts.output)
+        template = resolve(opts.output);
+    else if (opts.dir)
+        template = resolve(opts.dir, format.defaultOutput);
+    else if (cfg.output && loaded)
+        template = resolve(loaded.root, cfg.output);
+    else
+        template = resolve(format.defaultOutput);
+    const includeDrafts = Boolean(opts.includeDrafts || opts.publishedOnly === false || cfg.includeDrafts);
+    const module = opts.module ?? cfg.module;
+    const dryRun = Boolean(opts.check || opts.dryRun);
+    const session = await getSession();
+    const spin = spinner(`Fetching ${slug}…`);
+    let project, snapshot;
+    try {
+        project = await getProject(session, slug);
+        // ETag-cached: unchanged translations come back as a tiny 304 and the saved snapshot is reused
+        ({ data: snapshot } = await session.api.getCached(`/orgs/${session.orgId}/projects/${project.id}/export`, {
+            publishedOnly: includeDrafts ? 'false' : 'true',
+            includeUnreviewed: opts.includeUnreviewed ? 'true' : undefined,
+            module,
+        }));
     }
-    const orgId = config.get('organizationId');
-    if (!orgId) {
-        console.log(chalk.red('✗ Organization ID not found. Please run "langctl auth <api-key>" again.\n'));
-        process.exitCode = 1;
-        return;
+    finally {
+        spin.stop();
     }
-    // Set defaults
-    const format = (options.format || 'json');
-    const publishedOnly = options.publishedOnly !== false; // Default to true
-    const specificLanguage = options.language;
-    const baseDir = options.dir || './translations';
-    // Validate format
-    const validFormats = ['json', 'json-nested', 'ios', 'android', 'flutter'];
-    if (!validFormats.includes(format)) {
-        console.log(chalk.red(`✗ Invalid format: ${format}`));
-        console.log(chalk.yellow(`Valid formats: ${validFormats.join(', ')}\n`));
-        return;
+    const languages = opts.languages ? splitList(opts.languages) : (cfg.languages ?? project.languages);
+    assertLanguages(project, languages);
+    if (languages.length > 1 && !templateHasLanguage(template)) {
+        throw usageError(`Output "${relative(process.cwd(), template)}" has no {lang} placeholder, so ${languages.length} languages would overwrite each other.`, 'Use a template like "locales/{lang}.json", or pick one language with --languages.');
     }
-    const spinner = ora('Resolving project...').start();
-    try {
-        const api = getApiClient();
-        // Resolve project by slug
-        const project = await api.get(`/orgs/${orgId}/projects/by-slug/${projectIdentifier}`);
-        if (!project) {
-            spinner.fail(chalk.red(`Project "${projectIdentifier}" not found`));
-            console.log(chalk.yellow('\nRun "langctl projects list" to see available projects.\n'));
-            return;
-        }
-        // Determine which languages to pull
-        let languagesToPull;
-        if (specificLanguage) {
-            if (!project.languages.includes(specificLanguage)) {
-                spinner.fail(chalk.red(`Language "${specificLanguage}" not found in project`));
-                console.log(chalk.yellow(`Available languages: ${project.languages.join(', ')}\n`));
-                return;
-            }
-            languagesToPull = [specificLanguage];
+    const files = [];
+    for (const lang of languages) {
+        const entries = snapshot.keys
+            .filter(k => typeof k.translations[lang] === 'string' && k.translations[lang] !== '')
+            .map(k => ({ key: k.key, value: k.translations[lang], description: k.description }));
+        const path = expandTemplate(template, lang, project.defaultLanguage);
+        const status = syncFile(path, format.serialize(entries, lang), dryRun, text => format.parse(text, lang));
+        files.push({ path, language: lang, status, keys: entries.length, translated: entries.length, total: snapshot.keys.length });
+    }
+    const changed = files.filter(f => f.status !== 'unchanged');
+    const incomplete = files.filter(f => f.translated < f.total);
+    if (runtime.json) {
+        printJson({
+            project: project.slug,
+            format: format.id,
+            publishedOnly: !includeDrafts,
+            keys: snapshot.keys.length,
+            dryRun,
+            files: files.map(f => ({ ...f, path: relative(process.cwd(), f.path) })),
+            changed: changed.length,
+            unreviewedSkipped: snapshot.metadata?.unreviewedSkipped ?? 0,
+        });
+    }
+    else {
+        for (const f of files) {
+            const icon = f.status === 'unchanged' ? chalk.dim('=') : f.status === 'created' ? chalk.green('+') : chalk.yellow('~');
+            const verb = dryRun && f.status !== 'unchanged' ? `would be ${f.status}` : f.status;
+            const coverage = f.translated < f.total ? chalk.yellow(` ${f.translated}/${f.total} translated`) : '';
+            log.out(`${icon} ${relative(process.cwd(), f.path)}  ${chalk.dim(verb)}${coverage}`);
         }
-        else {
-            languagesToPull = project.languages;
+        log.info(chalk.dim(`${project.slug}: ${snapshot.keys.length} ${includeDrafts ? '' : 'published '}keys, ${languages.length} language(s), format ${format.id}`));
+        const unreviewed = snapshot.metadata?.unreviewedSkipped ?? 0;
+        if (unreviewed > 0) {
+            log.warn(`${unreviewed} AI translation(s) awaiting review were left out (your app falls back to ${project.defaultLanguage} for them). Review with "langctl review ${project.slug}", or pass --include-unreviewed.`);
         }
-        spinner.text = `Fetching translations for "${project.name}"...`;
-        // Get platform directory
-        const platformDir = getPlatformDirectory(format);
-        // Export translations for each language
-        const exportedFiles = [];
-        let totalKeyCount = 0;
-        for (const language of languagesToPull) {
-            spinner.text = `Exporting ${language}...`;
-            // Fetch flat translations from the API
-            const result = await api.get(`/orgs/${orgId}/projects/${project.id}/export`, {
-                language,
-                publishedOnly: publishedOnly ? 'true' : 'false'
-            });
-            // Convert flat translations to TranslationKey array for the exporter
-            const flatTranslations = result.translations || {};
-            const translationKeys = Object.entries(flatTranslations).map(([key, value]) => ({
-                key,
-                translations: { [language]: value }
-            }));
-            if (totalKeyCount === 0) {
-                totalKeyCount = translationKeys.length;
-            }
-            const exportResult = exportTranslations(translationKeys, language, format);
-            // Determine output path
-            let outputPath;
-            if (options.output) {
-                // If custom output is specified and multiple languages, append language code
-                if (languagesToPull.length > 1) {
-                    const ext = exportResult.filename.split('.').pop();
-                    const base = options.output.replace(/\.[^.]+$/, '');
-                    outputPath = `${base}-${language}.${ext}`;
-                }
-                else {
-                    outputPath = options.output;
-                }
-            }
-            else {
-                // Default output path: <baseDir>/<platform>/<language>.<ext>
-                const ext = exportResult.filename.split('.').pop();
-                outputPath = join(baseDir, platformDir, `${language}.${ext}`);
-            }
-            // Create directory if it doesn't exist
-            const dir = dirname(outputPath);
-            mkdirSync(dir, { recursive: true });
-            writeFileSync(outputPath, exportResult.content, 'utf-8');
-            exportedFiles.push(outputPath);
-            spinner.succeed(chalk.green(`Exported ${language} → ${outputPath}`));
-            // Restart spinner if more languages remain
-            if (languagesToPull.indexOf(language) < languagesToPull.length - 1) {
-                spinner.start();
-            }
+        if (snapshot.keys.length === 0 && !includeDrafts) {
+            log.warn('No published keys — drafts are excluded by default. Publish keys, or pass --include-drafts.');
         }
-        // Summary
-        console.log(chalk.hex('#10b981').bold('\n📦 Export Summary:'));
-        console.log(chalk.white(`  Project: ${project.name}`));
-        console.log(chalk.white(`  Format: ${format}`));
-        console.log(chalk.white(`  Platform: ${platformDir}`));
-        console.log(chalk.white(`  Output: ${baseDir}`));
-        console.log(chalk.white(`  Keys: ${totalKeyCount}`));
-        console.log(chalk.white(`  Languages: ${languagesToPull.join(', ')}`));
-        console.log(chalk.white(`  Files: ${exportedFiles.length}`));
-        console.log('');
     }
-    catch (error) {
-        spinner.fail(chalk.red('Failed to pull translations'));
-        console.error(chalk.red(`Error: ${error.message}\n`));
-        process.exitCode = 1;
+    if (opts.requireComplete && incomplete.length) {
+        throw new CliError(`Missing translations: ${incomplete.map(f => `${f.language} (${f.total - f.translated} missing)`).join(', ')}`, ExitCode.Error);
     }
+    if (opts.check && changed.length) {
+        throw new CliError(`${changed.length} translation file(s) are out of date.`, ExitCode.Drift, 'Run "langctl pull" and commit the result.');
+    }
+}
+export function splitList(value) {
+    return value.split(',').map(s => s.trim()).filter(Boolean);
 }
-//# sourceMappingURL=pull.js.map

package/dist/commands/push.js

@@ -0,0 +1,125 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { relative, resolve } from 'path';
+import { loadProjectConfig } from '../core/config.js';
+import { notFoundError, usageError } from '../core/errors.js';
+import { getSession } from '../core/http.js';
+import { log, printJson, runtime, spinner } from '../core/output.js';
+import { assertLanguages, getProject, projectSlugFrom } from '../core/project.js';
+import { expandTemplate, formatFromPath, getFormat, templateHasLanguage } from '../formats/index.js';
+import { splitList } from './pull.js';
+const CHUNK = 1000; // stay well under the API's 1 MB request body limit
+/** Upload one language's translations. Shared by `push` and the single-file `import`. */
+export async function uploadTranslations(session, project, language, translations, opts) {
+    const entries = Object.entries(translations);
+    const result = { language, keys: entries.length, created: 0, updated: 0, unchanged: 0, published: undefined };
+    if (entries.length === 0)
+        return result;
+    if (opts.dryRun) {
+        // Compare against the server, including drafts, without writing anything
+        const snap = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/export`, { language, publishedOnly: 'false' });
+        const all = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/export`, { publishedOnly: 'false' });
+        const existingKeys = new Set(all.keys.map(k => k.key));
+        for (const [key, value] of entries) {
+            if (!existingKeys.has(key))
+                result.created++;
+            else if (snap.translations[key] === value)
+                result.unchanged++;
+            else if (opts.overwrite || snap.translations[key] === undefined)
+                result.updated++;
+            else
+                result.unchanged++;
+        }
+        return result;
+    }
+    for (let i = 0; i < entries.length; i += CHUNK) {
+        const chunk = Object.fromEntries(entries.slice(i, i + CHUNK));
+        // Import is an upsert, so retrying after a dropped connection is safe
+        const res = await session.api.post(`/orgs/${session.orgId}/projects/${project.id}/import`, { language, translations: chunk, overwriteExisting: Boolean(opts.overwrite), module: opts.module }, true);
+        result.created += res.created;
+        result.updated += res.updated;
+        result.unchanged += res.skipped;
+    }
+    if (opts.publish) {
+        let published = 0;
+        const names = entries.map(([k]) => k);
+        for (let i = 0; i < names.length; i += 5000) {
+            const res = await session.api.post(`/orgs/${session.orgId}/projects/${project.id}/keys/bulk-publish`, { keys: names.slice(i, i + 5000), published: true }, true);
+            published += res.count;
+        }
+        result.published = published;
+    }
+    return result;
+}
+export function readTranslationFile(path, format, lang) {
+    if (!existsSync(path))
+        throw notFoundError(`File not found: ${relative(process.cwd(), path) || path}`);
+    const fmt = format ?? formatFromPath(path);
+    const translations = fmt.parse(readFileSync(path, 'utf-8'), lang);
+    if ((fmt.id === 'android' || fmt.id === 'ios') && Object.values(translations).some(v => /\{\{\d+\}\}/.test(v))) {
+        log.warn(`${relative(process.cwd(), path)}: positional placeholders (%1$s / %1$@) were imported as {{1}}, {{2}}… — named placeholders can't be recovered from ${fmt.id} files.`);
+    }
+    return translations;
+}
+export async function pushCommand(projectArg, opts) {
+    const loaded = loadProjectConfig();
+    const cfg = loaded?.config ?? {};
+    const slug = projectSlugFrom(projectArg);
+    const format = opts.format || cfg.format ? getFormat(opts.format ?? cfg.format) : undefined;
+    let template;
+    if (opts.input)
+        template = resolve(opts.input);
+    else if (cfg.output && loaded)
+        template = resolve(loaded.root, cfg.output);
+    else
+        template = resolve((format ?? getFormat('json')).defaultOutput);
+    const session = await getSession();
+    const spin = spinner(`Fetching ${slug}…`);
+    let project;
+    try {
+        project = await getProject(session, slug);
+    }
+    finally {
+        spin.stop();
+    }
+    // Default: push only the source language, so translators' work in other languages isn't overwritten
+    const explicit = Boolean(opts.languages);
+    const languages = opts.languages === 'all' ? project.languages
+        : opts.languages ? splitList(opts.languages)
+            : [cfg.sourceLanguage ?? project.defaultLanguage];
+    assertLanguages(project, languages);
+    if (languages.length > 1 && !templateHasLanguage(template)) {
+        throw usageError(`Input "${relative(process.cwd(), template)}" has no {lang} placeholder but ${languages.length} languages were requested.`);
+    }
+    const results = [];
+    for (const lang of languages) {
+        const path = expandTemplate(template, lang, project.defaultLanguage);
+        if (!existsSync(path)) {
+            if (explicit)
+                throw notFoundError(`File not found for ${lang}: ${relative(process.cwd(), path)}`);
+            throw notFoundError(`Source file not found: ${relative(process.cwd(), path)}`, 'Run "langctl pull" first, or set "output" in langctl.json / pass --input.');
+        }
+        const translations = readTranslationFile(path, format, lang);
+        const s = spinner(`${opts.dryRun ? 'Checking' : 'Uploading'} ${lang} (${Object.keys(translations).length} keys)…`);
+        try {
+            const r = await uploadTranslations(session, project, lang, translations, { ...opts, module: opts.module ?? cfg.module });
+            results.push({ ...r, file: relative(process.cwd(), path) });
+        }
+        finally {
+            s.stop();
+        }
+    }
+    if (runtime.json) {
+        printJson({ project: project.slug, dryRun: Boolean(opts.dryRun), overwrite: Boolean(opts.overwrite), results });
+        return;
+    }
+    for (const r of results) {
+        const parts = [`${chalk.green(`${r.created} new`)}`, `${chalk.yellow(`${r.updated} updated`)}`, chalk.dim(`${r.unchanged} unchanged`)];
+        if (r.published !== undefined)
+            parts.push(chalk.cyan(`${r.published} published`));
+        log.out(`${r.language}  ${r.file}  ${parts.join(', ')}${opts.dryRun ? chalk.dim('  (dry run)') : ''}`);
+    }
+    if (!opts.overwrite && results.some(r => r.unchanged > 0)) {
+        log.info(chalk.dim('Existing translations are never overwritten unless you pass --overwrite.'));
+    }
+}

package/dist/commands/review.js

@@ -0,0 +1,65 @@
+import chalk from 'chalk';
+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 { confirm } from '../core/prompts.js';
+const split = (v) => (v ? v.split(',').map(s => s.trim()).filter(Boolean) : undefined);
+/**
+ * List AI translations awaiting review, or approve them with --approve.
+ * Unreviewed AI translations are left out of `langctl pull` until approved (or edited) in langctl.
+ */
+export async function reviewCommand(projectArg, opts) {
+    const session = await getSession();
+    const project = await getProject(session, projectSlugFrom(projectArg));
+    const keys = split(opts.keys);
+    const languages = split(opts.languages);
+    if (languages)
+        assertLanguages(project, languages);
+    const spin = spinner('Fetching AI translations awaiting review…');
+    let list;
+    try {
+        list = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/review`);
+    }
+    finally {
+        spin.stop();
+    }
+    const items = list.items.filter(i => (!keys || keys.includes(i.key)) && (!languages || languages.includes(i.language)));
+    if (keys) {
+        const unknown = keys.filter(k => !list.items.some(i => i.key === k));
+        if (unknown.length)
+            log.warn(`Nothing awaiting review for: ${unknown.join(', ')}`);
+    }
+    if (!opts.approve) {
+        if (runtime.json)
+            return printJson({ project: project.slug, total: items.length, items });
+        if (!items.length) {
+            log.success('No AI translations awaiting review.');
+            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.`));
+        return;
+    }
+    if (!items.length) {
+        if (runtime.json)
+            return printJson({ project: project.slug, approved: 0 });
+        log.success('Nothing to approve.');
+        return;
+    }
+    if (!(await confirm(`Approve ${items.length} AI translation(s) in ${project.slug}? They will ship on the next pull.`))) {
+        throw usageError('Cancelled.');
+    }
+    const keyIds = [...new Set(items.map(i => i.keyId))];
+    let approved = 0;
+    for (let i = 0; i < keyIds.length; i += 1000) {
+        const res = await session.api.post(`/orgs/${session.orgId}/projects/${project.id}/keys/review`, {
+            keyIds: keyIds.slice(i, i + 1000),
+            languages: languages ?? [...new Set(items.map(it => it.language))],
+        });
+        approved += res.approved;
+    }
+    if (runtime.json)
+        return printJson({ project: project.slug, approved });
+    log.success(`Approved ${approved} AI translation(s). They'll be included in the next "langctl pull".`);
+}