@wenrwa/marketplace-cli 0.4.5 → 0.4.6

package/dist/__tests__/local.test.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * TDD — lws-03: `wen-market local add/list/remove`. Folder→workspace
+ * registry commands. Mocks the bridge config/apiClient/folderRegistry
+ * modules — no real network, no real fs (prior art: workspace.test.ts).
+ */
+const chalk_1 = __importDefault(require("chalk"));
+const mockLoadBridgeConfig = jest.fn();
+jest.mock('../bridge/config', () => ({
+    loadBridgeConfig: () => mockLoadBridgeConfig(),
+}));
+const mockCreateLocalWorkspace = jest.fn();
+const mockDeleteWorkspace = jest.fn();
+jest.mock('../bridge/apiClient', () => ({
+    createLocalWorkspace: (...args) => mockCreateLocalWorkspace(...args),
+    deleteWorkspace: (...args) => mockDeleteWorkspace(...args),
+    BridgeApiError: class BridgeApiError extends Error {
+        code;
+        status;
+        constructor(message, code, status) { super(message); this.code = code; this.status = status; }
+    },
+}));
+jest.mock('../commands/bridge', () => ({ bridgeApiUrl: () => 'https://api.x' }));
+let registryState = { v: 1, entries: {} };
+jest.mock('../bridge/folderRegistry', () => {
+    const actual = jest.requireActual('../bridge/folderRegistry');
+    return {
+        ...actual,
+        loadFolderRegistry: () => registryState,
+        saveFolderRegistry: (registry) => { registryState = registry; },
+    };
+});
+const local_1 = require("../commands/local");
+async function runCommand(...args) {
+    await local_1.localCommand.parseAsync(args, { from: 'user' });
+}
+beforeAll(() => {
+    chalk_1.default.level = 0;
+});
+beforeEach(() => {
+    jest.clearAllMocks();
+    registryState = { v: 1, entries: {} };
+    mockLoadBridgeConfig.mockReturnValue({ connectToken: 'wm_ct_' + 'a'.repeat(64), deviceId: 'device-1' });
+});
+describe('local add', () => {
+    it('creates a local workspace and registers the resolved path', async () => {
+        mockCreateLocalWorkspace.mockResolvedValue({ success: true, workspace: { id: 'ws-1', name: 'wenrwa-arena' } });
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('add', process.cwd());
+        expect(mockCreateLocalWorkspace).toHaveBeenCalledWith(expect.objectContaining({ apiUrl: 'https://api.x', connectToken: expect.stringMatching(/^wm_ct_/) }), { name: expect.any(String) });
+        expect(registryState.entries[process.cwd()]).toMatchObject({ workspaceId: 'ws-1' });
+        const output = spy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('ws-1');
+        spy.mockRestore();
+    });
+    it('is idempotent — re-adding the same path returns the existing workspace without creating a new one', async () => {
+        registryState = { v: 1, entries: { [process.cwd()]: { workspaceId: 'ws-existing', name: 'x', addedAt: 'now' } } };
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('add', process.cwd());
+        expect(mockCreateLocalWorkspace).not.toHaveBeenCalled();
+        const output = spy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('ws-existing');
+        spy.mockRestore();
+    });
+    it('errors clearly when this machine has not been connected yet (no deviceId)', async () => {
+        mockLoadBridgeConfig.mockReturnValue({ connectToken: 'wm_ct_' + 'a'.repeat(64) }); // no deviceId
+        const errSpy = jest.spyOn(console, 'error').mockImplementation();
+        const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined);
+        await runCommand('add', process.cwd());
+        expect(mockCreateLocalWorkspace).not.toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        errSpy.mockRestore();
+        exitSpy.mockRestore();
+    });
+    it('surfaces a clear, non-crashing error when the device was revoked (401 mid-registration)', async () => {
+        const { BridgeApiError } = jest.requireMock('../bridge/apiClient');
+        mockCreateLocalWorkspace.mockRejectedValue(new BridgeApiError('Connect token is invalid or revoked.', 'INVALID_CONNECT_TOKEN', 401));
+        const errSpy = jest.spyOn(console, 'error').mockImplementation();
+        const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => undefined);
+        await runCommand('add', process.cwd());
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        const output = errSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output.toLowerCase()).toContain('revoked');
+        errSpy.mockRestore();
+        exitSpy.mockRestore();
+    });
+});
+describe('local list', () => {
+    it('prints all registered folders', async () => {
+        registryState = {
+            v: 1,
+            entries: {
+                '/Users/x/app-a': { workspaceId: 'ws-a', name: 'app-a', addedAt: 'now' },
+                '/Users/x/app-b': { workspaceId: 'ws-b', name: 'app-b', addedAt: 'now' },
+            },
+        };
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('list');
+        const output = spy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output).toContain('ws-a');
+        expect(output).toContain('ws-b');
+        spy.mockRestore();
+    });
+    it('says so when nothing is registered', async () => {
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('list');
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining('No local workspaces registered'));
+        spy.mockRestore();
+    });
+});
+describe('local remove', () => {
+    it('removes the registration only — never deletes the workspace by default', async () => {
+        registryState = { v: 1, entries: { '/Users/x/app-a': { workspaceId: 'ws-a', name: 'app-a', addedAt: 'now' } } };
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('remove', '/Users/x/app-a');
+        expect(registryState.entries['/Users/x/app-a']).toBeUndefined();
+        expect(mockDeleteWorkspace).not.toHaveBeenCalled();
+        const output = spy.mock.calls.map((c) => c[0]).join('\n');
+        expect(output.toLowerCase()).toContain('files untouched');
+        spy.mockRestore();
+    });
+    it('finds the entry by workspaceId too, not just by path', async () => {
+        registryState = { v: 1, entries: { '/Users/x/app-a': { workspaceId: 'ws-a', name: 'app-a', addedAt: 'now' } } };
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('remove', 'ws-a');
+        expect(registryState.entries['/Users/x/app-a']).toBeUndefined();
+        spy.mockRestore();
+    });
+    it('--delete also deletes the workspace row server-side', async () => {
+        registryState = { v: 1, entries: { '/Users/x/app-a': { workspaceId: 'ws-a', name: 'app-a', addedAt: 'now' } } };
+        mockDeleteWorkspace.mockResolvedValue({ success: true });
+        const spy = jest.spyOn(console, 'log').mockImplementation();
+        await runCommand('remove', '/Users/x/app-a', '--delete');
+        expect(mockDeleteWorkspace).toHaveBeenCalledWith(expect.anything(), 'ws-a');
+        spy.mockRestore();
+    });
+    it('errors clearly when the path/id is not registered', async () => {
+        const errSpy = jest.spyOn(console, 'error').mockImplementation();
+        await runCommand('remove', '/nope');
+        expect(errSpy).toHaveBeenCalledWith(expect.stringContaining('not registered'));
+        errSpy.mockRestore();
+    });
+});

