@jackwener/opencli 1.7.6 → 1.7.7

package/dist/src/browser/verify-fixture.d.ts

@@ -0,0 +1,59 @@
+export type FixtureExpect = {
+    rowCount?: {
+        min?: number;
+        max?: number;
+    };
+    columns?: string[];
+    types?: Record<string, string>;
+    patterns?: Record<string, string>;
+    notEmpty?: string[];
+    /**
+     * Substrings/regex fragments that MUST NOT appear in the column value.
+     *
+     * Catches silent content contamination that `notEmpty` alone misses —
+     * e.g. a `description` field that accidentally carries "address: ..." /
+     * "category: ..." fragments from sibling DOM nodes, or a `title` that
+     * bled in a navigation-breadcrumb prefix. Each entry is matched as a
+     * plain substring against the stringified column value.
+     */
+    mustNotContain?: Record<string, string[]>;
+    /**
+     * Columns whose values must be truthy. Complements `notEmpty` (which
+     * only rejects empty-string/null/undefined) by also catching silent
+     * `|| 0` / `|| false` fallbacks in numeric/boolean fields. Fires when
+     * the value coerces to `false` in JS.
+     */
+    mustBeTruthy?: string[];
+};
+export type FixtureArgs = Record<string, unknown> | unknown[];
+export type Fixture = {
+    args?: FixtureArgs;
+    expect?: FixtureExpect;
+};
+export type ValidationFailure = {
+    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy';
+    detail: string;
+    rowIndex?: number;
+};
+export type Row = Record<string, unknown>;
+export declare function fixturePath(site: string, command: string): string;
+export declare function loadFixture(site: string, command: string): Fixture | null;
+export declare function writeFixture(site: string, command: string, fixture: Fixture): string;
+/**
+ * Derive a reasonable fixture from sample output. Used by `--write-fixture`
+ * to seed a first draft the author can hand-tune.
+ *
+ * Heuristics:
+ * - rowCount.min = 1 if rows non-empty, else 0
+ * - columns = keys from the first row
+ * - types = typeof of the first row's values, with "number|string" for mixed
+ * - no auto patterns / notEmpty — author should add those deliberately
+ */
+export declare function deriveFixture(rows: Row[], args?: FixtureArgs): Fixture;
+export declare function validateRows(rows: Row[], fixture: Fixture): ValidationFailure[];
+/**
+ * Convert fixture args into argv tokens appended after the command name.
+ * - Array form is passed through verbatim (stringified), supporting positional subjects.
+ * - Object form is expanded to `--key value` pairs.
+ */
+export declare function expandFixtureArgs(args: FixtureArgs | undefined): string[];

package/dist/src/browser/verify-fixture.js

