@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/dist/commands/secrets.js

@@ -7,7 +7,7 @@
  */
 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 { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, 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';
@@ -114,7 +114,11 @@ 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 || '')}`;
+    const expiring = countExpiringSoon(b.meta);
+    const expiringCol = expiring > 0
+        ? chalk.yellow(String(expiring).padEnd(10))
+        : ''.padEnd(10);
+    return `${chalk.cyan(b.name.padEnd(20))} ${String(keys).padEnd(6)} ${chalk.yellow(String(sensitive).padEnd(10))} ${expiringCol} ${chalk.gray(b.description || '')}`;
 }
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
@@ -135,11 +139,102 @@ function redact(value, reveal) {
         return '';
     return '*'.repeat(Math.min(value.length, 8));
 }
+/**
+ * Build a VarMeta patch from CLI flags. Validates each provided field. Returns
+ * undefined if no meta flag was passed (so callers know to skip meta updates).
+ *
+ * `--note -` reads the note from stdin so users can pass long/multi-line notes
+ * without shell-escaping. It's mutually exclusive with `--value-stdin`; both
+ * trying to consume stdin would race and silently corrupt one or the other.
+ */
+function buildMetaPatch(raw) {
+    if (raw.type === undefined && raw.expires === undefined && raw.note === undefined) {
+        return undefined;
+    }
+    const patch = {};
+    if (raw.type !== undefined) {
+        validateSecretType(raw.type);
+        patch.type = raw.type;
+    }
+    if (raw.expires !== undefined) {
+        validateExpiresFutureDated(raw.expires);
+        patch.expires = raw.expires;
+    }
+    if (raw.note !== undefined) {
+        if (raw.note === '-') {
+            if (raw.valueStdin) {
+                throw new Error('--note - and --value-stdin both want stdin; only one can read it.');
+            }
+            const fromStdin = readStdinSync();
+            if (!fromStdin)
+                throw new Error('No note received on stdin.');
+            patch.note = fromStdin;
+        }
+        else {
+            patch.note = raw.note;
+        }
+    }
+    return patch;
+}
+/** Whole days from now until midnight-UTC of the given ISO date. Negative if past. */
+function daysUntil(iso) {
+    const target = new Date(iso + 'T23:59:59Z').getTime();
+    const now = Date.now();
+    return Math.floor((target - now) / (24 * 60 * 60 * 1000));
+}
+/** Render the meta line under a var, indented. Returns empty string if nothing to show. */
+function renderMetaLine(meta, reveal) {
+    if (!meta)
+        return '';
+    const parts = [];
+    if (meta.type)
+        parts.push(`type: ${meta.type}`);
+    if (meta.expires) {
+        const days = daysUntil(meta.expires);
+        const tail = `(in ${days} days)`;
+        let colored;
+        if (days < 0) {
+            colored = chalk.red(`expires: ${meta.expires} ${tail}`);
+        }
+        else if (days < 30) {
+            colored = chalk.yellow(`expires: ${meta.expires} ${tail}`);
+        }
+        else {
+            colored = chalk.gray(`expires: ${meta.expires} ${tail}`);
+        }
+        parts.push(colored);
+    }
+    if (meta.note) {
+        let note = meta.note;
+        if (!reveal && note.length > 80) {
+            note = note.slice(0, 79) + '\u2026';
+        }
+        parts.push(`note: ${note}`);
+    }
+    if (parts.length === 0)
+        return '';
+    return `    ${parts.join('  ')}`;
+}
+/** Count entries in `meta` whose `expires` falls in the next 30 days. */
+function countExpiringSoon(meta) {
+    if (!meta)
+        return 0;
+    let n = 0;
+    for (const m of Object.values(meta)) {
+        if (!m.expires)
+            continue;
+        const d = daysUntil(m.expires);
+        if (d >= 0 && d < 30)
+            n++;
+    }
+    return n;
+}
 /** 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. Inject into agents via `agents run --secrets <name>`.')
+        .description('Named bundles of env variables backed by macOS Keychain (with optional iCloud sync). Inject into agents via `agents run --secrets <name>`.')
+        .hook('preAction', () => { migrateLegacyBundles(); })
         .addHelpText('after', `
 Workflow:
   Bundles are containers; secrets are the variables inside them. Create a
@@ -147,16 +242,29 @@ Workflow:
   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
 
+  # Add with metadata
+  agents secrets add prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "Live key, owner: payments-team"
+
+  # Rotate a key (replaces the value, preserves metadata unless overridden)
+  agents secrets rotate prod STRIPE_API_KEY
+
   # Import an entire .env file straight into keychain
   agents secrets import prod --from .env.prod
 
