@jackwener/opencli 1.6.1 → 1.6.3

package/dist/src/build-manifest.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Build-time CLI manifest compiler.
+ *
+ * Scans all YAML/TS CLI definitions and pre-compiles them into a single
+ * manifest.json for instant cold-start registration (no runtime YAML parsing).
+ *
+ * Usage: npx tsx src/build-manifest.ts
+ * Output: dist/cli-manifest.json
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { getErrorMessage } from './errors.js';
+import { fullName, getRegistry } from './registry.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLIS_DIR = path.resolve(__dirname, '..', 'clis');
+const OUTPUT = path.resolve(__dirname, '..', 'cli-manifest.json');
+import { parseYamlArgs } from './yaml-schema.js';
+import { isRecord } from './utils.js';
+const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+function toManifestArgs(args) {
+    return args.map(arg => ({
+        name: arg.name,
+        type: arg.type ?? 'str',
+        default: arg.default,
+        required: !!arg.required,
+        valueRequired: !!arg.valueRequired || undefined,
+        positional: arg.positional || undefined,
+        help: arg.help ?? '',
+        choices: arg.choices,
+    }));
+}
+function toTsModulePath(filePath, site) {
+    const baseName = path.basename(filePath, path.extname(filePath));
+    return `${site}/${baseName}.js`;
+}
+function isCliCommandValue(value, site) {
+    return isRecord(value)
+        && typeof value.site === 'string'
+        && value.site === site
+        && typeof value.name === 'string'
+        && Array.isArray(value.args);
+}
+function toManifestEntry(cmd, modulePath) {
+    return {
+        site: cmd.site,
+        name: cmd.name,
+        aliases: cmd.aliases,
+        description: cmd.description ?? '',
+        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,
+        type: 'ts',
+        modulePath,
+        navigateBefore: cmd.navigateBefore,
+    };
+}
+function scanYaml(filePath, site) {
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const def = yaml.load(raw);
+        if (!isRecord(def))
+            return null;
+        const cliDef = def;
+        const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
+        const strategy = strategyStr.toUpperCase();
+        const browser = cliDef.browser ?? (strategy !== 'PUBLIC');
+        const args = parseYamlArgs(cliDef.args);
+        return {
+            site: cliDef.site ?? site,
+            name: cliDef.name ?? path.basename(filePath, path.extname(filePath)),
+            description: cliDef.description ?? '',
+            domain: cliDef.domain,
+            strategy: strategy.toLowerCase(),
+            browser,
+            aliases: isRecord(cliDef) && Array.isArray(cliDef.aliases)
+                ? cliDef.aliases.filter((value) => typeof value === 'string')
+                : undefined,
+            args,
+            columns: cliDef.columns,
+            pipeline: cliDef.pipeline,
+            timeout: cliDef.timeout,
+            deprecated: cliDef.deprecated,
+            replacedBy: cliDef.replacedBy,
+            type: 'yaml',
+            navigateBefore: cliDef.navigateBefore,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`Warning: failed to parse ${filePath}: ${getErrorMessage(err)}\n`);
+        return null;
+    }
+}
+export async function loadTsManifestEntries(filePath, site, importer = moduleHref => import(moduleHref)) {
+    try {
+        const src = fs.readFileSync(filePath, 'utf-8');
+        // Helper/test modules should not appear as CLI commands in the manifest.
+        if (!CLI_MODULE_PATTERN.test(src))
+            return [];
+        const modulePath = toTsModulePath(filePath, site);
+        const registry = getRegistry();
+        const before = new Map(registry.entries());
+        const mod = await importer(pathToFileURL(filePath).href);
+        const exportedCommands = Object.values(isRecord(mod) ? mod : {})
+            .filter(value => isCliCommandValue(value, site));
+        const runtimeCommands = exportedCommands.length > 0
+            ? exportedCommands
+            : [...registry.entries()]
+                .filter(([key, cmd]) => {
+                if (cmd.site !== site)
+                    return false;
+                const previous = before.get(key);
+                return !previous || previous !== cmd;
+            })
+                .map(([, cmd]) => cmd);
+        const seen = new Set();
+        return runtimeCommands
+            .filter((cmd) => {
+            const key = fullName(cmd);
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        })
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(cmd => toManifestEntry(cmd, modulePath));
+    }
+    catch (err) {
+        // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
+        process.stderr.write(`Warning: failed to scan ${filePath}: ${getErrorMessage(err)}\n`);
+        return [];
+    }
+}
+/**
+ * When both YAML and TS adapters exist for the same site/name,
+ * prefer the TS version (it self-registers and typically has richer logic).
+ */
+export function shouldReplaceManifestEntry(current, next) {
+    if (current.type === next.type)
+        return false;
+    return current.type === 'yaml' && next.type === 'ts';
+}
+export async function buildManifest() {
+    const manifest = new Map();
+    if (fs.existsSync(CLIS_DIR)) {
+        for (const site of fs.readdirSync(CLIS_DIR)) {
+            const siteDir = path.join(CLIS_DIR, site);
+            if (!fs.statSync(siteDir).isDirectory())
+                continue;
+            for (const file of fs.readdirSync(siteDir)) {
+                const filePath = path.join(siteDir, file);
+                if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                    const entry = scanYaml(filePath, site);
+                    if (entry) {
+                        const key = `${entry.site}/${entry.name}`;
+                        const existing = manifest.get(key);
+                        if (!existing || shouldReplaceManifestEntry(existing, entry)) {
+                            if (existing && existing.type !== entry.type) {
+                                process.stderr.write(`⚠️  Duplicate adapter ${key}: ${existing.type} superseded by ${entry.type}\n`);
+                            }
+                            manifest.set(key, entry);
+                        }
+                    }
+                }
+                else if ((file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts') && file !== 'index.ts') ||
+                    (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js')) {
+                    const entries = await loadTsManifestEntries(filePath, site);
+                    for (const entry of entries) {
+                        const key = `${entry.site}/${entry.name}`;
+                        const existing = manifest.get(key);
+                        if (!existing || shouldReplaceManifestEntry(existing, entry)) {
+                            if (existing && existing.type !== entry.type) {
+                                process.stderr.write(`⚠️  Duplicate adapter ${key}: ${existing.type} superseded by ${entry.type}\n`);
+                            }
+                            manifest.set(key, entry);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
+}
+async function main() {
+    const manifest = await buildManifest();
+    fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+    fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
+    const yamlCount = manifest.filter(e => e.type === 'yaml').length;
+    const tsCount = manifest.filter(e => e.type === 'ts').length;
+    console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);
+    // Restore executable permissions on bin entries.
+    // tsc does not preserve the +x bit, so after a clean rebuild the CLI
+    // entry-point loses its executable permission, causing "Permission denied".
+    // See: https://github.com/jackwener/opencli/issues/446
+    if (process.platform !== 'win32') {
+        const projectRoot = path.resolve(__dirname, '..', '..');
+        const pkgPath = path.resolve(projectRoot, 'package.json');
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const bins = typeof pkg.bin === 'string'
+                ? { [pkg.name ?? 'cli']: pkg.bin }
+                : pkg.bin ?? {};
+            for (const binPath of Object.values(bins)) {
+                const abs = path.resolve(projectRoot, binPath);
+                if (fs.existsSync(abs)) {
+                    fs.chmodSync(abs, 0o755);
+                    console.log(`✅ Restored executable permission: ${binPath}`);
+                }
+            }
+        }
+        catch {
+            // Best-effort; never break the build for a permission fix.
+        }
+    }
+}
+const entrypoint = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;
+if (entrypoint === import.meta.url) {
+    void main();
+}

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

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

package/dist/src/capabilityRouting.test.d.ts

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

package/dist/src/cascade.js

@@ -0,0 +1,134 @@
+/**
+ * Strategy Cascade: automatic strategy downgrade chain.
+ *
+ * Probes an API endpoint starting from the simplest strategy (PUBLIC)
+ * and automatically downgrades through the strategy tiers until one works:
+ *
+ *   PUBLIC → COOKIE → HEADER → INTERCEPT → UI
+ *
+ * This eliminates the need for manual strategy selection — the system
+ * automatically finds the minimum-privilege strategy that works.
+ */
+import { Strategy } from './registry.js';
+import { getErrorMessage } from './errors.js';
+/** Strategy cascade order (simplest → most complex) */
+const CASCADE_ORDER = [
+    Strategy.PUBLIC,
+    Strategy.COOKIE,
+    Strategy.HEADER,
+    Strategy.INTERCEPT,
+    Strategy.UI,
+];
+/**
+ * Build the JavaScript source for a fetch probe.
+ * Shared logic for PUBLIC, COOKIE, and HEADER strategies.
+ */
+function buildFetchProbeJs(url, opts) {
+    const credentialsLine = opts.credentials ? `credentials: 'include',` : '';
+    const headerSetup = opts.extractCsrf
+        ? `
+      const cookies = document.cookie.split(';').map(c => c.trim());
+      const csrf = cookies.find(c => c.startsWith('ct0=') || c.startsWith('csrf_token=') || c.startsWith('_csrf='))?.split('=').slice(1).join('=');
+      const headers = {};
+      if (csrf) { headers['X-Csrf-Token'] = csrf; headers['X-XSRF-Token'] = csrf; }
+    `
+        : 'const headers = {};';
+    return `
+    async () => {
+      try {
+        ${headerSetup}
+        const resp = await fetch(${JSON.stringify(url)}, {
+          ${credentialsLine}
+          headers
+        });
+        const status = resp.status;
+        if (!resp.ok) return { status, ok: false };
+        const text = await resp.text();
+        let hasData = false;
+        try {
+          const json = JSON.parse(text);
+          hasData = !!json && (Array.isArray(json) ? json.length > 0 :
+            typeof json === 'object' && Object.keys(json).length > 0);
+          // Check for API-level error codes (common in Chinese sites)
+          if (json.code !== undefined && json.code !== 0) hasData = false;
+        } catch {}
+        return { status, ok: true, hasData, preview: text.slice(0, 200) };
+      } catch (e) { return { ok: false, error: e.message }; }
+    }
+  `;
+}
+/** Strategy → fetch probe options mapping for strategies that support probing. */
+const PROBE_OPTIONS = {
+    [Strategy.PUBLIC]: {},
+    [Strategy.COOKIE]: { credentials: true },
+    [Strategy.HEADER]: { credentials: true, extractCsrf: true },
+};
+/**
+ * Probe an endpoint with a specific strategy.
+ * Returns whether the probe succeeded and basic response info.
+ */
+export async function probeEndpoint(page, url, strategy, _opts = {}) {
+    const result = { strategy, success: false };
+    try {
+        const opts = PROBE_OPTIONS[strategy];
+        if (opts) {
+            const resp = await page.evaluate(buildFetchProbeJs(url, opts));
+            result.statusCode = resp?.status;
+            result.success = resp?.ok && resp?.hasData;
+            result.hasData = resp?.hasData;
+            result.responsePreview = resp?.preview;
+        }
+        else {
+            result.error = `Strategy ${strategy} requires site-specific implementation`;
+        }
+    }
+    catch (err) {
+        result.success = false;
+        result.error = getErrorMessage(err);
+    }
+    return result;
+}
+/**
+ * Run the cascade: try each strategy in order until one works.
+ * Returns the simplest working strategy.
+ */
+export async function cascadeProbe(page, url, opts = {}) {
+    const rawIdx = opts.maxStrategy
+        ? CASCADE_ORDER.indexOf(opts.maxStrategy)
+        : CASCADE_ORDER.indexOf(Strategy.HEADER); // Don't auto-try INTERCEPT/UI
+    const maxIdx = rawIdx === -1 ? CASCADE_ORDER.indexOf(Strategy.HEADER) : rawIdx;
+    const probes = [];
+    for (let i = 0; i <= Math.min(maxIdx, CASCADE_ORDER.length - 1); i++) {
+        const strategy = CASCADE_ORDER[i];
+        const probe = await probeEndpoint(page, url, strategy, opts);
+        probes.push(probe);
+        if (probe.success) {
+            return {
+                bestStrategy: strategy,
+                probes,
+                confidence: 1.0 - (i * 0.1), // Higher confidence for simpler strategies
+            };
+        }
+    }
+    // None worked — default to COOKIE (most common for logged-in sites)
+    return {
+        bestStrategy: Strategy.COOKIE,
+        probes,
+        confidence: 0.3,
+    };
+}
+/**
+ * Render cascade results for display.
+ */
+export function renderCascadeResult(result) {
+    const lines = [
+        `Strategy Cascade: ${result.bestStrategy} (${(result.confidence * 100).toFixed(0)}% confidence)`,
+    ];
+    for (const probe of result.probes) {
+        const icon = probe.success ? '✅' : '❌';
+        const status = probe.statusCode ? ` [${probe.statusCode}]` : '';
+        const err = probe.error ? ` — ${probe.error}` : '';
+        lines.push(`  ${icon} ${probe.strategy}${status}${err}`);
+    }
+    return lines.join('\n');
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI entry point: registers built-in commands and wires up Commander.
+ *
+ * Built-in commands are registered inline here (list, validate, explore, etc.).
+ * Dynamic adapter commands are registered via commanderAdapter.ts.
+ */
+import { Command } from 'commander';
+export declare function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command;
+export declare function runCli(BUILTIN_CLIS: string, USER_CLIS: string): void;
+export interface OperateVerifyInvocation {
+    binary: string;
+    args: string[];
+    cwd: string;
+    shell?: boolean;
+}
+export declare function findPackageRoot(startFile: string, fileExists?: (path: string) => boolean): string;
+export declare function resolveOperateVerifyInvocation(opts?: {
+    projectRoot?: string;
+    platform?: NodeJS.Platform;
+    fileExists?: (path: string) => boolean;
+    readFile?: (path: string) => string;
+}): OperateVerifyInvocation;