@jackwener/opencli 1.7.0 → 1.7.1

package/dist/src/record.js

@@ -14,7 +14,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 import { sendCommand } from './browser/daemon-client.js';
 import { SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES } from './constants.js';
 import { urlToPattern, findArrayPath, inferCapabilityName, inferStrategy, detectAuthFromContent, classifyQueryParams, isNoiseUrl, } from './analysis.js';
@@ -466,10 +466,10 @@ export async function recordSession(opts) {
         }
     })();
     const workspace = `record:${site}`;
-    console.log(chalk.bold.cyan('\n  opencli record'));
-    console.log(chalk.dim(`  Site: ${site}  URL: ${opts.url}`));
-    console.log(chalk.dim(`  Timeout: ${timeoutMs / 1000}s  Poll: ${pollMs}ms`));
-    console.log(chalk.dim('  Navigating…'));
+    console.log(styleText(['bold', 'cyan'], '\n  opencli record'));
+    console.log(styleText('dim', `  Site: ${site}  URL: ${opts.url}`));
+    console.log(styleText('dim', `  Timeout: ${timeoutMs / 1000}s  Poll: ${pollMs}ms`));
+    console.log(styleText('dim', '  Navigating…'));
     const factory = new opts.BrowserFactory();
     const page = await factory.connect({ timeout: 30, workspace });
     try {
@@ -481,8 +481,8 @@ export async function recordSession(opts) {
             if (tab.page)
                 await injectIntoPage(workspace, tab.page, injectedPages);
         }
-        console.log(chalk.bold('\n  Recording. Use the page in the browser automation window.'));
-        console.log(chalk.dim(`  Will auto-stop after ${timeoutMs / 1000}s, or press Enter to stop now.\n`));
+        console.log(styleText('bold', '\n  Recording. Use the page in the browser automation window.'));
+        console.log(styleText('dim', `  Will auto-stop after ${timeoutMs / 1000}s, or press Enter to stop now.\n`));
         // Race: Enter key vs timeout
         let stopped = false;
         const stop = () => { stopped = true; };
@@ -509,7 +509,7 @@ export async function recordSession(opts) {
                     if (Array.isArray(batch) && batch.length > 0) {
                         for (const r of batch)
                             allRequests.push(r);
-                        console.log(chalk.dim(`  [page:${page.slice(0, 8)}] +${batch.length} captured — total: ${allRequests.length}`));
+                        console.log(styleText('dim', `  [page:${page.slice(0, 8)}] +${batch.length} captured — total: ${allRequests.length}`));
                     }
                 }
             }
@@ -531,7 +531,7 @@ export async function recordSession(opts) {
             }
             catch { }
         }
-        console.log(chalk.dim(`\n  Stopped. Analyzing ${allRequests.length} captured requests…`));
+        console.log(styleText('dim', `\n  Stopped. Analyzing ${allRequests.length} captured requests…`));
         const result = analyzeAndWrite(site, opts.url, allRequests, opts.outDir);
         await factory.close().catch(() => { });
         return result;