@@ -180,7 +288,7 @@ Examples:
 `);
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
-        { title: 'Secret commands', names: ['add', 'remove', 'import', 'export'] },
+        { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
     ]);
     cmd
         .command('list')
@@ -193,7 +301,7 @@ Examples:
             console.log(chalk.gray('Try: agents secrets create <name>'));
             return;
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(6)} ${'SENSITIVE'.padEnd(10)} DESCRIPTION`));
+        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(6)} ${'SENSITIVE'.padEnd(10)} ${'EXPIRING'.padEnd(10)} DESCRIPTION`));
         for (const b of bundles) {
             console.log(renderBundleRow(b));
         }
@@ -252,6 +360,9 @@ Examples:
                 else {
                     console.log(`  ${chalk.cyan(e.key.padEnd(28))} ${kindLabel(e.kind).padEnd(18)} ${e.detail}`);
                 }
+                const metaLine = renderMetaLine(bundle.meta?.[e.key], reveal);
+                if (metaLine)
+                    console.log(metaLine);
             }
         }
         catch (err) {
@@ -297,29 +408,45 @@ Examples:
     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 <v>', 'Store as a plaintext literal in the bundle (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)')
+        .option('--type <kind>', 'Tag this secret with a type (api-key, token, password, url, database-url, ssh-key, certificate, webhook, note)')
+        .option('--expires <YYYY-MM-DD>', 'Mark when this secret expires (must be future-dated)')
+        .option('--note <text>', 'Attach a freeform note. Pass `-` to read from stdin (mutually exclusive with --value-stdin).')
         .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);
+            if (resolvedKey in bundle.vars) {
+                throw new Error(`Key '${resolvedKey}' already exists in bundle '${resolvedBundleName}'. Use 'agents secrets rotate' to refresh it.`);
+            }
             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.');
             }
+            const metaPatch = buildMetaPatch(opts);
+            const applyMeta = () => {
+                if (!metaPatch)
+                    return;
+                if (!bundle.meta)
+                    bundle.meta = {};
+                bundle.meta[resolvedKey] = { ...(bundle.meta[resolvedKey] ?? {}), ...metaPatch };
+            };
             if (opts.env) {
                 bundle.vars[resolvedKey] = `env:${opts.env}`;
+                applyMeta();
                 writeBundle(bundle);
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> env:${opts.env}`));
                 return;
             }
             if (opts.file) {
                 bundle.vars[resolvedKey] = `file:${opts.file}`;
+                applyMeta();
                 writeBundle(bundle);
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> file:${opts.file}`));
                 return;
@@ -329,12 +456,14 @@ Examples:
                     throw new Error(`Bundle '${resolvedBundleName}' does not allow exec refs. Re-create with --allow-exec.`);
                 }
                 bundle.vars[resolvedKey] = `exec:${opts.exec}`;
+                applyMeta();
                 writeBundle(bundle);
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} -> exec:${opts.exec}`));
                 return;
             }
             if (opts.value !== undefined) {
                 bundle.vars[resolvedKey] = { value: opts.value };
+                applyMeta();
                 writeBundle(bundle);
                 console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} = <literal>`));
                 return;
@@ -352,6 +481,7 @@ Examples:
             const item = secretsKeychainItem(resolvedBundleName, resolvedKey);
             setKeychainToken(item, secretValue, bundle.icloud_sync);
             bundle.vars[resolvedKey] = keychainRef(resolvedKey);
+            applyMeta();
             writeBundle(bundle);
             const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
             console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} stored in ${where} (${item}).`));
