@quenty/studio-bridge 0.7.0 → 0.8.0

package/dist/src/cli/adapters/group-builder.test.js

@@ -0,0 +1,108 @@
+/**
+ * Unit tests for the group builder.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { buildGroupCommands } from './group-builder.js';
+import { CommandRegistry } from '../../commands/framework/command-registry.js';
+import { defineCommand } from '../../commands/framework/define-command.js';
+import { arg } from '../../commands/framework/arg-builder.js';
+function makeRegistry() {
+    const registry = new CommandRegistry();
+    registry.register(defineCommand({
+        group: 'console',
+        name: 'exec',
+        description: 'Execute code',
+        category: 'execution',
+        safety: 'mutate',
+        scope: 'session',
+        args: { code: arg.positional({ description: 'Code' }) },
+        handler: async () => ({}),
+    }));
+    registry.register(defineCommand({
+        group: 'console',
+        name: 'logs',
+        description: 'View logs',
+        category: 'execution',
+        safety: 'read',
+        scope: 'session',
+        args: {},
+        handler: async () => ({}),
+    }));
+    registry.register(defineCommand({
+        group: 'process',
+        name: 'list',
+        description: 'List sessions',
+        category: 'infrastructure',
+        safety: 'read',
+        scope: 'connection',
+        args: {},
+        handler: async () => ({}),
+    }));
+    registry.register(defineCommand({
+        group: null,
+        name: 'serve',
+        description: 'Start server',
+        category: 'infrastructure',
+        safety: 'none',
+        scope: 'standalone',
+        args: {},
+        handler: async () => ({}),
+    }));
+    return registry;
+}
+function createMockYargs() {
+    const commands = [];
+    const mock = {
+        commands,
+        command: vi.fn((cmd) => {
+            commands.push(cmd);
+            return mock;
+        }),
+        demandCommand: vi.fn(() => mock),
+    };
+    return mock;
+}
+describe('buildGroupCommands', () => {
+    it('creates a group command for each unique group', () => {
+        const registry = makeRegistry();
+        const result = buildGroupCommands(registry);
+        expect(result.groups).toHaveLength(2);
+        const groupNames = result.groups.map((g) => g.command.split(' ')[0]);
+        expect(groupNames).toContain('console');
+        expect(groupNames).toContain('process');
+    });
+    it('creates top-level commands for null-group definitions', () => {
+        const registry = makeRegistry();
+        const result = buildGroupCommands(registry);
+        expect(result.topLevel).toHaveLength(1);
+        expect(result.topLevel[0].command).toBe('serve');
+    });
+    it('group commands use <command> suffix', () => {
+        const registry = makeRegistry();
+        const result = buildGroupCommands(registry);
+        const consoleMod = result.groups.find((g) => g.command.startsWith('console'));
+        expect(consoleMod.command).toBe('console <command>');
+    });
+    it('group commands have descriptions', () => {
+        const registry = makeRegistry();
+        const result = buildGroupCommands(registry);
+        const consoleMod = result.groups.find((g) => g.command.startsWith('console'));
+        expect(consoleMod.describe).toBe('Execute code and view logs');
+    });
+    it('group builder registers subcommands', () => {
+        const registry = makeRegistry();
+        const result = buildGroupCommands(registry);
+        const consoleMod = result.groups.find((g) => g.command.startsWith('console'));
+        const yargs = createMockYargs();
+        consoleMod.builder(yargs);
+        // Should register 2 subcommands (exec, logs)
+        expect(yargs.commands).toHaveLength(2);
+    });
+    it('returns empty arrays for empty registry', () => {
+        const registry = new CommandRegistry();
+        const result = buildGroupCommands(registry);
+        expect(result.groups).toEqual([]);
+        expect(result.topLevel).toEqual([]);
+    });
+});
+//# sourceMappingURL=group-builder.test.js.map

package/dist/src/cli/adapters/group-builder.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-builder.test.js","sourceRoot":"","sources":["../../../../src/cli/adapters/group-builder.test.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/adapters/help-formatter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Custom help formatter that groups commands into "Execution" and
+ * "Infrastructure" categories, matching the target CLI layout.
+ */
+import type { CommandRegistry } from '../../commands/framework/command-registry.js';
+/**
+ * Format a categorized help string from the command registry.
+ * Groups are listed under their category with aligned descriptions.
+ */
+export declare function formatGroupedHelp(registry: CommandRegistry): string;
+//# sourceMappingURL=help-formatter.d.ts.map