@@ -558,7 +558,7 @@ async function injectIntoPage(workspace, page, injectedPages) {
         await execOnPage(workspace, page, generateFullCaptureInterceptorJs());
         if (!injectedPages.has(page)) {
             injectedPages.add(page);
-            console.log(chalk.green(`  ✓  Interceptor injected into page:${page.slice(0, 8)}`));
+            console.log(styleText('green', `  ✓  Interceptor injected into page:${page.slice(0, 8)}`));
         }
     }
     catch {
@@ -588,7 +588,7 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
     const targetDir = outDir ?? path.join('.opencli', 'record', site);
     fs.mkdirSync(targetDir, { recursive: true });
     if (requests.length === 0) {
-        console.log(chalk.yellow('  No API requests captured.'));
+        console.log(styleText('yellow', '  No API requests captured.'));
         return { site, url: pageUrl, requests: [], outDir: targetDir, candidateCount: 0, candidates: [] };
     }
     // Score and rank deduplicated requests for console output and candidate generation.
@@ -599,18 +599,18 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
     // Generate candidate YAMLs (top 5)
     const candidates = [];
     const usedNames = new Set();
-    console.log(chalk.bold('\n  Captured endpoints:\n'));
+    console.log(styleText('bold', '\n  Captured endpoints:\n'));
     for (const entry of analysis.candidates.sort((a, b) => (b.arrayResult?.items.length ?? 0) - (a.arrayResult?.items.length ?? 0)).slice(0, 8)) {
         const itemCount = entry.arrayResult?.items.length ?? 0;
         const strategy = entry.kind === 'write'
             ? 'cookie'
             : inferStrategy(detectAuthFromContent(entry.req.url, entry.req.responseBody));
-        const marker = entry.kind === 'write' ? chalk.magenta('✎') : itemCount > 5 ? chalk.green('★') : chalk.dim('·');
-        console.log(`  ${marker} ${chalk.white(urlToPattern(entry.req.url))}` +
-            chalk.dim(` [${strategy}]`) +
+        const marker = entry.kind === 'write' ? styleText('magenta', '✎') : itemCount > 5 ? styleText('green', '★') : styleText('dim', '·');
+        console.log(`  ${marker} ${styleText('white', urlToPattern(entry.req.url))}` +
+            styleText('dim', ` [${strategy}]`) +
             (entry.kind === 'write'
-                ? chalk.magenta(' ← write')
-                : itemCount ? chalk.cyan(` ← ${itemCount} items`) : ''));
+                ? styleText('magenta', ' ← write')
+                : itemCount ? styleText('cyan', ` ← ${itemCount} items`) : ''));
     }
     console.log();
     const topCandidates = generateRecordedCandidates(site, pageUrl, analysisRequests);
@@ -623,12 +623,12 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
         const filePath = path.join(candidatesDir, `${entry.name}.json`);
         fs.writeFileSync(filePath, JSON.stringify(entry.yaml, null, 2));
         candidates.push({ name: entry.name, path: filePath, strategy: entry.strategy });
