langctl 0.2.0 → 0.4.0

package/dist/core/errors.js

@@ -0,0 +1,67 @@
+/**
+ * Exit codes are part of the CLI's contract — CI scripts branch on them. Keep in sync with README.
+ */
+export const ExitCode = {
+    Ok: 0,
+    Error: 1,
+    Usage: 2,
+    Auth: 3,
+    NotFound: 4,
+    Network: 5,
+    Limit: 6,
+    Drift: 7,
+};
+export class CliError extends Error {
+    constructor(message, exitCode = ExitCode.Error, hint, status) {
+        super(message);
+        this.exitCode = exitCode;
+        this.hint = hint;
+        this.status = status;
+        this.name = 'CliError';
+    }
+}
+export const usageError = (message, hint) => new CliError(message, ExitCode.Usage, hint);
+export const notFoundError = (message, hint) => new CliError(message, ExitCode.NotFound, hint);
+/** 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 (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);
+    }
+    if (status === 403) {
+        if (/limit/i.test(msg))
+            return new CliError(msg, ExitCode.Limit, 'See your plan limits with "langctl org plan".', status);
+        if (/scope/i.test(msg)) {
+            return new CliError(msg, ExitCode.Auth, 'Create an API key with the required permission at https://app.langctl.com/organization/api-keys.', status);
+        }
+        return new CliError(msg, ExitCode.Auth, undefined, status);
+    }
+    if (status === 404)
+        return new CliError(msg, ExitCode.NotFound, undefined, status);
+    if (status === 400 || status === 409 || status === 422)
+        return new CliError(msg, ExitCode.Usage, undefined, status);
+    if (status === 429)
+        return new CliError('Rate limited by the Langctl API.', ExitCode.Network, 'Wait a moment and retry.', status);
+    if (status >= 500) {
+        return new CliError(`The Langctl API failed (${status}) on ${method} ${path}.`, ExitCode.Network, 'This is usually temporary — retry in a minute. If it persists, contact hello@langctl.com.', status);
+    }
+    return new CliError(msg, ExitCode.Error, undefined, status);
+}
+/** Map a fetch/network failure (no HTTP response) to a CliError. */
+export function networkError(err, baseUrl, timeoutMs) {
+    const e = err;
+    const code = e?.cause?.code;
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError') {
+        return new CliError(`Request to ${baseUrl} timed out after ${Math.round(timeoutMs / 1000)}s.`, ExitCode.Network, 'Check your connection, or raise the limit with --timeout <seconds> / LANGCTL_TIMEOUT.');
+    }
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+        return new CliError(`Cannot resolve ${new URL(baseUrl).host}.`, ExitCode.Network, 'Check your network/DNS, or LANGCTL_API_URL if you set it.');
+    }
+    if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'UND_ERR_SOCKET') {
+        return new CliError(`Could not connect to ${baseUrl} (${code}).`, ExitCode.Network, 'Check your network, proxy, or LANGCTL_API_URL.');
+    }
+    if (code === 'CERT_HAS_EXPIRED' || code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' || code === 'SELF_SIGNED_CERT_IN_CHAIN') {
+        return new CliError(`TLS error talking to ${baseUrl} (${code}).`, ExitCode.Network, 'If you are behind a corporate proxy, set NODE_EXTRA_CA_CERTS to its CA bundle.');
+    }
+    return new CliError(`Network error: ${e?.cause?.message || e?.message || String(err)}`, ExitCode.Network);
+}

package/dist/core/files.js

