@phnx-labs/agents-cli 1.15.0 → 1.16.0

package/dist/commands/view.js

@@ -2,16 +2,16 @@ import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import * as yaml from 'yaml';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
-import { getAgentsDir, getUserAgentsDir, getPromptcutsPath } from '../lib/state.js';
+import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
+import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -512,25 +512,19 @@ async function showAgentResources(agentId, requestedVersion) {
             console.log(`    ${display.padEnd(38)} ${pathStr}${syncStr}`);
         }
     }
-    // Render the single ~/.agents/promptcuts.yaml (cross-agent, not per-version).
-    // Reads the file to surface the shortcut count — cheap (<1KB typical).
+    // Render promptcuts (cross-agent, not per-version). Shortcuts are layered
+    // across system + user files with user precedence; the displayed file path
+    // is whichever is "live" — user if it exists, else system.
     function renderPromptcuts() {
         console.log(chalk.bold(`\nPromptcuts\n`));
-        const promptcutsPath = getPromptcutsPath();
-        if (!fs.existsSync(promptcutsPath)) {
+        const merged = readMergedPromptcuts();
+        const count = Object.keys(merged).length;
+        if (count === 0) {
             console.log(`  ${chalk.gray('none')}`);
             return;
         }
-        let count = 0;
-        try {
-            const parsed = yaml.parse(fs.readFileSync(promptcutsPath, 'utf-8'));
-            count = parsed?.shortcuts ? Object.keys(parsed.shortcuts).length : 0;
-        }
-        catch {
-            count = 0;
-        }
         const label = `${count} shortcut${count === 1 ? '' : 's'}`;
-        console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(promptcutsPath, cwd))}`);
+        console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(getEffectivePromptcutsPath(), cwd))}`);
     }
     // 1. Agent CLI info
     console.log(chalk.bold('Agent CLIs\n'));
@@ -565,7 +559,58 @@ async function showAgentResources(agentId, requestedVersion) {
         }
     }
     renderSection('MCP Servers', agentData.mcp);
-    renderSection('Rules', agentData.memory);
+    // Rules section with subrules breakdown
+    function renderRulesSection() {
+        console.log(chalk.bold('\nRules\n'));
+        const items = agentData.memory;
+        if (items.length === 0) {
+            console.log(`  ${chalk.gray('none')}`);
+            return;
+        }
+        const versionStr = agentData.version ? ` (${agentData.version})` : '';
+        console.log(`  ${chalk.bold(agentData.agentName)}${chalk.gray(versionStr)}:`);
+        // Get composed subrules for the user scope
+        let composedSubrules = [];
+        try {
+            const composed = composeRulesFromState({ cwd });
+            composedSubrules = composed.subrules;
+        }
+        catch {
+            // No preset configured or rules.yaml missing — show rules without subrule breakdown
+        }
+        for (const r of items) {
+            let nameColor = chalk.cyan;
+            if (r.syncState === 'synced')
+                nameColor = chalk.green;
+            else if (r.syncState === 'new')
+                nameColor = chalk.blue;
+            else if (r.syncState === 'modified')
+                nameColor = chalk.yellow;
+            else if (r.syncState === 'deleted')
+                nameColor = chalk.red;
+            let display = nameColor(r.name);
+            if (r.ruleCount !== undefined)
+                display += chalk.gray(` (${r.ruleCount} rules)`);
+            const sourceTag = r.scope === 'project' ? chalk.blue('[project]')
+                : r.scope === 'user' ? chalk.cyan('[user]')
+                    : chalk.gray('[system]');
+            display += ` ${sourceTag}`;
+            const pathStr = r.path ? chalk.gray(formatPath(r.path, cwd)) : '';
+            const syncStr = r.syncState ? chalk.gray(` [${r.syncState}]`) : '';
+            console.log(`    ${display.padEnd(38)} ${pathStr}${syncStr}`);
+            // Show subrules for user-scope rules (the compiled CLAUDE.md)
+            if (r.scope === 'user' && composedSubrules.length > 0) {
+                for (const sub of composedSubrules) {
+                    const scopeLabel = sub.layerScope === 'project' ? chalk.blue('[project]')
+                        : sub.layerScope === 'user' ? chalk.cyan('[user]')
+                            : sub.layerScope === 'extra' ? chalk.magenta(`[${sub.layerAlias || 'extra'}]`)
+                                : chalk.gray('[system]');
+                    console.log(`      ${chalk.gray('-')} ${sub.name} ${scopeLabel}`);
+                }
+            }
+        }
+    }
+    renderRulesSection();
     renderSection('Hooks', agentData.hooks);
     renderPromptcuts();
     // Show legend at the end if git repo exists

package/dist/index.d.ts

