@jackwener/opencli 1.7.11 → 1.7.13

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

@@ -15,6 +15,7 @@
  *   - selector_not_found:     0 matches
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
+ *   - not_editable:           target exists but cannot accept text input
  */
 export class TargetError extends Error {
     code;

package/dist/src/browser/target-resolver.d.ts

@@ -72,11 +72,32 @@ export declare function resolveTargetJs(ref: string, opts?: ResolveOptions): str
  * Generate JS for click that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function clickResolvedJs(): string;
+export declare function clickResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS for type that uses the unified resolver.
  */
 export declare function typeResolvedJs(text: string): string;
+export type FillResolvedResult = {
+    ok: true;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    reason: string;
+    tag?: string;
+    type?: string;
+    role?: string;
+};
 /**
  * Prepare the resolved element for native CDP Input.insertText.
  *
@@ -84,12 +105,23 @@ export declare function typeResolvedJs(text: string): string;
  * 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 declare function prepareNativeTypeResolvedJs(): string;
+export declare function prepareNativeTypeResolvedJs(opts?: {
+    skipScroll?: boolean;
+    skipFocus?: boolean;
+}): string;
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export declare function verifyFilledResolvedJs(expected: string): string;
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.
  */
-export declare function scrollResolvedJs(): string;
+export declare function scrollResolvedJs(opts?: {
+    skipScroll?: boolean;
+}): string;
 /**
  * Generate JS to get text content of resolved element.
  */

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);
@@ -338,7 +339,9 @@ export function typeResolvedJs(text) {
  * 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() {
+export function prepareNativeTypeResolvedJs(opts = {}) {
+    const shouldScroll = opts.skipScroll ? 'false' : 'true';
+    const shouldFocus = opts.skipFocus ? 'false' : 'true';
     return `
     (() => {
       const original = window.__resolved;
@@ -369,11 +372,13 @@ export function prepareNativeTypeResolvedJs() {
       }
 
       window.__resolved = el;
-      el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
-      try {
-        el.focus({ preventScroll: true });
-      } catch (_) {
-        el.focus();
+      if (${shouldScroll}) el.scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
+      if (${shouldFocus}) {
+        try {
+          el.focus({ preventScroll: true });
+        } catch (_) {
+          el.focus();
+        }
       }
 
       if (editableHost) {
@@ -406,16 +411,60 @@ export function prepareNativeTypeResolvedJs() {
     })()
   `;
 }
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export function verifyFilledResolvedJs(expected) {
+    const safeText = JSON.stringify(expected);
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) return { ok: false, reason: 'no_resolved_element' };
+
+      const tag = el.tagName ? el.tagName.toLowerCase() : '';
+      const isInput = el instanceof HTMLInputElement;
+      const isTextarea = el instanceof HTMLTextAreaElement;
+      const mode = el.isContentEditable
+        ? 'contenteditable'
+        : isTextarea
+          ? 'textarea'
+          : isInput
+            ? 'input'
+            : '';
+
+      if (!mode) {
+        return {
+          ok: false,
+          reason: 'not_editable',
+          tag,
+          role: el.getAttribute ? (el.getAttribute('role') || '') : '',
+        };
+      }
+
+      const actual = mode === 'contenteditable' ? (el.innerText || '') : String(el.value || '');
+      return {
+        ok: actual === ${safeText},
+        actual,
+        expected: ${safeText},
+        length: actual.length,
+        mode,
+      };
+    })()
+  `;
+}
 /**
  * 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,6 +55,7 @@ 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.

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.
@@ -221,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, parseSeedArgs, 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 } } });

package/dist/src/build-manifest.js

@@ -32,7 +32,13 @@ const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
-const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+// Module is treated as a CLI command source if it either:
+//   1. Calls `cli(...)` directly (the common case), or
+//   2. Calls a factory `make<Pascal>Command(...)` from clis/_shared/ that
+//      wraps `cli(...)`. Without (2), shared-factory adapters
+//      (codex/cursor/chatwise new/status/dump/screenshot) match no `cli(`
+//      token at the top level and silently drop out of the manifest.
+const CLI_MODULE_PATTERN = /\bcli\s*\(|\bmake[A-Z]\w*Command\s*\(/;
 /**
  * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
  * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
@@ -75,6 +81,7 @@ function isCliCommandValue(value, site) {
         && typeof value.site === 'string'
         && value.site === site
         && typeof value.name === 'string'
+        && (value.access === 'read' || value.access === 'write')
         && Array.isArray(value.args);
 }
 function toManifestEntry(cmd, modulePath, sourceFile) {
@@ -83,18 +90,19 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         name: cmd.name,
         aliases: cmd.aliases,
         description: cmd.description ?? '',
+        access: cmd.access,
+        example: cmd.example,
         domain: cmd.domain,
         strategy: (cmd.strategy ?? 'public').toString().toLowerCase(),
         browser: cmd.browser ?? true,
         args: toManifestArgs(cmd.args),
         columns: cmd.columns,
-        timeout: cmd.timeoutSeconds,
-        deprecated: cmd.deprecated,
-        replacedBy: cmd.replacedBy,
+        defaultFormat: cmd.defaultFormat,
         type: 'js',
         modulePath,
         sourceFile,
         navigateBefore: cmd.navigateBefore,
+        browserSession: cmd.browserSession,
     };
 }
 /**

package/dist/src/build-manifest.test.js

@@ -24,11 +24,12 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'dynamic' });`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'dynamic', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => ({
             command: cli({
                 site,
                 name: 'dynamic',
+                access: 'read',
                 description: 'dynamic command',
                 strategy: Strategy.PUBLIC,
                 browser: false,
@@ -45,14 +46,14 @@ describe('manifest helper rules', () => {
                 ],
                 domain: 'localhost',
                 navigateBefore: 'https://example.com/session',
-                deprecated: 'legacy command',
-                replacedBy: 'opencli demo new',
+                defaultFormat: 'plain',
             }),
         }));
         expect(entries).toMatchObject([
             {
                 site,
                 name: 'dynamic',
+                access: 'read',
                 description: 'dynamic command',
                 domain: 'localhost',
                 strategy: 'public',
@@ -72,8 +73,7 @@ describe('manifest helper rules', () => {
                 type: 'js',
                 modulePath: `${site}/${site}.js`,
                 navigateBefore: 'https://example.com/session',
-                deprecated: 'legacy command',
-                replacedBy: 'opencli demo new',
+                defaultFormat: 'plain',
             },
         ]);
         // Verify sourceFile is included and stable for manifest consumers.
@@ -87,14 +87,13 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `cli({ site: '${site}', name: 'legacy' });`);
+        fs.writeFileSync(file, `cli({ site: '${site}', name: 'legacy', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => {
             cli({
                 site,
                 name: 'legacy',
+                access: 'read',
                 description: 'legacy command',
-                deprecated: 'legacy is deprecated',
-                replacedBy: 'opencli demo new',
             });
             return {};
         });
@@ -102,14 +101,13 @@ describe('manifest helper rules', () => {
             {
                 site,
                 name: 'legacy',
+                access: 'read',
                 description: 'legacy command',
                 strategy: 'cookie',
                 browser: true,
                 args: [],
                 type: 'js',
                 modulePath: `${site}/${site}.js`,
-                deprecated: 'legacy is deprecated',
-                replacedBy: 'opencli demo new',
             },
         ]);
         // Verify sourceFile is included
@@ -123,16 +121,18 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
         tempDirs.push(dir);
         const file = path.join(dir, `${site}.ts`);
-        fs.writeFileSync(file, `export const screen = cli({ site: '${site}', name: 'screen' });`);
+        fs.writeFileSync(file, `export const screen = cli({ site: '${site}', name: 'screen', access: 'read' });`);
         const entries = await loadManifestEntries(file, site, async () => ({
             screen: cli({
                 site,
                 name: 'screen',
+                access: 'read',
                 description: 'capture screen',
             }),
             status: cli({
                 site,
                 name: 'status',
+                access: 'read',
                 description: 'show status',
             }),
         }));
@@ -147,7 +147,7 @@ describe('manifest helper rules', () => {
     it('serializes manifest json with a trailing newline', () => {
         const serialized = serializeManifest([{
                 site: 'demo',
-                name: 'status',
+                name: 'status', access: 'read',
                 description: '',
                 strategy: 'public',
                 browser: false,
@@ -164,7 +164,7 @@ describe('manifest helper rules', () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-fail-'));
         tempDirs.push(dir);
         const file = path.join(dir, 'broken.ts');
-        fs.writeFileSync(file, `export const command = cli({ site: 'demo', name: 'broken' });`);
+        fs.writeFileSync(file, `export const command = cli({ site: 'demo', name: 'broken', access: 'read' });`);
         const importer = async () => { throw new Error('boom: stale dist'); };
         await expect(loadManifestEntries(file, 'demo', importer))
             .rejects.toBeInstanceOf(ManifestImportError);
@@ -194,12 +194,12 @@ describe('manifest helper rules', () => {
         tempDirs.push(root);
         const siteDir = path.join(root, 'demo');
         fs.mkdirSync(siteDir);
-        fs.writeFileSync(path.join(siteDir, 'good.js'), `export const cmd = cli({ site: 'demo', name: 'good' });`);
-        fs.writeFileSync(path.join(siteDir, 'broken.js'), `export const cmd = cli({ site: 'demo', name: 'broken' });`);
+        fs.writeFileSync(path.join(siteDir, 'good.js'), `export const cmd = cli({ site: 'demo', name: 'good', access: 'read' });`);
+        fs.writeFileSync(path.join(siteDir, 'broken.js'), `export const cmd = cli({ site: 'demo', name: 'broken', access: 'read' });`);
         const importer = async (href) => {
             if (href.endsWith('broken.js'))
                 throw new Error('stale dist drops broken');
-            return { cmd: cli({ site: 'demo', name: 'good', description: 'ok' }) };
+            return { cmd: cli({ site: 'demo', name: 'good', access: 'read', description: 'ok' }) };
         };
         const result = await scanClisDir(root, importer);
         expect(result.failures).toHaveLength(1);
@@ -211,12 +211,12 @@ describe('manifest helper rules', () => {
     });
     it('diffRemovedEntries returns site/name keys present only in prev', () => {
         const prev = [
-            { site: 'a', name: '1', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
-            { site: 'a', name: '2', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
-            { site: 'b', name: '3', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '2', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'b', name: '3', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
         ];
         const next = [
-            { site: 'a', name: '1', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
+            { site: 'a', name: '1', access: 'read', description: '', strategy: 'public', browser: false, args: [], type: 'js' },
         ];
         expect(diffRemovedEntries(prev, next)).toEqual(['a/2', 'b/3']);
         expect(diffRemovedEntries(prev, prev)).toEqual([]);

package/dist/src/capabilityRouting.d.ts

@@ -1,4 +1,19 @@
 import type { CliCommand } from './registry.js';
-/** Pipeline steps that require a live browser session. */
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
 export declare const BROWSER_ONLY_STEPS: Set<string>;
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export declare function _validateBrowserOnlyStepsAgainstRegistry(): {
+    extras: string[];
+};
 export declare function shouldUseBrowserSession(cmd: CliCommand): boolean;

package/dist/src/capabilityRouting.js

@@ -1,8 +1,21 @@
-/** Pipeline steps that require a live browser session. */
+import { getRegisteredStepNames } from './pipeline/registry.js';
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
 export const BROWSER_ONLY_STEPS = new Set([
     'navigate',
     'click',
     'type',
+    'fill',
     'wait',
     'press',
     'snapshot',
@@ -10,6 +23,16 @@ export const BROWSER_ONLY_STEPS = new Set([
     'intercept',
     'tap',
 ]);
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export function _validateBrowserOnlyStepsAgainstRegistry() {
+    const registered = new Set(getRegisteredStepNames());
+    const extras = [];
+    for (const step of BROWSER_ONLY_STEPS) {
+        if (!registered.has(step))
+            extras.push(step);
+    }
+    return { extras };
+}
 function pipelineNeedsBrowserSession(pipeline) {
     return pipeline.some((step) => {
         if (!step || typeof step !== 'object')

package/dist/src/capabilityRouting.test.js

@@ -1,10 +1,11 @@
 import { describe, expect, it } from 'vitest';
 import { Strategy } from './registry.js';
-import { shouldUseBrowserSession } from './capabilityRouting.js';
+import { BROWSER_ONLY_STEPS, _validateBrowserOnlyStepsAgainstRegistry, shouldUseBrowserSession } from './capabilityRouting.js';
+import { getRegisteredStepNames } from './pipeline/registry.js';
 function makeCmd(partial) {
     return {
         site: 'test',
-        name: 'command',
+        name: 'command', access: 'read',
         description: '',
         args: [],
         ...partial,
@@ -42,4 +43,21 @@ describe('shouldUseBrowserSession', () => {
             func: async () => [],
         }))).toBe(true);
     });
+    it('routes pipelines containing the fill step into a browser session', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            pipeline: [{ navigate: 'https://example.com' }, { fill: { ref: '#q', text: 'hello' } }],
+        }))).toBe(true);
+    });
+});
+describe('BROWSER_ONLY_STEPS / pipeline registry alignment', () => {
+    it('is a subset of registered pipeline step names', () => {
+        const { extras } = _validateBrowserOnlyStepsAgainstRegistry();
+        expect(extras).toEqual([]);
+    });
+    it('includes fill (DOM-touching step added in PR #1222)', () => {
+        expect(BROWSER_ONLY_STEPS.has('fill')).toBe(true);
+        expect(getRegisteredStepNames()).toContain('fill');
+    });
 });