@@ -0,0 +1,213 @@
+/**
+ * Verify fixture: structural expectations for `opencli browser verify` output.
+ *
+ * The adapter-author skill runbook says every published adapter must write a
+ * fixture under `~/.opencli/sites/<site>/verify/<command>.json` so later verify
+ * runs can catch shape regressions (missing columns, wrong types, bleeding
+ * values) without relying on exact content match — BBS / news / market data is
+ * too volatile for value equality.
+ *
+ * Schema:
+ *   {
+ *     // args can be either:
+ *     //   - an object of named flags: { "limit": 3 }  → expands to `--limit 3`
+ *     //   - a raw argv array:         ["123", "--limit", "3"]  → passed verbatim
+ *     // Use the array form for adapters that take positional subjects (e.g. <tid>, <url>, <query>).
+ *     "args": { "limit": 3 },
+ *     "expect": {
+ *       "rowCount": { "min": 1, "max": 10 },  // inclusive bounds
+ *       "columns":  ["a", "b"],                // every row must have these keys
+ *       "types":    { "a": "string", "b": "number|string" },
+ *       "patterns": { "url": "^https?://" },
+ *       "notEmpty": ["title", "url"],          // trimmed string must be non-empty
+ *       "mustNotContain": {                     // catch content-contamination bleed
+ *         "description": ["address:", "category:"]
+ *       },
+ *       "mustBeTruthy": ["count"]               // catch silent `|| 0` fallbacks
+ *     }
+ *   }
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function fixturePath(site, command) {
+    return path.join(os.homedir(), '.opencli', 'sites', site, 'verify', `${command}.json`);
+}
+export function loadFixture(site, command) {
+    const p = fixturePath(site, command);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = fs.readFileSync(p, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`Failed to parse fixture ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function writeFixture(site, command, fixture) {
+    const p = fixturePath(site, command);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(fixture, null, 2)}\n`, 'utf-8');
+    return p;
+}
+/**
+ * Derive a reasonable fixture from sample output. Used by `--write-fixture`
+ * to seed a first draft the author can hand-tune.
+ *
+ * Heuristics:
+ * - rowCount.min = 1 if rows non-empty, else 0
+ * - columns = keys from the first row
+ * - types = typeof of the first row's values, with "number|string" for mixed
+ * - no auto patterns / notEmpty — author should add those deliberately
+ */
+export function deriveFixture(rows, args) {
+    const expect = {};
+    if (rows.length === 0) {
+        expect.rowCount = { min: 0 };
+        return { ...(args ? { args } : {}), expect };
+    }
+    expect.rowCount = { min: 1 };
+    const first = rows[0];
+    const columns = Object.keys(first);
+    expect.columns = columns;
+    const types = {};
+    for (const col of columns) {
+        const observed = new Set();
+        for (const row of rows) {
+            const v = row[col];
+            observed.add(jsType(v));
+        }
+        types[col] = [...observed].sort().join('|');
+    }
+    expect.types = types;
+    return { ...(args ? { args } : {}), expect };
+}
+export function validateRows(rows, fixture) {
+    const failures = [];
+    const expect = fixture.expect;
+    if (!expect)
+        return failures;
+    if (expect.rowCount) {
+        const { min, max } = expect.rowCount;
+        if (typeof min === 'number' && rows.length < min) {
+            failures.push({ rule: 'rowCount', detail: `got ${rows.length} rows, expected at least ${min}` });
+        }
+        if (typeof max === 'number' && rows.length > max) {
+            failures.push({ rule: 'rowCount', detail: `got ${rows.length} rows, expected at most ${max}` });
+        }
+    }
+    const columns = expect.columns ?? [];
+    const types = expect.types ?? {};
+    const patterns = expect.patterns ?? {};
+    const notEmpty = expect.notEmpty ?? [];
+    const compiledPatterns = {};
+    for (const [col, src] of Object.entries(patterns)) {
+        try {
+            compiledPatterns[col] = new RegExp(src);
+        }
+        catch (err) {
+            failures.push({ rule: 'pattern', detail: `pattern for "${col}" invalid: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    rows.forEach((row, i) => {
+        for (const col of columns) {
+            if (!(col in row)) {
+                failures.push({ rule: 'column', detail: `missing column "${col}"`, rowIndex: i });
+            }
+        }
+        for (const [col, declared] of Object.entries(types)) {
+            if (!(col in row))
+                continue;
+            const actual = jsType(row[col]);
+            if (!typeMatches(actual, declared)) {
+                failures.push({
+                    rule: 'type',
+                    detail: `"${col}" is ${actual}, expected ${declared}`,
+                    rowIndex: i,
+                });
+            }
+        }
+        for (const [col, re] of Object.entries(compiledPatterns)) {
+            if (!(col in row))
+                continue;
+            const v = row[col];
+            if (v === null || v === undefined)
+                continue;
+            if (!re.test(String(v))) {
+                failures.push({
+                    rule: 'pattern',
+                    detail: `"${col}"=${JSON.stringify(String(v).slice(0, 60))} does not match /${re.source}/`,
+                    rowIndex: i,
+                });
+            }
+        }
+        for (const col of notEmpty) {
+            const v = row[col];
+            if (v === null || v === undefined || String(v).trim() === '') {
+                failures.push({ rule: 'notEmpty', detail: `"${col}" is empty`, rowIndex: i });
+            }
+        }
+        for (const [col, needles] of Object.entries(expect.mustNotContain ?? {})) {
+            if (!(col in row))
+                continue;
+            const v = row[col];
+            if (v === null || v === undefined)
+                continue;
+            const haystack = String(v);
+            for (const needle of needles) {
+                if (haystack.includes(needle)) {
+                    failures.push({
+                        rule: 'mustNotContain',
+                        detail: `"${col}" contains forbidden substring ${JSON.stringify(needle)}`,
+                        rowIndex: i,
+                    });
+                }
+            }
+        }
+        for (const col of expect.mustBeTruthy ?? []) {
+            if (!(col in row))
+                continue;
+            if (!row[col]) {
+                failures.push({
+                    rule: 'mustBeTruthy',
+                    detail: `"${col}" is falsy (${JSON.stringify(row[col])}) — likely silent fallback`,
+                    rowIndex: i,
+                });
+            }
+        }
+    });
+    return failures;
+}
+/**
+ * Convert fixture args into argv tokens appended after the command name.
+ * - Array form is passed through verbatim (stringified), supporting positional subjects.
+ * - Object form is expanded to `--key value` pairs.
+ */
+export function expandFixtureArgs(args) {
+    if (!args)
+        return [];
+    if (Array.isArray(args))
+        return args.map((v) => String(v));
+    const out = [];
+    for (const [k, v] of Object.entries(args)) {
+        out.push(`--${k}`, String(v));
+    }
+    return out;
+}
+function jsType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function typeMatches(actual, declared) {
+    const allowed = declared.split('|').map((s) => s.trim()).filter(Boolean);
+    if (allowed.length === 0)
+        return true;
+    if (allowed.includes('any'))
+        return true;
+    return allowed.includes(actual);
+}

package/dist/src/browser/verify-fixture.test.d.ts

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

package/dist/src/browser/verify-fixture.test.js

@@ -0,0 +1,161 @@
+import { describe, expect, it } from 'vitest';
+import { deriveFixture, expandFixtureArgs, validateRows } from './verify-fixture.js';
+describe('validateRows', () => {
+    it('passes when rows meet all expectations', () => {
+        const fixture = {
+            expect: {
+                rowCount: { min: 1, max: 3 },
+                columns: ['id', 'title', 'url'],
+                types: { id: 'number', title: 'string', url: 'string' },
+                patterns: { url: '^https://' },
+                notEmpty: ['title', 'url'],
+            },
+        };
+        const rows = [
+            { id: 1, title: 'a', url: 'https://x.com/a' },
+            { id: 2, title: 'b', url: 'https://x.com/b' },
+        ];
+        expect(validateRows(rows, fixture)).toEqual([]);
+    });
+    it('reports rowCount below min', () => {
+        const failures = validateRows([], { expect: { rowCount: { min: 1 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'rowCount' });
+        expect(failures[0].detail).toContain('at least 1');
+    });
+    it('reports rowCount above max', () => {
+        const failures = validateRows([{}, {}, {}, {}], { expect: { rowCount: { max: 3 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0].detail).toContain('at most 3');
+    });
+    it('reports missing columns per row', () => {
+        const failures = validateRows([{ a: 1 }, { a: 2, b: 3 }], { expect: { columns: ['a', 'b'] } });
+        // row 0 missing 'b', row 1 complete
+        expect(failures).toEqual([
+            { rule: 'column', detail: 'missing column "b"', rowIndex: 0 },
+        ]);
+    });
+    it('reports type mismatch including null', () => {
+        const failures = validateRows([{ a: 'abc' }, { a: null }, { a: 42 }], { expect: { types: { a: 'string' } } });
+        // row 0 string ok, row 1 null fail, row 2 number fail
+        expect(failures).toHaveLength(2);
+        expect(failures[0].rowIndex).toBe(1);
+        expect(failures[0].detail).toContain('null');
+        expect(failures[1].rowIndex).toBe(2);
+        expect(failures[1].detail).toContain('number');
+    });
+    it('accepts union types like "number|string"', () => {
+        const failures = validateRows([{ id: 1 }, { id: 'abc' }], { expect: { types: { id: 'number|string' } } });
+        expect(failures).toEqual([]);
+    });
+    it('accepts "any" as wildcard type', () => {
+        const failures = validateRows([{ v: 1 }, { v: 'x' }, { v: null }, { v: [1, 2] }], { expect: { types: { v: 'any' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports pattern mismatch with row index and truncated value', () => {
+        const failures = validateRows([{ url: 'https://ok.com' }, { url: 'not-a-url' }], { expect: { patterns: { url: '^https?://' } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'pattern', rowIndex: 1 });
+        expect(failures[0].detail).toContain('not-a-url');
+    });
+    it('skips pattern check for null/undefined values', () => {
+        const failures = validateRows([{ url: null }, { url: undefined }], { expect: { patterns: { url: '^x' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports invalid regex without crashing', () => {
+        const failures = validateRows([{ a: 'x' }], { expect: { patterns: { a: '[unclosed' } } });
+        expect(failures.some((f) => f.rule === 'pattern' && f.detail.includes('invalid'))).toBe(true);
+    });
+    it('treats empty/whitespace/null as failing notEmpty', () => {
+        const failures = validateRows([{ t: '' }, { t: '   ' }, { t: null }, { t: 'ok' }], { expect: { notEmpty: ['t'] } });
+        expect(failures).toHaveLength(3);
+        expect(failures.map((f) => f.rowIndex)).toEqual([0, 1, 2]);
+    });
+    it('no failures when fixture has no expect block', () => {
+        expect(validateRows([{ anything: 1 }], {})).toEqual([]);
+    });
+    it('mustNotContain flags substring bleed in columns', () => {
+        const failures = validateRows([
+            { description: 'Lead engineer, 5 years exp. address: Shanghai. category: IT' },
+            { description: 'Clean text.' },
+        ], {
+            expect: {
+                mustNotContain: { description: ['address:', 'category:'] },
+            },
+        });
+        expect(failures).toHaveLength(2);
+        expect(failures.every((f) => f.rule === 'mustNotContain')).toBe(true);
+        expect(failures.every((f) => f.rowIndex === 0)).toBe(true);
+    });
+    it('mustNotContain skips null/undefined values', () => {
+        const failures = validateRows([{ description: null }, { description: undefined }], { expect: { mustNotContain: { description: ['x'] } } });
+        expect(failures).toEqual([]);
+    });
+    it('mustBeTruthy catches silent 0 / false / "" fallbacks', () => {
+        const failures = validateRows([{ count: 10 }, { count: 0 }, { count: false }, { count: '' }, { count: null }], { expect: { mustBeTruthy: ['count'] } });
+        expect(failures).toHaveLength(4);
+        expect(failures.every((f) => f.rule === 'mustBeTruthy')).toBe(true);
+        expect(failures.map((f) => f.rowIndex)).toEqual([1, 2, 3, 4]);
+    });
+});
+describe('deriveFixture', () => {
+    it('returns rowCount.min=0 when rows are empty', () => {
+        expect(deriveFixture([])).toEqual({ expect: { rowCount: { min: 0 } } });
+    });
+    it('extracts columns from first row and infers types per column', () => {
+        const fixture = deriveFixture([
+            { id: 1, title: 'a', url: 'https://x' },
+            { id: 2, title: 'b', url: 'https://y' },
+        ]);
+        expect(fixture.expect?.columns).toEqual(['id', 'title', 'url']);
+        expect(fixture.expect?.types).toEqual({
+            id: 'number',
+            title: 'string',
+            url: 'string',
+        });
+        expect(fixture.expect?.rowCount).toEqual({ min: 1 });
+    });
+    it('unions mixed types across rows as "a|b"', () => {
+        const fixture = deriveFixture([
+            { v: 1 },
+            { v: 'two' },
+            { v: null },
+        ]);
+        expect(fixture.expect?.types?.v).toBe('null|number|string');
+    });
+    it('embeds args when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], { limit: 5 });
+        expect(fixture.args).toEqual({ limit: 5 });
+    });
+    it('embeds positional argv array when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], ['123', '--limit', '3']);
+        expect(fixture.args).toEqual(['123', '--limit', '3']);
+    });
+    it('does not add patterns or notEmpty automatically', () => {
+        const fixture = deriveFixture([{ a: 'x' }]);
+        expect(fixture.expect?.patterns).toBeUndefined();
+        expect(fixture.expect?.notEmpty).toBeUndefined();
+    });
+});
+describe('expandFixtureArgs', () => {
+    it('returns [] for undefined', () => {
+        expect(expandFixtureArgs(undefined)).toEqual([]);
+    });
+    it('expands object form as --key value pairs', () => {
+        expect(expandFixtureArgs({ limit: 3, sort: 'hot' })).toEqual(['--limit', '3', '--sort', 'hot']);
+    });
+    it('passes array form verbatim, stringifying values', () => {
+        expect(expandFixtureArgs(['123456', '--limit', 3])).toEqual(['123456', '--limit', '3']);
+    });
+    it('handles empty object and empty array', () => {
+        expect(expandFixtureArgs({})).toEqual([]);
+        expect(expandFixtureArgs([])).toEqual([]);
+    });
+    it('preserves positional + flag mix (e.g. <tid> --limit 3)', () => {
+        expect(expandFixtureArgs(['https://example.com/thread-1', '--comments', '5'])).toEqual([
+            'https://example.com/thread-1',
+            '--comments',
+            '5',
+        ]);
+    });
+});

package/dist/src/cli.d.ts

@@ -6,6 +6,38 @@
  */
 import { Command } from 'commander';
 import { findPackageRoot } from './package-paths.js';
+/**
+ * Check whether the site-memory scaffolding exists under
+ * ~/.opencli/sites/<site>/. Agents have a strong tendency to forget to write
+ * endpoints.json / notes.md after a successful verify, which dooms the next
+ * agent to redo recon from scratch. Surfacing the current state as part of
+ * verify's final report converts that "silent skip" into a visible nudge;
+ * `--strict-memory` escalates it to a failure so agents driving a hardened
+ * workflow can't forget.
+ */
+export type SiteMemoryReport = {
+    ok: boolean;
+    siteDir: string;
+    endpoints: {
+        present: boolean;
+        count: number;
+        path: string;
+    };
+    notes: {
+        present: boolean;
+        path: string;
+    };
+};
+export declare function checkSiteMemory(site: string): SiteMemoryReport;
+export declare function printSiteMemoryReport(report: SiteMemoryReport, strict: boolean | undefined): void;
+/** Coerce adapter JSON output into a row array. Accepts `[{...}]`, single `{}`, or `{items:[...]}`-style envelopes. */
+export declare function normalizeVerifyRows(data: unknown): Record<string, unknown>[];
+/** Render up to 10 rows as a compact padded table for eyeball inspection during verify. */
+export declare function renderVerifyPreview(rows: Record<string, unknown>[], opts?: {
+    maxRows?: number;
+    maxCols?: number;
+    cellMax?: number;
+}): string;
 export declare function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command;
 export declare function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void;
 export interface BrowserVerifyInvocation {