package/dist/src/cli/adapters/help-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatter.d.ts","sourceRoot":"","sources":["../../../../src/cli/adapters/help-formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8CAA8C,CAAC;AAcpF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAyDnE"}

package/dist/src/cli/adapters/help-formatter.js

@@ -0,0 +1,78 @@
+/**
+ * Custom help formatter that groups commands into "Execution" and
+ * "Infrastructure" categories, matching the target CLI layout.
+ */
+const GROUP_DESCRIPTIONS = {
+    console: 'Execute code and view logs',
+    explorer: 'Query and modify the DataModel',
+    properties: 'Read and write instance properties',
+    viewport: 'Screenshots and camera control',
+    data: 'Load and save serialized data',
+    playtest: 'Control play test sessions',
+    process: 'Manage Studio processes',
+    plugin: 'Manage the bridge plugin',
+    action: 'Invoke a Studio action',
+};
+/**
+ * Format a categorized help string from the command registry.
+ * Groups are listed under their category with aligned descriptions.
+ */
+export function formatGroupedHelp(registry) {
+    const lines = [];
+    lines.push('studio-bridge <command> [options]');
+    lines.push('');
+    // Collect unique groups per category
+    const executionGroups = new Set();
+    const infrastructureGroups = new Set();
+    const executionTopLevel = [];
+    const infrastructureTopLevel = [];
+    for (const cmd of registry.getAll()) {
+        if (cmd.group !== null) {
+            if (cmd.category === 'execution') {
+                executionGroups.add(cmd.group);
+            }
+            else {
+                infrastructureGroups.add(cmd.group);
+            }
+        }
+        else {
+            const entry = { name: cmd.name, description: cmd.description };
+            if (cmd.category === 'execution') {
+                executionTopLevel.push(entry);
+            }
+            else {
+                infrastructureTopLevel.push(entry);
+            }
+        }
+    }
+    // Execution section
+    if (executionGroups.size > 0 || executionTopLevel.length > 0) {
+        lines.push('Execution:');
+        for (const group of executionGroups) {
+            const desc = GROUP_DESCRIPTIONS[group] ?? '';
+            lines.push(formatLine(`${group} <command>`, desc));
+        }
+        for (const cmd of executionTopLevel) {
+            lines.push(formatLine(cmd.name, cmd.description));
+        }
+        lines.push('');
+    }
+    // Infrastructure section
+    if (infrastructureGroups.size > 0 || infrastructureTopLevel.length > 0) {
+        lines.push('Infrastructure:');
+        for (const group of infrastructureGroups) {
+            const desc = GROUP_DESCRIPTIONS[group] ?? '';
+            lines.push(formatLine(`${group} <command>`, desc));
+        }
+        for (const cmd of infrastructureTopLevel) {
+            lines.push(formatLine(cmd.name, cmd.description));
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function formatLine(label, description) {
+    const padding = Math.max(2, 22 - label.length);
+    return `  ${label}${' '.repeat(padding)}${description}`;
+}
+//# sourceMappingURL=help-formatter.js.map

package/dist/src/cli/adapters/help-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatter.js","sourceRoot":"","sources":["../../../../src/cli/adapters/help-formatter.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/adapters/help-formatter.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the help formatter.
+ */
+export {};
+//# sourceMappingURL=help-formatter.test.d.ts.map

package/dist/src/cli/adapters/help-formatter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatter.test.d.ts","sourceRoot":"","sources":["../../../../src/cli/adapters/help-formatter.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/cli/adapters/help-formatter.test.js

@@ -0,0 +1,79 @@
+/**
+ * Unit tests for the help formatter.
+ */
+import { describe, it, expect } from 'vitest';
+import { formatGroupedHelp } from './help-formatter.js';
+import { CommandRegistry } from '../../commands/framework/command-registry.js';
+import { defineCommand } from '../../commands/framework/define-command.js';
+function makeRegistry() {
+    const registry = new CommandRegistry();
+    registry.register(defineCommand({
+        group: 'console',
+        name: 'exec',
+        description: 'Execute code',
+        category: 'execution',
+        safety: 'mutate',
+        scope: 'session',
+        args: {},
+        handler: async () => ({}),
+    }));
+    registry.register(defineCommand({
+        group: 'process',
+        name: 'list',
+        description: 'List sessions',
+        category: 'infrastructure',
+        safety: 'read',
+        scope: 'connection',
+        args: {},
+        handler: async () => ({}),
+    }));
+    registry.register(defineCommand({
+        group: null,
+        name: 'serve',
+        description: 'Start the bridge server',
+        category: 'infrastructure',
+        safety: 'none',
+        scope: 'standalone',
+        args: {},
+        handler: async () => ({}),
+    }));
+    return registry;
+}
+describe('formatGroupedHelp', () => {
+    it('includes Execution header', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        expect(help).toContain('Execution:');
+    });
+    it('includes Infrastructure header', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        expect(help).toContain('Infrastructure:');
+    });
+    it('lists execution groups under Execution', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        const executionSection = help.split('Infrastructure:')[0];
+        expect(executionSection).toContain('console <command>');
+    });
+    it('lists infrastructure groups under Infrastructure', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        const infraSection = help.split('Infrastructure:')[1];
+        expect(infraSection).toContain('process <command>');
+    });
+    it('lists top-level infrastructure commands', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        const infraSection = help.split('Infrastructure:')[1];
+        expect(infraSection).toContain('serve');
+        expect(infraSection).toContain('Start the bridge server');
+    });
+    it('includes group descriptions', () => {
+        const help = formatGroupedHelp(makeRegistry());
+        expect(help).toContain('Execute code and view logs');
+        expect(help).toContain('Manage Studio processes');
+    });
+    it('returns empty for empty registry', () => {
+        const help = formatGroupedHelp(new CommandRegistry());
+        expect(help).toContain('studio-bridge <command>');
+        expect(help).not.toContain('Execution:');
+        expect(help).not.toContain('Infrastructure:');
+    });
+});
+//# sourceMappingURL=help-formatter.test.js.map