@@ -363,10 +493,71 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('rotate [bundle] [key]')
+        .description('Rotate an existing keychain-backed secret (replaces the value, preserves metadata unless overridden).')
+        .option('--value <v>', 'New value (non-secret cases). Prompts interactively if omitted.')
+        .option('--value-stdin', 'Read the new value from stdin (stored in keychain unless combined with --value)')
+        .option('--type <kind>', 'Update the type metadata (api-key, token, password, url, database-url, ssh-key, certificate, webhook, note)')
+        .option('--expires <YYYY-MM-DD>', 'Update the expiration date (must be future-dated)')
+        .option('--note <text>', 'Update the note. Pass `-` to read from stdin (mutually exclusive with --value-stdin).')
+        .option('--clear-meta', 'Wipe all metadata for this key while rotating')
+        .addHelpText('after', `
+Examples:
+  # Rotate the value, preserve all metadata
+  agents secrets rotate prod STRIPE_API_KEY
+
+  # Rotate with a metadata refresh
+  agents secrets rotate prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "rotated after employee offboarding"
+`)
+        .action(async (bundleName, key, opts) => {
+        try {
+            const resolvedBundleName = bundleName ?? (await pickBundleName('rotate in'));
+            const bundle = readBundle(resolvedBundleName);
+            const resolvedKey = key ?? (await pickKey(bundle, 'rotate'));
+            if (!(resolvedKey in bundle.vars)) {
+                throw new Error(`Key '${resolvedKey}' not in bundle '${resolvedBundleName}'. Use 'agents secrets add' to add a new key.`);
+            }
+            const raw = bundle.vars[resolvedKey];
+            if (typeof raw !== 'string' || !raw.startsWith('keychain:')) {
+                throw new Error(`Key '${resolvedKey}' in bundle '${resolvedBundleName}' is not keychain-backed; cannot rotate.`);
+            }
+            const metaPatch = buildMetaPatch(opts);
+            if (opts.clearMeta && metaPatch) {
+                throw new Error('--clear-meta and --type/--expires/--note are mutually exclusive.');
+            }
+            // Resolve the new value: --value > --value-stdin > prompt.
+            let newValue;
+            if (opts.value !== undefined) {
+                newValue = opts.value;
+            }
+            else if (opts.valueStdin) {
+                newValue = readStdinSync();
+                if (!newValue)
+                    throw new Error('No value received on stdin.');
+            }
+            else {
+                newValue = await promptForSecret(`Enter new value for ${resolvedBundleName}.${resolvedKey}`);
+            }
+            rotateBundleSecret(bundle, resolvedKey, {
+                newValue,
+                clearMeta: opts.clearMeta,
+                meta: metaPatch,
+            });
+            const where = bundle.icloud_sync ? 'iCloud Keychain' : 'keychain';
+            console.log(chalk.green(`${resolvedBundleName}.${resolvedKey} rotated in ${where}.`));
+        }
+        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')
+        .option('--keep-secret', 'Leave the keychain item in place after removing the ref from the bundle')
         .action(async (bundleName, key, opts) => {
         try {
             const resolvedBundleName = bundleName ?? (await pickBundleName('remove from'));
@@ -399,7 +590,7 @@ Examples:
     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('--keep-secrets', 'Leave keychain items in place after deleting the bundle')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .action(async (name, opts) => {
         try {
@@ -447,7 +638,7 @@ Examples:
         .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('--all-plaintext', 'Store every imported value as a literal in the bundle metadata (skip keychain item creation)')
         .option('--force', 'Overwrite an existing key in the bundle')
         .action(async (bundleName, opts) => {
         try {
@@ -488,7 +679,7 @@ Examples:
         .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 { resolveBundleEnv, bundleToEnvPrefix, isReservedEnvName } = await import('../lib/secrets/bundles.js');
             const resolvedBundleName = bundleName ?? (await pickBundleName('export'));
             const bundle = readBundle(resolvedBundleName);
             if (isInteractiveTerminal() && !opts.plaintext) {
@@ -496,9 +687,12 @@ Examples:
                 process.exit(1);
             }
             const env = resolveBundleEnv(bundle);
+            const prefix = bundleToEnvPrefix(resolvedBundleName);
             for (const [k, v] of Object.entries(env)) {
-                const escaped = v.replace(/'/g, `'\\''`);
-                process.stdout.write(`export ${k}='${escaped}'\n`);
+                const exportKey = isReservedEnvName(k) ? `${prefix}_${k}` : k;
+                const needsQuotes = /[\s$`"'\\|&;<>(){}[\]!#~]/.test(v);
+                const output = needsQuotes ? `'${v.replace(/'/g, `'\\''`)}'` : v;
+                process.stdout.write(`export ${exportKey}=${output}\n`);
             }
         }
         catch (err) {

package/dist/commands/sync.js

@@ -5,9 +5,11 @@
  * synchronize resources (commands, skills, hooks, memory, MCP, etc.)
  * into a specific agent version home before launch.
  */
+import * as path from 'path';
 import chalk from 'chalk';
 import { AGENTS } from '../lib/agents.js';
 import { isVersionInstalled, syncResourcesToVersion } from '../lib/versions.js';
+import { compileRulesForProject } from '../lib/rules/compile.js';
 /** Register the hidden `agents sync` command. */
 export function registerSyncCommand(program) {
     program
@@ -39,6 +41,14 @@ export function registerSyncCommand(program) {
             return;
         }
         const result = syncResourcesToVersion(agentId, version, undefined, { projectDir, cwd });
+        // Compile project-scope rules into the workspace itself so each agent's
+        // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
+        // .agents/ directory; the workspace root is its parent.
+        let projectCompile = null;
+        if (projectDir) {
+            const projectRoot = path.dirname(projectDir);
+            projectCompile = compileRulesForProject(projectRoot);
+        }
         if (quiet) {
             return;
         }
@@ -65,5 +75,14 @@ export function registerSyncCommand(program) {
         else {
             console.log(chalk.gray('No resources to sync'));
         }
+        if (projectCompile?.compiled) {
+            const linkInfo = projectCompile.symlinks.length > 0
+                ? ` (+ ${projectCompile.symlinks.join(', ')})`
+                : '';
+            console.log(chalk.gray(`Compiled project rules → ${projectCompile.agentsPath}${linkInfo}`));
+        }
+        if (projectCompile && projectCompile.skippedClobber.length > 0) {
+            console.log(chalk.yellow(`Skipped (user-authored, not overwritten): ${projectCompile.skippedClobber.join(', ')}`));
+        }
     });
 }