package/dist/bridge/activityParser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * pucc-int-03 (ADR-0032) — Claude Code PTY activity parser (the PRODUCER).
+ *
+ * A Claude Code agent is a real PTY session the platform never drives
+ * (ADR-0028). To give it the same file-targeted drones/holograms a credits
+ * agent gets, the bridge OBSERVES its PTY output (read-only) and extracts the
+ * tool-use it renders — Edit/Write/Read/Bash targets + a short "thinking"
+ * summary — so the arena can swarm the files it touches.
+ *
+ * This module is PURE and defensive by contract:
+ *   - Input is raw PTY output: ANSI escapes, \r cursor redraws, and tool lines
+ *     split arbitrarily across chunks. It buffers partial lines across `push`.
+ *   - A parse MISS yields NOTHING (empty array). It NEVER throws — every code
+ *     path that could fail is caught and degraded to "no signal", because a
+ *     parser bug must never break the terminal it is only watching.
+ *   - The recognized markers are a SMALL, VERSIONED set (see TOOL_VERBS): if
+ *     Claude Code's output format drifts, this table is the one thing to bump.
+ *
+ * Recognized shape (best-effort): Claude Code renders a tool call as a bulleted
+ * line — `● Edit(src/foo.ts)`, `⏺ Read(package.json)`, `● Bash(npm test)`,
+ * `⏺ Update(src/x.ts)` — a bullet glyph, the Tool name, and a parenthesized
+ * arg. For file tools the arg's first token is the (repo-relative) path; for
+ * Bash it is a command (no path is extracted — the consumer degrades an empty
+ * `filePaths` to an ambient pulse). Every recognized tool also yields a
+ * human "thinking" phrase ("Editing foo.ts", "Running npm test").
+ */
+export interface ActivitySignal {
+    /** Repo-relative file targets extracted from a file-tool call (may be empty). */
+    filePaths: string[];
+    /** Short human summary of what the agent is doing, e.g. "Editing foo.ts". */
+    thinking?: string;
+}
+export interface ActivityParserOpts {
+    /** A single un-terminated line longer than this is abandoned (binary spew /
+     *  a pathological redraw) — the buffer is trimmed to its tail so a later
+     *  newline can still complete a plausible line. Default 16384. */
+    maxLineLength?: number;
+}
+export declare class ActivityParser {
+    private buf;
+    private maxLineLength;
+    /** Suppress consecutive identical signals (TUI re-renders the same line). */
+    private lastKey;
+    constructor(opts?: ActivityParserOpts);
+    /**
+     * Feed a chunk of PTY output. Returns every NEW tool-use signal completed by
+     * this chunk (usually 0 or 1). Never throws: any internal failure degrades
+     * to an empty result so the caller's PTY forwarding is never disturbed.
+     */
+    push(chunk: string): ActivitySignal[];
+    private pushUnsafe;
+    private parseLine;
+}

