@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/commands/secrets.js

@@ -0,0 +1,518 @@
+/**
+ * Secrets bundle management commands.
+ *
+ * Registers the `agents secrets` command tree for creating, viewing,
+ * and managing named bundles of environment variables backed by macOS
+ * Keychain. Bundles are injected at run time via `agents run --secrets`.
+ */
+import chalk from 'chalk';
+import * as fs from 'fs';
+import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, parseDotenv, readBundle, validateBundleName, validateEnvKey, writeBundle, } from '../lib/secrets/bundles.js';
+import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { registerCommandGroups } from '../lib/help.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
+async function promptForSecret(message) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A secret is required but the shell is not interactive. Pass --value, --value-stdin, or run from a TTY.');
+    }
+    const { password } = await import('@inquirer/prompts');
+    return await password({ message, mask: true });
+}
+/** Prompt the user to pick an existing bundle by name. Requires an interactive TTY. */
+async function pickBundleName(action) {
+    const bundles = listBundles();
+    if (bundles.length === 0) {
+        throw new Error('No secrets bundles configured. Try: agents secrets create <name>');
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { select } = await import('@inquirer/prompts');
+    return await select({
+        message: `Which bundle to ${action}?`,
+        choices: bundles.map((b) => ({
+            name: b.name,
+            value: b.name,
+            description: b.description || undefined,
+        })),
+    });
+}
+/** Prompt the user to type a new bundle name. Requires an interactive TTY. */
+async function promptBundleName() {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A bundle name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { input } = await import('@inquirer/prompts');
+    return await input({
+        message: 'Bundle name',
+        validate: (value) => {
+            try {
+                validateBundleName(value);
+                return true;
+            }
+            catch (err) {
+                return err.message;
+            }
+        },
+    });
+}
+/** Prompt the user to pick an existing key from a bundle. Requires an interactive TTY. */
+async function pickKey(bundle, action) {
+    const keys = Object.keys(bundle.vars);
+    if (keys.length === 0) {
+        throw new Error(`Bundle '${bundle.name}' has no keys.`);
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { select } = await import('@inquirer/prompts');
+    return await select({
+        message: `Which key to ${action}?`,
+        choices: keys.map((k) => ({ name: k, value: k })),
+    });
+}
+/** Prompt the user to type a new key name for a bundle. Requires an interactive TTY. */
+async function promptKeyName(bundleName) {
+    if (!isInteractiveTerminal()) {
+        throw new Error('A key name is required. Pass it as an argument or run from a TTY.');
+    }
+    const { input } = await import('@inquirer/prompts');
+    return await input({
+        message: `Key name to add to '${bundleName}'`,
+        validate: (value) => {
+            try {
+                validateEnvKey(value);
+                return true;
+            }
+            catch (err) {
+                return err.message;
+            }
+        },
+    });
+}
+/** Read all available data from stdin synchronously, trimmed. */
+function readStdinSync() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+        let bytesRead;
+        try {
+            bytesRead = fs.readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            break;
+        }
+        if (bytesRead === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
+    }
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+/** Format a single bundle as a table row for the `secrets list` output. */
+function renderBundleRow(b) {
+    const entries = describeBundle(b);
+    const keys = entries.length;
+    const sensitive = entries.filter((e) => e.kind === 'keychain').length;
+    return `${chalk.cyan(b.name.padEnd(20))} ${String(keys).padEnd(6)} ${chalk.yellow(String(sensitive).padEnd(10))} ${chalk.gray(b.description || '')}`;
+}
+/** Colorize a variable source kind (literal, keychain, env, file, exec). */
+function kindLabel(kind) {
+    switch (kind) {
+        case 'literal': return chalk.gray('literal');
+        case 'keychain': return chalk.green('keychain');
+        case 'env': return chalk.blue('env');
+        case 'file': return chalk.magenta('file');
+        case 'exec': return chalk.red('exec');
+        default: return kind;
+    }
+}
+/** Mask a value with asterisks unless reveal is true. */
+function redact(value, reveal) {
+    if (reveal)
+        return value;
+    if (!value)
+        return '';
+    return '*'.repeat(Math.min(value.length, 8));
+}
+/** Register the `agents secrets` command tree. */
+export function registerSecretsCommands(program) {
+    const cmd = program
+        .command('secrets')
+        .description('Named bundles of env variables backed by macOS Keychain (with optional iCloud sync). Inject into agents via `agents run --secrets <name>`.')
+        .addHelpText('after', `
+Workflow:
+  Bundles are containers; secrets are the variables inside them. Create a
+  bundle once, add secrets to it, then inject the whole bundle into any agent
+  run with --secrets <name>. Keychain-backed values never touch disk in
+  plaintext.
+
+  Pass --icloud-sync at create time to store values in the iCloud-synced
+  keychain so they appear automatically on your other Macs (same iCloud
+  account, iCloud Keychain enabled). Without the flag, values are device-local.
+
+Examples:
+  # Create a bundle for production credentials
+  agents secrets create prod --description "Production keys for the api stack"
+
+  # Create a bundle that syncs to your other Macs via iCloud Keychain
+  agents secrets create npm-tokens --icloud-sync
+
+  # Add a keychain-backed secret (prompts for the value)
+  agents secrets add prod STRIPE_API_KEY
+
+  # Add a literal (non-sensitive) value
+  agents secrets add prod LOG_LEVEL --value info
+
+  # Import an entire .env file straight into keychain
+  agents secrets import prod --from .env.prod
+
+  # See what's in a bundle (values masked)
+  agents secrets view prod
+
+  # Reveal the real values in an interactive shell
+  agents secrets view prod --reveal
+
+  # Inject the bundle into an agent run
+  agents run claude "deploy the worker" --secrets prod
+
+  # Eval the bundle into your current shell
+  eval "$(agents secrets export prod --plaintext)"
+
+  # Remove one key (purges the keychain item by default)
+  agents secrets remove prod STRIPE_API_KEY
+
+  # Delete the whole bundle and purge every keychain item it owned
+  agents secrets delete prod
+`);
+    registerCommandGroups(cmd, [
+        { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
+        { title: 'Secret commands', names: ['add', 'remove', 'import', 'export'] },
+    ]);
+    cmd
+        .command('list')
+        .alias('ls')
+        .description('List configured secrets bundles')
+        .action(() => {
+        const bundles = listBundles();
+        if (bundles.length === 0) {
+            console.log(chalk.gray('No secrets bundles configured.'));
+            console.log(chalk.gray('Try: agents secrets create <name>'));
+            return;
+        }
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(6)} ${'SENSITIVE'.padEnd(10)} DESCRIPTION`));
+        for (const b of bundles) {
+            console.log(renderBundleRow(b));
+        }
+    });
+    cmd
+        .command('view [name]')
+        .alias('show')
+        .description('Show a bundle. Keychain values are masked by default — pass --reveal to see them.')
+        .option('--reveal', 'Print keychain-backed values in the clear (TTY only unless --plaintext)')
+        .option('--plaintext', 'Allow --reveal in non-interactive shells (use with care)')
+        .action(async (name, opts) => {
+        try {
+            const resolvedName = name ?? (await pickBundleName('view'));
+            const bundle = readBundle(resolvedName);
+            const entries = describeBundle(bundle);
+            console.log(chalk.bold(bundle.name));
+            if (bundle.description)
+                console.log(chalk.gray(bundle.description));
+            if (bundle.allow_exec)
+                console.log(chalk.yellow('allow_exec: true'));
+            if (bundle.icloud_sync)
+                console.log(chalk.cyan('icloud_sync: true'));
+            console.log();
+            if (entries.length === 0) {
+                console.log(chalk.gray('(no keys)'));
+                return;
+            }
+            const reveal = Boolean(opts.reveal);
+            if (reveal && !isInteractiveTerminal() && !opts.plaintext) {
+                console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
+                process.exit(1);
+            }
+            for (const e of entries) {
+                if (e.kind === 'keychain') {
+                    const item = secretsKeychainItem(bundle.name, e.detail);
+                    const stored = hasKeychainToken(item, bundle.icloud_sync);
+                    const marker = stored ? chalk.green('stored') : chalk.red('missing');
+                    let valueCol = `[keychain:${e.detail}] ${marker}`;
+                    if (reveal && stored) {
+                        try {
+                            valueCol = redact(getKeychainToken(item, bundle.icloud_sync), true);
+                        }
+                        catch {
+                            // fall through to masked
+                        }
+                    }
+                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${valueCol}`);
+                }
+                else if (e.kind === 'literal') {
+                    const raw = bundle.vars[e.key];
+                    const literalValue = typeof raw === 'string'
+                        ? raw
+                        : (raw && typeof raw === 'object' && 'value' in raw ? raw.value : '');
+                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${literalValue}`);
+                }
+                else {
+                    console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${e.detail}`);
+                }
+            }
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('create [name]')
+        .description('Create an empty bundle')
+        .option('--description <text>', 'Free-form description')
+        .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
+        .option('--icloud-sync', 'Store keychain values in iCloud Keychain so they sync across your Macs (requires Xcode CLT)')
+        .option('--force', 'Overwrite an existing bundle')
+        .action(async (name, opts) => {
+        try {
+            const resolvedName = name ?? (await promptBundleName());
+            validateBundleName(resolvedName);
+            if (bundleExists(resolvedName) && !opts.force) {
+                console.error(chalk.red(`Bundle '${resolvedName}' already exists. Use --force to overwrite.`));
+                process.exit(1);
+            }
+            const bundle = {
+                name: resolvedName,
+                description: opts.description,
+                allow_exec: opts.allowExec,
+                icloud_sync: opts.icloudSync,
+                vars: {},
+            };
+            writeBundle(bundle);
+            console.log(chalk.green(`Bundle '${resolvedName}' created.`));
+            console.log(chalk.gray(`Try: agents secrets add ${resolvedName} MY_KEY`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('add [bundle] [key]')
+        .description('Add a variable to a bundle. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.')
+        .option('--value <v>', 'Store as a plaintext literal in the YAML (non-sensitive values only)')
+        .option('--value-stdin', 'Read the value from stdin (stored in keychain unless combined with --value)')
+        .option('--env <VAR>', 'Store as an env: ref that reads from the parent process.env at run time')
+        .option('--file <path>', 'Store as a file: ref that reads from a file at run time')
+        .option('--exec <cmd>', 'Store as an exec: ref that runs a command at run time (requires allow_exec)')
+        .action(async (bundleName, key, opts) => {
+        try {
+            const resolvedBundleName = bundleName ?? (await pickBundleName('add to'));
+            const bundle = readBundle(resolvedBundleName);
+            const resolvedKey = key ?? (await promptKeyName(resolvedBundleName));
+            validateEnvKey(resolvedKey);
+            const sources = [opts.value !== undefined, Boolean(opts.env), Boolean(opts.file), Boolean(opts.exec)].filter(Boolean).length;
+            if (sources > 1) {
+                throw new Error('Pick one of: --value, --env, --file, --exec.');
+            }
+            if (opts.env) {
+                bundle.vars[resolvedKey] = `env:${opts.env}`;
+                writeBundle(bundle);
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> env:${opts.env}`));
+                return;
+            }
+            if (opts.file) {
+                bundle.vars[resolvedKey] = `file:${opts.file}`;
+                writeBundle(bundle);
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> file:${opts.file}`));
+                return;
+            }
+            if (opts.exec) {
+                if (!bundle.allow_exec) {
+                    throw new Error(`Bundle '${resolvedBundleName}' does not allow exec refs. Re-create with --allow-exec.`);
+                }
+                bundle.vars[resolvedKey] = `exec:${opts.exec}`;
+                writeBundle(bundle);
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> exec:${opts.exec}`));
+                return;
+            }
+            if (opts.value !== undefined) {
+                bundle.vars[resolvedKey] = { value: opts.value };
+                writeBundle(bundle);
+                console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
+                return;
+            }
+            // Default path: keychain-backed.
+            let secretValue;
+            if (opts.valueStdin) {
+                secretValue = readStdinSync();
+                if (!secretValue)
+                    throw new Error('No value received on stdin.');
+            }
+            else {
+                secretValue = await promptForSecret(`Enter value for ${resolvedBundleName}.${resolvedKey}`);
+            }
+            const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
+            setKeychainToken(item, secretValue, bundle.icloud_sync);
+            bundle.vars[resolvedKey] = keychainRef(resolvedKey);
+            writeBundle(bundle);
+            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('remove [bundle] [key]')
+        .description('Remove a key from the bundle. Purges the keychain item if the ref was keychain:. Use --keep-secret to retain it.')
+        .option('--keep-secret', 'Leave the keychain item in place after removing the YAML ref')
+        .action(async (bundleName, key, opts) => {
+        try {
+            const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
+            const bundle = readBundle(resolvedBundleName);
+            const resolvedKey = key ?? (await pickKey(bundle, 'remove'));
+            if (!(resolvedKey in bundle.vars)) {
+                console.error(chalk.red(`Key '${resolvedKey}' not found in bundle '${resolvedBundleName}'.`));
+                process.exit(1);
+            }
+            const raw = bundle.vars[resolvedKey];
+            delete bundle.vars[resolvedKey];
+            writeBundle(bundle);
+            if (!opts.keepSecret && typeof raw === 'string' && raw.startsWith('keychain:')) {
+                const item = secretsKeychainItem(resolvedBundleName, raw.slice('keychain:'.length));
+                const removed = deleteKeychainToken(item, bundle.icloud_sync);
+                if (removed) {
+                    console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey} and purged keychain item.`));
+                    return;
+                }
+            }
+            console.log(chalk.green(`Removed ${resolvedBundleName}.${resolvedKey}.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('delete [name]')
+        .description('Delete a bundle and purge all its keychain items (use --keep-secrets to retain them).')
+        .option('--keep-secrets', 'Leave keychain items in place after deleting the bundle file')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .action(async (name, opts) => {
+        try {
+            const resolvedName = name ?? (await pickBundleName('delete'));
+            const bundle = readBundle(resolvedName);
+            if (!opts.yes) {
+                if (!isInteractiveTerminal()) {
+                    console.error(chalk.red(`Refusing to delete '${resolvedName}' without --yes in a non-interactive shell.`));
+                    process.exit(1);
+                }
+                const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
+                const suffix = keychainCount && !opts.keepSecrets
+                    ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
+                    : '';
+                const { confirm } = await import('@inquirer/prompts');
+                const proceed = await confirm({
+                    message: `Delete bundle '${resolvedName}'${suffix}?`,
+                    default: false,
+                });
+                if (!proceed) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
+            }
+            if (!opts.keepSecrets) {
+                for (const { item } of keychainItemsForBundle(bundle)) {
+                    deleteKeychainToken(item, bundle.icloud_sync);
+                }
+            }
+            const existed = deleteBundle(resolvedName);
+            if (!existed) {
+                console.error(chalk.red(`Bundle '${resolvedName}' not found.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Bundle '${resolvedName}' deleted.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('import [bundle]')
+        .description('Import keys from a .env file into a bundle. By default every key is stored in keychain.')
+        .requiredOption('--from <path>', 'Path to a .env file')
+        .option('--all-plaintext', 'Store every imported value as a YAML literal (skip keychain prompts)')
+        .option('--force', 'Overwrite an existing key in the bundle')
+        .action(async (bundleName, opts) => {
+        try {
+            const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
+            const bundle = readBundle(resolvedBundleName);
+            const raw = fs.readFileSync(opts.from, 'utf-8');
+            const pairs = parseDotenv(raw);
+            let added = 0;
+            let skipped = 0;
+            for (const [key, value] of Object.entries(pairs)) {
+                if (!opts.force && key in bundle.vars) {
+                    skipped++;
+                    continue;
+                }
+                if (opts.allPlaintext) {
+                    bundle.vars[key] = { value };
+                }
+                else {
+                    const item = secretsKeychainItem(resolvedBundleName, key);
+                    setKeychainToken(item, value, bundle.icloud_sync);
+                    bundle.vars[key] = keychainRef(key);
+                }
+                added++;
+            }
+            writeBundle(bundle);
+            console.log(chalk.green(`Imported ${added} key(s)${skipped ? `, skipped ${skipped} (already set, pass --force)` : ''}.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('export [bundle]')
+        .description('Resolve a bundle and print KEY=VALUE lines (for `eval "$(agents secrets export prod)"`). Refuses on a TTY unless --plaintext.')
+        .option('--plaintext', 'Acknowledge that the resolved values will be printed in the clear')
+        .action(async (bundleName, opts) => {
+        try {
+            const { resolveBundleEnv } = await import('../lib/secrets/bundles.js');
+            const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
+            const bundle = readBundle(resolvedBundleName);
+            if (isInteractiveTerminal() && !opts.plaintext) {
+                console.error(chalk.red('export to a TTY requires --plaintext (prevents shoulder-surfing).'));
+                process.exit(1);
+            }
+            const env = resolveBundleEnv(bundle);
+            for (const [k, v] of Object.entries(env)) {
+                const escaped = v.replace(/'/g, `'\\''`);
+                process.stdout.write(`export ${k}='${escaped}'\n`);
+            }
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/sessions-picker.d.ts

@@ -11,6 +11,7 @@ export interface SessionPickerConfig {
     pageSize?: number;
     initialSearch?: string;
 }
+/** Build a cached multi-line preview string for display in the session picker. */
 export declare function buildPreview(session: SessionMeta): string;
+/** Show an interactive session picker and return the selected session with its action (resume or view). */
 export declare function sessionPicker(config: SessionPickerConfig): Promise<PickedSession | null>;
-//# sourceMappingURL=sessions-picker.d.ts.map