package/dist/src/cli/adapters/help-formatter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatter.test.js","sourceRoot":"","sources":["../../../../src/cli/adapters/help-formatter.test.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/adapters/target-resolver.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Unified target resolution for the `--target` flag.
+ *
+ * Replaces the old `--session`/`--instance` system with a single
+ * `--target` option that supports:
+ *
+ *   - Explicit ID: `--target <sessionId>`
+ *   - All sessions: `--target all`
+ *   - Auto-resolve: omit `--target` → single session auto-selects
+ *
+ * Behavior varies by safety classification:
+ *   - `read`   CLI: aggregate all sessions (no target required)
+ *   - `mutate`  CLI: auto-resolve if 1, prompt/error if multiple
+ *   - `none`:   no targeting needed
+ *   - MCP:      always require explicit target, error with session list
+ */
+import type { BridgeConnection } from '../../bridge/index.js';
+import type { BridgeSession, SessionContext, SessionInfo } from '../../bridge/index.js';
+import type { CommandSafety } from '../../commands/framework/define-command.js';
+export interface TargetResolveOptions {
+    /** Explicit target from `--target` flag. */
+    target?: string;
+    /** Context filter from `--context` flag. */
+    context?: SessionContext;
+    /** Safety classification of the command. */
+    safety: CommandSafety;
+    /** Whether this is an MCP invocation (stricter targeting). */
+    isMcp?: boolean;
+}
+/** Successful resolution — one or more sessions. */
+export interface TargetResolved {
+    sessions: BridgeSession[];
+}
+/** Structured error when target cannot be resolved. */
+export interface MultipleSessionsError {
+    error: 'multiple_sessions';
+    hint: string;
+    sessions: SessionInfo[];
+}
+/**
+ * Resolve target session(s) from a `BridgeConnection` based on the
+ * `--target` flag, safety classification, and invocation context.
+ *
+ * @throws {Error} When no sessions match or when multiple sessions
+ *   exist and the command requires an explicit target.
+ */
+export declare function resolveTargetAsync(connection: BridgeConnection, options: TargetResolveOptions): Promise<TargetResolved>;
+export declare class TargetRequiredError extends Error {
+    readonly sessions: SessionInfo[];
+    constructor(sessions: SessionInfo[]);
+    /** Structured error payload for non-interactive / MCP responses. */
+    toStructuredError(): MultipleSessionsError;
+}
+//# sourceMappingURL=target-resolver.d.ts.map