-        console.log(chalk.green(`  ✓ Generated: ${chalk.bold(entry.name)}.json  [${entry.strategy}]`));
-        console.log(chalk.dim(`    → ${filePath}`));
+        console.log(styleText('green', `  ✓ Generated: ${styleText('bold', entry.name)}.json  [${entry.strategy}]`));
+        console.log(styleText('dim', `    → ${filePath}`));
     }
     if (candidates.length === 0) {
-        console.log(chalk.yellow('  No candidates found.'));
-        console.log(chalk.dim('  Tip: make sure you triggered JSON API calls (open lists, search, scroll).'));
+        console.log(styleText('yellow', '  No candidates found.'));
+        console.log(styleText('dim', '  Tip: make sure you triggered JSON API calls (open lists, search, scroll).'));
     }
     return {
         site,
@@ -641,7 +641,7 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
 }
 export function renderRecordSummary(result) {
     const lines = [
-        `\n  opencli record: ${result.candidateCount > 0 ? chalk.green('OK') : chalk.yellow('no candidates')}`,
+        `\n  opencli record: ${result.candidateCount > 0 ? styleText('green', 'OK') : styleText('yellow', 'no candidates')}`,
         `  Site: ${result.site}`,
         `  Captured: ${result.requests.length} requests`,
         `  Candidates: ${result.candidateCount}`,
@@ -651,7 +651,7 @@ export function renderRecordSummary(result) {
     }
     if (result.candidateCount > 0) {
         lines.push('');
-        lines.push(chalk.dim(`  Copy a candidate to clis/${result.site}/ and run: npm run build`));
+        lines.push(styleText('dim', `  Copy a candidate to clis/${result.site}/ and run: npm run build`));
     }
     return lines.join('\n');
 }

package/dist/src/registry.d.ts

@@ -47,14 +47,19 @@ export interface CliCommand {
     /** Preferred replacement command, if any. */
     replacedBy?: string;
     /**
-     * Control pre-navigation for cookie/header context before command execution.
+     * Control pre-navigation and browser-session requirement.
      *
-     * Browser adapters using COOKIE/HEADER strategy need the page to be on the
-     * target domain so that `fetch(url, { credentials: 'include' })` carries cookies.
+     * After normalizeCommand() expands strategy, this field carries the
+     * resolved runtime intent:
      *
-     * - `undefined` / `true`: navigate to `https://${domain}` (default)
-     * - `false`: skip — adapter handles its own navigation (e.g. boss common.ts)
-     * - `string`: navigate to this specific URL instead of the domain root
+     * - `undefined`: no pre-navigation, browser session decided by pipeline steps
+     * - `false`: explicitly skip pre-navigation (adapter handles its own navigation)
+     * - `true`: needs authenticated browser context but no specific pre-nav URL
+     *   (e.g. INTERCEPT/UI adapters, or COOKIE without domain)
+     * - `string`: pre-navigate to this URL before running the adapter
+     *   (e.g. `'https://x.com'` for COOKIE strategy with domain)
+     *
+     * Adapter authors can set this explicitly to override the strategy-based default.
      */
     navigateBefore?: boolean | string;
     /** Override the default CLI output format when the user does not pass -f/--format. */

package/dist/src/registry.js

@@ -11,17 +11,14 @@ export var Strategy;
 })(Strategy || (Strategy = {}));
 const _registry = globalThis.__opencli_registry__ ??= new Map();
 export function cli(opts) {
-    const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
-    const browser = opts.browser ?? (strategy !== Strategy.PUBLIC);
-    const aliases = normalizeAliases(opts.aliases, opts.name);
     const cmd = {
         site: opts.site,
         name: opts.name,
-        aliases,
+        aliases: opts.aliases,
         description: opts.description ?? '',
         domain: opts.domain,
-        strategy,
-        browser,
+        strategy: opts.strategy,
+        browser: opts.browser,
         args: opts.args ?? [],
         columns: opts.columns,
         func: opts.func,
@@ -35,7 +32,7 @@ export function cli(opts) {
         defaultFormat: opts.defaultFormat,
     };
     registerCommand(cmd);
-    return cmd;
+    return _registry.get(fullName(cmd));
 }
 export function getRegistry() {
     return _registry;
@@ -46,8 +43,39 @@ export function fullName(cmd) {
 export function strategyLabel(cmd) {
     return cmd.strategy ?? Strategy.PUBLIC;
 }
+/**
+ * Normalize a command's runtime fields. This is the single place where
+ * `strategy` is decoded into the concrete fields that the execution path
+ * reads (`browser`, `navigateBefore`). After normalization, execution code
+ * (resolvePreNav, shouldUseBrowserSession) never reads `cmd.strategy`.
+ *
+ * `strategy` itself is preserved as metadata for `opencli list`, cascade
+ * probe, adapter generation, and human documentation.
+ *
+ * Override priority (highest wins):
+ *   1. Explicit field on the command (`browser: false`, `navigateBefore: false`)
+ *   2. Derived from strategy + domain (the defaults below)
+ */
+function normalizeCommand(cmd) {
+    const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
+    const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC);
+    let navigateBefore = cmd.navigateBefore;
+    if (navigateBefore === undefined) {
+        if ((strategy === Strategy.COOKIE || strategy === Strategy.HEADER) && cmd.domain) {
+            navigateBefore = `https://${cmd.domain}`;
+        }
+        else if (strategy !== Strategy.PUBLIC) {
+            // Non-PUBLIC without domain: needs authenticated browser context
+            // but no specific pre-navigation URL. `true` signals this to
+            // shouldUseBrowserSession without triggering resolvePreNav.
+            navigateBefore = true;
+        }
+    }
+    return { ...cmd, strategy, browser, navigateBefore };
+}
 export function registerCommand(cmd) {
-    const canonicalKey = fullName(cmd);
+    const normalized = normalizeCommand(cmd);
+    const canonicalKey = fullName(normalized);
     const existing = _registry.get(canonicalKey);
     if (existing) {
         for (const [key, value] of _registry.entries()) {
@@ -55,11 +83,11 @@ export function registerCommand(cmd) {
                 _registry.delete(key);
         }
     }
-    const aliases = normalizeAliases(cmd.aliases, cmd.name);
-    cmd.aliases = aliases.length > 0 ? aliases : undefined;
-    _registry.set(canonicalKey, cmd);
+    const aliases = normalizeAliases(normalized.aliases, normalized.name);
+    normalized.aliases = aliases.length > 0 ? aliases : undefined;
+    _registry.set(canonicalKey, normalized);
     for (const alias of aliases) {
-        _registry.set(`${cmd.site}/${alias}`, cmd);
+        _registry.set(`${normalized.site}/${alias}`, normalized);
     }
 }
 function normalizeAliases(aliases, commandName) {

package/dist/src/registry.test.js

@@ -111,3 +111,59 @@ describe('registerCommand', () => {
         expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.HEADER);
     });
 });
+describe('normalizeCommand (via registerCommand)', () => {
+    it('COOKIE + domain → navigateBefore is the domain URL', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-domain', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'x.com',
+        });
+        const cmd = getRegistry().get('test-norm/cookie-domain');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe('https://x.com');
+    });
+    it('COOKIE without domain → navigateBefore is true (auth context, no URL)', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-nodomain', description: '', args: [],
+            strategy: Strategy.COOKIE,
+        });
+        const cmd = getRegistry().get('test-norm/cookie-nodomain');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(true);
+    });
+    it('INTERCEPT → navigateBefore is true (auth context)', () => {
+        registerCommand({
+            site: 'test-norm', name: 'intercept', description: '', args: [],
+            strategy: Strategy.INTERCEPT, domain: 'example.com',
+        });
+        const cmd = getRegistry().get('test-norm/intercept');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(true);
+    });
+    it('PUBLIC → browser false, navigateBefore undefined', () => {
+        registerCommand({
+            site: 'test-norm', name: 'public', description: '', args: [],
+            strategy: Strategy.PUBLIC,
+        });
+        const cmd = getRegistry().get('test-norm/public');
+        expect(cmd.browser).toBe(false);
+        expect(cmd.navigateBefore).toBeUndefined();
+    });
+    it('explicit navigateBefore: false overrides COOKIE + domain', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-override', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'amazon.com', navigateBefore: false,
+        });
+        const cmd = getRegistry().get('test-norm/cookie-override');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(false);
+    });
+    it('explicit navigateBefore URL overrides strategy default', () => {
+        registerCommand({
+            site: 'test-norm', name: 'explicit-url', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'x.com',
+            navigateBefore: 'https://x.com/explore',
+        });
+        const cmd = getRegistry().get('test-norm/explicit-url');
+        expect(cmd.navigateBefore).toBe('https://x.com/explore');
+    });
+});