@@ -3,6 +3,6 @@
  * CLI entry point for agents-cli.
  *
  * Registers all commands, handles update checks, auto-corrects typos,
- * and launches the first-run interactive init when appropriate.
+ * and launches the first-run interactive setup when appropriate.
  */
 export {};

package/dist/index.js

@@ -3,7 +3,7 @@
  * CLI entry point for agents-cli.
  *
  * Registers all commands, handles update checks, auto-corrects typos,
- * and launches the first-run interactive init when appropriate.
+ * and launches the first-run interactive setup when appropriate.
  */
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -26,7 +26,7 @@ const VERSION = packageJson.version;
 // Import command registrations
 import { registerPullCommand } from './commands/pull.js';
 import { registerRepoCommands } from './commands/repo.js';
-import { registerInitCommand, runInit } from './commands/init.js';
+import { registerSetupCommand, runSetup } from './commands/setup.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerViewCommand } from './commands/view.js';
 import { registerCommandsCommands } from './commands/commands.js';
@@ -59,7 +59,6 @@ import { registerAliasCommand } from './commands/alias.js';
 import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { isPromptCancelled } from './commands/utils.js';
-import { getAgentsDir } from './lib/state.js';
 import { AGENTS } from './lib/agents.js';
 import { getGlobalDefault } from './lib/versions.js';
 import { addShimsToPath, ensureShimCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
@@ -80,7 +79,7 @@ Install, configure, run, and dispatch AI coding agents from one place.
 Works with Claude, Codex, Gemini, Cursor, OpenCode, OpenClaw, and Droid.
 
 Quick start:
-  agents init                     First-time setup (interactive)
+  agents setup                    First-time setup (interactive)
   agents view                     See what's installed
   agents run <agent> ["prompt"]   Run an agent (interactive without prompt, headless with)
   agents sessions                 Browse past sessions across all agents
@@ -199,7 +198,8 @@ async function showWhatsNew(fromVersion, toVersion) {
     }
 }
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const UPDATE_CHECK_FILE = path.join(getAgentsDir(), '.update-check');
+import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir } from './lib/state.js';
+const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /** Read the cached update-check state from disk. Returns null if the file is missing or corrupt. */
 function readUpdateCache() {
     try {
@@ -526,7 +526,7 @@ program
 });
 registerPullCommand(program);
 registerRepoCommands(program);
-registerInitCommand(program);
+registerSetupCommand(program);
 applyGlobalHelpConventions(program);
 /** Calculate the Levenshtein edit distance between two strings. */
 function levenshtein(a, b) {
@@ -582,7 +582,7 @@ await checkForUpdates();
 // status marker that we'll print on the *next* invocation.
 const { spawnDetachedSync } = await import('./lib/auto-pull.js');
 spawnDetachedSync();
-// First-run experience: no args + no config yet + TTY -> launch interactive init.
+// First-run experience: no args + no config yet + TTY -> launch interactive setup.
 // Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
 const passedArgs = process.argv.slice(2);
 const requestedCommand = passedArgs.find((arg) => !arg.startsWith('-'));
@@ -613,14 +613,14 @@ async function registerLazyCommands() {
     }
 }
 await registerLazyCommands();
