@jackwener/opencli 1.7.5 → 1.7.6

package/dist/src/browser/network-cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Persistent cache for browser network captures.
+ *
+ * The live capture buffer (JS interceptor / daemon ring) can be cleared
+ * by navigation or lost between CLI invocations. Agents still need
+ * stable references to request bodies after running other commands,
+ * so every `browser network` call snapshots its results to disk.
+ *
+ * Layout: <cacheDir>/browser-network/<workspace>.json
+ * Entries expire after DEFAULT_TTL_MS (24h).
+ */
+export declare const DEFAULT_TTL_MS: number;
+export interface CachedNetworkEntry {
+    key: string;
+    url: string;
+    method: string;
+    status: number;
+    /** Full body size in chars (may exceed stored body length when truncated). */
+    size: number;
+    ct: string;
+    body: unknown;
+    /**
+     * Truncation signals use snake_case so `--raw` (which emits cache entries
+     * verbatim) matches the agent-facing contract used by list / --detail.
+     */
+    body_truncated?: boolean;
+    body_full_size?: number;
+}
+export interface NetworkCacheFile {
+    version: 1;
+    workspace: string;
+    savedAt: string;
+    entries: CachedNetworkEntry[];
+}
+export declare function getCachePath(workspace: string, baseDir?: string): string;
+export declare function saveNetworkCache(workspace: string, entries: CachedNetworkEntry[], baseDir?: string): void;
+export interface LoadOptions {
+    baseDir?: string;
+    ttlMs?: number;
+    now?: number;
+}
+export interface LoadResult {
+    status: 'ok' | 'missing' | 'expired' | 'corrupt';
+    file?: NetworkCacheFile;
+    ageMs?: number;
+}
+export declare function loadNetworkCache(workspace: string, opts?: LoadOptions): LoadResult;
+export declare function findEntry(file: NetworkCacheFile, key: string): CachedNetworkEntry | null;

package/dist/src/browser/network-cache.js