package/dist/src/cli/adapters/target-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-resolver.d.ts","sourceRoot":"","sources":["../../../../src/cli/adapters/target-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAEhF,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,4CAA4C;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAmDzB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,QAAQ,EAAE,WAAW,EAAE,CAAC;gBAE5B,QAAQ,EAAE,WAAW,EAAE;IAUnC,oEAAoE;IACpE,iBAAiB,IAAI,qBAAqB;CAO3C"}

package/dist/src/cli/adapters/target-resolver.js

@@ -0,0 +1,90 @@
+/**
+ * Unified target resolution for the `--target` flag.
+ *
+ * Replaces the old `--session`/`--instance` system with a single
+ * `--target` option that supports:
+ *
+ *   - Explicit ID: `--target <sessionId>`
+ *   - All sessions: `--target all`
+ *   - Auto-resolve: omit `--target` → single session auto-selects
+ *
+ * Behavior varies by safety classification:
+ *   - `read`   CLI: aggregate all sessions (no target required)
+ *   - `mutate`  CLI: auto-resolve if 1, prompt/error if multiple
+ *   - `none`:   no targeting needed
+ *   - MCP:      always require explicit target, error with session list
+ */
+/**
+ * Resolve target session(s) from a `BridgeConnection` based on the
+ * `--target` flag, safety classification, and invocation context.
+ *
+ * @throws {Error} When no sessions match or when multiple sessions
+ *   exist and the command requires an explicit target.
+ */
+export async function resolveTargetAsync(connection, options) {
+    const { target, context, safety, isMcp } = options;
+    // Explicit target
+    if (target && target !== 'all') {
+        const session = await connection.resolveSessionAsync(target, context);
+        return { sessions: [session] };
+    }
+    // --target all: broadcast to all matching sessions
+    if (target === 'all') {
+        const sessions = filterSessions(connection, context);
+        if (sessions.length === 0) {
+            throw new Error('No sessions connected. Is Studio running with the studio-bridge plugin?');
+        }
+        return {
+            sessions: sessions.map((info) => connection.getSession(info.sessionId)),
+        };
+    }
+    // No explicit target — behavior depends on safety and context
+    const sessions = filterSessions(connection, context);
+    if (sessions.length === 0) {
+        throw new Error('No sessions connected. Is Studio running with the studio-bridge plugin?');
+    }
+    // MCP always requires explicit target when multiple sessions exist
+    if (isMcp && sessions.length > 1) {
+        throw new TargetRequiredError(sessions);
+    }
+    // CLI read commands: aggregate all sessions
+    if (safety === 'read' && !isMcp) {
+        return {
+            sessions: sessions.map((info) => connection.getSession(info.sessionId)),
+        };
+    }
+    // Single session: auto-resolve
+    if (sessions.length === 1) {
+        const session = connection.getSession(sessions[0].sessionId);
+        return { sessions: [session] };
+    }
+    // Multiple sessions + mutate: require explicit target
+    throw new TargetRequiredError(sessions);
+}
+export class TargetRequiredError extends Error {
+    sessions;
+    constructor(sessions) {
+        const listing = sessions
+            .map((s) => `  - ${s.sessionId} (${s.placeName}, context=${s.context})`)
+            .join('\n');
+        super(`Multiple sessions connected. Specify --target <id>:\n${listing}`);
+        this.name = 'TargetRequiredError';
+        this.sessions = sessions;
+    }
+    /** Structured error payload for non-interactive / MCP responses. */
+    toStructuredError() {
+        return {
+            error: 'multiple_sessions',
+            hint: 'Specify --target <id>',
+            sessions: this.sessions,
+        };
+    }
+}
+function filterSessions(connection, context) {
+    let sessions = connection.listSessions();
+    if (context) {
+        sessions = sessions.filter((s) => s.context === context);
+    }
+    return sessions;
+}
+//# sourceMappingURL=target-resolver.js.map