-const metaFilePath = path.join(getAgentsDir(), 'agents.yaml');
+const metaFilePath = path.join(getUserAgentsDir(), 'agents.yaml');
 const firstRun = passedArgs.length === 0 &&
     !fs.existsSync(metaFilePath) &&
     process.stdin.isTTY &&
     process.stdout.isTTY;
 if (firstRun) {
     try {
-        await runInit(program);
+        await runSetup(program);
     }
     catch (err) {
         if (!(err instanceof Error && err.name === 'ExitPromptError')) {
@@ -629,14 +629,11 @@ if (firstRun) {
     }
     process.exit(0);
 }
-// Commands that require the system repo to be cloned first.
-const SYSTEM_REPO_COMMANDS = new Set([
-    'view', 'status', 'skills', 'rules', 'commands', 'hooks',
-    'mcp', 'permissions', 'versions', 'packages', 'sync',
-    'subagents', 'repo', 'plugins', 'doctor',
-]);
-if (!firstRun && requestedCommand && SYSTEM_REPO_COMMANDS.has(requestedCommand)) {
-    const { ensureInitialized } = await import('./commands/init.js');
+// Every command requires the system repo to be cloned first. `setup` is the
+// only exemption — it's the command that does the cloning.
+const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
+if (!firstRun && requestedCommand && !SETUP_EXEMPT_COMMANDS.has(requestedCommand)) {
+    const { ensureInitialized } = await import('./commands/setup.js');
     await ensureInitialized(program);
 }
 // One-shot idempotent migrations (split-layout, legacy file moves).
@@ -648,8 +645,8 @@ if (!firstRun && requestedCommand && SYSTEM_REPO_COMMANDS.has(requestedCommand))
 if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     try {
         const { runMigration } = await import('./lib/migrate.js');
-        const sentinel = path.join(getAgentsDir(), '.migrated');
-        const sentinelValue = `${VERSION}-v2`;
+        const sentinel = getMigratedSentinelPath();
+        const sentinelValue = `${VERSION}-v8`;
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {
@@ -658,7 +655,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         }
         catch { /* best-effort — fall through to run */ }
         if (needRun) {
-            runMigration();
+            await runMigration();
             try {
                 fs.mkdirSync(path.dirname(sentinel), { recursive: true });
                 fs.writeFileSync(sentinel, sentinelValue);

package/dist/lib/agents.js

@@ -16,7 +16,7 @@ import * as os from 'os';
 import * as TOML from 'smol-toml';
 import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
-import { getVersionsDir, getShimsDir, getAgentsDir } from './state.js';
+import { getVersionsDir, getShimsDir, getCliVersionCachePath } from './state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from './versions.js';
 import { loadClaudeOauth } from './usage.js';
 const execFileAsync = promisify(execFile);
@@ -29,7 +29,7 @@ const HOME = os.homedir();
 export const CODEX_HOOKS_MIN_VERSION = '0.116.0';
 /** Minimum Gemini CLI version that supports the hooks system (v0.26.0, Jan 2026). */
 export const GEMINI_HOOKS_MIN_VERSION = '0.26.0';
-const CLI_VERSION_CACHE_PATH = path.join(getAgentsDir(), '.cli-version-cache.json');
+const CLI_VERSION_CACHE_PATH = getCliVersionCachePath();
 let cliVersionCache = null;
 function loadCliVersionCache() {
     if (cliVersionCache)

package/dist/lib/auto-pull-worker.js

@@ -9,14 +9,13 @@
  * Lock mtime under 5 min => skip (another invocation already in flight).
  */
 import * as fs from 'fs';
-import * as path from 'path';
 import { simpleGit } from 'simple-git';
 import { tryAutoPull, isGitRepo } from './git.js';
-import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, } from './state.js';
+import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos, getFetchCacheDir, } from './state.js';
 import { lockFilePath, statusFilePath } from './auto-pull.js';
 const LOCK_TTL_MS = 5 * 60 * 1000;
 function ensureFetchDir() {
-    const dir = path.join(getSystemAgentsDir(), '.fetch');
+    const dir = getFetchCacheDir();
     if (!fs.existsSync(dir)) {
         try {
             fs.mkdirSync(dir, { recursive: true });

package/dist/lib/auto-pull.js

@@ -13,10 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
-import { getSystemAgentsDir } from './state.js';
+import { getFetchCacheDir } from './state.js';
 /** Where lock files and per-repo status markers live. */
 function fetchStateDir() {
-    return path.join(getSystemAgentsDir(), '.fetch');
+    return getFetchCacheDir();
 }
 /** Per-repo lock file path. mtime acts as a recency check. */
 export function lockFilePath(alias) {

package/dist/lib/browser/cdp.d.ts

@@ -14,7 +14,13 @@ export declare class CDPClient {
     private handleMessage;
     private handleClose;
 }
-export declare function discoverBrowserWsUrl(port: number, host?: string): Promise<string>;
+export interface BrowserDiscovery {
+    wsUrl: string;
+    browser: string;
+}
+export declare function discoverBrowserWsUrl(port: number, host?: string): Promise<BrowserDiscovery>;
+export declare function normalizeBrowserName(s: string): string;
+export declare function verifyBrowserIdentity(reported: string, expected: string, port: number, host?: string): void;
 export declare function listTargets(port: number, host?: string): Promise<Array<{
     id: string;
     type: string;

package/dist/lib/browser/cdp.js

@@ -83,7 +83,35 @@ export async function discoverBrowserWsUrl(port, host = 'localhost') {
         throw new Error(`Failed to discover browser: ${response.status}`);
     }
     const data = (await response.json());
-    return data.webSocketDebuggerUrl;
+    const browserField = data.Browser || data.Product || '';
+    return {
+        wsUrl: data.webSocketDebuggerUrl,
+        browser: normalizeBrowserName(browserField),
+    };
+}
+export function normalizeBrowserName(s) {
+    if (!s)
+        return 'unknown';
+    return s.split('/')[0].trim().toLowerCase().replace(/\s+/g, '-');
+}
+export function verifyBrowserIdentity(reported, expected, port, host = 'localhost') {
+    if (expected === 'custom')
+        return;
+    if (reported === 'unknown')
+        return;
+    const matches = {
+        chrome: ['chrome', 'google-chrome', 'headlesschrome'],
+        chromium: ['chromium', 'headlesschrome'],
+        comet: ['comet'],
+        brave: ['brave', 'brave-browser'],
+        edge: ['edge', 'microsoft-edge', 'msedge'],
+    };
+    const accepted = matches[expected] || [expected];
+    if (accepted.includes(reported))
+        return;
+    const target = host === 'localhost' || host === '127.0.0.1' ? `port ${port}` : `${host}:${port}`;
+    throw new Error(`Browser identity mismatch: profile expects "${expected}" but ${target} is serving "${reported}". ` +
+        `Stop the running browser (e.g. \`pkill -f ${reported}\`) or update the profile to browser=${reported}, then retry.`);
 }
 export async function listTargets(port, host = 'localhost') {
     const response = await fetch(`http://${host}:${port}/json`);

package/dist/lib/browser/chrome.js

@@ -77,6 +77,7 @@ export async function launchBrowser(profileName, browserType, port, options = {}
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
         ...(options.headless ? ['--headless=new'] : []),
+        ...(options.viewport ? [`--window-size=${options.viewport.width},${options.viewport.height}`] : []),
         ...(options.args || []),
     ];
     let env = { ...process.env };
@@ -103,7 +104,8 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     for (let i = 0; i < 30; i++) {
         await sleep(200);
         try {
-            wsUrl = await discoverBrowserWsUrl(port);
+            const result = await discoverBrowserWsUrl(port);
+            wsUrl = result.wsUrl;
             break;
         }
         catch {
@@ -116,7 +118,8 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     return { pid, port, wsUrl };
 }
 export async function attachToChrome(port) {
-    return discoverBrowserWsUrl(port);
+    const { wsUrl } = await discoverBrowserWsUrl(port);
+    return wsUrl;
 }
 export function killChrome(pid) {
     try {

package/dist/lib/browser/devices.d.ts

@@ -0,0 +1,4 @@
+import type { DeviceDescriptor } from './types.js';
+export declare const DEVICES: Record<string, DeviceDescriptor>;
+export declare function getDevice(name: string): DeviceDescriptor | undefined;
+export declare function listDevices(): string[];

package/dist/lib/browser/devices.js

@@ -0,0 +1,27 @@
+export const DEVICES = {
+    'iPhone 14': {
+        width: 390,
+        height: 844,
+        deviceScaleFactor: 3,
+        mobile: true,
+    },
+    'iPad': {
+        width: 768,
+        height: 1024,
+        deviceScaleFactor: 2,
+        mobile: true,
+    },
+    'MacBook Pro': {
+        width: 1440,
+        height: 900,
+        deviceScaleFactor: 2,
+        mobile: false,
+    },
+};
+export function getDevice(name) {
+    const key = Object.keys(DEVICES).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? DEVICES[key] : undefined;
+}
+export function listDevices() {
+    return Object.keys(DEVICES);
+}

package/dist/lib/browser/drivers/local.js

@@ -1,4 +1,4 @@
-import { CDPClient, discoverBrowserWsUrl } from '../cdp.js';
+import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { launchBrowser, allocatePort } from '../chrome.js';
 export async function connectLocal(endpoint, profile) {
     const url = new URL(endpoint);
@@ -7,14 +7,19 @@ export async function connectLocal(endpoint, profile) {
     }
     const port = parseInt(url.port, 10) || 9222;
     try {
-        const wsUrl = await discoverBrowserWsUrl(port);
+        const { wsUrl, browser } = await discoverBrowserWsUrl(port);
+        verifyBrowserIdentity(browser, profile.browser, port);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port, pid: 0 };
     }
-    catch {
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
+            throw err;
+        }
         const newPort = allocatePort();
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, profile.chrome, profile.secrets, profile.binary);
+        const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
+        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port: newPort, pid };

package/dist/lib/browser/drivers/ssh.js

@@ -1,6 +1,6 @@
 import { spawn } from 'child_process';
 import * as net from 'net';
-import { CDPClient, discoverBrowserWsUrl } from '../cdp.js';
+import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { allocatePort } from '../chrome.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
@@ -25,7 +25,14 @@ export async function connectSSH(endpoint, profile) {
         tunnel.kill();
         throw new Error(`SSH tunnel failed to establish to ${host}`);
     }
-    const wsUrl = await discoverBrowserWsUrl(localPort);
+    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort);
+    try {
+        verifyBrowserIdentity(browser, profile.browser, remotePort, host);
+    }
+    catch (err) {
+        tunnel.kill();
+        throw err;
+    }
     const cdp = new CDPClient();
     await cdp.connect(wsUrl);
     return {