@@ -0,0 +1,66 @@
+/**
+ * Persistent cache for browser network captures.
+ *
+ * The live capture buffer (JS interceptor / daemon ring) can be cleared
+ * by navigation or lost between CLI invocations. Agents still need
+ * stable references to request bodies after running other commands,
+ * so every `browser network` call snapshots its results to disk.
+ *
+ * Layout: <cacheDir>/browser-network/<workspace>.json
+ * Entries expire after DEFAULT_TTL_MS (24h).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+function getDefaultCacheDir() {
+    return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
+}
+export function getCachePath(workspace, baseDir = getDefaultCacheDir()) {
+    const safe = workspace.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return path.join(baseDir, 'browser-network', `${safe}.json`);
+}
+export function saveNetworkCache(workspace, entries, baseDir) {
+    const target = getCachePath(workspace, baseDir);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const payload = {
+        version: 1,
+        workspace,
+        savedAt: new Date().toISOString(),
+        entries,
+    };
+    fs.writeFileSync(target, JSON.stringify(payload), 'utf-8');
+}
+export function loadNetworkCache(workspace, opts = {}) {
+    const target = getCachePath(workspace, opts.baseDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(target, 'utf-8');
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    let parsed;
+    try {
+        const obj = JSON.parse(raw);
+        if (!obj || obj.version !== 1 || !Array.isArray(obj.entries)) {
+            return { status: 'corrupt' };
+        }
+        parsed = obj;
+    }
+    catch {
+        return { status: 'corrupt' };
+    }
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const now = opts.now ?? Date.now();
+    const savedAt = Date.parse(parsed.savedAt);
+    if (!Number.isFinite(savedAt))
+        return { status: 'corrupt' };
+    const ageMs = now - savedAt;
+    if (ageMs > ttl)
+        return { status: 'expired', file: parsed, ageMs };
+    return { status: 'ok', file: parsed, ageMs };
+}
+export function findEntry(file, key) {
+    return file.entries.find((e) => e.key === key) ?? null;
+}

package/dist/src/browser/network-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/network-cache.test.js

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { DEFAULT_TTL_MS, findEntry, getCachePath, loadNetworkCache, saveNetworkCache, } from './network-cache.js';
+function makeEntry(key, body = { ok: true }) {
+    return { key, url: `https://x.com/${key}`, method: 'GET', status: 200, size: 2, ct: 'application/json', body };
+}
+describe('network-cache', () => {
+    let baseDir;
+    beforeEach(() => {
+        baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-netcache-'));
+    });
+    afterEach(() => {
+        fs.rmSync(baseDir, { recursive: true, force: true });
+    });
+    it('sanitizes workspace names into safe filenames', () => {
+        const p = getCachePath('browser:default', baseDir);
+        expect(path.basename(p)).toBe('browser_default.json');
+    });
+    it('round-trips entries through save + load', () => {
+        saveNetworkCache('ws', [makeEntry('UserTweets'), makeEntry('UserByScreenName')], baseDir);
+        const res = loadNetworkCache('ws', { baseDir });
+        expect(res.status).toBe('ok');
+        expect(res.file?.entries).toHaveLength(2);
+        expect(res.file?.entries[0].key).toBe('UserTweets');
+    });
+    it('reports missing when cache file does not exist', () => {
+        expect(loadNetworkCache('nope', { baseDir }).status).toBe('missing');
+    });
+    it('reports expired when the cache is older than ttl', () => {
+        saveNetworkCache('ws', [makeEntry('A')], baseDir);
+        const future = Date.now() + DEFAULT_TTL_MS + 60_000;
+        const res = loadNetworkCache('ws', { baseDir, now: future });
+        expect(res.status).toBe('expired');
+        expect(res.file?.entries).toHaveLength(1);
+    });
+    it('reports corrupt for malformed json', () => {
+        const file = getCachePath('ws', baseDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, '{not json');
+        expect(loadNetworkCache('ws', { baseDir }).status).toBe('corrupt');
+    });
+    it('reports corrupt for wrong schema version', () => {
+        const file = getCachePath('ws', baseDir);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ version: 0, entries: [] }));
+        expect(loadNetworkCache('ws', { baseDir }).status).toBe('corrupt');
+    });
+    it('findEntry returns matching entry or null', () => {
+        const file = {
+            version: 1, workspace: 'ws', savedAt: new Date().toISOString(),
+            entries: [makeEntry('A'), makeEntry('B')],
+        };
+        expect(findEntry(file, 'B')?.key).toBe('B');
+        expect(findEntry(file, 'missing')).toBeNull();
+    });
+});

package/dist/src/browser/network-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export interface KeyableRequest {
+    url: string;
+    method: string;
+}
+export declare function deriveKey(req: KeyableRequest): string;
+export declare function assignKeys<T extends KeyableRequest>(requests: T[]): Array<T & {
+    key: string;
+}>;

package/dist/src/browser/network-key.js

@@ -0,0 +1,66 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export function deriveKey(req) {
+    const parsed = safeParseUrl(req.url);
+    if (!parsed)
+        return `${req.method.toUpperCase()} ${truncate(req.url, 120)}`;
+    const path = parsed.pathname;
+    if (path.includes('/graphql/')) {
+        const op = graphqlOperationName(path);
+        if (op)
+            return op;
+    }
+    return `${req.method.toUpperCase()} ${parsed.host}${path}`;
+}
+export function assignKeys(requests) {
+    const counts = new Map();
+    const out = [];
+    for (const req of requests) {
+        const base = deriveKey(req);
+        const n = counts.get(base) ?? 0;
+        counts.set(base, n + 1);
+        const key = n === 0 ? base : `${base}#${n + 1}`;
+        out.push({ ...req, key });
+    }
+    return out;
+}
+function graphqlOperationName(pathname) {
+    // Patterns we've seen in the wild:
+    //   /i/api/graphql/<queryId>/UserTweets
+    //   /graphql/<queryId>/SomeOp
+    //   /graphql/SomeOp                       (rare, no id)
+    const segments = pathname.split('/').filter(Boolean);
+    const idx = segments.indexOf('graphql');
+    if (idx < 0)
+        return null;
+    const tail = segments.slice(idx + 1);
+    if (tail.length === 0)
+        return null;
+    if (tail.length === 1)
+        return tail[0];
+    // tail[0] is usually a query id; the operation name is the next segment.
+    return tail[1] || tail[0];
+}
+function safeParseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}

package/dist/src/browser/network-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/network-key.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { assignKeys, deriveKey } from './network-key.js';
+describe('deriveKey', () => {
+    it('extracts operationName from Twitter-style graphql URLs', () => {
+        expect(deriveKey({
+            method: 'GET',
+            url: 'https://x.com/i/api/graphql/6fWQaBPK51aGyC_VC7t9GQ/UserTweets?variables=...',
+        })).toBe('UserTweets');
+    });
+    it('handles graphql URLs without a query id', () => {
+        expect(deriveKey({
+            method: 'POST',
+            url: 'https://example.com/graphql/MyOp?vars=1',
+        })).toBe('MyOp');
+    });
+    it('uses METHOD host+pathname for REST calls', () => {
+        expect(deriveKey({
+            method: 'get',
+            url: 'https://api.example.com/v1/users?page=1',
+        })).toBe('GET api.example.com/v1/users');
+    });
+    it('falls back to truncated raw url when URL parsing fails', () => {
+        const key = deriveKey({ method: 'GET', url: 'not-a-valid-url' });
+        expect(key.startsWith('GET ')).toBe(true);
+        expect(key).toContain('not-a-valid-url');
+    });
+});
+describe('assignKeys', () => {
+    it('disambiguates collisions with #N suffixes', () => {
+        const out = assignKeys([
+            { url: 'https://x.com/i/api/graphql/a/UserTweets', method: 'GET' },
+            { url: 'https://x.com/i/api/graphql/b/UserTweets', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+        ]);
+        expect(out.map(o => o.key)).toEqual([
+            'UserTweets',
+            'UserTweets#2',
+            'GET api.example.com/v1/u',
+            'GET api.example.com/v1/u#2',
+            'GET api.example.com/v1/u#3',
+        ]);
+    });
+    it('preserves extra fields on each request', () => {
+        const out = assignKeys([{ url: 'https://a.com/x', method: 'GET', status: 200 }]);
+        expect(out[0]).toMatchObject({ status: 200, key: 'GET a.com/x' });
+    });
+});

package/dist/src/browser/shape-filter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shape-based field filter for `browser network --filter <fields>`.
+ *
+ * Agents know what fields a target request's body should contain
+ * (e.g. "author, text, likes") but not which of the captured requests
+ * carries that body. This module lets the network command filter
+ * entries down to those whose inferred shape exposes every requested
+ * field name as some path segment.
+ *
+ * Matching is "any-segment" (not last-segment-only): a field matches
+ * if it equals any segment name of any path in the shape map. This
+ * keeps nested-container fields (e.g. `legacy`, `author` used as an
+ * object key with further nesting) findable.
+ */
+import type { Shape } from './shape.js';
+export interface ParsedFilter {
+    /** Deduped, order-preserving, trimmed non-empty field names. */
+    fields: string[];
+}
+export interface FilterParseError {
+    /** `invalid_filter` structured error reason for agents. */
+    reason: string;
+}
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export declare function parseFilter(raw: string): ParsedFilter | FilterParseError;
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export declare function extractSegments(path: string): string[];
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export declare function collectShapeSegments(shape: Shape): Set<string>;
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export declare function shapeMatchesFilter(shape: Shape, fields: string[]): boolean;

