@jackwener/opencli 1.7.10 → 1.7.12

package/dist/src/browser/target-resolver.js

@@ -277,12 +277,13 @@ export function resolveTargetJs(ref, opts = {}) {
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export function clickResolvedJs() {
+export function clickResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
     return `
     (() => {
       const el = window.__resolved;
       if (!el) throw new Error('No resolved element');
-      el.scrollIntoView({ behavior: 'instant', block: 'center' });
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center' });
       const rect = el.getBoundingClientRect();
       const x = Math.round(rect.left + rect.width / 2);
       const y = Math.round(rect.top + rect.height / 2);
@@ -331,16 +332,96 @@ export function typeResolvedJs(text) {
     })()
   `;
 }
+/**
+ * Prepare the resolved element for native CDP Input.insertText.
+ *
+ * This preserves `browser type`'s existing "replace current text" semantics:
+ * focus the editable target, select its current contents, then let CDP insert
+ * real browser text input so rich editors can update their internal state.
+ */
+export function prepareNativeTypeResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    const shouldFocus = opts.skipFocus ? 'false' : 'true';
+    return `
+    (() => {
+      const original = window.__resolved;
+      if (!original) throw new Error('No resolved element');
+
+      function nearestContentEditableHost(el) {
+        let current = el;
+        while (current && current.nodeType === 1) {
+          if (current.hasAttribute && current.hasAttribute('contenteditable')) return current;
+          current = current.parentElement;
+        }
+        return el.isContentEditable ? el : null;
+      }
+
+      const editableHost = original.isContentEditable ? nearestContentEditableHost(original) : null;
+      const inputTypes = new Set(['', 'text', 'search', 'url', 'tel', 'email', 'password']);
+      const isInput = original instanceof HTMLInputElement;
+      const isTextarea = original instanceof HTMLTextAreaElement;
+      const isTextControl = isTextarea || (isInput && inputTypes.has((original.getAttribute('type') || original.type || '').toLowerCase()));
+      const el = editableHost || (isTextControl ? original : null);
+
+      if (!el) {
+        return {
+          ok: false,
+          reason: 'not_editable',
+          tag: original.tagName ? original.tagName.toLowerCase() : '',
+        };
+      }
+
+      window.__resolved = el;
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
+      if (${shouldFocus}) {
+        try {
+          el.focus({ preventScroll: true });
+        } catch (_) {
+          el.focus();
+        }
+      }
+
+      if (editableHost) {
+        const sel = window.getSelection();
+        if (!sel) return { ok: false, reason: 'selection_unavailable', mode: 'contenteditable' };
+        const range = document.createRange();
+        range.selectNodeContents(el);
+        sel.removeAllRanges();
+        sel.addRange(range);
+        return { ok: true, mode: 'contenteditable' };
+      }
+
+      let selected = false;
+      try {
+        if (typeof el.setSelectionRange === 'function') {
+          el.setSelectionRange(0, String(el.value || '').length);
+          selected = true;
+        }
+      } catch (_) {}
+      try {
+        if (!selected && typeof el.select === 'function') {
+          el.select();
+          selected = true;
+        }
+      } catch (_) {}
+
+      return selected
+        ? { ok: true, mode: isTextarea ? 'textarea' : 'input' }
+        : { ok: false, reason: 'selection_unavailable', mode: isTextarea ? 'textarea' : 'input' };
+    })()
+  `;
+}
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export function scrollResolvedJs() {
+export function scrollResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
     return `
     (() => {
       const el = window.__resolved;
       if (!el) throw new Error('No resolved element');
-      el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'nearest' });
       return { scrolled: true, tag: el.tagName.toLowerCase(), text: (el.textContent || '').trim().slice(0, 80) };
     })()
   `;

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

@@ -31,11 +31,15 @@ export type Fixture = {
     expect?: FixtureExpect;
 };
 export type ValidationFailure = {
-    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy';
+    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy' | 'shapeKeyCount' | 'shapeDepth' | 'shapeNestedId';
     detail: string;
     rowIndex?: number;
 };
 export type Row = Record<string, unknown>;
+export type RowShapeOptions = {
+    maxTopLevelKeys?: number;
+    maxNestedDepth?: number;
+};
 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;
@@ -51,9 +55,11 @@ export declare function writeFixture(site: string, command: string, fixture: Fix
  */
 export declare function deriveFixture(rows: Row[], args?: FixtureArgs): Fixture;
 export declare function validateRows(rows: Row[], fixture: Fixture): ValidationFailure[];
+export declare function validateRowShape(rows: Row[], opts?: RowShapeOptions): 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[];
+export declare function parseSeedArgs(raw: string | undefined): FixtureArgs | undefined;

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

@@ -30,6 +30,26 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+const DEFAULT_MAX_TOP_LEVEL_KEYS = 12;
+const DEFAULT_MAX_NESTED_DEPTH = 1;
+const ID_SHAPED_KEY_PATTERNS = [
+    /^id$/i,
+    /_id$/i,
+    /Id$/,
+    /^short_id$/i,
+    /^bvid$/i,
+    /^aid$/i,
+    /^tid$/i,
+    /^asin$/i,
+    /^sku$/i,
+    /^isbn$/i,
+    /^doi$/i,
+    /^slug$/i,
+    /^hn_id$/i,
+    /^username$/i,
+    /^handle$/i,
+    /^uri$/i,
+];
 export function fixturePath(site, command) {
     return path.join(os.homedir(), '.opencli', 'sites', site, 'verify', `${command}.json`);
 }
@@ -180,6 +200,39 @@ export function validateRows(rows, fixture) {
     });
     return failures;
 }
