@jackwener/opencli 1.1.1 → 1.2.1

package/dist/pipeline/template.js

@@ -1,16 +1,20 @@
 /**
  * Pipeline template engine: ${{ ... }} expression rendering.
  */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export function render(template, ctx) {
     if (typeof template !== 'string')
         return template;
+    const trimmed = template.trim();
     // Full expression: entire string is a single ${{ ... }}
     // Use [^}] to prevent matching across }} boundaries (e.g. "${{ a }}-${{ b }}")
-    const fullMatch = template.match(/^\$\{\{\s*([^}]*(?:\}[^}][^}]*)*)\s*\}\}$/);
-    if (fullMatch && !template.includes('}}-') && !template.includes('}}${{'))
+    const fullMatch = trimmed.match(/^\$\{\{\s*([^}]*(?:\}[^}][^}]*)*)\s*\}\}$/);
+    if (fullMatch && !trimmed.includes('}}-') && !trimmed.includes('}}${{'))
         return evalExpr(fullMatch[1].trim(), ctx);
     // Check if the entire string is a single expression (no other text around it)
-    const singleExpr = template.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
+    const singleExpr = trimmed.match(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/);
     if (singleExpr) {
         // Verify it's truly a single expression (no other ${{ inside)
         const inner = singleExpr[1];
@@ -62,7 +66,10 @@ export function evalExpr(expr, ctx) {
         const right = orMatch[2].trim();
         return right.replace(/^['"]|['"]$/g, '');
     }
-    return resolvePath(expr, { args, item, data, index });
+    const resolved = resolvePath(expr, { args, item, data, index });
+    if (resolved !== null && resolved !== undefined)
+        return resolved;
+    return evalJsExpr(expr, { args, item, data, index });
 }
 /**
  * Apply a named filter to a value.
@@ -142,6 +149,10 @@ function applyFilter(filterExpr, value) {
             const parts = value.split(/[/\\]/);
             return parts[parts.length - 1] || value;
         }
+        case 'urlencode':
+            return typeof value === 'string' ? encodeURIComponent(value) : value;
+        case 'urldecode':
+            return typeof value === 'string' ? decodeURIComponent(value) : value;
         default:
             return value;
     }
@@ -174,7 +185,7 @@ export function resolvePath(pathStr, ctx) {
         rest = parts;
     }
     for (const part of rest) {
-        if (obj && typeof obj === 'object' && !Array.isArray(obj))
+        if (isRecord(obj))
             obj = obj[part];
         else if (Array.isArray(obj) && /^\d+$/.test(part))
             obj = obj[parseInt(part, 10)];
@@ -183,6 +194,33 @@ export function resolvePath(pathStr, ctx) {
     }
     return obj;
 }
+/**
+ * Evaluate arbitrary JS expressions as a last-resort fallback.
+ *
+ * ⚠️  SECURITY NOTE: Uses `new Function()` to execute the expression.
+ * This is acceptable here because:
+ *   1. YAML adapters are authored by trusted repo contributors only.
+ *   2. The expression runs in the same Node.js process (no sandbox).
+ *   3. Only a curated set of globals is exposed (no require/import/process/fs).
+ * If opencli ever loads untrusted third-party adapters, this MUST be replaced
+ * with a proper sandboxed evaluator.
+ */
+function evalJsExpr(expr, ctx) {
+    // Guard against absurdly long expressions that could indicate injection.
+    if (expr.length > 2000)
+        return undefined;
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const index = ctx.index ?? 0;
+    try {
+        const fn = new Function('args', 'item', 'data', 'index', 'encodeURIComponent', 'decodeURIComponent', 'JSON', 'Math', 'Number', 'String', 'Boolean', 'Array', 'Object', 'Date', `"use strict"; return (${expr});`);
+        return fn(args, item, data, index, encodeURIComponent, decodeURIComponent, JSON, Math, Number, String, Boolean, Array, Object, Date);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Normalize JavaScript source for browser evaluate() calls.
  */

package/dist/pipeline/template.test.js

@@ -54,6 +54,15 @@ describe('evalExpr', () => {
     it('resolves simple path', () => {
         expect(evalExpr('item.title', { item: { title: 'Test' } })).toBe('Test');
     });
+    it('evaluates JS helper expressions', () => {
+        expect(evalExpr('encodeURIComponent(args.keyword)', { args: { keyword: 'hello world' } })).toBe('hello%20world');
+    });
+    it('evaluates ternary expressions', () => {
+        expect(evalExpr("args.kind === 'tech' ? 'technology' : args.kind", { args: { kind: 'tech' } })).toBe('technology');
+    });
+    it('evaluates method calls on values', () => {
+        expect(evalExpr("args.username.startsWith('@') ? args.username : '@' + args.username", { args: { username: 'alice' } })).toBe('@alice');
+    });
     it('applies join filter', () => {
         expect(evalExpr('item.tags | join(,)', { item: { tags: ['a', 'b', 'c'] } })).toBe('a,b,c');
     });
@@ -100,6 +109,15 @@ describe('render', () => {
     it('renders URL template', () => {
         expect(render('https://api.example.com/search?q=${{ args.keyword }}', { args: { keyword: 'test' } })).toBe('https://api.example.com/search?q=test');
     });
+    it('renders inline helper expressions', () => {
+        expect(render('https://example.com/search?q=${{ encodeURIComponent(args.keyword) }}', { args: { keyword: 'hello world' } })).toBe('https://example.com/search?q=hello%20world');
+    });
+    it('renders full multiline expressions', () => {
+        expect(render("${{\n  args.topic ? `https://medium.com/tag/${args.topic}` : 'https://medium.com/tag/technology'\n}}", { args: { topic: 'ai' } })).toBe('https://medium.com/tag/ai');
+    });
+    it('renders block expressions with surrounding whitespace', () => {
+        expect(render("\n  ${{ args.kind === 'tech' ? 'technology' : args.kind }}\n", { args: { kind: 'tech' } })).toBe('technology');
+    });
 });
 describe('normalizeEvaluateSource', () => {
     it('wraps bare expression', () => {

package/dist/pipeline/transform.test.js

@@ -49,6 +49,17 @@ describe('stepMap', () => {
     it('returns null/undefined as-is', async () => {
         expect(await stepMap(null, { x: '${{ item.x }}' }, null, {})).toBeNull();
     });
+    it('supports inline select before mapping', async () => {
+        const result = await stepMap(null, {
+            select: 'posts',
+            title: '${{ item.title }}',
+            rank: '${{ index + 1 }}',
+        }, { posts: [{ title: 'One' }, { title: 'Two' }] }, {});
+        expect(result).toEqual([
+            { title: 'One', rank: 1 },
+            { title: 'Two', rank: 2 },
+        ]);
+    });
 });
 describe('stepFilter', () => {
     it('filters by expression', async () => {

package/dist/plugin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Install source format: "github:user/repo"
+ */
+export interface PluginInfo {
+    name: string;
+    path: string;
+    commands: string[];
+    source?: string;
+}
+/**
+ * Install a plugin from a source.
+ * Currently supports "github:user/repo" format (git clone wrapper).
+ */
+export declare function installPlugin(source: string): string;
+/**
+ * Uninstall a plugin by name.
+ */
+export declare function uninstallPlugin(name: string): void;
+/**
+ * List all installed plugins.
+ */
+export declare function listPlugins(): PluginInfo[];
+/** Parse a plugin source string into clone URL and name */
+declare function parseSource(source: string): {
+    cloneUrl: string;
+    name: string;
+} | null;
+export { parseSource as _parseSource };

package/dist/plugin.js

@@ -0,0 +1,216 @@
+/**
+ * Plugin management: install, uninstall, and list plugins.
+ *
+ * Plugins live in ~/.opencli/plugins/<name>/.
+ * Install source format: "github:user/repo"
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { PLUGINS_DIR } from './discovery.js';
+import { log } from './logger.js';
+/**
+ * Install a plugin from a source.
+ * Currently supports "github:user/repo" format (git clone wrapper).
+ */
+export function installPlugin(source) {
+    const parsed = parseSource(source);
+    if (!parsed) {
+        throw new Error(`Invalid plugin source: "${source}"\n` +
+            `Supported formats:\n` +
+            `  github:user/repo\n` +
+            `  https://github.com/user/repo`);
+    }
+    const { cloneUrl, name } = parsed;
+    const targetDir = path.join(PLUGINS_DIR, name);
+    if (fs.existsSync(targetDir)) {
+        throw new Error(`Plugin "${name}" is already installed at ${targetDir}`);
+    }
+    // Ensure plugins directory exists
+    fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+    try {
+        execFileSync('git', ['clone', '--depth', '1', cloneUrl, targetDir], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        throw new Error(`Failed to clone plugin: ${err.message}`);
+    }
+    // If the plugin has a package.json, run npm install for regular deps,
+    // then symlink the host opencli into node_modules for peerDep resolution.
+    const pkgJsonPath = path.join(targetDir, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+        try {
+            execFileSync('npm', ['install', '--omit=dev'], {
+                cwd: targetDir,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            // Non-fatal: npm install may fail if no real deps
+        }
+        // Symlink host opencli into plugin's node_modules so TS plugins
+        // can resolve '@jackwener/opencli/registry' against the running host.
+        // This is more reliable than depending on the npm-published version
+        // which may lag behind the local installation.
+        linkHostOpencli(targetDir);
+        // Transpile TS plugin files to JS so they work in production mode
+        // (node cannot load .ts files directly without tsx).
+        transpilePluginTs(targetDir);
+    }
+    return name;
+}
+/**
+ * Uninstall a plugin by name.
+ */
+export function uninstallPlugin(name) {
+    const targetDir = path.join(PLUGINS_DIR, name);
+    if (!fs.existsSync(targetDir)) {
+        throw new Error(`Plugin "${name}" is not installed.`);
+    }
+    fs.rmSync(targetDir, { recursive: true, force: true });
+}
+/**
+ * List all installed plugins.
+ */
+export function listPlugins() {
+    if (!fs.existsSync(PLUGINS_DIR))
+        return [];
+    const entries = fs.readdirSync(PLUGINS_DIR, { withFileTypes: true });
+    const plugins = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pluginDir = path.join(PLUGINS_DIR, entry.name);
+        const commands = scanPluginCommands(pluginDir);
+        const source = getPluginSource(pluginDir);
+        plugins.push({
+            name: entry.name,
+            path: pluginDir,
+            commands,
+            source,
+        });
+    }
+    return plugins;
+}
+/** Scan a plugin directory for command files */
+function scanPluginCommands(dir) {
+    try {
+        const files = fs.readdirSync(dir);
+        const names = new Set(files
+            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml') ||
+            (f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts')) ||
+            (f.endsWith('.js') && !f.endsWith('.d.js')))
+            .map(f => path.basename(f, path.extname(f))));
+        return [...names];
+    }
+    catch {
+        return [];
+    }
+}
+/** Get git remote origin URL */
+function getPluginSource(dir) {
+    try {
+        return execSync('git config --get remote.origin.url', {
+            cwd: dir,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse a plugin source string into clone URL and name */
+function parseSource(source) {
+    // github:user/repo
+    const githubMatch = source.match(/^github:([\w.-]+)\/([\w.-]+)$/);
+    if (githubMatch) {
+        const [, user, repo] = githubMatch;
+        const name = repo.replace(/^opencli-plugin-/, '');
+        return {
+            cloneUrl: `https://github.com/${user}/${repo}.git`,
+            name,
+        };
+    }
+    // https://github.com/user/repo (or .git)
+    const urlMatch = source.match(/^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+    if (urlMatch) {
+        const [, user, repo] = urlMatch;
+        const name = repo.replace(/^opencli-plugin-/, '');
+        return {
+            cloneUrl: `https://github.com/${user}/${repo}.git`,
+            name,
+        };
+    }
+    return null;
+}
+/**
+ * Symlink the host opencli package into a plugin's node_modules.
+ * This ensures TS plugins resolve '@jackwener/opencli/registry' against
+ * the running host installation rather than a stale npm-published version.
+ */
+function linkHostOpencli(pluginDir) {
+    try {
+        // Determine the host opencli package root from this module's location.
+        // Both dev (tsx src/plugin.ts) and prod (node dist/plugin.js) are one level
+        // deep, so path.dirname + '..' always gives us the package root.
+        const thisFile = new URL(import.meta.url).pathname;
+        const hostRoot = path.resolve(path.dirname(thisFile), '..');
+        const targetLink = path.join(pluginDir, 'node_modules', '@jackwener', 'opencli');
+        // Remove existing (npm-installed copy or stale symlink)
+        if (fs.existsSync(targetLink)) {
+            fs.rmSync(targetLink, { recursive: true, force: true });
+        }
+        // Ensure parent directory exists
+        fs.mkdirSync(path.dirname(targetLink), { recursive: true });
+        // Create symlink
+        fs.symlinkSync(hostRoot, targetLink, 'dir');
+        log.debug(`Linked host opencli into plugin: ${targetLink} → ${hostRoot}`);
+    }
+    catch (err) {
+        log.warn(`Failed to link host opencli into plugin: ${err.message}`);
+    }
+}
+/**
+ * Transpile TS plugin files to JS so they work in production mode.
+ * Uses esbuild from the host opencli's node_modules for fast single-file transpilation.
+ */
+function transpilePluginTs(pluginDir) {
+    try {
+        // Resolve esbuild binary from the host opencli's node_modules
+        const thisFile = new URL(import.meta.url).pathname;
+        const hostRoot = path.resolve(path.dirname(thisFile), '..');
+        const esbuildBin = path.join(hostRoot, 'node_modules', '.bin', 'esbuild');
+        if (!fs.existsSync(esbuildBin)) {
+            log.debug('esbuild not found in host node_modules, skipping TS transpilation');
+            return;
+        }
+        const files = fs.readdirSync(pluginDir);
+        const tsFiles = files.filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts'));
+        for (const tsFile of tsFiles) {
+            const jsFile = tsFile.replace(/\.ts$/, '.js');
+            const jsPath = path.join(pluginDir, jsFile);
+            // Skip if .js already exists (plugin may ship pre-compiled)
+            if (fs.existsSync(jsPath))
+                continue;
+            try {
+                execFileSync(esbuildBin, [tsFile, `--outfile=${jsFile}`, '--format=esm', '--platform=node'], {
+                    cwd: pluginDir,
+                    encoding: 'utf-8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                log.debug(`Transpiled plugin file: ${tsFile} → ${jsFile}`);
+            }
+            catch (err) {
+                log.warn(`Failed to transpile ${tsFile}: ${err.message}`);
+            }
+        }
+    }
+    catch {
+        // Non-fatal: skip transpilation if anything goes wrong
+    }
+}
+export { parseSource as _parseSource };

package/dist/plugin.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for plugin management: install, uninstall, list.
+ */
+export {};

package/dist/plugin.test.js

@@ -0,0 +1,76 @@
+/**
+ * Tests for plugin management: install, uninstall, list.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PLUGINS_DIR } from './discovery.js';
+import { listPlugins, uninstallPlugin, _parseSource } from './plugin.js';
+describe('parseSource', () => {
+    it('parses github:user/repo format', () => {
+        const result = _parseSource('github:ByteYue/opencli-plugin-github-trending');
+        expect(result).toEqual({
+            cloneUrl: 'https://github.com/ByteYue/opencli-plugin-github-trending.git',
+            name: 'github-trending',
+        });
+    });
+    it('parses https URL format', () => {
+        const result = _parseSource('https://github.com/ByteYue/opencli-plugin-hot-digest');
+        expect(result).toEqual({
+            cloneUrl: 'https://github.com/ByteYue/opencli-plugin-hot-digest.git',
+            name: 'hot-digest',
+        });
+    });
+    it('strips opencli-plugin- prefix from name', () => {
+        const result = _parseSource('github:user/opencli-plugin-my-tool');
+        expect(result.name).toBe('my-tool');
+    });
+    it('keeps name without prefix', () => {
+        const result = _parseSource('github:user/awesome-cli');
+        expect(result.name).toBe('awesome-cli');
+    });
+    it('returns null for invalid source', () => {
+        expect(_parseSource('invalid')).toBeNull();
+        expect(_parseSource('npm:some-package')).toBeNull();
+    });
+});
+describe('listPlugins', () => {
+    const testDir = path.join(PLUGINS_DIR, '__test-list-plugin__');
+    afterEach(() => {
+        try {
+            fs.rmSync(testDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('lists installed plugins', () => {
+        fs.mkdirSync(testDir, { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'hello.yaml'), 'site: test\nname: hello\n');
+        const plugins = listPlugins();
+        const found = plugins.find(p => p.name === '__test-list-plugin__');
+        expect(found).toBeDefined();
+        expect(found.commands).toContain('hello');
+    });
+    it('returns empty array when no plugins dir', () => {
+        // listPlugins should handle missing dir gracefully
+        const plugins = listPlugins();
+        expect(Array.isArray(plugins)).toBe(true);
+    });
+});
+describe('uninstallPlugin', () => {
+    const testDir = path.join(PLUGINS_DIR, '__test-uninstall__');
+    afterEach(() => {
+        try {
+            fs.rmSync(testDir, { recursive: true });
+        }
+        catch { }
+    });
+    it('removes plugin directory', () => {
+        fs.mkdirSync(testDir, { recursive: true });
+        fs.writeFileSync(path.join(testDir, 'test.yaml'), 'site: test');
+        uninstallPlugin('__test-uninstall__');
+        expect(fs.existsSync(testDir)).toBe(false);
+    });
+    it('throws for non-existent plugin', () => {
+        expect(() => uninstallPlugin('__nonexistent__')).toThrow('not installed');
+    });
+});

package/dist/registry-api.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions } from './registry.js';
+export type { IPage } from './types.js';

package/dist/registry-api.js

@@ -0,0 +1,9 @@
+/**
+ * Public API for opencli plugins.
+ *
+ * TS plugins should import from '@jackwener/opencli/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';

package/dist/registry.d.ts

@@ -32,6 +32,17 @@ export interface CliCommand {
     timeoutSeconds?: number;
     source?: string;
     footerExtra?: (kwargs: Record<string, any>) => string | undefined;
+    /**
+     * Control pre-navigation for cookie/header context before command execution.
+     *
+     * Browser adapters using COOKIE/HEADER strategy need the page to be on the
+     * target domain so that `fetch(url, { credentials: 'include' })` carries cookies.
+     *
+     * - `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
+     */
+    navigateBefore?: boolean | string;
 }
 /** Internal extension for lazy-loaded TS modules (not exposed in public API) */
 export interface InternalCliCommand extends CliCommand {

package/dist/registry.js

@@ -9,7 +9,11 @@ export var Strategy;
     Strategy["INTERCEPT"] = "intercept";
     Strategy["UI"] = "ui";
 })(Strategy || (Strategy = {}));
-const _registry = new Map();
+// Use globalThis to ensure a single shared registry across all module instances.
+// This is critical for TS plugins loaded via npm link / peerDependency — without
+// this, the plugin's import creates a separate module instance with its own Map.
+const REGISTRY_KEY = '__opencli_registry__';
+const _registry = globalThis[REGISTRY_KEY] ??= new Map();
 export function cli(opts) {
     const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     const browser = opts.browser ?? (strategy !== Strategy.PUBLIC);
@@ -26,6 +30,7 @@ export function cli(opts) {
         pipeline: opts.pipeline,
         timeoutSeconds: opts.timeoutSeconds,
         footerExtra: opts.footerExtra,
+        navigateBefore: opts.navigateBefore,
     };
     const key = fullName(cmd);
     _registry.set(key, cmd);

package/dist/synthesize.d.ts

@@ -2,12 +2,102 @@
  * Synthesize candidate CLIs from explore artifacts.
  * Generates evaluate-based YAML pipelines (matching hand-written adapter patterns).
  */
+import type { ExploreAuthSummary, ExploreEndpointArtifact, ExploreManifest } from './explore.js';
+interface RecommendedArg {
+    name: string;
+    type?: string;
+    required?: boolean;
+    default?: unknown;
+}
+interface StoreHint {
+    store: string;
+    action: string;
+}
+export interface SynthesizeCapability {
+    name: string;
+    description: string;
+    strategy: string;
+    confidence?: number;
+    endpoint?: string;
+    itemPath?: string | null;
+    recommendedColumns?: string[];
+    recommendedArgs?: RecommendedArg[];
+    recommended_args?: RecommendedArg[];
+    recommendedColumnsLegacy?: string[];
+    recommended_columns?: string[];
+    storeHint?: StoreHint;
+}
+export interface GeneratedArgDefinition {
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+}
+type CandidatePipelineStep = {
+    navigate: string;
+} | {
+    wait: number;
+} | {
+    evaluate: string;
+} | {
+    select: string;
+} | {
+    map: Record<string, string>;
+} | {
+    limit: string;
+} | {
+    fetch: {
+        url: string;
+    };
+} | {
+    tap: {
+        store: string;
+        action: string;
+        timeout: number;
+        capture?: string;
+        select?: string | null;
+    };
+};
+export interface CandidateYaml {
+    site: string;
+    name: string;
+    description: string;
+    domain: string;
+    strategy: string;
+    browser: boolean;
+    args: Record<string, GeneratedArgDefinition>;
+    pipeline: CandidatePipelineStep[];
+    columns: string[];
+}
+export interface SynthesizeCandidateSummary {
+    name: string;
+    path: string;
+    strategy: string;
+    confidence?: number;
+}
+export interface SynthesizeResult {
+    site: string;
+    explore_dir: string;
+    out_dir: string;
+    candidate_count: number;
+    candidates: SynthesizeCandidateSummary[];
+}
+interface LoadedExploreBundle {
+    manifest: ExploreManifest;
+    endpoints: ExploreEndpointArtifact[];
+    capabilities: SynthesizeCapability[];
+    auth: ExploreAuthSummary;
+}
 export declare function synthesizeFromExplore(target: string, opts?: {
     outDir?: string;
     top?: number;
-}): Record<string, any>;
-export declare function renderSynthesizeSummary(result: Record<string, any>): string;
+}): SynthesizeResult;
+export declare function renderSynthesizeSummary(result: SynthesizeResult): string;
 export declare function resolveExploreDir(target: string): string;
-export declare function loadExploreBundle(exploreDir: string): Record<string, any>;
+export declare function loadExploreBundle(exploreDir: string): LoadedExploreBundle;
 /** Backward-compatible export for scaffold.ts */
-export declare function buildCandidate(site: string, targetUrl: string, cap: any, endpoint: any): any;
+export declare function buildCandidate(site: string, targetUrl: string, cap: SynthesizeCapability, endpoint: ExploreEndpointArtifact): {
+    name: string;
+    yaml: CandidateYaml;
+};
+export {};

package/dist/synthesize.js

@@ -60,11 +60,12 @@ function chooseEndpoint(cap, endpoints) {
         return null;
     // Match by endpoint pattern from capability
     if (cap.endpoint) {
-        const match = endpoints.find((e) => e.pattern === cap.endpoint || e.url?.includes(cap.endpoint));
+        const endpointPattern = cap.endpoint;
+        const match = endpoints.find((endpoint) => endpoint.pattern === endpointPattern || endpoint.url?.includes(endpointPattern));
         if (match)
             return match;
     }
-    return endpoints.sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
+    return [...endpoints].sort((a, b) => (b.score ?? 0) - (a.score ?? 0))[0];
 }
 // ── URL templating ─────────────────────────────────────────────────────────
 function buildTemplatedUrl(rawUrl, cap, _endpoint) {
@@ -72,7 +73,7 @@ function buildTemplatedUrl(rawUrl, cap, _endpoint) {
         const u = new URL(rawUrl);
         const base = `${u.protocol}//${u.host}${u.pathname}`;
         const params = [];
-        const hasKeyword = cap.recommendedArgs?.some((a) => a.name === 'keyword');
+        const hasKeyword = cap.recommendedArgs?.some((arg) => arg.name === 'keyword');
         u.searchParams.forEach((v, k) => {
             if (VOLATILE_PARAMS.has(k))
                 return;
@@ -166,7 +167,7 @@ function buildCandidateYaml(site, manifest, cap, endpoint) {
     // Map fields
     const mapStep = {};
     const columns = cap.recommendedColumns ?? ['title', 'url'];
-    if (!cap.recommendedArgs?.some((a) => a.name === 'keyword'))
+    if (!cap.recommendedArgs?.some((arg) => arg.name === 'keyword'))
         mapStep['rank'] = '${{ index + 1 }}';
     const detectedFields = endpoint?.detectedFields ?? {};
     for (const col of columns) {