package/dist/src/cli/adapters/target-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-resolver.js","sourceRoot":"","sources":["../../../../src/cli/adapters/target-resolver.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/adapters/target-resolver.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Unit tests for the target resolver.
+ */
+export {};
+//# sourceMappingURL=target-resolver.test.d.ts.map

package/dist/src/cli/adapters/target-resolver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-resolver.test.d.ts","sourceRoot":"","sources":["../../../../src/cli/adapters/target-resolver.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/cli/adapters/target-resolver.test.js

@@ -0,0 +1,169 @@
+/**
+ * Unit tests for the target resolver.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { resolveTargetAsync, TargetRequiredError } from './target-resolver.js';
+function mockSessionInfo(overrides = {}) {
+    return {
+        sessionId: overrides.sessionId ?? 'sess-1',
+        placeName: overrides.placeName ?? 'TestPlace',
+        state: 'Edit',
+        pluginVersion: '1.0.0',
+        capabilities: [],
+        connectedAt: new Date(),
+        origin: 'user',
+        context: overrides.context ?? 'edit',
+        instanceId: overrides.instanceId ?? 'inst-1',
+        placeId: overrides.placeId ?? 123,
+        gameId: overrides.gameId ?? 456,
+    };
+}
+function mockConnection(sessions = []) {
+    const sessionMap = new Map(sessions.map((s) => [s.sessionId, s]));
+    return {
+        listSessions: vi.fn().mockReturnValue(sessions),
+        getSession: vi.fn((id) => sessionMap.get(id)),
+        resolveSessionAsync: vi.fn(async (id) => {
+            const info = sessionMap.get(id);
+            if (!info)
+                throw new Error(`Session '${id}' not found`);
+            return info;
+        }),
+    };
+}
+describe('resolveTargetAsync', () => {
+    describe('explicit --target', () => {
+        it('resolves a specific session by ID', async () => {
+            const sess = mockSessionInfo({ sessionId: 'abc-123' });
+            const conn = mockConnection([sess]);
+            const result = await resolveTargetAsync(conn, {
+                target: 'abc-123',
+                safety: 'mutate',
+            });
+            expect(result.sessions).toHaveLength(1);
+            expect(conn.resolveSessionAsync).toHaveBeenCalledWith('abc-123', undefined);
+        });
+        it('passes context to resolveSessionAsync', async () => {
+            const sess = mockSessionInfo({ sessionId: 'abc-123' });
+            const conn = mockConnection([sess]);
+            await resolveTargetAsync(conn, {
+                target: 'abc-123',
+                context: 'edit',
+                safety: 'mutate',
+            });
+            expect(conn.resolveSessionAsync).toHaveBeenCalledWith('abc-123', 'edit');
+        });
+        it('throws when session ID not found', async () => {
+            const conn = mockConnection([]);
+            await expect(resolveTargetAsync(conn, {
+                target: 'nonexistent',
+                safety: 'mutate',
+            })).rejects.toThrow('not found');
+        });
+    });
+    describe('--target all', () => {
+        it('returns all sessions', async () => {
+            const sess1 = mockSessionInfo({ sessionId: 'a' });
+            const sess2 = mockSessionInfo({ sessionId: 'b' });
+            const conn = mockConnection([sess1, sess2]);
+            const result = await resolveTargetAsync(conn, {
+                target: 'all',
+                safety: 'read',
+            });
+            expect(result.sessions).toHaveLength(2);
+        });
+        it('filters by context when provided', async () => {
+            const edit = mockSessionInfo({ sessionId: 'a', context: 'edit' });
+            const server = mockSessionInfo({ sessionId: 'b', context: 'server' });
+            const conn = mockConnection([edit, server]);
+            const result = await resolveTargetAsync(conn, {
+                target: 'all',
+                context: 'edit',
+                safety: 'read',
+            });
+            expect(result.sessions).toHaveLength(1);
+        });
+        it('throws when no sessions available', async () => {
+            const conn = mockConnection([]);
+            await expect(resolveTargetAsync(conn, {
+                target: 'all',
+                safety: 'read',
+            })).rejects.toThrow('No sessions connected');
+        });
+    });
+    describe('auto-resolve', () => {
+        it('auto-selects when exactly one session', async () => {
+            const sess = mockSessionInfo({ sessionId: 'only-one' });
+            const conn = mockConnection([sess]);
+            const result = await resolveTargetAsync(conn, {
+                safety: 'mutate',
+            });
+            expect(result.sessions).toHaveLength(1);
+        });
+        it('throws TargetRequiredError for mutate with multiple sessions', async () => {
+            const sess1 = mockSessionInfo({ sessionId: 'a' });
+            const sess2 = mockSessionInfo({ sessionId: 'b' });
+            const conn = mockConnection([sess1, sess2]);
+            await expect(resolveTargetAsync(conn, { safety: 'mutate' })).rejects.toThrow(TargetRequiredError);
+        });
+        it('aggregates all sessions for read safety on CLI', async () => {
+            const sess1 = mockSessionInfo({ sessionId: 'a' });
+            const sess2 = mockSessionInfo({ sessionId: 'b' });
+            const conn = mockConnection([sess1, sess2]);
+            const result = await resolveTargetAsync(conn, {
+                safety: 'read',
+                isMcp: false,
+            });
+            expect(result.sessions).toHaveLength(2);
+        });
+        it('throws when no sessions available', async () => {
+            const conn = mockConnection([]);
+            await expect(resolveTargetAsync(conn, { safety: 'read' })).rejects.toThrow('No sessions connected');
+        });
+    });
+    describe('MCP targeting', () => {
+        it('throws TargetRequiredError when multiple sessions and isMcp', async () => {
+            const sess1 = mockSessionInfo({ sessionId: 'a' });
+            const sess2 = mockSessionInfo({ sessionId: 'b' });
+            const conn = mockConnection([sess1, sess2]);
+            await expect(resolveTargetAsync(conn, {
+                safety: 'read',
+                isMcp: true,
+            })).rejects.toThrow(TargetRequiredError);
+        });
+        it('auto-selects single session even in MCP mode', async () => {
+            const sess = mockSessionInfo({ sessionId: 'only' });
+            const conn = mockConnection([sess]);
+            const result = await resolveTargetAsync(conn, {
+                safety: 'read',
+                isMcp: true,
+            });
+            expect(result.sessions).toHaveLength(1);
+        });
+    });
+});
+describe('TargetRequiredError', () => {
+    it('includes session listing in message', () => {
+        const sessions = [
+            mockSessionInfo({ sessionId: 'a', placeName: 'Place A' }),
+            mockSessionInfo({ sessionId: 'b', placeName: 'Place B' }),
+        ];
+        const err = new TargetRequiredError(sessions);
+        expect(err.message).toContain('Multiple sessions');
+        expect(err.message).toContain('a');
+        expect(err.message).toContain('b');
+    });
+    it('provides structured error payload', () => {
+        const sessions = [mockSessionInfo({ sessionId: 'a' })];
+        const err = new TargetRequiredError(sessions);
+        const structured = err.toStructuredError();
+        expect(structured.error).toBe('multiple_sessions');
+        expect(structured.hint).toContain('--target');
+        expect(structured.sessions).toHaveLength(1);
+    });
+    it('has correct name', () => {
+        const err = new TargetRequiredError([]);
+        expect(err.name).toBe('TargetRequiredError');
+    });
+});
+//# sourceMappingURL=target-resolver.test.js.map