+export function validateRowShape(rows, opts = {}) {
+    const failures = [];
+    const maxTopLevelKeys = opts.maxTopLevelKeys ?? DEFAULT_MAX_TOP_LEVEL_KEYS;
+    const maxNestedDepth = opts.maxNestedDepth ?? DEFAULT_MAX_NESTED_DEPTH;
+    rows.forEach((row, i) => {
+        const keys = Object.keys(row);
+        if (keys.length > maxTopLevelKeys) {
+            failures.push({
+                rule: 'shapeKeyCount',
+                detail: `row has ${keys.length} top-level keys, expected at most ${maxTopLevelKeys}`,
+                rowIndex: i,
+            });
+        }
+        for (const [key, value] of Object.entries(row)) {
+            const depth = nestedDepth(value);
+            if (depth > maxNestedDepth) {
+                failures.push({
+                    rule: 'shapeDepth',
+                    detail: `"${key}" nesting depth is ${depth}, expected at most ${maxNestedDepth}`,
+                    rowIndex: i,
+                });
+            }
+            for (const path of nestedIdPaths(value, key)) {
+                failures.push({
+                    rule: 'shapeNestedId',
+                    detail: `id-shaped field "${path}" must be a top-level row key`,
+                    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.
@@ -196,6 +249,24 @@ export function expandFixtureArgs(args) {
     }
     return out;
 }
+export function parseSeedArgs(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed !== null && typeof parsed === 'object')
+            return parsed;
+        return [parsed];
+    }
+    catch {
+        return [raw];
+    }
+}
 function jsType(v) {
     if (v === null)
         return 'null';
@@ -203,6 +274,40 @@ function jsType(v) {
         return 'array';
     return typeof v;
 }
+function nestedDepth(value) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return 0;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 1;
+        return 1 + Math.max(...value.map(nestedDepth));
+    }
+    const values = Object.values(value);
+    if (values.length === 0)
+        return 1;
+    return 1 + Math.max(...values.map(nestedDepth));
+}
+function nestedIdPaths(value, prefix) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return [];
+    const paths = [];
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            paths.push(...nestedIdPaths(item, `${prefix}[${index}]`));
+        });
+        return paths;
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        const childPath = `${prefix}.${key}`;
+        if (isIdShapedKey(key))
+            paths.push(childPath);
+        paths.push(...nestedIdPaths(nested, childPath));
+    }
+    return paths;
+}
+function isIdShapedKey(key) {
+    return ID_SHAPED_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
 function typeMatches(actual, declared) {
     const allowed = declared.split('|').map((s) => s.trim()).filter(Boolean);
     if (allowed.length === 0)

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { deriveFixture, expandFixtureArgs, validateRows } from './verify-fixture.js';
+import { deriveFixture, expandFixtureArgs, parseSeedArgs, validateRows, validateRowShape } from './verify-fixture.js';
 describe('validateRows', () => {
     it('passes when rows meet all expectations', () => {
         const fixture = {
@@ -98,6 +98,49 @@ describe('validateRows', () => {
         expect(failures.map((f) => f.rowIndex)).toEqual([1, 2, 3, 4]);
     });
 });
+describe('validateRowShape', () => {
+    it('passes flat rows with a compact key set', () => {
+        const failures = validateRowShape([
+            { id: '1', title: 'A', author: { name: 'Ada' }, tags: ['ai', 'web'] },
+        ]);
+        expect(failures).toEqual([]);
+    });
+    it('reports rows with too many top-level keys', () => {
+        const row = Object.fromEntries(Array.from({ length: 13 }, (_, i) => [`k${i}`, i]));
+        const failures = validateRowShape([row]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeKeyCount',
+                detail: 'row has 13 top-level keys, expected at most 12',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nesting deeper than one level', () => {
+        const failures = validateRowShape([
+            { title: 'A', stats: { author: { name: 'Ada' } } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeDepth',
+                detail: '"stats" nesting depth is 2, expected at most 1',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nested id-shaped fields even when one-level nesting is otherwise allowed', () => {
+        const failures = validateRowShape([
+            { title: 'A', author: { user_id: 'u1', name: 'Ada' } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeNestedId',
+                detail: 'id-shaped field "author.user_id" must be a top-level row key',
+                rowIndex: 0,
+            },
+        ]);
+    });
+});
 describe('deriveFixture', () => {
     it('returns rowCount.min=0 when rows are empty', () => {
         expect(deriveFixture([])).toEqual({ expect: { rowCount: { min: 0 } } });
@@ -159,3 +202,18 @@ describe('expandFixtureArgs', () => {
         ]);
     });
 });
+describe('parseSeedArgs', () => {
+    it('treats plain text as one positional arg', () => {
+        expect(parseSeedArgs('opencli-verify')).toEqual(['opencli-verify']);
+    });
+    it('accepts JSON array seed args', () => {
+        expect(parseSeedArgs('["subject", "--limit", 3]')).toEqual(['subject', '--limit', 3]);
+    });
+    it('accepts JSON object seed args', () => {
+        expect(parseSeedArgs('{"limit":3,"sort":"hot"}')).toEqual({ limit: 3, sort: 'hot' });
+    });
+    it('ignores empty input', () => {
+        expect(parseSeedArgs(undefined)).toBeUndefined();
+        expect(parseSeedArgs('   ')).toBeUndefined();
+    });
+});

package/dist/src/build-manifest.d.ts

@@ -5,41 +5,76 @@
  * Scans all JS CLI definitions in clis/ and pre-compiles them into a single
  * manifest.json for instant cold-start registration.
  *
- * Usage: npx tsx src/build-manifest.ts
+ * Usage: npx tsx src/build-manifest.ts [--allow-removals[=N]]
+ *
  * Output: cli-manifest.json next to clis/
+ *
+ * Safety invariants:
+ *   - Adapters whose source file does not call `cli(...)` are silently
+ *     skipped (they are helpers / type modules, not commands).
+ *   - Adapters that look like commands but fail to import are reported as
+ *     failures, the manifest is NOT written, and the process exits 1. This
+ *     prevents a stale dist or a broken adapter from silently dropping
+ *     other adapters' entries (root cause of the "manifest lost 478 lines"
+ *     incident).
+ *   - Net-deletions vs the existing committed manifest abort the build by
+ *     default; pass `--allow-removals=N` (or just `--allow-removals` for any
+ *     amount) to confirm an intentional removal.
+ */
+import type { ManifestEntry } from './manifest-types.js';
+export type { ManifestEntry } from './manifest-types.js';
+/**
+ * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
+ * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
+ * decide whether to abort or aggregate failures across the whole scan.
  */
-export interface ManifestEntry {
-    site: string;
-    name: string;
-    aliases?: string[];
-    description: string;
-    domain?: string;
-    strategy: string;
-    browser: boolean;
-    args: Array<{
-        name: string;
-        type?: string;
-        default?: unknown;
-        required?: boolean;
-        valueRequired?: boolean;
-        positional?: boolean;
-        help?: string;
-        choices?: string[];
-    }>;
-    columns?: string[];
-    pipeline?: Record<string, unknown>[];
-    timeout?: number;
-    deprecated?: boolean | string;
-    replacedBy?: string;
-    type: 'js';
-    /** Relative path from clis/ dir, e.g. 'bilibili/search.js' */
-    modulePath?: string;
-    /** Relative path to the source file from clis/ dir (e.g. 'site/cmd.js') */
-    sourceFile?: string;
-    /** Pre-navigation control — see CliCommand.navigateBefore */
-    navigateBefore?: boolean | string;
+export declare class ManifestImportError extends Error {
+    readonly filePath: string;
+    readonly cause: unknown;
+    constructor(filePath: string, cause: unknown);
+}
+export interface BuildManifestResult {
+    entries: ManifestEntry[];
+    /** Adapters that look like CLI modules but failed to import. */
+    failures: ManifestImportError[];
+}
+export interface BuildManifestArgs {
+    /** Maximum number of entries that may be removed vs the existing manifest.
+     *  `Number.POSITIVE_INFINITY` disables the safety net entirely. */
+    allowRemovals: number;
 }
 export declare function normalizeManifestPath(relativePath: string): string;
-export declare function loadManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<ManifestEntry[]>;
-export declare function buildManifest(): Promise<ManifestEntry[]>;
+/**
+ * Load all manifest entries from a single adapter file.
+ *
+ * Returns `[]` for files that do not register a CLI command (helpers, types).
+ * Throws `ManifestImportError` when a file looks like a CLI module but its
+ * import or post-import processing fails — callers must decide whether to
+ * surface or aggregate the failure.
+ *
+ * The third argument `clisDir` is used to compute the POSIX-style
+ * `sourceFile` relative path; it defaults to the package's `clis/` dir so
+ * existing test callers stay backward-compatible.
+ */
+export declare function loadManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>, clisDir?: string): Promise<ManifestEntry[]>;
+/**
+ * Scan a `clis/` directory and aggregate per-adapter results. Import
+ * failures are collected in `failures` instead of crashing the whole scan,
+ * but the caller (e.g. `main()`) is expected to fail loud if any failure
+ * is present.
+ */
+export declare function scanClisDir(clisDir: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<BuildManifestResult>;
+export declare function buildManifest(): Promise<BuildManifestResult>;
 export declare function serializeManifest(manifest: ManifestEntry[]): string;
+/**
+ * Diff helper: returns site/name keys that exist in `prev` but not in
+ * `next`. Used as a safety net to detect accidental mass-deletions caused
+ * by silently failing adapter imports.
+ */
+export declare function diffRemovedEntries(prev: readonly ManifestEntry[], next: readonly ManifestEntry[]): string[];
+/**
+ * Parse `--allow-removals` and `--allow-removals=N` from argv.
+ * Bare `--allow-removals` disables the safety net (`Infinity`); the
+ * numeric form sets an explicit upper bound.
+ */
+export declare function parseBuildManifestArgs(argv: readonly string[]): BuildManifestArgs;