ts-prorm-orm 1.1.0 → 1.2.0

package/dist/cli/framework.js

@@ -0,0 +1,436 @@
+"use strict";
+// Modular CLI framework for the cloud/account commands (auth, pull, add, new, …).
+// Each command is a self-contained module registered here, so the command
+// surface can grow without touching a central switch. The legacy monolithic
+// commands in ../cli.ts still work; unknown commands fall through to this
+// registry (see wiring in ../cli.ts).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.out = exports.UsageError = exports.GLOBAL_FLAGS = exports.EXIT = void 0;
+exports.defineCommand = defineCommand;
+exports.getGlobalOptions = getGlobalOptions;
+exports.register = register;
+exports.getCommand = getCommand;
+exports.allCommands = allCommands;
+exports.resolveCommand = resolveCommand;
+exports.closest = closest;
+exports.suggestCommand = suggestCommand;
+exports.parseArgs = parseArgs;
+exports.configureOutput = configureOutput;
+exports.commandHelp = commandHelp;
+exports.topLevelHelp = topLevelHelp;
+exports.runRegistered = runRegistered;
+exports.exitCodeFor = exitCodeFor;
+function defineCommand(cmd) {
+    return cmd;
+}
+// ─── Exit codes ───────────────────────────────────────────────────────────────
+// Distinct, script-friendly exit codes so callers can tell classes of failure
+// apart instead of collapsing everything to 1.
+exports.EXIT = {
+    OK: 0,
+    ERROR: 1,
+    USAGE: 2,
+    AUTH: 3,
+    NETWORK: 4,
+    NOT_FOUND: 5,
+    TIMEOUT: 124,
+};
+const globalOptions = {
+    json: false,
+    quiet: false,
+    verbose: false,
+    assumeYes: false,
+    noInput: false,
+    truncate: true,
+};
+function getGlobalOptions() {
+    return globalOptions;
+}
+/** Flags accepted on every command (merged unless a command declares its own). */
+exports.GLOBAL_FLAGS = [
+    { name: 'json', type: 'boolean', description: 'Output raw JSON.' },
+    { name: 'output', alias: 'o', type: 'string', description: 'Output format.', choices: ['table', 'json', 'csv', 'tsv'] },
+    { name: 'quiet', alias: 'q', type: 'boolean', description: 'Suppress non-essential output.' },
+    { name: 'verbose', type: 'boolean', description: 'Verbose / debug output.' },
+    { name: 'color', type: 'boolean', description: 'Force color (use --no-color to disable).' },
+    { name: 'api-url', type: 'string', description: 'Override the API base URL for this run.' },
+    { name: 'team', type: 'string', description: 'Team context for this run.' },
+    { name: 'yes', alias: 'y', type: 'boolean', description: 'Assume yes; skip confirmation prompts.' },
+    { name: 'no-input', type: 'boolean', description: 'Never prompt (CI/non-interactive mode).' },
+    { name: 'profile', type: 'string', description: 'Named config profile to use.' },
+    { name: 'config', type: 'string', description: 'Path to an alternate config file.' },
+    { name: 'no-truncate', type: 'boolean', description: 'Do not truncate wide table columns.' },
+    { name: 'wide', type: 'boolean', description: 'Show full-width table columns (no truncation).' },
+    { name: 'timeout', type: 'number', description: 'HTTP timeout in seconds.' },
+];
+const GLOBAL_FLAG_NAMES = new Set(exports.GLOBAL_FLAGS.map((f) => f.name));
+/** Populate the global-options singleton from parsed flags. */
+function captureGlobalOptions(flags) {
+    if (flags.json === true)
+        globalOptions.json = true;
+    const output = flags.output;
+    if (typeof output === 'string') {
+        globalOptions.output = output;
+        if (output === 'json')
+            globalOptions.json = true;
+    }
+    if (flags.quiet === true)
+        globalOptions.quiet = true;
+    if (flags.verbose === true)
+        globalOptions.verbose = true;
+    if (typeof flags.color === 'boolean')
+        globalOptions.color = flags.color;
+    if (typeof flags['api-url'] === 'string' && flags['api-url'])
+        globalOptions.apiUrl = flags['api-url'];
+    if (typeof flags.team === 'string' && flags.team)
+        globalOptions.team = flags.team;
+    if (flags.yes === true)
+        globalOptions.assumeYes = true;
+    if (flags['no-input'] === true)
+        globalOptions.noInput = true;
+    if (typeof flags.profile === 'string' && flags.profile)
+        globalOptions.profile = flags.profile;
+    if (typeof flags.config === 'string' && flags.config)
+        globalOptions.configPath = flags.config;
+    if (flags['no-truncate'] === true || flags.wide === true)
+        globalOptions.truncate = false;
+    if (typeof flags.timeout === 'number' && !Number.isNaN(flags.timeout))
+        globalOptions.timeoutSec = flags.timeout;
+}
+// ─── Registry ───────────────────────────────────────────────────────────────
+const registry = new Map();
+const aliasMap = new Map();
+function register(...cmds) {
+    for (const c of cmds) {
+        if (registry.has(c.name))
+            throw new Error(`Duplicate CLI command: ${c.name}`);
+        registry.set(c.name, c);
+        for (const a of c.aliases ?? []) {
+            if (!aliasMap.has(a))
+                aliasMap.set(a, c.name);
+        }
+    }
+}
+function getCommand(name) {
+    return registry.get(name) ?? registry.get(aliasMap.get(name) ?? '');
+}
+function allCommands() {
+    return [...registry.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Resolve a possibly multi-word command from argv (longest match wins). */
+function resolveCommand(argv) {
+    for (const take of [3, 2, 1]) {
+        const name = argv.slice(0, take).join(' ');
+        const cmd = registry.get(name) ?? registry.get(aliasMap.get(name) ?? '');
+        if (cmd)
+            return { cmd, rest: argv.slice(take) };
+    }
+    return { rest: argv };
+}
+// ─── Levenshtein "did you mean" ────────────────────────────────────────────────
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...new Array(n).fill(0)]);
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+/** Closest candidate to `input` within an edit-distance threshold, if any. */
+function closest(input, candidates) {
+    let best;
+    let bestScore = Infinity;
+    for (const cand of candidates) {
+        const score = levenshtein(input, cand);
+        if (score < bestScore) {
+            bestScore = score;
+            best = cand;
+        }
+    }
+    const threshold = Math.max(2, Math.floor(input.length / 3));
+    return best !== undefined && bestScore <= threshold ? best : undefined;
+}
+/** Suggest a registered command (or alias) close to `name`. */
+function suggestCommand(name) {
+    const names = [...registry.keys(), ...aliasMap.keys()];
+    // Also match on the first word for namespaced commands.
+    return closest(name, names) ?? closest(name, [...new Set(names.map((n) => n.split(' ')[0]))]);
+}
+// ─── Arg parsing ──────────────────────────────────────────────────────────────
+function parseArgs(argv, cmd) {
+    const flags = {};
+    const positionals = [];
+    const flagByName = new Map();
+    const flagByAlias = new Map();
+    // Command flags first; globals fill any names the command did not claim.
+    const merged = [...(cmd.flags ?? [])];
+    const declared = new Set(merged.map((f) => f.name));
+    for (const g of exports.GLOBAL_FLAGS)
+        if (!declared.has(g.name))
+            merged.push(g);
+    for (const f of merged) {
+        flagByName.set(f.name, f);
+        if (f.alias && !flagByAlias.has(f.alias))
+            flagByAlias.set(f.alias, f);
+        if (f.default !== undefined)
+            flags[f.name] = f.default;
+    }
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        let spec;
+        let inlineVal;
+        let negated = false;
+        if (tok.startsWith('--')) {
+            const eq = tok.indexOf('=');
+            const name = eq >= 0 ? tok.slice(2, eq) : tok.slice(2);
+            if (eq >= 0)
+                inlineVal = tok.slice(eq + 1);
+            spec = flagByName.get(name);
+            if (!spec && name.startsWith('no-')) {
+                const base = flagByName.get(name.slice(3));
+                if (base && base.type === 'boolean') {
+                    spec = base;
+                    negated = true;
+                }
+            }
+            if (!spec) {
+                const hint = closest(name, [...flagByName.keys()]);
+                throw new UsageError(`Unknown flag: ${tok}${hint ? ` (did you mean --${hint}?)` : ''}`);
+            }
+        }
+        else if (tok.startsWith('-') && tok.length > 1) {
+            spec = flagByAlias.get(tok.slice(1));
+            if (!spec)
+                throw new UsageError(`Unknown flag: ${tok}`);
+        }
+        else {
+            positionals.push(tok);
+            continue;
+        }
+        if (negated) {
+            flags[spec.name] = false;
+            continue;
+        }
+        if (spec.type === 'boolean') {
+            flags[spec.name] = inlineVal === undefined ? true : inlineVal !== 'false';
+        }
+        else {
+            const val = inlineVal ?? argv[++i];
+            if (val === undefined)
+                throw new UsageError(`Flag --${spec.name} needs a value`);
+            if (spec.choices && !spec.choices.includes(val)) {
+                throw new UsageError(`--${spec.name} must be one of: ${spec.choices.join(', ')}`);
+            }
+            flags[spec.name] = spec.type === 'number' ? Number(val) : val;
+        }
+    }
+    // Validate required flags + positionals.
+    for (const f of cmd.flags ?? []) {
+        if (f.required && flags[f.name] === undefined)
+            throw new UsageError(`Missing required flag --${f.name}`);
+    }
+    (cmd.positionals ?? []).forEach((p, idx) => {
+        if (p.required && positionals[idx] === undefined)
+            throw new UsageError(`Missing argument <${p.name}>`);
+        if (p.choices && positionals[idx] && !p.choices.includes(positionals[idx])) {
+            throw new UsageError(`<${p.name}> must be one of: ${p.choices.join(', ')}`);
+        }
+    });
+    captureGlobalOptions(flags);
+    return { positionals, flags, raw: argv };
+}
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+/** A user/usage error (bad flags, missing args) — exits with EXIT.USAGE. */
+class UsageError extends Error {
+}
+exports.UsageError = UsageError;
+// ─── Output helpers ───────────────────────────────────────────────────────────
+const outState = {
+    color: process.stdout.isTTY && !process.env.NO_COLOR && process.env.FORCE_COLOR !== '0',
+    quiet: false,
+    format: 'table',
+    truncate: true,
+};
+/** Apply global options to the output layer. Call once after parsing. */
+function configureOutput() {
+    const g = globalOptions;
+    if (g.color === true)
+        outState.color = true;
+    else if (g.color === false)
+        outState.color = false;
+    else if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0')
+        outState.color = true;
+    else
+        outState.color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+    outState.quiet = g.quiet;
+    outState.truncate = g.truncate;
+    if (g.output === 'csv' || g.output === 'tsv')
+        outState.format = g.output;
+}
+const c = (code, s) => (outState.color ? `\x1b[${code}m${s}\x1b[0m` : s);
+function cell(value) {
+    return value === undefined || value === null ? '' : String(value);
+}
+function delimited(rows, sep) {
+    if (!rows.length)
+        return;
+    const cols = Object.keys(rows[0]);
+    const esc = (s) => sep === ',' && /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+    console.log(cols.map(esc).join(sep));
+    for (const r of rows)
+        console.log(cols.map((col) => esc(cell(r[col]))).join(sep));
+}
+exports.out = {
+    info: (m) => { if (!outState.quiet)
+        console.log(m); },
+    success: (m) => { if (!outState.quiet)
+        console.log(`${c('32', '✓')} ${m}`); },
+    warn: (m) => console.warn(`${c('33', '!')} ${m}`),
+    error: (m) => console.error(`${c('31', '✗')} ${m}`),
+    dim: (m) => { if (!outState.quiet)
+        console.log(c('2', m)); },
+    json: (v) => console.log(JSON.stringify(v, null, 2)),
+    table: (rows) => {
+        if (outState.format === 'csv')
+            return delimited(rows, ',');
+        if (outState.format === 'tsv')
+            return delimited(rows, '\t');
+        if (!rows.length)
+            return console.log('(none)');
+        const cols = Object.keys(rows[0]);
+        // Budget per-column width against the terminal so wide values (URLs, source)
+        // don't blow past the screen. Disabled by --no-truncate/--wide.
+        const termWidth = outState.truncate ? (process.stdout.columns || 0) : 0;
+        const cap = termWidth > 0 ? Math.max(12, Math.floor(termWidth / cols.length) - 2) : Infinity;
+        const trunc = (s) => (s.length > cap ? s.slice(0, cap - 1) + '…' : s);
+        const w = cols.map((col) => Math.max(col.length, ...rows.map((r) => trunc(cell(r[col])).length)));
+        const line = (cells) => cells.map((s, i) => s.padEnd(w[i])).join('  ');
+        console.log(c('1', line(cols)));
+        rows.forEach((r) => console.log(line(cols.map((col) => trunc(cell(r[col]))))));
+    },
+};
+// ─── Help ─────────────────────────────────────────────────────────────────────
+function commandHelp(cmd) {
+    const lines = [`\n${cmd.name} — ${cmd.description}\n`];
+    const usageParts = ['orm-cli', cmd.name];
+    (cmd.positionals ?? []).forEach((p) => usageParts.push(p.required ? `<${p.name}>` : `[${p.name}]`));
+    if (cmd.flags?.length)
+        usageParts.push('[flags]');
+    lines.push(`Usage: ${usageParts.join(' ')}\n`);
+    if (cmd.aliases?.length)
+        lines.push(`Aliases: ${cmd.aliases.join(', ')}\n`);
+    if (cmd.positionals?.length) {
+        lines.push('Arguments:');
+        cmd.positionals.forEach((p) => {
+            const meta = p.choices ? ` [choices: ${p.choices.join(', ')}]` : '';
+            lines.push(`  ${p.name.padEnd(18)} ${p.description}${meta}`);
+        });
+        lines.push('');
+    }
+    if (cmd.flags?.length) {
+        lines.push('Flags:');
+        cmd.flags.forEach((f) => {
+            const names = `--${f.name}${f.alias ? `, -${f.alias}` : ''}`;
+            const bits = [];
+            if (f.choices)
+                bits.push(`choices: ${f.choices.join(', ')}`);
+            if (f.default !== undefined)
+                bits.push(`default: ${f.default}`);
+            const meta = bits.length ? ` [${bits.join('; ')}]` : '';
+            lines.push(`  ${names.padEnd(22)} ${f.description}${f.required ? ' (required)' : ''}${meta}`);
+        });
+        lines.push('');
+    }
+    if (cmd.examples?.length) {
+        lines.push('Examples:');
+        cmd.examples.forEach((e) => lines.push(`  ${e}`));
+        lines.push('');
+    }
+    lines.push('Global flags: --json, -o <fmt>, --quiet, --verbose, --color/--no-color,');
+    lines.push('  --api-url <url>, --team <slug>, --yes, --no-input, --profile <name>,');
+    lines.push('  --config <path>, --no-truncate, --timeout <sec>');
+    return lines.join('\n');
+}
+function topLevelHelp() {
+    const groups = new Map();
+    for (const cmd of allCommands()) {
+        const g = cmd.group ?? 'Commands';
+        if (!groups.has(g))
+            groups.set(g, []);
+        groups.get(g).push(cmd);
+    }
+    const lines = ['\norm-cli — prorm command line\n', 'Usage: orm-cli <command> [args] [flags]\n'];
+    for (const [g, cmds] of [...groups].sort()) {
+        lines.push(c('1', g));
+        cmds.forEach((cmd) => lines.push(`  ${cmd.name.padEnd(22)} ${cmd.description}`));
+        lines.push('');
+    }
+    lines.push('Global flags (any command):');
+    lines.push('  --json / -o <table|json|csv|tsv>  Output format');
+    lines.push('  --quiet / --verbose               Silence or expand output');
+    lines.push('  --color / --no-color              Force or disable ANSI color');
+    lines.push('  --api-url <url> --team <slug>     Per-invocation context override');
+    lines.push('  --yes / --no-input                Confirm-all / never-prompt (CI)');
+    lines.push('  --profile <name> --config <path>  Alternate account / config file');
+    lines.push('');
+    lines.push('Environment: PRORM_API_URL, PRORM_CONFIG, PRORM_PROFILE, PRORM_NO_INPUT,');
+    lines.push('  PRORM_NO_KEYCHAIN, NO_COLOR, FORCE_COLOR, HTTP(S)_PROXY, PRORM_DEBUG');
+    lines.push('');
+    lines.push('Run `orm-cli help <command>` or `orm-cli <command> --help` for details.');
+    return lines.join('\n');
+}
+// ─── Dispatch ───────────────────────────────────────────────────────────────
+/** Dispatch argv against the registry. Returns an exit code, or null if no
+ *  registered command matched (so the caller can fall back to legacy handling). */
+async function runRegistered(argv) {
+    // `help [command]` form.
+    if (argv[0] === 'help') {
+        const { cmd } = resolveCommand(argv.slice(1));
+        console.log(cmd ? commandHelp(cmd) : topLevelHelp());
+        return 0;
+    }
+    const { cmd, rest } = resolveCommand(argv);
+    if (!cmd)
+        return null;
+    if (rest.includes('--help') || rest.includes('-h')) {
+        console.log(commandHelp(cmd));
+        return 0;
+    }
+    try {
+        const ctx = parseArgs(rest, cmd);
+        configureOutput();
+        const code = await cmd.run(ctx);
+        return typeof code === 'number' ? code : 0;
+    }
+    catch (err) {
+        configureOutput();
+        exports.out.error(err instanceof Error ? err.message : String(err));
+        return exitCodeFor(err);
+    }
+}
+/** Map a thrown error to a script-friendly exit code. */
+function exitCodeFor(err) {
+    if (err instanceof UsageError)
+        return exports.EXIT.USAGE;
+    const anyErr = err;
+    if (anyErr && typeof anyErr.status === 'number') {
+        if (anyErr.status === 401 || anyErr.status === 403)
+            return exports.EXIT.AUTH;
+        if (anyErr.status === 404)
+            return exports.EXIT.NOT_FOUND;
+    }
+    if (anyErr && (anyErr.code === 'ENETWORK' || anyErr.code === 'ENOTFOUND' || anyErr.code === 'ETIMEDOUT')) {
+        return exports.EXIT.NETWORK;
+    }
+    return exports.EXIT.ERROR;
+}