package/dist/src/browser/shape-filter.js

@@ -0,0 +1,101 @@
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export function parseFilter(raw) {
+    if (typeof raw !== 'string') {
+        return { reason: `--filter value must be a non-empty comma-separated field list` };
+    }
+    const parts = raw.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return { reason: `--filter value must be a non-empty comma-separated field list (got "${raw}")` };
+    }
+    const seen = new Set();
+    const fields = [];
+    for (const p of parts) {
+        if (!seen.has(p)) {
+            seen.add(p);
+            fields.push(p);
+        }
+    }
+    return { fields };
+}
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export function extractSegments(path) {
+    if (!path || path === '$')
+        return [];
+    const out = [];
+    // Start past the leading `$`; if path doesn't start with `$` treat
+    // it as a raw segment list (keeps us robust to unexpected input).
+    let i = path.startsWith('$') ? 1 : 0;
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') {
+            i++;
+            continue;
+        }
+        if (c === '[') {
+            // Either `[N]` (numeric) or `["key"]` (quoted key). Handle both.
+            const end = path.indexOf(']', i);
+            if (end === -1)
+                break;
+            const inner = path.slice(i + 1, end);
+            i = end + 1;
+            if (inner.length >= 2 && inner.startsWith('"') && inner.endsWith('"')) {
+                try {
+                    out.push(JSON.parse(inner));
+                }
+                catch {
+                    out.push(inner.slice(1, -1));
+                }
+            }
+            // numeric index: drop
+            continue;
+        }
+        // Bare identifier: read up to next `.` or `[`
+        let j = i;
+        while (j < path.length && path[j] !== '.' && path[j] !== '[')
+            j++;
+        out.push(path.slice(i, j));
+        i = j;
+    }
+    return out;
+}
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export function collectShapeSegments(shape) {
+    const acc = new Set();
+    for (const p of Object.keys(shape)) {
+        for (const seg of extractSegments(p))
+            acc.add(seg);
+    }
+    return acc;
+}
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export function shapeMatchesFilter(shape, fields) {
+    if (fields.length === 0)
+        return true;
+    const segs = collectShapeSegments(shape);
+    for (const f of fields) {
+        if (!segs.has(f))
+            return false;
+    }
+    return true;
+}