package/dist/src/runtime.js

@@ -1,6 +1,7 @@
 import { BrowserBridge, CDPBridge } from './browser/index.js';
 import { TimeoutError } from './errors.js';
 import { isElectronApp } from './electron-apps.js';
+import { log } from './logger.js';
 /**
  * Returns the appropriate browser factory based on site type.
  * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
@@ -16,7 +17,7 @@ function parseEnvTimeout(envVar, fallback) {
         return fallback;
     const parsed = parseInt(raw, 10);
     if (Number.isNaN(parsed) || parsed <= 0) {
-        console.error(`[runtime] Invalid ${envVar}="${raw}", using default ${fallback}s`);
+        log.warn(`[runtime] Invalid ${envVar}="${raw}", using default ${fallback}s`);
         return fallback;
     }
     return parsed;

package/dist/src/tui.js

@@ -3,7 +3,7 @@
  *
  * Uses raw stdin mode + ANSI escape codes for interactive prompts.
  */
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 import { EXIT_CODES } from './errors.js';
 /**
  * Interactive multi-select checkbox prompt.
@@ -29,28 +29,28 @@ export async function checkboxPrompt(items, opts = {}) {
         if (!status)
             return '';
         switch (color) {
-            case 'green': return chalk.green(status);
-            case 'yellow': return chalk.yellow(status);
-            case 'red': return chalk.red(status);
-            case 'dim': return chalk.dim(status);
-            default: return chalk.dim(status);
+            case 'green': return styleText('green', status);
+            case 'yellow': return styleText('yellow', status);
+            case 'red': return styleText('red', status);
+            case 'dim': return styleText('dim', status);
+            default: return styleText('dim', status);
         }
     }
     function render() {
         // Move cursor to start and clear
         let out = '';
         if (opts.title) {
-            out += `\n${chalk.bold(opts.title)}\n\n`;
+            out += `\n${styleText('bold', opts.title)}\n\n`;
         }
         for (let i = 0; i < state.length; i++) {
             const item = state[i];
-            const pointer = i === cursor ? chalk.cyan('❯') : ' ';
-            const checkbox = item.checked ? chalk.green('◉') : chalk.dim('○');
-            const label = i === cursor ? chalk.bold(item.label) : item.label;
+            const pointer = i === cursor ? styleText('cyan', '❯') : ' ';
+            const checkbox = item.checked ? styleText('green', '◉') : styleText('dim', '○');
+            const label = i === cursor ? styleText('bold', item.label) : item.label;
             const status = colorStatus(item.status, item.statusColor);
             out += `  ${pointer} ${checkbox} ${label}${status ? `  ${status}` : ''}\n`;
         }
-        out += `\n  ${chalk.dim('↑↓ navigate  ·  Space toggle  ·  a all  ·  Enter confirm  ·  q cancel')}\n`;
+        out += `\n  ${styleText('dim', '↑↓ navigate  ·  Space toggle  ·  a all  ·  Enter confirm  ·  q cancel')}\n`;
         return out;
     }
     return new Promise((resolve) => {
@@ -117,14 +117,14 @@ export async function checkboxPrompt(items, opts = {}) {
                 cleanup();
                 const selected = state.filter(i => i.checked).map(i => i.value);
                 // Show summary
-                stdout.write(`  ${chalk.green('✓')} ${chalk.bold(`${selected.length} file(s) selected`)}\n\n`);
+                stdout.write(`  ${styleText('green', '✓')} ${styleText('bold', `${selected.length} file(s) selected`)}\n\n`);
                 resolve(selected);
                 return;
             }
             // q / Esc — cancel
             if (key === 'q' || key === '\x1b') {
                 cleanup();
-                stdout.write(`  ${chalk.yellow('✗')} ${chalk.dim('Cancelled')}\n\n`);
+                stdout.write(`  ${styleText('yellow', '✗')} ${styleText('dim', 'Cancelled')}\n\n`);
                 resolve([]);
                 return;
             }
@@ -149,7 +149,7 @@ export async function confirmPrompt(message, defaultYes = true) {
     if (!stdin.isTTY)
         return defaultYes;
     const hint = defaultYes ? '[Y/n]' : '[y/N]';
-    stdout.write(`  ${message} ${chalk.dim(hint)} `);
+    stdout.write(`  ${message} ${styleText('dim', hint)} `);
     return new Promise((resolve) => {
         const wasRaw = stdin.isRaw;
         stdin.setRawMode(true);

package/dist/src/update-check.js

@@ -11,7 +11,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 import { PKG_VERSION } from './version.js';
 const CACHE_DIR = path.join(os.homedir(), '.opencli');
 const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json');
@@ -72,8 +72,8 @@ export function registerUpdateNoticeOnExit() {
         if (!isNewer(_cache.latestVersion, PKG_VERSION))
             return;
         try {
-            process.stderr.write(chalk.yellow(`\n  Update available: v${PKG_VERSION} → v${_cache.latestVersion}\n`) +
-                chalk.dim(`  Run: npm install -g @jackwener/opencli\n\n`));
+            process.stderr.write(styleText('yellow', `\n  Update available: v${PKG_VERSION} → v${_cache.latestVersion}\n`) +
+                styleText('dim', `  Run: npm install -g @jackwener/opencli\n\n`));
         }
         catch {
             // Ignore broken pipe (stderr closed before process exits)

package/dist/src/validate.d.ts

@@ -1,14 +1,21 @@
-export interface FileValidationResult {
-    path: string;
+export interface CommandValidationResult {
+    /** Display label: "site/name" or source path if available */
+    label: string;
     errors: string[];
     warnings: string[];
 }
 export interface ValidationReport {
     ok: boolean;
-    results: FileValidationResult[];
+    results: CommandValidationResult[];
     errors: number;
     warnings: number;
-    files: number;
+    commands: number;
 }