package/dist/cli/io.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Guard a local write: if `dest` already exists, confirm before clobbering it.
+ * Returns true when it is safe to proceed. `assumeYes` (from --yes) skips the
+ * prompt; in a non-interactive session without --yes this refuses.
+ */
+export declare function ensureOverwrite(dest: string, assumeYes: boolean): Promise<boolean>;
+/** Stream a local file to a presigned PUT URL without buffering it in memory. */
+export declare function uploadFile(url: string, filePath: string, contentType: string): Promise<number>;
+/** Stream a presigned GET URL to a local file without buffering it in memory. */
+export declare function downloadFile(url: string, dest: string): Promise<void>;
+/**
+ * Expand simple `*`/`?` globs against the filesystem. Patterns without wildcards
+ * are returned as-is. Only the basename segment is matched (single directory).
+ */
+export declare function expandGlobs(patterns: string[]): string[];
+/**
+ * Warn when writing credentials to a file that is not git-ignored. Best-effort:
+ * checks a sibling/ancestor .gitignore for the target's basename. Never blocks.
+ */
+export declare function warnIfTracked(file: string): void;
+export interface Spinner {
+    update(text: string): void;
+    stop(finalText?: string): void;
+}
+/** Start a spinner (no-op when quiet or not a TTY). */
+export declare function spinner(text: string): Spinner;