@@ -0,0 +1,38 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+/**
+ * Write a file only if its content changed (atomic temp-file + rename).
+ * With `dryRun`, report what would happen without touching disk (used by --check / --dry-run).
+ */
+export function syncFile(path, content, dryRun, 
+/** Parse function of the file's format: if the existing file holds the same translations, leave it alone */
+parse) {
+    const exists = existsSync(path);
+    if (exists) {
+        const current = readFileSync(path, 'utf-8');
+        if (current === content)
+            return 'unchanged';
+        // A hand-edited file (other key order, indentation, no trailing newline) with the same
+        // translations is not drift — keep the user's formatting and don't fail `pull --check`
+        if (parse && sameTranslations(current, content, parse))
+            return 'unchanged';
+    }
+    if (!dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.langctl-${process.pid}.tmp`;
+        writeFileSync(tmp, content, 'utf-8');
+        renameSync(tmp, path);
+    }
+    return exists ? 'updated' : 'created';
+}
+function sameTranslations(a, b, parse) {
+    try {
+        const x = parse(a);
+        const y = parse(b);
+        const kx = Object.keys(x);
+        return kx.length === Object.keys(y).length && kx.every(k => x[k] === y[k]);
+    }
+    catch {
+        return false; // unparseable existing file → rewrite it
+    }
+}

package/dist/core/http.js

@@ -0,0 +1,156 @@
+import { CliError, ExitCode, httpError, networkError } from './errors.js';
+import { requireCredentials } from './config.js';
+import { detectCi, log } from './output.js';
+import { VERSION } from '../version.js';
+import { cacheEnabled, cacheKey, readCache, writeCache } from './cache.js';
+export const httpSettings = {
+    timeoutMs: Number(process.env.LANGCTL_TIMEOUT || 30) * 1000,
+    retries: 3,
+};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+function userAgent() {
+    const ci = detectCi();
+    return `langctl/${VERSION} (node ${process.versions.node}; ${process.platform}${ci ? `; ci=${ci}` : ''})`;
+}
+export class ApiClient {
+    constructor(creds) {
+        this.creds = creds;
+    }
+    get baseUrl() {
+        return this.creds.apiUrl;
+    }
+    async request(method, path, opts = {}) {
+        return (await this.send(method, this.buildUrl(path, opts.query), opts)).data;
+    }
+    buildUrl(path, query) {
+        const url = new URL(this.creds.apiUrl + path);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        return url;
+    }
+    /**
+     * GET with an ETag cache: if the server reports the resource unchanged (304) the saved body is
+     * reused. Used for exports, which CI fetches over and over while translations rarely change.
+     */
+    async getCached(path, query) {
+        const url = this.buildUrl(path, query);
+        if (!cacheEnabled())
+            return { data: (await this.send('GET', url, {})).data, fromCache: false };
+        const key = cacheKey(this.creds.apiUrl, this.creds.apiKey, url.toString());
+        const cached = readCache(key);
+        const res = await this.send('GET', url, { ifNoneMatch: cached?.etag });
+        if (res.notModified && cached) {
+            log.debug(`cache hit for ${url.pathname} (${cached.etag})`);
+            return { data: cached.data, fromCache: true };
+        }
+        if (res.notModified) {
+            // 304 without a cached body (cache wiped mid-run): fetch unconditionally
+            return { data: (await this.send('GET', url, {})).data, fromCache: false };
+        }
+        if (res.etag)
+            writeCache(key, res.etag, res.data);
+        return { data: res.data, fromCache: false };
+    }
+    async send(method, url, opts) {
+        const headers = {
+            'X-API-Key': this.creds.apiKey,
+            'User-Agent': userAgent(),
+            Accept: 'application/json',
+        };
+        // Only declare a JSON body when there is one — Fastify rejects an empty body with this header
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (opts.ifNoneMatch)
+            headers['If-None-Match'] = opts.ifNoneMatch;
+        const idempotent = opts.idempotent ?? (method === 'GET');
+        const attempts = idempotent ? httpSettings.retries : 1;
+        for (let attempt = 1;; attempt++) {
+            const started = Date.now();
+            let res;
+            try {
+                res = await fetch(url, {
+                    method,
+                    headers,
+                    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: AbortSignal.timeout(httpSettings.timeoutMs),
+                });
+            }
+            catch (err) {
+                const mapped = networkError(err, this.creds.apiUrl, httpSettings.timeoutMs);
+                log.debug(`${method} ${url.pathname} → ${mapped.message} (${Date.now() - started}ms, attempt ${attempt}/${attempts})`);
+                if (attempt < attempts) {
+                    await sleep(backoff(attempt));
+                    continue;
+                }
+                throw mapped;
+            }
+            log.debug(`${method} ${url.pathname}${url.search} → ${res.status} (${Date.now() - started}ms)`);
+            if (res.status === 304) {
+                return { status: 304, data: undefined, etag: res.headers.get('etag'), notModified: true };
+            }
+            const retryable = res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504;
+            if (retryable && attempt < attempts) {
+                const retryAfter = Number(res.headers.get('retry-after'));
+                await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 30) * 1000 : backoff(attempt));
+                continue;
+            }
+            const text = await res.text();
+            let data = undefined;
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    if (!res.ok)
+                        throw httpError(res.status, undefined, method, url.pathname);
+                    throw new CliError(`Unexpected non-JSON response from ${url.host} (${res.status}).`, ExitCode.Network, 'Is LANGCTL_API_URL pointing at the Langctl API (…/api/v1)?');
+                }
+            }
+            if (!res.ok) {
+                const d = data;
+                throw httpError(res.status, d?.error || d?.message, method, url.pathname);
+            }
+            return { status: res.status, data: data, etag: res.headers.get('etag'), notModified: false };
+        }
+    }
+    get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    post(path, body, idempotent = false) {
+        return this.request('POST', path, { body, idempotent });
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, { body, idempotent: true });
+    }
+    delete(path) {
+        return this.request('DELETE', path, { idempotent: true });
+    }
+}
+function backoff(attempt) {
+    return Math.min(8000, 500 * 2 ** (attempt - 1)) + Math.floor(Math.random() * 250);
+}
+/** Look up which org a key belongs to (and its scopes). Returns null if the key is invalid/revoked. */
+export async function validateKey(api, apiKey) {
+    const res = await api.request('POST', '/api-keys/validate', { body: { apiKey }, idempotent: true });
+    return res.valid && res.organizationId ? { organizationId: res.organizationId, scopes: res.scopes ?? [] } : null;
+}
+let cached = null;
+export async function getSession() {
+    if (cached)
+        return cached;
+    const creds = requireCredentials();
+    const api = new ApiClient(creds);
+    if (creds.organizationId) {
+        cached = { api, orgId: creds.organizationId, creds };
+        return cached;
+    }
+    // Env/flag key: resolve the org from the key itself, so CI needs no config file
+    const info = await validateKey(api, creds.apiKey);
+    if (!info) {
+        throw new CliError(`The API key from ${creds.source === 'env' ? 'LANGCTL_API_KEY' : '--api-key'} is invalid or revoked.`, ExitCode.Auth, 'Create a new key at https://app.langctl.com/organization/api-keys.');
+    }
+    cached = { api, orgId: info.organizationId, creds, scopes: info.scopes };
+    return cached;
+}

package/dist/core/output.js

@@ -0,0 +1,96 @@
+import chalk from 'chalk';
+/**
+ * Process-wide output settings, set once from global flags in index.ts.
+ *
+ * Contract: command *results* go to stdout (and only JSON when --json is set);
+ * progress, warnings and errors go to stderr. That keeps `langctl ... --json | jq`
+ * and `$(langctl ...)` reliable in CI.
+ */
+export const runtime = {
+    json: false,
+    quiet: false,
+    verbose: false,
+    yes: false,
+};
+const ciEnv = ['CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'BUILDKITE', 'CIRCLECI', 'JENKINS_URL', 'TF_BUILD', 'BITBUCKET_BUILD_NUMBER'];
+export function detectCi() {
+    for (const name of ciEnv) {
+        const value = process.env[name];
+        if (value && value !== 'false' && value !== '0')
+            return name === 'CI' ? 'ci' : name.toLowerCase();
+    }
+    return null;
+}
+/** True only when a human is at an interactive terminal (prompts and spinners allowed). */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !detectCi() && !runtime.json;
+}
+const write = (stream, line) => stream.write(line + '\n');
+export const log = {
+    /** Human-readable result line (stdout). Suppressed in --json mode — print JSON with `printJson` instead. */
+    out(line = '') {
+        if (!runtime.json)
+            write(process.stdout, line);
+    },
+    info(line) {
+        if (!runtime.quiet && !runtime.json)
+            write(process.stderr, line);
+    },
+    success(line) {
+        if (!runtime.quiet && !runtime.json)
+            write(process.stderr, `${chalk.green('✔')} ${line}`);
+    },
+    warn(line) {
+        write(process.stderr, `${chalk.yellow('warning:')} ${line}`);
+    },
+    error(line, hint) {
+        write(process.stderr, `${chalk.red('error:')} ${line}`);
+        if (hint)
+            write(process.stderr, `${chalk.dim('hint:')} ${hint}`);
+    },
+    debug(line) {
+        if (runtime.verbose)
+            write(process.stderr, chalk.dim(`[debug] ${line}`));
+    },
+};
+export function printJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/**
+ * Progress indicator that only animates for humans at a terminal; elsewhere (CI, pipes,
+ * --json, --quiet) it is a no-op. Deliberately not `ora`: ora touches stdin/cursor state and
+ * froze the CLI under emulated terminals (`script`, `docker -t`, some CI runners). This
+ * writes to stderr only, and its timer is unref'd so it can never keep the process alive.
+ */
+export function spinner(text) {
+    if (!isInteractive() || runtime.quiet || runtime.verbose)
+        return { text, stop() { } };
+    let i = 0;
+    const state = { text };
+    const render = () => process.stderr.write(`\r\x1b[2K${chalk.cyan(FRAMES[i++ % FRAMES.length])} ${state.text}`);
+    render();
+    const timer = setInterval(render, 80);
+    timer.unref();
+    return {
+        get text() { return state.text; },
+        set text(t) { state.text = t; },
+        stop() {
+            clearInterval(timer);
+            process.stderr.write('\r\x1b[2K');
+        },
+    };
+}
+/** Minimal aligned table for human output. */
+export function table(rows, header) {
+    const all = header ? [header, ...rows] : rows;
+    const widths = all[0]?.map((_, i) => Math.max(...all.map(r => stripAnsi(r[i] ?? '').length))) ?? [];
+    const fmt = (r) => r.map((c, i) => (i === r.length - 1 ? c : c + ' '.repeat(widths[i] - stripAnsi(c).length))).join('  ');
+    if (header)
+        log.out(chalk.bold(fmt(header)));
+    rows.forEach(r => log.out(fmt(r)));
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/dist/core/project.js

@@ -0,0 +1,58 @@
+import { CliError, ExitCode, notFoundError, usageError } from './errors.js';
+import { loadProjectConfig } from './config.js';
+/** Project slug from the argument, else langctl.json, else a usage error. */
+export function projectSlugFrom(arg) {
+    if (arg)
+        return arg;
+    const loaded = loadProjectConfig();
+    if (loaded?.config.project)
+        return loaded.config.project;
+    throw usageError('No project given.', 'Pass a project slug, or add "project" to langctl.json (see "langctl init"). List projects with "langctl projects list".');
+}
+export async function getProject(session, slug) {
+    try {
+        return await session.api.get(`/orgs/${session.orgId}/projects/by-slug/${encodeURIComponent(slug)}`);
+    }
+    catch (err) {
+        if (err instanceof CliError && err.exitCode === ExitCode.NotFound) {
+            const projects = await session.api.get(`/orgs/${session.orgId}/projects`).catch(() => []);
+            const available = projects.map(p => p.slug);
+            throw notFoundError(`Project "${slug}" not found.`, available.length ? `Available projects: ${available.join(', ')}` : 'This organization has no projects yet — create one with "langctl projects create".');
+        }
+        throw err;
+    }
+}
+export function assertLanguages(project, languages) {
+    const missing = languages.filter(l => !project.languages.includes(l));
+    if (missing.length) {
+        throw usageError(`Language${missing.length > 1 ? 's' : ''} ${missing.join(', ')} not in project "${project.slug}".`, `Project languages: ${project.languages.join(', ')}. Add one with "langctl projects add-language ${project.slug} <code>".`);
+    }
+}
+export async function findKey(session, project, keyName) {
+    const res = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/keys`, { key: keyName, pageSize: 1 });
+    return res.data.find(k => k.key === keyName) ?? null;
+}
+export async function requireKey(session, project, keyName) {
+    const key = await findKey(session, project, keyName);
+    if (!key)
+        throw notFoundError(`Key "${keyName}" not found in project "${project.slug}".`, `Search with "langctl keys list ${project.slug} --search <text>".`);
+    return key;
+}
+/** Fetch every key page by page (the API caps pages at 100). */
+export async function listAllKeys(session, project, filters = {}) {
+    const out = [];
+    for (let page = 1;; page++) {
+        const res = await session.api.get(`/orgs/${session.orgId}/projects/${project.id}/keys`, {
+            page,
+            pageSize: 100,
+            sortBy: 'key',
+            sortOrder: 'asc',
+            module: filters.module,
+            search: filters.search,
+            published: filters.published === undefined ? undefined : String(filters.published),
+        });
+        out.push(...res.data);
+        if (page >= res.pagination.totalPages)
+            return out;
+    }
+}

package/dist/core/prompts.js

@@ -0,0 +1,56 @@
+import { createInterface } from 'readline';
+import { Writable } from 'stream';
+import { isInteractive, runtime } from './output.js';
+import { usageError } from './errors.js';
+/**
+ * Tiny prompts on node:readline (replaces inquirer). They are only ever shown at an
+ * interactive terminal; in CI a missing answer is a usage error, never a hang.
+ */
+function ask(question, { hidden = false } = {}) {
+    let muted = false;
+    const output = new Writable({
+        write(chunk, _enc, cb) {
+            if (!muted)
+                process.stderr.write(chunk);
+            cb();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output, terminal: true });
+    return new Promise((resolve, reject) => {
+        rl.question(question, answer => {
+            rl.close();
+            if (hidden)
+                process.stderr.write('\n');
+            resolve(answer.trim());
+        });
+        rl.on('SIGINT', () => { rl.close(); process.stderr.write('\n'); reject(usageError('Cancelled.')); });
+        muted = hidden;
+    });
+}
+export async function input(question, fallback) {
+    const answer = await ask(`${question}${fallback ? ` (${fallback})` : ''}: `);
+    return answer || fallback || '';
+}
+export async function password(question) {
+    return ask(`${question}: `, { hidden: true });
+}
+/**
+ * Ask before something destructive. `--yes` skips the question; without a TTY and
+ * without `--yes` we refuse instead of guessing.
+ */
+export async function confirm(question, flagName = '--yes') {
+    if (runtime.yes)
+        return true;
+    if (!isInteractive()) {
+        throw usageError(`Refusing to ${question.replace(/\?$/, '').toLowerCase()} without confirmation.`, `Re-run with ${flagName} to confirm in non-interactive environments.`);
+    }
+    const answer = (await ask(`${question} [y/N] `)).toLowerCase();
+    return answer === 'y' || answer === 'yes';
+}
+/** Read all of stdin (for `auth --stdin`). */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}