ultraclaude-agent 0.0.25 → 0.0.28

package/__tests__/cli-commands.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Tests for the non-interactive CLI surface (src/cli.ts), driven through the shared registry.
+ *
+ * Strategy: cli.ts runs `await runCli(process.argv)` at module top-level, so each case sets
+ * `process.argv`, calls `vi.resetModules()`, and `await import('../src/cli.js')` — which builds
+ * the commander program from the registry and parses the preset args. We then assert the
+ * config/console/exit-code effects of the account commands and `reset`.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// --- Mocks (hoisted; arrows capture the mock fns lazily at module-import time) ---
+
+const mockLoadCredentials = vi.fn();
+const mockLoadAllCredentials = vi.fn();
+const mockLoadServerConfig = vi.fn();
+const mockSaveServerConfig = vi.fn().mockResolvedValue(undefined);
+const mockGetServerUrl = vi.fn();
+const mockGetProjectId = vi.fn();
+const mockLoadRegistry = vi.fn();
+const mockReadPid = vi.fn();
+const mockIsDaemonRunning = vi.fn();
+const mockIsPidAlive = vi.fn();
+const mockCleanStalePidFile = vi.fn().mockResolvedValue(undefined);
+const mockResolveServerPaths = vi.fn();
+const mockClearServerConfig = vi.fn().mockResolvedValue(undefined);
+
+vi.mock('../src/config.js', () => ({
+  loadCredentials: (...a: unknown[]) => mockLoadCredentials(...a),
+  loadAllCredentials: (...a: unknown[]) => mockLoadAllCredentials(...a),
+  loadServerConfig: (...a: unknown[]) => mockLoadServerConfig(...a),
+  saveServerConfig: (...a: unknown[]) => mockSaveServerConfig(...a),
+  getServerUrl: (...a: unknown[]) => mockGetServerUrl(...a),
+  getProjectId: (...a: unknown[]) => mockGetProjectId(...a),
+  loadRegistry: (...a: unknown[]) => mockLoadRegistry(...a),
+  readPid: (...a: unknown[]) => mockReadPid(...a),
+  isDaemonRunning: (...a: unknown[]) => mockIsDaemonRunning(...a),
+  isPidAlive: (...a: unknown[]) => mockIsPidAlive(...a),
+  cleanStalePidFile: (...a: unknown[]) => mockCleanStalePidFile(...a),
+  resolveServerPaths: (...a: unknown[]) => mockResolveServerPaths(...a),
+  clearServerConfig: (...a: unknown[]) => mockClearServerConfig(...a),
+}));
+
+const mockUnlink = vi.fn().mockResolvedValue(undefined);
+vi.mock('node:fs/promises', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:fs/promises')>();
+  return { ...actual, unlink: mockUnlink };
+});
+
+vi.mock('../src/auth.js', () => ({ login: vi.fn() }));
+
+const mockStopDaemon = vi.fn().mockResolvedValue(undefined);
+const mockGetDaemonStatus = vi.fn();
+const mockIsRunningInProcess = vi.fn().mockReturnValue(false);
+const mockForkDaemon = vi.fn();
+vi.mock('../src/daemon.js', () => ({
+  startDaemon: vi.fn(),
+  stopDaemon: (...a: unknown[]) => mockStopDaemon(...a),
+  getDaemonStatus: (...a: unknown[]) => mockGetDaemonStatus(...a),
+  isRunningInProcess: (...a: unknown[]) => mockIsRunningInProcess(...a),
+  forkDaemon: (...a: unknown[]) => mockForkDaemon(...a),
+}));
+
+vi.mock('../src/service.js', () => ({
+  isServiceInstalled: vi.fn().mockResolvedValue(false),
+  installService: vi.fn().mockResolvedValue(undefined),
+}));
+vi.mock('../src/sync.js', () => ({
+  initialSync: vi.fn().mockResolvedValue(undefined),
+  createSnapshot: vi.fn().mockResolvedValue(true),
+}));
+vi.mock('../src/watcher.js', () => ({ getCurrentBranch: vi.fn().mockReturnValue('main') }));
+vi.mock('../src/logger.js', () => ({
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(), child: () => ({}) },
+  initMultistreamLogger: vi.fn(),
+}));
+
+const SERVER_URL = 'http://localhost:3000';
+const alice = {
+  apiKey: 'k-a',
+  userId: 'user-alice',
+  serverUrl: SERVER_URL,
+  email: 'alice@example.com',
+};
+const bob = { apiKey: 'k-b', userId: 'user-bob', serverUrl: SERVER_URL, email: 'bob@acme.io' };
+
+function config(overrides: Record<string, unknown> = {}) {
+  return { defaultAccount: 'user-alice', projectAccounts: {}, ...overrides };
+}
+
+const originalArgv = process.argv;
+let isTTYDescriptor: PropertyDescriptor | undefined;
+
+/** Drive cli.ts with a preset argv. */
+async function runCli(args: string[]): Promise<void> {
+  process.argv = ['node', 'cli.js', ...args];
+  vi.resetModules();
+  await import('../src/cli.js');
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  process.exitCode = 0;
+  isTTYDescriptor = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+
+  mockGetServerUrl.mockReturnValue(SERVER_URL);
+  mockLoadCredentials.mockResolvedValue(alice);
+  mockLoadAllCredentials.mockResolvedValue(
+    new Map([
+      ['user-alice', alice],
+      ['user-bob', bob],
+    ]),
+  );
+  mockLoadServerConfig.mockResolvedValue(config());
+  mockSaveServerConfig.mockResolvedValue(undefined);
+  mockLoadRegistry.mockResolvedValue({
+    projects: [{ path: '/home/user/projects/my-app', name: 'my-app' }],
+  });
+  mockGetProjectId.mockResolvedValue('proj-uuid');
+  mockResolveServerPaths.mockReturnValue({ accountsDir: '/tmp/accounts', logDir: '/tmp/logs' });
+  mockIsRunningInProcess.mockReturnValue(false);
+  mockReadPid.mockResolvedValue(null);
+  mockClearServerConfig.mockResolvedValue(undefined);
+  mockUnlink.mockResolvedValue(undefined);
+});
+
+afterEach(() => {
+  process.argv = originalArgv;
+  if (isTTYDescriptor) Object.defineProperty(process.stdin, 'isTTY', isTTYDescriptor);
+  process.exitCode = 0;
+});
+
+describe('cli — assign', () => {
+  it('writes the project→account mapping to config.json', async () => {
+    await runCli(['assign', 'my-app', 'bob']);
+    expect(mockSaveServerConfig).toHaveBeenCalledWith(
+      SERVER_URL,
+      expect.objectContaining({
+        projectAccounts: expect.objectContaining({ '/home/user/projects/my-app': 'user-bob' }),
+      }),
+    );
+  });
+});
+
+describe('cli — default', () => {
+  it('sets the default account', async () => {
+    await runCli(['default', 'bob']);
+    expect(mockSaveServerConfig).toHaveBeenCalledWith(
+      SERVER_URL,
+      expect.objectContaining({ defaultAccount: 'user-bob' }),
+    );
+  });
+});
+
+describe('cli — auto-assign', () => {
+  it('on → sets autoAssignNewProjects true', async () => {
+    await runCli(['auto-assign', 'on']);
+    expect(mockSaveServerConfig).toHaveBeenCalledWith(
+      SERVER_URL,
+      expect.objectContaining({ autoAssignNewProjects: true }),
+    );
+  });
+
+  it('off → sets autoAssignNewProjects false', async () => {
+    await runCli(['auto-assign', 'off']);
+    expect(mockSaveServerConfig).toHaveBeenCalledWith(
+      SERVER_URL,
+      expect.objectContaining({ autoAssignNewProjects: false }),
+    );
+  });
+});
+
+describe('cli — remove', () => {
+  it('deletes the account file and updates config', async () => {
+    await runCli(['remove', 'bob']);
+    expect(mockUnlink).toHaveBeenCalledWith(expect.stringContaining('user-bob.json'));
+    expect(mockSaveServerConfig).toHaveBeenCalled();
+  });
+
+  it('warns about orphaned projects', async () => {
+    mockLoadServerConfig.mockResolvedValue(
+      config({
+        projectAccounts: {
+          '/home/user/projects/work': 'user-bob',
+          '/home/user/projects/api': 'user-bob',
+        },
+      }),
+    );
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await runCli(['remove', 'bob']);
+      const output = logSpy.mock.calls.flat().join('\n');
+      expect(output).toMatch(/warn/i);
+      expect(output).toContain('2');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});
+
+describe('cli — accounts / projects (read)', () => {
+  it('accounts lists logged-in accounts', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    try {
+      await runCli(['accounts']);
+      const output = logSpy.mock.calls.flat().join('\n');
+      expect(output).toContain('alice@example.com');
+      expect(output).toContain('bob@acme.io');
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});
+
+describe('cli — reset', () => {
+  it('--yes wipes configuration', async () => {
+    await runCli(['reset', '--yes']);
+    expect(mockClearServerConfig).toHaveBeenCalledWith(SERVER_URL);
+  });
+
+  it('refuses (exit 1, no wipe) without --yes in a non-TTY', async () => {
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+    await runCli(['reset']);
+    expect(process.exitCode).toBe(1);
+    expect(mockClearServerConfig).not.toHaveBeenCalled();
+  });
+});

package/__tests__/config-registry.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+
+// These tests seed a real temp directory tree that mimics ~/.claude/projects/
+// and exercise loadRegistry against it via a mocked os.homedir().
+
+const mockHomedir = vi.fn<() => string>();
+const mockPlatform = vi.fn<() => NodeJS.Platform>().mockReturnValue('linux');
+
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>();
+  return {
+    ...actual,
+    homedir: () => mockHomedir(),
+    platform: () => mockPlatform(),
+  };
+});
+
+describe('config — loadRegistry path decoding', () => {
+  let tmpHome: string;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    tmpHome = await mkdtemp(join(tmpdir(), 'uc-registry-test-'));
+    mockHomedir.mockReturnValue(tmpHome);
+    mockPlatform.mockReturnValue('linux');
+  });
+
+  afterEach(async () => {
+    await rm(tmpHome, { recursive: true, force: true });
+  });
+
+  async function seedUltraProject(realPath: string, appContext?: string) {
+    await mkdir(join(realPath, '.claude', 'ultra'), { recursive: true });
+    await writeFile(join(realPath, '.claude', 'ultra', 'version.json'), '{}');
+    if (appContext) {
+      await writeFile(join(realPath, '.claude', 'ultra', 'app-context.md'), appContext);
+    }
+  }
+
+  async function seedSessionFile(encodedEntry: string, fileName: string, cwd: string) {
+    const entryDir = join(tmpHome, '.claude', 'projects', encodedEntry);
+    await mkdir(entryDir, { recursive: true });
+    const line = JSON.stringify({ type: 'user', cwd }) + '\n';
+    await writeFile(join(entryDir, fileName), line);
+    return join(entryDir, fileName);
+  }
+
+  // --- REPRODUCTION TEST ---
+  // Pre-patch: hyphen-permutation decoder cannot reinsert a space, so the
+  // entry is silently dropped and loadRegistry returns zero projects.
+  // Post-patch: session-file cwd lookup recovers the real path verbatim.
+  it('REPRODUCTION: resolves a path containing spaces via session cwd', async () => {
+    const realPath = join(tmpHome, 'Users', 'fake', 'WS LAB', 'proj');
+    await seedUltraProject(realPath);
+    await seedSessionFile('-Users-fake-WS-LAB-proj', 'session-abc.jsonl', realPath);
+
+    const { loadRegistry } = await import('../src/config.js');
+    const registry = await loadRegistry();
+
+    expect(registry.projects).toHaveLength(1);
+    expect(registry.projects[0]!.path).toBe(realPath);
+  });
+
+  it('falls back to legacy permutation when no session files exist', async () => {
+    // The legacy decoder searches from absolute `/` and has no knowledge of our
+    // mocked homedir. So to exercise the fallback safely we make tmpHome itself
+    // the "real project" — mkdtemp produces a real absolute path that is
+    // guaranteed to exist and is safe to put marker files under.
+    await seedUltraProject(tmpHome);
+    const encoded = tmpHome.replace(/\//g, '-'); // e.g. -tmp-uc-registry-test-XXXXXX
+    // Empty encoded entry — no .jsonl files → forces legacy fallback path
+    await mkdir(join(tmpHome, '.claude', 'projects', encoded), { recursive: true });
+
+    const { loadRegistry } = await import('../src/config.js');
+    const registry = await loadRegistry();
+
+    expect(registry.projects).toHaveLength(1);
+    expect(registry.projects[0]!.path).toBe(tmpHome);
+  });
+
+  it('reads project name from app-context.md', async () => {
+    const realPath = join(tmpHome, 'Users', 'alice', 'My Project');
+    await seedUltraProject(
+      realPath,
+      '# Context\n\n**Name:** Alice\'s Thing\n\nSome description.\n',
+    );
+    await seedSessionFile('-Users-alice-My-Project', 'session-1.jsonl', realPath);
+
+    const { loadRegistry } = await import('../src/config.js');
+    const registry = await loadRegistry();
+
+    expect(registry.projects).toHaveLength(1);
+    expect(registry.projects[0]!.name).toBe("Alice's Thing");
+  });
+
+  it('picks cwd from the newest session file when multiple exist', async () => {
+    const realPath = join(tmpHome, 'srv', 'app with spaces');
+    await seedUltraProject(realPath);
+    const encodedEntry = '-srv-app-with-spaces';
+
+    // Older session — points at a stale, non-existent path
+    const older = await seedSessionFile(encodedEntry, 'session-old.jsonl', '/tmp/does-not-exist');
+    // Force older mtime
+    const past = new Date(Date.now() - 60_000);
+    await utimes(older, past, past);
+
+    // Newer session — points at the real path
+    await seedSessionFile(encodedEntry, 'session-new.jsonl', realPath);
+
+    const { loadRegistry } = await import('../src/config.js');
+    const registry = await loadRegistry();
+
+    expect(registry.projects).toHaveLength(1);
+    expect(registry.projects[0]!.path).toBe(realPath);
+  });
+
+  it('drops entries whose resolved cwd has no .claude/ultra/version.json', async () => {
+    const realPath = join(tmpHome, 'not', 'ultra', 'project');
+    await mkdir(realPath, { recursive: true }); // exists, but no marker
+    await seedSessionFile('-not-ultra-project', 'session-1.jsonl', realPath);
+
+    const { loadRegistry } = await import('../src/config.js');
+    const registry = await loadRegistry();
+
+    expect(registry.projects).toHaveLength(0);
+  });
+});

package/__tests__/matching.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Tests for the shared fuzzy matchers (src/matching.ts).
+ * Pure module — no mocks needed. Both command surfaces consume these via the registry.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { matchProject, matchAccount, accountDisplay } from '../src/matching.js';
+import type { AgentCredentials, ProjectRegistryEntry } from '@ultra-claude/shared';
+
+function project(path: string): ProjectRegistryEntry {
+  return { path, name: path.split('/').pop()! };
+}
+
+function account(overrides: Partial<AgentCredentials> = {}): AgentCredentials {
+  return {
+    apiKey: 'key',
+    userId: 'user-x',
+    serverUrl: 'http://localhost:3000',
+    email: 'x@example.com',
+    ...overrides,
+  };
+}
+
+describe('matchProject', () => {
+  const projects = [
+    project('/home/user/projects/my-app'),
+    project('/home/user/projects/my-api'),
+    project('/home/user/projects/website'),
+  ];
+
+  it('matches an exact basename', () => {
+    const r = matchProject('website', projects);
+    expect(r.error).toBeNull();
+    expect(r.match?.path).toBe('/home/user/projects/website');
+  });
+
+  it('matches a unique prefix', () => {
+    const r = matchProject('webs', projects);
+    expect(r.error).toBeNull();
+    expect(r.match?.path).toBe('/home/user/projects/website');
+  });
+
+  it('matches a unique substring (includes)', () => {
+    const r = matchProject('bsit', projects);
+    expect(r.error).toBeNull();
+    expect(r.match?.path).toBe('/home/user/projects/website');
+  });
+
+  it('reports no match', () => {
+    const r = matchProject('nonexistent', projects);
+    expect(r.match).toBeNull();
+    expect(r.error).toMatch(/no project matching/i);
+  });
+
+  it('reports ambiguity when multiple projects match', () => {
+    const r = matchProject('my-a', projects);
+    expect(r.match).toBeNull();
+    expect(r.error).toMatch(/ambiguous/i);
+    expect(r.error).toContain('my-app');
+    expect(r.error).toContain('my-api');
+  });
+
+  it('prefers an exact basename over a broader prefix collision', () => {
+    const withExact = [project('/a/my'), project('/b/my-app')];
+    const r = matchProject('my', withExact);
+    expect(r.error).toBeNull();
+    expect(r.match?.path).toBe('/a/my');
+  });
+
+  it('is case-insensitive', () => {
+    const r = matchProject('WEBSITE', projects);
+    expect(r.match?.path).toBe('/home/user/projects/website');
+  });
+});
+
+describe('matchAccount', () => {
+  const alice = account({ userId: 'user-alice', email: 'alice@example.com' });
+  const bob = account({ userId: 'user-bob', email: 'bob@acme.io' });
+  const accounts = new Map([
+    ['user-alice', alice],
+    ['user-bob', bob],
+  ]);
+
+  it('matches an exact email', () => {
+    const r = matchAccount('bob@acme.io', accounts);
+    expect(r.error).toBeNull();
+    expect(r.match?.userId).toBe('user-bob');
+  });
+
+  it('matches an exact userId', () => {
+    const r = matchAccount('user-alice', accounts);
+    expect(r.error).toBeNull();
+    expect(r.match?.userId).toBe('user-alice');
+  });
+
+  it('matches an email prefix (before @)', () => {
+    const r = matchAccount('bob', accounts);
+    expect(r.error).toBeNull();
+    expect(r.match?.userId).toBe('user-bob');
+  });
+
+  it('matches an email startsWith', () => {
+    const r = matchAccount('ali', accounts);
+    expect(r.error).toBeNull();
+    expect(r.match?.userId).toBe('user-alice');
+  });
+
+  it('is case-insensitive', () => {
+    const r = matchAccount('ALICE@EXAMPLE.COM', accounts);
+    expect(r.match?.userId).toBe('user-alice');
+  });
+
+  it('reports when there are no accounts', () => {
+    const r = matchAccount('anyone', new Map());
+    expect(r.match).toBeNull();
+    expect(r.error).toMatch(/no accounts found/i);
+  });
+
+  it('reports no match when query matches nothing', () => {
+    const r = matchAccount('charlie', accounts);
+    expect(r.match).toBeNull();
+    expect(r.error).toMatch(/no account matching/i);
+  });
+
+  it('reports ambiguity (richer logic preserved from the REPL)', () => {
+    const a1 = account({ userId: 'user-1', email: 'sam@one.com' });
+    const a2 = account({ userId: 'user-2', email: 'sam@two.com' });
+    const ambiguous = new Map([
+      ['user-1', a1],
+      ['user-2', a2],
+    ]);
+    const r = matchAccount('sam', ambiguous);
+    expect(r.match).toBeNull();
+    expect(r.error).toMatch(/ambiguous/i);
+    expect(r.error).toContain('sam@one.com');
+    expect(r.error).toContain('sam@two.com');
+  });
+
+  it('matches by userId when email is absent', () => {
+    const noEmail = account({ userId: 'user-keyonly', email: undefined });
+    const r = matchAccount('user-keyonly', new Map([['user-keyonly', noEmail]]));
+    expect(r.match?.userId).toBe('user-keyonly');
+  });
+});
+
+describe('accountDisplay', () => {
+  it('prefers email', () => {
+    expect(accountDisplay(account({ email: 'a@b.com', userId: 'u' }))).toBe('a@b.com');
+  });
+
+  it('falls back to userId when email is absent', () => {
+    expect(accountDisplay(account({ email: undefined, userId: 'user-x' }))).toBe('user-x');
+  });
+});

package/__tests__/registry.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Tests for the shared command registry (src/commands/registry.ts).
+ * Verifies the single source of truth that both surfaces are generated from:
+ *  - every command declares the required fields + a surface-agnostic run(ctx)
+ *  - surfaces/interaction markers are honoured (quit/exit REPL-only; setup/logs/version CLI-only)
+ *  - parity: account commands appear in BOTH surfaces (define once → both surfaces expose it)
+ *  - generated help + signatures
+ *
+ * Heavy src deps are mocked so importing the registry is side-effect free; only metadata
+ * (and one trivial handler) are exercised here.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('../src/config.js', () => ({
+  loadAllCredentials: vi.fn(),
+  loadCredentials: vi.fn(),
+  loadServerConfig: vi.fn(),
+  saveServerConfig: vi.fn(),
+  getServerUrl: vi.fn(),
+  getProjectId: vi.fn(),
+  loadRegistry: vi.fn(),
+  readPid: vi.fn(),
+  isDaemonRunning: vi.fn(),
+  isPidAlive: vi.fn(),
+  cleanStalePidFile: vi.fn(),
+  resolveServerPaths: vi.fn(),
+  clearServerConfig: vi.fn(),
+}));
+vi.mock('../src/auth.js', () => ({ login: vi.fn() }));
+vi.mock('../src/daemon.js', () => ({
+  startDaemon: vi.fn(),
+  stopDaemon: vi.fn(),
+  getDaemonStatus: vi.fn(),
+  isRunningInProcess: vi.fn(),
+  forkDaemon: vi.fn(),
+}));
+vi.mock('../src/service.js', () => ({ isServiceInstalled: vi.fn(), installService: vi.fn() }));
+vi.mock('../src/sync.js', () => ({ initialSync: vi.fn(), createSnapshot: vi.fn() }));
+vi.mock('../src/watcher.js', () => ({ getCurrentBranch: vi.fn() }));
+vi.mock('../src/logger.js', () => ({
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(), child: () => ({}) },
+  initMultistreamLogger: vi.fn(),
+}));
+
+import { commands, commandSignature, formatReplHelp, type IO } from '../src/commands/registry.js';
+
+const INTERACTIONS = new Set(['none', 'browser', 'wizard', 'confirm']);
+const SURFACES = new Set(['cli', 'repl']);
+
+function names(surface: 'cli' | 'repl'): string[] {
+  return commands.filter((d) => d.surfaces.includes(surface)).map((d) => d.name);
+}
+
+describe('registry — command shape', () => {
+  it('every command declares the required fields and a run function', () => {
+    for (const def of commands) {
+      expect(typeof def.name).toBe('string');
+      expect(def.name.length).toBeGreaterThan(0);
+      expect(typeof def.summary).toBe('string');
+      expect(Array.isArray(def.args)).toBe(true);
+      expect(Array.isArray(def.surfaces)).toBe(true);
+      expect(def.surfaces.length).toBeGreaterThan(0);
+      for (const s of def.surfaces) expect(SURFACES.has(s)).toBe(true);
+      expect(INTERACTIONS.has(def.interaction)).toBe(true);
+      expect(typeof def.run).toBe('function');
+    }
+  });
+
+  it('command names are unique', () => {
+    const seen = new Set<string>();
+    for (const def of commands) {
+      expect(seen.has(def.name)).toBe(false);
+      seen.add(def.name);
+    }
+  });
+
+  it('declared positionals are well-formed (variadic only last)', () => {
+    for (const def of commands) {
+      def.args.forEach((arg, idx) => {
+        expect(typeof arg.name).toBe('string');
+        expect(typeof arg.required).toBe('boolean');
+        if (arg.variadic) expect(idx).toBe(def.args.length - 1);
+      });
+    }
+  });
+});
+
+describe('registry — surfaces and interaction markers', () => {
+  it('quit/exit are REPL-only and absent from the CLI surface', () => {
+    expect(names('repl')).toEqual(expect.arrayContaining(['quit', 'exit']));
+    expect(names('cli')).not.toContain('quit');
+    expect(names('cli')).not.toContain('exit');
+  });
+
+  it('help is REPL-only', () => {
+    expect(names('repl')).toContain('help');
+    expect(names('cli')).not.toContain('help');
+  });
+
+  it('setup, logs, version are CLI-only', () => {
+    for (const name of ['setup', 'logs', 'version']) {
+      expect(names('cli')).toContain(name);
+      expect(names('repl')).not.toContain(name);
+    }
+  });
+
+  it('login is browser, setup is wizard, reset is confirm, account commands are none', () => {
+    const byName = Object.fromEntries(commands.map((d) => [d.name, d]));
+    expect(byName.login!.interaction).toBe('browser');
+    expect(byName.setup!.interaction).toBe('wizard');
+    expect(byName.reset!.interaction).toBe('confirm');
+    for (const name of ['accounts', 'projects', 'assign', 'default', 'auto-assign', 'remove']) {
+      expect(byName[name]!.interaction).toBe('none');
+    }
+  });
+
+  it('reset declares a --yes option', () => {
+    const reset = commands.find((d) => d.name === 'reset')!;
+    expect((reset.options ?? []).some((o) => o.flags.includes('--yes'))).toBe(true);
+  });
+});
+
+describe('registry — parity (define once → both surfaces)', () => {
+  it('account-routing commands appear in BOTH surfaces', () => {
+    const both = new Set(names('cli').filter((n) => names('repl').includes(n)));
+    for (const name of [
+      'accounts',
+      'projects',
+      'assign',
+      'default',
+      'auto-assign',
+      'remove',
+      'reset',
+    ]) {
+      expect(both.has(name)).toBe(true);
+    }
+  });
+});
+
+describe('registry — generated signatures and help', () => {
+  it('renders positional signatures', () => {
+    const byName = Object.fromEntries(commands.map((d) => [d.name, d]));
+    expect(commandSignature(byName.assign!)).toBe('assign <project> <account>');
+    expect(commandSignature(byName['auto-assign']!)).toBe('auto-assign <on|off>');
+    expect(commandSignature(byName.snapshot!)).toBe('snapshot <project> [label...]');
+    expect(commandSignature(byName.accounts!)).toBe('accounts');
+  });
+
+  it('formatReplHelp lists repl-surface commands only', () => {
+    const help = formatReplHelp();
+    expect(help).toContain('accounts');
+    expect(help).toContain('assign');
+    expect(help).toContain('reset');
+    expect(help).toContain('quit');
+    // CLI-only commands are not in the REPL help
+    expect(help).not.toContain('setup');
+    expect(help).not.toContain('logs');
+  });
+});
+
+describe('registry — handlers are surface-agnostic (use ctx.io)', () => {
+  it('version handler prints via io, not console', async () => {
+    const printed: string[] = [];
+    const io: IO = { print: (m) => printed.push(m), error: vi.fn(), confirm: vi.fn() };
+    const version = commands.find((d) => d.name === 'version')!;
+    await version.run({ serverUrl: 'http://x', positionals: [], flags: {}, io });
+    expect(printed).toHaveLength(1);
+    expect(printed[0]).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});