@lionrapid/cli 0.2.1 → 0.2.2

package/dist/commands/login.js

@@ -0,0 +1,110 @@
+/**
+ * `login` / `logout` — manage `~/.lionrapid/credentials`, the JSON map
+ * (`{ "default": "sk_…", "<server-url>": "sk_…" }`) that `resolveApiKey`
+ * reads. The key is verified against the server BEFORE persisting (a
+ * config:read probe, so publishable pk_ keys work too) — a failed
+ * verification writes nothing. Directory is 0700, file 0600.
+ *
+ * `--server` writes a server-scoped entry (the per-host opt-in that
+ * `resolveApiKey` demands for non-LionRapid hosts); bare `login` writes
+ * `default`. The key itself is never echoed or included in any envelope.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+import { ApiKeyError, assertKeyCharset, defaultCredentialsPath, findConfigPath, loadConfig, } from '../config.js';
+import { LionRapidApiClient } from '../api-client.js';
+export const DEFAULT_SERVER = 'https://api.lionrapid.com';
+export async function runLogin(opts = {}) {
+    const scope = opts.server ? 'server' : 'default';
+    const server = normalizeServer(opts.server ?? repoServer(opts.cwd) ?? DEFAULT_SERVER);
+    const key = (opts.key ?? (await (opts.promptKey ?? promptHidden)())).trim();
+    if (!key)
+        throw new ApiKeyError('No API key provided.');
+    assertKeyCharset(key);
+    // Verify before persisting — a bad key must never land in the file. The
+    // probe is project-config (`config:read`), which every key class carries —
+    // publishable pk_ keys included; the old editor/workflow ping needed
+    // `targets:write` and wrongly rejected pk_ logins.
+    const client = new LionRapidApiClient({
+        baseUrl: server,
+        apiKey: key,
+        fetchImpl: opts.fetchImpl,
+    });
+    await client.getProjectConfig();
+    const path = opts.credentialsPath ?? defaultCredentialsPath();
+    const creds = readCreds(path);
+    creds[scope === 'server' ? server : 'default'] = key;
+    writeCreds(path, creds);
+    return { server, scope, credentialsPath: path };
+}
+export function runLogout(opts = {}) {
+    const scope = opts.server ? 'server' : 'default';
+    const entry = opts.server ? normalizeServer(opts.server) : 'default';
+    const path = opts.credentialsPath ?? defaultCredentialsPath();
+    if (!existsSync(path))
+        return { scope, removed: false, credentialsPath: path };
+    const creds = readCreds(path);
+    const removed = Object.prototype.hasOwnProperty.call(creds, entry);
+    if (removed) {
+        delete creds[entry];
+        if (Object.keys(creds).length === 0) {
+            rmSync(path);
+        }
+        else {
+            writeCreds(path, creds);
+        }
+    }
+    return { scope, removed, credentialsPath: path };
+}
+/** Match the `config.server` normalization so scoped lookups hit exactly. */
+function normalizeServer(server) {
+    return server.replace(/\/$/, '');
+}
+/** The repo's configured server, when a valid lionrapid.yml is present. */
+function repoServer(cwd) {
+    const path = findConfigPath(cwd);
+    if (!path)
+        return undefined;
+    try {
+        return loadConfig(path).server;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCreds(path) {
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        throw new ApiKeyError(`Could not parse credentials file ${path}: ${err instanceof Error ? err.message : String(err)}. Fix or delete it, then retry.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ApiKeyError(`Credentials file ${path} is not a JSON object. Fix or delete it, then retry.`);
+    }
+    return parsed;
+}
+function writeCreds(path, creds) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    // writeFileSync's mode only applies on create — enforce it on merges too.
+    chmodSync(path, 0o600);
+}
+/** Hidden interactive prompt (no echo) via node:readline — no new dependency. */
+export function promptHidden(question = 'API key (input hidden): ') {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        process.stderr.write(question);
+        rl._writeToOutput = () => { };
+        rl.question('', (answer) => {
+            rl.close();
+            process.stderr.write('\n');
+            resolve(answer);
+        });
+    });
+}
+//# sourceMappingURL=login.js.map

package/dist/commands/pull.d.ts

@@ -9,16 +9,25 @@
  */
 import type { LionRapidConfig } from '../config.js';
 import type { LionRapidApiClient } from '../api-client.js';
+import { type TranslationEntry } from '../adapters/index.js';
 export interface PullOptions {
     cwd: string;
     /** Fetch + count what would be written, but write no files. */
     dryRun?: boolean;
+    /** Overwrite target files wholesale instead of merging (drops local-only keys). */
+    force?: boolean;
     /** Progress callback, invoked as each namespace fetch completes. */
     onProgress?: (done: number, total: number) => void;
 }
 export interface PullFileResult {
     target: string;
     count: number;
+    /** Merge diff vs the existing target (absent on fresh writes and --force). */
+    added?: number;
+    updated?: number;
+    keptLocal?: number;
+    /** Set when this file failed (fetch or write) — the file was not written. */
+    error?: string;
 }
 export interface PullLocaleResult {
     locale: string;
@@ -31,5 +40,18 @@ export interface PullResult {
     /** True when this was a dry run — no files were written. */
     dryRun?: boolean;
 }
+/**
+ * Overlay fetched entries onto the existing local file: server wins per key,
+ * local-only entries survive, existing key order is preserved and new keys
+ * append. Local `comment`s survive even on overlaid keys — the server bundle
+ * has no comment channel, so replacing the entry would silently drop them.
+ * Exported for direct unit testing.
+ */
+export declare function mergeEntries(local: TranslationEntry[], fetched: TranslationEntry[]): {
+    entries: TranslationEntry[];
+    added: number;
+    updated: number;
+    keptLocal: number;
+};
 export declare function runPull(config: LionRapidConfig, client: LionRapidApiClient, opts: PullOptions): Promise<PullResult>;
 //# sourceMappingURL=pull.d.ts.map

package/dist/commands/pull.js

@@ -10,7 +10,40 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { getAdapter } from '../adapters/index.js';
-import { mapLimit, resolveConcurrency } from './context.js';
+import { assertInside, mapLimit, resolveConcurrency } from './context.js';
+/**
+ * Overlay fetched entries onto the existing local file: server wins per key,
+ * local-only entries survive, existing key order is preserved and new keys
+ * append. Local `comment`s survive even on overlaid keys — the server bundle
+ * has no comment channel, so replacing the entry would silently drop them.
+ * Exported for direct unit testing.
+ */
+export function mergeEntries(local, fetched) {
+    const newByKey = new Map(fetched.map((e) => [e.key, e]));
+    const entries = [];
+    let updated = 0;
+    let keptLocal = 0;
+    for (const l of local) {
+        const f = newByKey.get(l.key);
+        if (!f) {
+            keptLocal += 1;
+            entries.push(l);
+            continue;
+        }
+        if (JSON.stringify(f.value) !== JSON.stringify(l.value))
+            updated += 1;
+        entries.push(l.comment !== undefined ? { ...f, comment: l.comment } : f);
+        newByKey.delete(l.key); // consumed — what remains is genuinely new
+    }
+    let added = 0;
+    for (const f of fetched) {
+        if (newByKey.has(f.key)) {
+            entries.push(f);
+            added += 1;
+        }
+    }
+    return { entries, added, updated, keptLocal };
+}
 /** Union of source keys per namespace, for "pending" reporting. */
 function sourceKeysByNamespace(config, cwd) {
     const byNs = new Map();
@@ -31,16 +64,29 @@ export async function runPull(config, client, opts) {
     const sourceKeys = sourceKeysByNamespace(config, opts.cwd);
     const perLocaleFiles = config.files.filter((f) => !getAdapter(f.format).multiLocale);
     const multiFiles = config.files.filter((f) => getAdapter(f.format).multiLocale);
-    // Run-wide namespace cache, keyed `${locale}:${namespace}`.
+    // Run-wide namespace cache, keyed `${locale}:${namespace}`. A failed fetch
+    // is cached as an error instead of aborting the run — one bad namespace
+    // must not zero out a 56-file pull (partial progress, exit 5).
     const nsCache = new Map();
+    const nsErrors = new Map();
+    let firstError;
     const fetchNs = async (locale, namespace) => {
         const cacheKey = `${locale}:${namespace}`;
         const hit = nsCache.get(cacheKey);
         if (hit)
             return hit;
-        const bundle = await client.getNamespace(locale, namespace);
-        nsCache.set(cacheKey, bundle.translations);
-        return bundle.translations;
+        if (nsErrors.has(cacheKey))
+            return null;
+        try {
+            const bundle = await client.getNamespace(locale, namespace);
+            nsCache.set(cacheKey, bundle.translations);
+            return bundle.translations;
+        }
+        catch (err) {
+            firstError ??= err;
+            nsErrors.set(cacheKey, err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
     };
     // Pre-fetch every needed (locale, namespace) bundle concurrently so the slow
     // network fan-out runs in parallel; the write loops below then read the warm
@@ -75,30 +121,85 @@ export async function runPull(config, client, opts) {
             const adapter = getAdapter(file.format);
             const namespace = file.namespace ?? config.namespace;
             usedNamespaces.add(namespace);
-            const entries = toEntries(await fetchNs(locale, namespace));
             const relPath = file.target.replace('{locale}', locale);
-            // Don't clobber an existing target with an empty result (locked/pending).
-            // Dry run computes counts but writes nothing.
-            if (entries.length > 0 && !opts.dryRun) {
-                const absPath = resolve(opts.cwd, relPath);
-                mkdirSync(dirname(absPath), { recursive: true });
-                writeFileSync(absPath, adapter.serialize(entries, { locale, sourceLocale: config.sourceLocale }));
+            const translations = await fetchNs(locale, namespace);
+            if (translations === null) {
+                fileResults.push({
+                    target: relPath,
+                    count: 0,
+                    error: nsErrors.get(`${locale}:${namespace}`).message,
+                });
+                continue;
+            }
+            const fetched = toEntries(translations);
+            try {
+                const absPath = assertInside(opts.cwd, relPath);
+                // Default is a non-destructive merge with the existing target: server
+                // wins per key, local-only keys survive. `--force` restores the
+                // wholesale overwrite.
+                let toWrite = fetched;
+                let diff;
+                if (!opts.force && fetched.length > 0 && existsSync(absPath)) {
+                    const merged = mergeEntries(adapter.parse(readFileSync(absPath, 'utf8')), fetched);
+                    toWrite = merged.entries;
+                    diff = { added: merged.added, updated: merged.updated, keptLocal: merged.keptLocal };
+                }
+                // Don't clobber an existing target with an empty result (locked/pending).
+                // Dry run computes counts but writes nothing.
+                if (fetched.length > 0 && !opts.dryRun) {
+                    mkdirSync(dirname(absPath), { recursive: true });
+                    writeFileSync(absPath, adapter.serialize(toWrite, {
+                        locale,
+                        sourceLocale: config.sourceLocale,
+                        flat: file.flat,
+                    }));
+                }
+                fileResults.push({ target: relPath, count: fetched.length, ...(diff ?? {}) });
+            }
+            catch (err) {
+                firstError ??= err;
+                fileResults.push({
+                    target: relPath,
+                    count: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
-            fileResults.push({ target: relPath, count: entries.length });
         }
         for (const file of multiFiles) {
             const adapter = getAdapter(file.format);
             const namespace = file.namespace ?? config.namespace;
             usedNamespaces.add(namespace);
-            const entries = toEntries(await fetchNs(locale, namespace));
-            if (entries.length > 0) {
-                const merged = adapter.mergeLocale(catalogContent.get(file) ?? null, entries, locale);
-                catalogContent.set(file, merged);
+            const translations = await fetchNs(locale, namespace);
+            if (translations === null) {
+                fileResults.push({
+                    target: file.target,
+                    count: 0,
+                    error: nsErrors.get(`${locale}:${namespace}`).message,
+                });
+                continue;
+            }
+            const entries = toEntries(translations);
+            try {
+                if (entries.length > 0) {
+                    const merged = adapter.mergeLocale(catalogContent.get(file) ?? null, entries, locale);
+                    catalogContent.set(file, merged);
+                }
+                fileResults.push({ target: file.target, count: entries.length });
+            }
+            catch (err) {
+                firstError ??= err;
+                fileResults.push({
+                    target: file.target,
+                    count: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                });
             }
-            fileResults.push({ target: file.target, count: entries.length });
         }
         let pending = 0;
         for (const namespace of usedNamespaces) {
+            // A failed namespace's state is unknown — don't report its keys pending.
+            if (nsErrors.has(`${locale}:${namespace}`))
+                continue;
             const have = new Set(Object.keys(nsCache.get(`${locale}:${namespace}`) ?? {}));
             for (const key of sourceKeys.get(namespace) ?? new Set()) {
                 if (!have.has(key))
@@ -112,12 +213,30 @@ export async function runPull(config, client, opts) {
         for (const file of multiFiles) {
             const content = catalogContent.get(file);
             if (content != null) {
-                const absPath = resolve(opts.cwd, file.target);
-                mkdirSync(dirname(absPath), { recursive: true });
-                writeFileSync(absPath, content);
+                try {
+                    const absPath = assertInside(opts.cwd, file.target);
+                    mkdirSync(dirname(absPath), { recursive: true });
+                    writeFileSync(absPath, content);
+                }
+                catch (err) {
+                    firstError ??= err;
+                    const message = err instanceof Error ? err.message : String(err);
+                    for (const loc of locales) {
+                        for (const f of loc.files) {
+                            if (f.target === file.target && !f.error)
+                                f.error = message;
+                        }
+                    }
+                }
             }
         }
     }
+    // Partial progress is a result; total failure keeps today's error contract —
+    // rethrow the first error so the exit-code mapping is unchanged.
+    const all = locales.flatMap((l) => l.files);
+    if (all.length > 0 && all.every((f) => f.error) && firstError !== undefined) {
+        throw firstError;
+    }
     return { locales, ...(opts.dryRun ? { dryRun: true } : {}) };
 }
 //# sourceMappingURL=pull.js.map

package/dist/commands/push.d.ts

@@ -23,6 +23,8 @@ export interface PushFileResult {
     file: string;
     count: number;
     skipped?: boolean;
+    /** Set when this file failed (parse or upload) — it was not (fully) pushed. */
+    error?: string;
 }
 export interface PushResult {
     mode: 'source' | 'target';

package/dist/commands/push.js

@@ -13,6 +13,8 @@ import { resolve } from 'node:path';
 import { ConfigError } from '../config.js';
 import { getAdapter } from '../adapters/index.js';
 import { chunk } from './context.js';
+// The server's enforced ceiling is 1000 items per sync/targets batch (Pydantic
+// `max_length` on the request model) — 500 stays comfortably under it.
 const BATCH = 500;
 export async function runPush(config, client, opts) {
     const mode = opts.target ? 'target' : 'source';
@@ -32,6 +34,7 @@ export async function runPush(config, client, opts) {
     const canPublish = mode === 'target' && opts.publish === true && client.canPublish;
     const publishSkipped = mode === 'target' && opts.publish === true && !client.canPublish;
     let pushed = 0;
+    let firstError;
     for (const file of config.files) {
         const adapter = getAdapter(file.format);
         const namespace = file.namespace ?? config.namespace;
@@ -41,27 +44,47 @@ export async function runPush(config, client, opts) {
             files.push({ file: relPath, count: 0, skipped: true });
             continue;
         }
-        const parseLocale = mode === 'source' ? config.sourceLocale : opts.target;
-        const entries = adapter.parse(readFileSync(absPath, 'utf8'), { locale: parseLocale });
-        const items = entries.map((e) => ({ key: e.key, value: e.value }));
-        // Dry run: parse + count only, never touch the network.
-        if (!opts.dryRun) {
-            for (const batch of chunk(items, BATCH)) {
-                if (mode === 'source') {
-                    await client.syncBatch(config.sourceLocale, namespace, batch);
-                }
-                else {
-                    await client.targetsBatch(opts.target, namespace, batch);
-                    if (canPublish) {
-                        for (const it of batch) {
-                            await client.markReady(opts.target, namespace, it.key);
+        // One bad file/namespace must not zero out the rest of the push (a rate
+        // limit on a many-namespace site, one corrupt file). Record the failure
+        // and move on — sync/batch upserts by composite key, so re-running push
+        // retries just the failures (partial progress, exit 5).
+        try {
+            const parseLocale = mode === 'source' ? config.sourceLocale : opts.target;
+            const entries = adapter.parse(readFileSync(absPath, 'utf8'), { locale: parseLocale });
+            const items = entries.map((e) => ({ key: e.key, value: e.value }));
+            // Dry run: parse + count only, never touch the network.
+            if (!opts.dryRun) {
+                for (const batch of chunk(items, BATCH)) {
+                    if (mode === 'source') {
+                        await client.syncBatch(config.sourceLocale, namespace, batch);
+                    }
+                    else {
+                        await client.targetsBatch(opts.target, namespace, batch);
+                        if (canPublish) {
+                            for (const it of batch) {
+                                await client.markReady(opts.target, namespace, it.key);
+                            }
                         }
                     }
                 }
             }
+            pushed += items.length;
+            files.push({ file: relPath, count: items.length });
         }
-        pushed += items.length;
-        files.push({ file: relPath, count: items.length });
+        catch (err) {
+            firstError ??= err;
+            files.push({
+                file: relPath,
+                count: 0,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // Partial progress is a result; total failure keeps today's error contract —
+    // rethrow the first error so the exit-code mapping is unchanged.
+    const attempted = files.filter((f) => !f.skipped);
+    if (attempted.length > 0 && attempted.every((f) => f.error) && firstError !== undefined) {
+        throw firstError;
     }
     return {
         mode,

package/dist/commands/snapshot.js

@@ -13,7 +13,8 @@
  * surface with no re-derivation.
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname } from 'node:path';
+import { assertInside } from './context.js';
 export const DEFAULT_SNAPSHOT_DIR = 'snapshots';
 export async function runSnapshot(config, client, opts) {
     const out = opts.out ?? DEFAULT_SNAPSHOT_DIR;
@@ -41,7 +42,7 @@ export async function runSnapshot(config, client, opts) {
                 translations: bundle.translations, // raw — styles preserved
             };
             const rel = `${out}/${locale}.${namespace}.json`;
-            const abs = resolve(opts.cwd, rel);
+            const abs = assertInside(opts.cwd, rel);
             mkdirSync(dirname(abs), { recursive: true });
             writeFileSync(abs, `${JSON.stringify(snapshot, null, 2)}\n`);
             files.push({ path: rel, locale, namespace, keys });

package/dist/commands/types.js

@@ -14,6 +14,7 @@ import { dirname, resolve } from 'node:path';
 import { getAdapter } from '../adapters/index.js';
 import { generateDts } from '../types-gen/generate.js';
 import { extractParams, IcuError } from '../types-gen/extract.js';
+import { assertInside } from './context.js';
 const DEFAULT_OUTPUT = 'types/translations.d.ts';
 /** Map every source key to its ICU message text (first definition wins). */
 export function collectSourceKeyTexts(config, cwd) {
@@ -50,7 +51,7 @@ export async function collectServerKeyTexts(config, client) {
 function writeDts(keyTexts, config, opts) {
     const dts = generateDts(keyTexts, { strictIcu: opts.strictIcu });
     const output = opts.output ?? config.typesOutput ?? DEFAULT_OUTPUT;
-    const abs = resolve(opts.cwd, output);
+    const abs = assertInside(opts.cwd, output);
     mkdirSync(dirname(abs), { recursive: true });
     writeFileSync(abs, dts);
     return { keys: keyTexts.size, output };

package/dist/commands/validate.d.ts

@@ -9,12 +9,13 @@
  */
 import type { LionRapidConfig } from '../config.js';
 import type { LionRapidApiClient } from '../api-client.js';
-export type ValidateIssueType = 'missing' | 'empty' | 'orphan';
+export type ValidateIssueType = 'missing' | 'empty' | 'orphan' | 'locked';
 export interface ValidateIssue {
     locale: string;
     namespace: string;
     type: ValidateIssueType;
-    key: string;
+    /** Absent for namespace-level issues (`locked`). */
+    key?: string;
 }
 export interface ValidateResult {
     ok: boolean;
@@ -23,6 +24,8 @@ export interface ValidateResult {
 }
 export interface ValidateOptions {
     cwd: string;
+    /** Treat locked (423) namespaces as a warning instead of a failure. */
+    allowLocked?: boolean;
 }
 export declare function runValidate(config: LionRapidConfig, client: LionRapidApiClient, opts: ValidateOptions): Promise<ValidateResult>;
 //# sourceMappingURL=validate.d.ts.map

package/dist/commands/validate.js

@@ -29,6 +29,12 @@ export async function runValidate(config, client, opts) {
     for (const locale of config.targetLocales) {
         for (const [namespace, sourceKeys] of sourceByNs) {
             const bundle = await client.getNamespace(locale, namespace);
+            // A locked (423) namespace has nothing approved for delivery yet — one
+            // namespace-level issue, not N spurious `missing` per source key.
+            if (bundle.locked) {
+                issues.push({ locale, namespace, type: 'locked' });
+                continue;
+            }
             const translations = bundle.translations;
             const have = new Set(Object.keys(translations));
             for (const key of sourceKeys) {
@@ -36,13 +42,20 @@ export async function runValidate(config, client, opts) {
                     issues.push({ locale, namespace, type: 'missing', key });
             }
             for (const [key, value] of Object.entries(translations)) {
-                if (!value.text.trim())
+                // Defensive: a value that isn't a real ContentUnit counts as empty
+                // rather than crashing the run (the client normalizes these, but
+                // `validate` is also driven directly in tests and by embedders).
+                if (typeof value?.text !== 'string' || !value.text.trim()) {
                     issues.push({ locale, namespace, type: 'empty', key });
+                }
                 if (!sourceKeys.has(key))
                     issues.push({ locale, namespace, type: 'orphan', key });
             }
         }
     }
-    return { ok: issues.length === 0, sourceKeys: totalSourceKeys, issues };
+    // `locked` fails by default (nothing is deliverable); `allowLocked`
+    // downgrades it so brand-new namespaces don't block CI.
+    const blocking = opts.allowLocked ? issues.filter((i) => i.type !== 'locked') : issues;
+    return { ok: blocking.length === 0, sourceKeys: totalSourceKeys, issues };
 }
 //# sourceMappingURL=validate.js.map

package/dist/config.d.ts

@@ -17,14 +17,29 @@ export type FileFormat = (typeof FILE_FORMATS)[number];
  * `target` path is one shared file and does not need a `{locale}` placeholder.
  */
 export declare const MULTI_LOCALE_FORMATS: ReadonlySet<FileFormat>;
-/** One source→target file mapping. `target` carries a `{locale}` placeholder. */
+/**
+ * One source→target file mapping. `target` carries a `{locale}` placeholder.
+ *
+ * `source` may be a glob (`*`/`?`, e.g. `locales/en/*.json`); then `target`
+ * and `namespace` must carry a `{basename}` token, and the entry expands at
+ * config load ({@link expandGlobEntries}) into one concrete entry per matched
+ * file with `{basename}` replaced by the file's extension-less name.
+ */
 export interface FileEntry {
     format: FileFormat;
     source: string;
     target: string;
     /** Optional per-entry namespace override (defaults to the top-level namespace). */
     namespace?: string;
+    /**
+     * Write dotted keys flat on `pull` (JSON/YAML only): a pushed `hero.title`
+     * stays `"hero.title"` instead of re-nesting into `{hero: {title}}`, so
+     * flat-keyed consumers (CMS imports, webhook payloads) round-trip.
+     */
+    flat?: boolean;
 }
+/** True when a `files[].source` is a glob pattern rather than a concrete path. */
+export declare function isGlobSource(source: string): boolean;
 export interface LionRapidConfig {
     project: string;
     server: string;
@@ -60,8 +75,33 @@ export declare class ApiKeyError extends Error {
 export declare function findConfigPath(cwd?: string): string | null;
 /** Parse + validate a YAML config string into a typed config. */
 export declare function parseConfig(rawYaml: string): LionRapidConfig;
+/**
+ * Expand glob `files` entries into one concrete entry per matched file: the
+ * match's extension-less basename substitutes the `{basename}` token in
+ * `target` and `namespace`. Non-glob entries pass through untouched; matches
+ * come back sorted (deterministic expansion). A glob matching nothing warns
+ * instead of silently vanishing — a typo'd pattern must not no-op a push.
+ *
+ * Called at config load (loadOfflineContext / doctor), so every command
+ * downstream only ever sees concrete entries.
+ */
+export declare function expandGlobEntries(files: FileEntry[], cwd: string, warn?: (message: string) => void): FileEntry[];
 /** Read + parse + validate the config at `path`. */
 export declare function loadConfig(path: string): LionRapidConfig;
+/** Where the CLI reads/writes credentials: `~/.lionrapid/credentials`. */
+export declare function defaultCredentialsPath(): string;
+/**
+ * Reject a key that can't travel in an HTTP header (fetch encodes headers as
+ * Latin-1 and throws an obscure ByteString error otherwise). The classic case
+ * is copying the dashboard's truncated key display, `sk_eng_…last4` — that
+ * ellipsis is U+2026, not part of the key.
+ */
+export declare function assertKeyCharset(key: string): string;
+/**
+ * Server URLs that have a scoped entry in the credentials file. Lets `init`
+ * default its server to the one you just logged into instead of asking again.
+ */
+export declare function listCredentialServers(credentialsPath?: string): string[];
 export interface ResolveApiKeyOptions {
     /** Environment to read `LIONRAPID_API_KEY` from (defaults to process.env). */
     env?: NodeJS.ProcessEnv;