package/dist/src/browser/shape-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/shape-filter.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { collectShapeSegments, extractSegments, parseFilter, shapeMatchesFilter, } from './shape-filter.js';
+describe('parseFilter', () => {
+    it('splits comma-separated fields, trims, and drops empty tokens', () => {
+        const r = parseFilter('author, text , likes');
+        expect(r).toEqual({ fields: ['author', 'text', 'likes'] });
+    });
+    it('dedupes while preserving first-seen order', () => {
+        const r = parseFilter('a,b,a,c,b');
+        expect(r).toEqual({ fields: ['a', 'b', 'c'] });
+    });
+    it('rejects empty string as invalid_filter', () => {
+        const r = parseFilter('');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects whitespace-only as invalid_filter', () => {
+        const r = parseFilter('   ');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects commas-only as invalid_filter', () => {
+        const r = parseFilter(',,,');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('accepts a single field', () => {
+        expect(parseFilter('author')).toEqual({ fields: ['author'] });
+    });
+});
+describe('extractSegments', () => {
+    it('returns empty for root', () => {
+        expect(extractSegments('$')).toEqual([]);
+    });
+    it('splits dotted path and drops $', () => {
+        expect(extractSegments('$.data.user.name')).toEqual(['data', 'user', 'name']);
+    });
+    it('drops numeric array indices', () => {
+        expect(extractSegments('$.items[0].author')).toEqual(['items', 'author']);
+        expect(extractSegments('$.rows[0][12]')).toEqual(['rows']);
+    });
+    it('unwraps bracket-quoted keys', () => {
+        expect(extractSegments('$.data["weird key"]')).toEqual(['data', 'weird key']);
+    });
+    it('handles bracket-quoted keys at root', () => {
+        expect(extractSegments('$["123bad"]')).toEqual(['123bad']);
+    });
+    it('mixes bracket keys and dot segments', () => {
+        expect(extractSegments('$.data.user["nick name"].age'))
+            .toEqual(['data', 'user', 'nick name', 'age']);
+    });
+});
+describe('collectShapeSegments', () => {
+    it('collects every segment name from every path in a shape', () => {
+        const shape = {
+            '$': 'object',
+            '$.data': 'object',
+            '$.data.items': 'array(3)',
+            '$.data.items[0]': 'object',
+            '$.data.items[0].author': 'string',
+            '$.data.items[0].text': 'string',
+        };
+        const segs = collectShapeSegments(shape);
+        expect(segs.has('data')).toBe(true);
+        expect(segs.has('items')).toBe(true);
+        expect(segs.has('author')).toBe(true);
+        expect(segs.has('text')).toBe(true);
+        expect(segs.has('$')).toBe(false);
+        expect(segs.has('[0]')).toBe(false);
+    });
+    it('returns an empty set for an empty shape', () => {
+        expect(collectShapeSegments({}).size).toBe(0);
+    });
+});
+describe('shapeMatchesFilter', () => {
+    const shape = {
+        '$': 'object',
+        '$.data': 'object',
+        '$.data.items': 'array(1)',
+        '$.data.items[0].author': 'string',
+        '$.data.items[0].text': 'string',
+        '$.data.items[0].likes': 'number',
+    };
+    it('returns true when every field matches some path segment (AND)', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'text', 'likes'])).toBe(true);
+    });
+    it('matches nested container names, not just leaves (any-segment rule)', () => {
+        // `data` and `items` are container segments, not leaves; still must match.
+        expect(shapeMatchesFilter(shape, ['data', 'items'])).toBe(true);
+    });
+    it('returns false when any field is missing', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'missing'])).toBe(false);
+    });
+    it('is case-sensitive', () => {
+        expect(shapeMatchesFilter(shape, ['Author'])).toBe(false);
+        expect(shapeMatchesFilter(shape, ['author'])).toBe(true);
+    });
+    it('empty filter list vacuously matches', () => {
+        expect(shapeMatchesFilter(shape, [])).toBe(true);
+    });
+    it('rejects requests whose shape has no body (empty shape)', () => {
+        expect(shapeMatchesFilter({}, ['author'])).toBe(false);
+    });
+});

package/dist/src/browser/shape.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON shape inference for browser network response previews.
+ *
+ * Produces a flat path → type descriptor map so agents can understand
+ * response structure without paying the token cost of the full body.
+ *
+ * Descriptors:
+ *   string | number | boolean | null              primitives
+ *   string(len=N)                                 strings longer than sampleStringLen
+ *   array(0) | array(N)                           array at depth cap or summarized
+ *   object | object(empty)                        objects at depth cap or summarized
+ *   (truncated)                                   output size budget exceeded
+ */
+export interface InferShapeOptions {
+    /** Max path depth to descend into (default 6) */
+    maxDepth?: number;
+    /** Byte budget for the serialized output; truncates when exceeded (default 2048) */
+    maxBytes?: number;
+    /** Strings longer than this get summarized as `string(len=N)` (default 80) */
+    sampleStringLen?: number;
+}
+export type Shape = Record<string, string>;
+export declare function inferShape(value: unknown, opts?: InferShapeOptions): Shape;