package/dist/bridge/activityParser.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * pucc-int-03 (ADR-0032) — Claude Code PTY activity parser (the PRODUCER).
+ *
+ * A Claude Code agent is a real PTY session the platform never drives
+ * (ADR-0028). To give it the same file-targeted drones/holograms a credits
+ * agent gets, the bridge OBSERVES its PTY output (read-only) and extracts the
+ * tool-use it renders — Edit/Write/Read/Bash targets + a short "thinking"
+ * summary — so the arena can swarm the files it touches.
+ *
+ * This module is PURE and defensive by contract:
+ *   - Input is raw PTY output: ANSI escapes, \r cursor redraws, and tool lines
+ *     split arbitrarily across chunks. It buffers partial lines across `push`.
+ *   - A parse MISS yields NOTHING (empty array). It NEVER throws — every code
+ *     path that could fail is caught and degraded to "no signal", because a
+ *     parser bug must never break the terminal it is only watching.
+ *   - The recognized markers are a SMALL, VERSIONED set (see TOOL_VERBS): if
+ *     Claude Code's output format drifts, this table is the one thing to bump.
+ *
+ * Recognized shape (best-effort): Claude Code renders a tool call as a bulleted
+ * line — `● Edit(src/foo.ts)`, `⏺ Read(package.json)`, `● Bash(npm test)`,
+ * `⏺ Update(src/x.ts)` — a bullet glyph, the Tool name, and a parenthesized
+ * arg. For file tools the arg's first token is the (repo-relative) path; for
+ * Bash it is a command (no path is extracted — the consumer degrades an empty
+ * `filePaths` to an ambient pulse). Every recognized tool also yields a
+ * human "thinking" phrase ("Editing foo.ts", "Running npm test").
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActivityParser = void 0;
+/**
+ * The VERSIONED marker table. Tool → gerund used in the "thinking" phrase.
+ * FILE_TOOLS is the subset whose arg is a path we extract into `filePaths`.
+ * Bash is recognized (for a thinking cue) but yields no path.
+ */
+const TOOL_VERBS = {
+    Read: 'Reading',
+    Edit: 'Editing',
+    Write: 'Writing',
+    Update: 'Updating',
+    Create: 'Creating',
+    MultiEdit: 'Editing',
+    NotebookEdit: 'Editing',
+    Bash: 'Running',
+};
+const FILE_TOOLS = new Set(['Read', 'Edit', 'Write', 'Update', 'Create', 'MultiEdit', 'NotebookEdit']);
+/** Bullet glyphs Claude Code (and similar TUIs) prefix a tool line with. */
+const BULLET = '[\\u25cf\\u23fa\\u23f5\\u25b6\\u25b7\\u2022*>]'; // ● ⏺ ⏵ ▶ ▷ • * >
+/**
+ * `<bullet> <Tool>(<arg>` — arg captured up to the first ')' or end-of-line
+ * (Claude Code truncates long args with `…` and NO closing paren, so a missing
+ * ')' must still parse). Operates on a single already-newline-split, ANSI-free
+ * line, so `.` never crosses lines.
+ */
+const TOOL_LINE = new RegExp('^' + BULLET + '\\s+([A-Za-z][A-Za-z0-9_]*)\\(([^)]*)\\)?');
+/**
+ * ANSI/VT control-sequence matchers, built from \\u001b (ESC) / \\u0007 (BEL)
+ * escapes so this source carries NO literal control bytes (which an editor can
+ * silently corrupt). Stateless with /g; String.replace resets lastIndex.
+ */
+const _ESC = "\\u001b";
+const _BEL = "\\u0007";
+// OSC: ESC ] ... (BEL | ESC \\)
+const OSC = new RegExp(_ESC + '\\][\\s\\S]*?(?:' + _BEL + '|' + _ESC + '\\\\)', 'g');
+// CSI + other ESC-introduced sequences (SGR colors, cursor moves, ...): ESC,
+// optional intro chars, optional numeric params, a final byte in @-~.
+const CSI = new RegExp(_ESC + '[[\\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[@-~]', 'g');
+// Any remaining lone ESC + C0 control chars EXCEPT tab(09) newline(0a) cr(0d).
+const STRAY = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+/** Strip ANSI/VT control sequences to leave printable text. */
+function stripAnsi(input) {
+    return input.replace(OSC, "").replace(CSI, "").replace(STRAY, "");
+}
+/**
+ * Reduce a raw line to its final RENDERED content. A TUI redraws in place with
+ * carriage returns: "old\rnew" displays "new". Keep only the text after the
+ * last \r so repeated redraws collapse to one signal.
+ */
+function finalRendered(line) {
+    const cr = line.lastIndexOf('\r');
+    return cr >= 0 ? line.slice(cr + 1) : line;
+}
+/** Extract a plausible repo-relative path from a file-tool arg, or null. */
+function extractPath(arg) {
+    // Take the first comma-separated segment (Claude Code appends `, offset:…`).
+    let s = arg.split(',')[0].trim();
+    // Drop an optional `file_path:` / `path:` label if present.
+    const labelled = s.match(/^(?:file_path|path|notebook_path)\s*:\s*(.+)$/i);
+    if (labelled)
+        s = labelled[1].trim();
+    // Strip a single pair of surrounding quotes.
+    s = s.replace(/^["'`](.*)["'`]$/, '$1').trim();
+    // Strip a trailing truncation ellipsis Claude Code adds to long args.
+    s = s.replace(/(?:…|\.\.\.)+$/, '').trim();
+    // Strip a leading "./".
+    s = s.replace(/^\.\//, '');
+    if (!s || s.length > 512)
+        return null;
+    // Reject obvious non-paths (nothing path-like left after cleanup).
+    if (!/[A-Za-z0-9._/\\-]/.test(s))
+        return null;
+    return s;
+}
+function basename(p) {
+    const parts = p.split(/[\\/]/);
+    return parts[parts.length - 1] || p;
+}
+/** Truncate a thinking phrase to a bounded, single-line length. */
+function boundThinking(s) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > 80 ? oneLine.slice(0, 79) + '…' : oneLine;
+}
+/** Best-effort short summary of a Bash arg for the thinking cue. */
+function extractCommandSummary(arg) {
+    const s = arg
+        .replace(/(?:…|\.\.\.)+$/, '')
+        .trim()
+        .replace(/^["'`](.*)["'`]$/, '$1')
+        .trim();
+    return s || null;
+}
+const DEFAULT_MAX_LINE = 16384;
+class ActivityParser {
+    buf = '';
+    maxLineLength;
+    /** Suppress consecutive identical signals (TUI re-renders the same line). */
+    lastKey = '';
+    constructor(opts = {}) {
+        this.maxLineLength = opts.maxLineLength ?? DEFAULT_MAX_LINE;
+    }
+    /**
+     * Feed a chunk of PTY output. Returns every NEW tool-use signal completed by
+     * this chunk (usually 0 or 1). Never throws: any internal failure degrades
+     * to an empty result so the caller's PTY forwarding is never disturbed.
+     */
+    push(chunk) {
+        try {
+            return this.pushUnsafe(chunk);
+        }
+        catch {
+            // A parser bug must never break the terminal it only observes. Reset the
+            // buffer so one bad state can't wedge all future parsing.
+            this.buf = '';
+            return [];
+        }
+    }
+    pushUnsafe(chunk) {
+        if (typeof chunk !== 'string' || chunk.length === 0)
+            return [];
+        this.buf += chunk;
+        // Normalize CRLF line endings to LF so a terminal's trailing `\r\n` is a
+        // line break, not mistaken for a mid-line redraw. A lone trailing `\r`
+        // (chunk boundary) stays buffered — the next chunk's `\n` completes it.
+        this.buf = this.buf.replace(/\r\n/g, '\n');
+        // Bounded buffer: if a single line runs away without a newline (binary
+        // spew), keep only the tail so a future newline can still complete a line.
+        if (this.buf.length > this.maxLineLength && !this.buf.includes('\n')) {
+            this.buf = this.buf.slice(-this.maxLineLength);
+        }
+        const nl = this.buf.lastIndexOf('\n');
+        if (nl < 0)
+            return []; // no complete line yet — keep buffering
+        const complete = this.buf.slice(0, nl);
+        this.buf = this.buf.slice(nl + 1);
+        const out = [];
+        for (const rawLine of complete.split('\n')) {
+            const signal = this.parseLine(rawLine);
+            if (!signal)
+                continue;
+            const key = JSON.stringify(signal);
+            if (key === this.lastKey)
+                continue; // dedup rapid repeats
+            this.lastKey = key;
+            out.push(signal);
+        }
+        return out;
+    }
+    parseLine(rawLine) {
+        const line = stripAnsi(finalRendered(rawLine)).trim();
+        if (!line)
+            return null;
+        const m = TOOL_LINE.exec(line);
+        if (!m)
+            return null;
+        const tool = m[1];
+        const verb = TOOL_VERBS[tool];
+        if (!verb)
+            return null; // unknown tool → no signal (fewer false events)
+        const arg = m[2] ?? '';
+        if (FILE_TOOLS.has(tool)) {
+            const path = extractPath(arg);
+            if (path) {
+                return { filePaths: [path], thinking: boundThinking(verb + ' ' + basename(path)) };
+            }
+            // Recognized file tool but no usable path → thinking-only (ambient pulse).
+            return { filePaths: [], thinking: boundThinking(verb) };
+        }
+        // Bash (and any future non-file tool): a thinking cue, no path.
+        const cmd = extractCommandSummary(arg);
+        return { filePaths: [], thinking: boundThinking(cmd ? verb + ' ' + cmd : verb) };
+    }
+}
+exports.ActivityParser = ActivityParser;

package/dist/bridge/apiClient.d.ts

@@ -0,0 +1,56 @@
+/**
+ * lws-03 — bridge REST client. The daemon talks to the backend AS ITSELF
+ * (Authorization: Bearer <Connect Token>), distinct from utils/client.ts
+ * (the interactive CLI's X-Wallet-Pubkey login flow). Used for device
+ * pairing ("Connect this machine") and local-workspace creation/deletion.
+ * fetchImpl is injectable so callers/tests never hit the network.
+ */
+export type FetchImpl = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<any>;
+}>;
+export interface BridgeApiOpts {
+    apiUrl: string;
+    connectToken: string;
+    fetchImpl?: FetchImpl;
+}
+export declare class BridgeApiError extends Error {
+    code: string;
+    status: number;
+    constructor(message: string, code: string, status: number);
+}
+export interface DeviceRecord {
+    id: string;
+    name: string;
+    createdAt?: string;
+    revokedAt?: string | null;
+}
+export declare function registerDevice(opts: BridgeApiOpts, name: string): Promise<{
+    success: boolean;
+    device: DeviceRecord;
+}>;
+export declare function listDevices(opts: BridgeApiOpts): Promise<{
+    success: boolean;
+    devices: DeviceRecord[];
+}>;
+export declare function revokeDevice(opts: BridgeApiOpts, deviceId: string): Promise<{
+    success: boolean;
+}>;
+export interface WorkspaceRecord {
+    id: string;
+    name: string;
+}
+export declare function createLocalWorkspace(opts: BridgeApiOpts, params: {
+    name: string;
+}): Promise<{
+    success: boolean;
+    workspace: WorkspaceRecord;
+}>;
+export declare function deleteWorkspace(opts: BridgeApiOpts, workspaceId: string): Promise<{
+    success: boolean;
+}>;

package/dist/bridge/apiClient.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BridgeApiError = void 0;
+exports.registerDevice = registerDevice;
+exports.listDevices = listDevices;
+exports.revokeDevice = revokeDevice;
+exports.createLocalWorkspace = createLocalWorkspace;
+exports.deleteWorkspace = deleteWorkspace;
+class BridgeApiError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'BridgeApiError';
+    }
+}
+exports.BridgeApiError = BridgeApiError;
+async function bridgeRequest(opts, method, path, body) {
+    const f = opts.fetchImpl ?? fetch;
+    const res = await f(`${opts.apiUrl}${path}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${opts.connectToken}`,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json();
+    if (!res.ok || json?.success === false) {
+        throw new BridgeApiError(json?.error?.message || `HTTP ${res.status}`, json?.error?.code || 'UNKNOWN', res.status);
+    }
+    return json;
+}
+function registerDevice(opts, name) {
+    return bridgeRequest(opts, 'POST', '/me/devices', { name });
+}
+function listDevices(opts) {
+    return bridgeRequest(opts, 'GET', '/me/devices');
+}
+function revokeDevice(opts, deviceId) {
+    return bridgeRequest(opts, 'DELETE', `/me/devices/${deviceId}`);
+}
+function createLocalWorkspace(opts, params) {
+    return bridgeRequest(opts, 'POST', '/workspaces', { name: params.name, kind: 'local' });
+}
+function deleteWorkspace(opts, workspaceId) {
+    return bridgeRequest(opts, 'DELETE', `/workspaces/${workspaceId}`);
+}

package/dist/bridge/browserDriver.d.ts

@@ -0,0 +1,98 @@
+/**
+ * cbs-02 — bridge CDP browser driver.
+ *
+ * (docs/prd/cloud-browser-session.md, issues/cbs-02-bridge-cdp-driver.md)
+ * The deep module inside the in-container bridge that owns one headless
+ * Chromium tab: spawn (child_process, NOT node-pty/SessionManager — this
+ * must never touch the PTY session manager or spawn a shell), a minimal
+ * hand-rolled CDP client (cdpClient.ts) driving `Page.startScreencast` for
+ * output and `Input.dispatch*`/`insertText` for input, screencast frames
+ * piped through the cbs-01 keep-newest pacer (framePacer.ts), and
+ * navigation/lifecycle state surfaced as plain callbacks. All CDP mechanics
+ * (target attach, session ids, event wiring) are hidden behind this
+ * interface — relayClient.ts (or any future caller) only sees start/
+ * navigate/input/back/forward/reload/onFrame/onState/ackFrame/stop.
+ */
+import { ChromiumLaunchHandle } from './chromiumLauncher';
+import { CdpTransportLike } from './cdpClient';
+import { BrowserInputEvent, BrowserSessionState } from './browserFrames';
+/** container -> pane screencast frame, minus the wire envelope (`t`,
+ *  `sessionId`) — the driver doesn't know the relay session id; the caller
+ *  (relayClient) stamps those on when forwarding. */
+export interface BrowserDriverFramePayload {
+    seq: number;
+    data: string;
+    w: number;
+    h: number;
+}
+/** container -> pane lifecycle/navigation state, minus the wire envelope. */
+export interface BrowserDriverStatePayload {
+    state: BrowserSessionState;
+    url?: string;
+    title?: string;
+    reason?: string;
+}
+export interface BrowserDriver {
+    /** Launches Chromium (if not already running), attaches to a page
+     *  target, starts the screencast, and navigates to `url`. */
+    start(url: string): Promise<void>;
+    /** Navigates the already-open tab to `url` (also what a `browser-open`
+     *  on an already-open session should call — see relayClient wiring). */
+    navigate(url: string): Promise<void>;
+    /** Dispatches one input event. Never dropped/paced (unlike frames). */
+    input(event: BrowserInputEvent): void;
+    back(): Promise<void>;
+    forward(): Promise<void>;
+    reload(): Promise<void>;
+    /** Registers the (single) frame consumer. Frames are keep-newest paced —
+     *  see ackFrame(). */
+    onFrame(cb: (frame: BrowserDriverFramePayload) => void): void;
+    /** Registers the (single) lifecycle/navigation state consumer. */
+    onState(cb: (state: BrowserDriverStatePayload) => void): void;
+    /** Consumer contract for the cbs-01 pacer (framePacer.ts): call once a
+     *  delivered frame has been handed off downstream. The wire protocol
+     *  (browserFrames.ts, v1) has no pane-side ack frame yet, so relayClient's
+     *  interim policy is to call this right after forwarding — true end-to-end
+     *  backpressure to the pane is a later slice (see PRD module 5). */
+    ackFrame(): void;
+    /** Kills the Chromium process and tears down the CDP transport, emitting a
+     *  terminal 'closed' state. Safe to call more than once and safe to call
+     *  before start() resolves. */
+    stop(): void;
+    /** cbs-06: same physical teardown as stop() (kills Chromium, tears down
+     *  CDP — no orphaned process either way), but emits a terminal 'asleep'
+     *  state instead of 'closed' — intentional and resumable (a later
+     *  browser-open on this sessionId gets a FRESH driver instance per the
+     *  relayClient "replace, not navigate" policy; this driver instance is
+     *  done either way). `reason` rides straight onto the emitted
+     *  browser-state (default 'sleep'; relayClient passes 'idle-timeout' for
+     *  the 15-minute auto-close path — see browserFrames.ts's BrowserStateFrame
+     *  doc comment for the reason-string convention). Safe to call more than
+     *  once, safe to call before start() resolves, and safe to call after
+     *  stop() (or vice versa) — only the FIRST of stop()/sleep() wins; the
+     *  second is a no-op (exactly one terminal browser-state frame per driver
+     *  lifetime). */
+    sleep(reason?: string): void;
+}
+export interface BrowserDriverOpts {
+    chromiumPath?: string;
+    userDataDir?: string;
+    /** Window size AND `Page.startScreencast` maxWidth/maxHeight. Default 1280x800. */
+    width?: number;
+    height?: number;
+    /** JPEG quality for the screencast. Default 60 (PRD: "JPEG quality tuned
+     *  for text legibility"). */
+    quality?: number;
+    /** Injectable for tests: defaults to chromiumLauncher.launchChromium. */
+    launchChromiumFn?: (opts: {
+        chromiumPath?: string;
+        userDataDir?: string;
+        width?: number;
+        height?: number;
+    }) => ChromiumLaunchHandle;
+    /** Injectable for tests: defaults to a `ws`-backed transport connected to
+     *  the Chromium DevTools websocket URL. Tests inject an in-process
+     *  MockCdpEndpoint transport here to avoid a real socket/process. */
+    wsFactory?: (url: string) => CdpTransportLike;
+}
+export declare function createBrowserDriver(opts?: BrowserDriverOpts): BrowserDriver;