package/dist/cli/io.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureOverwrite = ensureOverwrite;
+exports.uploadFile = uploadFile;
+exports.downloadFile = downloadFile;
+exports.expandGlobs = expandGlobs;
+exports.warnIfTracked = warnIfTracked;
+exports.spinner = spinner;
+// Filesystem + transfer helpers shared by the storage/code/user commands:
+// streaming up/downloads (so large files never buffer fully in memory),
+// overwrite protection, glob expansion, a .env git-tracking guard, and a small
+// TTY spinner for long-running operations.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const stream_1 = require("stream");
+const promises_1 = require("stream/promises");
+const framework_1 = require("./framework");
+const prompt_1 = require("./prompt");
+// ─── Overwrite protection ──────────────────────────────────────────────────────
+/**
+ * Guard a local write: if `dest` already exists, confirm before clobbering it.
+ * Returns true when it is safe to proceed. `assumeYes` (from --yes) skips the
+ * prompt; in a non-interactive session without --yes this refuses.
+ */
+async function ensureOverwrite(dest, assumeYes) {
+    if (!fs.existsSync(dest))
+        return true;
+    const ok = await (0, prompt_1.confirm)(`${dest} already exists. Overwrite?`, { assumeYes, default: false });
+    if (!ok)
+        framework_1.out.warn(`Skipped ${dest} (exists; pass --yes to overwrite).`);
+    return ok;
+}
+// ─── Streaming transfers ───────────────────────────────────────────────────────
+/** Stream a local file to a presigned PUT URL without buffering it in memory. */
+async function uploadFile(url, filePath, contentType) {
+    const size = fs.statSync(filePath).size;
+    const stream = fs.createReadStream(filePath);
+    const res = await fetch(url, {
+        method: 'PUT',
+        // Node's fetch (undici) requires duplex for a stream body.
+        body: stream_1.Readable.toWeb(stream),
+        duplex: 'half',
+        headers: { 'content-type': contentType, 'content-length': String(size) },
+    });
+    if (!res.ok)
+        throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+    return size;
+}
+/** Stream a presigned GET URL to a local file without buffering it in memory. */
+async function downloadFile(url, dest) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+    if (!res.body) {
+        fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+        return;
+    }
+    const dir = path.dirname(dest);
+    if (dir)
+        fs.mkdirSync(dir, { recursive: true });
+    await (0, promises_1.pipeline)(stream_1.Readable.fromWeb(res.body), fs.createWriteStream(dest));
+}
+// ─── Glob expansion ────────────────────────────────────────────────────────────
+/**
+ * Expand simple `*`/`?` globs against the filesystem. Patterns without wildcards
+ * are returned as-is. Only the basename segment is matched (single directory).
+ */
+function expandGlobs(patterns) {
+    const results = [];
+    for (const pattern of patterns) {
+        if (!/[*?]/.test(pattern)) {
+            results.push(pattern);
+            continue;
+        }
+        const dir = path.dirname(pattern);
+        const base = path.basename(pattern);
+        const re = new RegExp('^' + base.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+        let entries = [];
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            entries = [];
+        }
+        const matched = entries.filter((e) => re.test(e)).map((e) => path.join(dir, e));
+        if (matched.length)
+            results.push(...matched);
+        else
+            framework_1.out.warn(`No files match ${pattern}`);
+    }
+    return results;
+}
+// ─── .env git-tracking guard ────────────────────────────────────────────────────
+/**
+ * Warn when writing credentials to a file that is not git-ignored. Best-effort:
+ * checks a sibling/ancestor .gitignore for the target's basename. Never blocks.
+ */
+function warnIfTracked(file) {
+    const abs = path.resolve(file);
+    const base = path.basename(abs);
+    let dir = path.dirname(abs);
+    for (let i = 0; i < 6; i++) {
+        const gi = path.join(dir, '.gitignore');
+        try {
+            const contents = fs.readFileSync(gi, 'utf8');
+            const patterns = contents.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+            if (patterns.some((p) => p === base || p === '*.env' || p === base.replace(/^\./, '.') || (p.startsWith('.env') && base.startsWith('.env')))) {
+                return; // Looks ignored.
+            }
+        }
+        catch {
+            // no .gitignore here
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+        if (fs.existsSync(path.join(dir, '.git')))
+            break;
+    }
+    framework_1.out.warn(`${file} may not be git-ignored — add it to .gitignore so credentials aren't committed.`);
+}
+// ─── Spinner ────────────────────────────────────────────────────────────────────
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** Start a spinner (no-op when quiet or not a TTY). */
+function spinner(text) {
+    const g = (0, framework_1.getGlobalOptions)();
+    const active = Boolean(process.stderr.isTTY) && !g.quiet && !g.json;
+    if (!active) {
+        return { update: () => undefined, stop: () => undefined };
+    }
+    let i = 0;
+    let current = text;
+    const render = () => {
+        process.stderr.write(`\r${FRAMES[i = (i + 1) % FRAMES.length]} ${current}`);
+    };
+    const timer = setInterval(render, 80);
+    render();
+    return {
+        update: (t) => { current = t; },
+        stop: (finalText) => {
+            clearInterval(timer);
+            process.stderr.write('\r\x1b[K');
+            if (finalText)
+                process.stderr.write(finalText + '\n');
+        },
+    };
+}

package/dist/cli/keychain.d.ts

@@ -0,0 +1,10 @@
+/** The keychain backend available on this host, or null if none. */
+export declare function backend(): 'macos' | 'libsecret' | null;
+/** True when a native credential store will be used for the token. */
+export declare function isAvailable(): boolean;
+/** Store the token in the OS keychain. Returns false if no backend handled it. */
+export declare function setToken(token: string): boolean;
+/** Read the token from the OS keychain, or undefined if absent/unavailable. */
+export declare function getToken(): string | undefined;
+/** Delete the token from the OS keychain (best-effort). */
+export declare function deleteToken(): void;