-export declare function validateClisWithTarget(dirs: string[], target?: string): ValidationReport;
+/**
+ * Validate registered CLI commands from the in-memory registry.
+ *
+ * The `_dirs` parameter is kept for call-site compatibility but is no longer
+ * used — validation now operates on the registry populated by `discoverClis()`.
+ */
+export declare function validateClisWithTarget(_dirs: string[], target?: string): ValidationReport;
 export declare function renderValidationReport(report: ValidationReport): string;

package/dist/src/validate.js

@@ -1,8 +1,5 @@
-/** Validate CLI definitions. */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import yaml from 'js-yaml';
-import { getErrorMessage } from './errors.js';
+/** Validate CLI definitions from the registry (JS-first). */
+import { getRegistry, fullName } from './registry.js';
 /** All recognized pipeline step names */
 const KNOWN_STEP_NAMES = new Set([
     'navigate', 'click', 'type', 'wait', 'press', 'snapshot',
@@ -10,82 +7,114 @@ const KNOWN_STEP_NAMES = new Set([
     'select', 'map', 'filter', 'sort', 'limit',
     'intercept', 'tap', 'download',
 ]);
-import { isRecord } from './utils.js';
-export function validateClisWithTarget(dirs, target) {
+/**
+ * Validate registered CLI commands from the in-memory registry.
+ *
+ * The `_dirs` parameter is kept for call-site compatibility but is no longer
+ * used — validation now operates on the registry populated by `discoverClis()`.
+ */
+export function validateClisWithTarget(_dirs, target) {
+    const registry = getRegistry();
     const results = [];
     let errors = 0;
     let warnings = 0;
-    let files = 0;
-    for (const dir of dirs) {
-        if (!fs.existsSync(dir))
+    if (registry.size === 0) {
+        const r = {
+            label: '(registry)',
+            errors: [],
+            warnings: ['Registry is empty — no commands discovered. Did discoverClis() run?'],
+        };
+        return { ok: true, results: [r], errors: 0, warnings: 1, commands: 0 };
+    }
+    // Resolve alias target: if target is "site/alias", resolve to canonical "site/name"
+    let resolvedTarget = target;
+    if (target?.includes('/')) {
+        const cmd = registry.get(target);
+        if (cmd)
+            resolvedTarget = fullName(cmd);
+    }
+    // Deduplicate: registry maps both canonical "site/name" and aliases to the same command
+    const seen = new Set();
+    for (const [key, cmd] of registry) {
+        if (seen.has(cmd))
+            continue;
+        // Only validate via canonical key to avoid duplicates from aliases
+        if (key !== fullName(cmd))
             continue;
-        for (const site of fs.readdirSync(dir)) {
-            if (target && site !== target && !target.startsWith(site + '/'))
-                continue;
-            const siteDir = path.join(dir, site);
-            if (!fs.statSync(siteDir).isDirectory())
-                continue;
-            for (const file of fs.readdirSync(siteDir)) {
-                if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
+        seen.add(cmd);
+        // Target filter: "site" or "site/name"
+        if (resolvedTarget) {
+            if (resolvedTarget.includes('/')) {
+                if (key !== resolvedTarget)
                     continue;
-                if (target && target.includes('/') && !target.endsWith(file.replace(/\.(yaml|yml)$/, '')))
+            }
+            else {
+                if (cmd.site !== resolvedTarget)
                     continue;
-                files++;
-                const filePath = path.join(siteDir, file);
-                const r = validateYamlFile(filePath);
-                results.push(r);
-                errors += r.errors.length;
-                warnings += r.warnings.length;
             }
         }
+        const r = validateCommand(cmd);
+        results.push(r);
+        errors += r.errors.length;
+        warnings += r.warnings.length;
     }
-    return { ok: errors === 0, results, errors, warnings, files };
+    return { ok: errors === 0, results, errors, warnings, commands: results.length };
 }
-function validateYamlFile(filePath) {
+function validateCommand(cmd) {
+    const label = fullName(cmd);
     const errors = [];
     const warnings = [];
-    try {
-        const raw = fs.readFileSync(filePath, 'utf-8');
-        const def = yaml.load(raw);
-        if (!isRecord(def)) {
-            errors.push('Not a valid YAML object');
-            return { path: filePath, errors, warnings };
-        }
-        if (!def.site)
-            errors.push('Missing "site"');
-        if (!def.name)
-            errors.push('Missing "name"');
-        if (def.pipeline && !Array.isArray(def.pipeline))
-            errors.push('"pipeline" must be an array');
-        if (def.columns && !Array.isArray(def.columns))
-            errors.push('"columns" must be an array');
-        if (def.args && typeof def.args !== 'object')
-            errors.push('"args" must be an object');
-        // Validate pipeline step names (catch typos like 'navaigate')
-        if (Array.isArray(def.pipeline)) {
-            for (let i = 0; i < def.pipeline.length; i++) {
-                const step = def.pipeline[i];
-                if (step && typeof step === 'object') {
-                    const stepKeys = Object.keys(step);
-                    for (const key of stepKeys) {
-                        if (!KNOWN_STEP_NAMES.has(key)) {
-                            warnings.push(`Pipeline step ${i}: unknown step name "${key}" (did you mean one of: ${[...KNOWN_STEP_NAMES].join(', ')}?)`);
-                        }
+    if (!cmd.description)
+        warnings.push('Missing description');
+    // Browser commands should specify a domain for cookie/header context
+    if (cmd.browser && !cmd.domain) {
+        warnings.push('Browser command without "domain" — cookie/header context may not work');
+    }
+    // Pipeline validation: check step names for typos
+    if (Array.isArray(cmd.pipeline)) {
+        for (let i = 0; i < cmd.pipeline.length; i++) {
+            const step = cmd.pipeline[i];
+            if (step && typeof step === 'object') {
+                for (const key of Object.keys(step)) {
+                    if (!KNOWN_STEP_NAMES.has(key)) {
+                        warnings.push(`Pipeline step ${i}: unknown step name "${key}" (did you mean one of: ${[...KNOWN_STEP_NAMES].join(', ')}?)`);
                     }
                 }
             }
         }
     }
-    catch (e) {
-        errors.push(`YAML parse error: ${getErrorMessage(e)}`);
+    // Commands should have either func, pipeline, or be a lazy-loaded module
+    const internal = cmd;
+    if (!cmd.func && !cmd.pipeline && !internal._lazy) {
+        errors.push('Command has neither "func" nor "pipeline" — it cannot execute');
+    }
+    // Arg validation
+    if (cmd.args && cmd.args.length > 0) {
+        const argNames = new Set();
+        let seenNonPositional = false;
+        for (const arg of cmd.args) {
+            if (argNames.has(arg.name)) {
+                errors.push(`Duplicate arg name "${arg.name}"`);
+            }
+            argNames.add(arg.name);
+            if (arg.positional && seenNonPositional) {
+                warnings.push(`Positional arg "${arg.name}" appears after named args`);
+            }
+            if (!arg.positional)
+                seenNonPositional = true;
+        }
     }
-    return { path: filePath, errors, warnings };
+    return { label, errors, warnings };
 }
 export function renderValidationReport(report) {
-    const lines = [`opencli validate: ${report.ok ? 'PASS' : 'FAIL'}`, `Checked ${report.results.length} CLI(s) in ${report.files} file(s)`, `Errors: ${report.errors}  Warnings: ${report.warnings}`];
+    const lines = [
+        `opencli validate: ${report.ok ? 'PASS' : 'FAIL'}`,
+        `Checked ${report.commands} command(s)`,
+        `Errors: ${report.errors}  Warnings: ${report.warnings}`,
+    ];
     for (const r of report.results) {
         if (r.errors.length > 0 || r.warnings.length > 0) {
-            lines.push(`\n${r.path}:`);
+            lines.push(`\n${r.label}:`);
             for (const e of r.errors)
                 lines.push(`  ❌ ${e}`);
             for (const w of r.warnings)

package/dist/src/weixin-download.test.js

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 async function loadModule() {
+    // @ts-expect-error JS adapter — no type declarations
     return import('../clis/weixin/download.js');
 }
 describe('weixin publish time extraction', () => {