website-api 1.1.3 → 1.1.4

package/dist/src/cli/ext.js

@@ -1 +1,338 @@
-import{createInterface as o}from"node:readline/promises";import{stdin as e,stdout as n}from"node:process";import{existsSync as t,readdirSync as i,statSync as s,writeFileSync as r}from"node:fs";import{join as a,resolve as l}from"node:path";import{pathToFileURL as c}from"node:url";import d from"chalk";import m from"cli-table3";import{loadSites as g,getSite as p}from"../core/runtime.js";import{defineSite as y}from"../core/define-site.js";import{createContext as f}from"../core/context.js";import{parseArgsForWebsite as h}from"../util/args-parser.js";import{addRegistry as u,installEntry as $,listInstalled as b,loadIndex as w,removeInstalled as x,removeRegistry as j,resolveEntry as v,resolveRegistries as R,searchRegistries as N}from"../core/registry.js";async function D(t){if(!e.isTTY)return!1;const i=o({input:e,output:n});try{const o=(await i.question(`${t} ${d.gray("[y/N]")} `)).trim().toLowerCase();return"y"===o||"yes"===o}finally{i.close()}}function S(o){console.error(d.red(`Error: ${o}`)),process.exit(1)}const I=o=>o instanceof Error?o.message:String(o);export function registerExtCommands(o){o.enablePositionalOptions();const e=o.command("ext").description("Discover and install website extensions from a public registry").enablePositionalOptions();e.command("test <path> [args...]").description("Load and run a site .js file (or its folder) directly from disk — no install").allowUnknownOption().passThroughOptions().action(async(o,e)=>{const n=function(o){const e=l(process.cwd(),o);if(t(e)||S(`path not found: ${o}`),s(e).isFile())return e;const n=i(e);for(const o of["index.mjs","index.js"])if(n.includes(o))return a(e,o);const r=n.find(o=>/\.(m?js)$/.test(o)&&!o.includes(".test."));if(r)return a(e,r);S(`no .js/.mjs entry found in ${o}`)}(o);let m;try{m=await import(c(n).href)}catch(o){S(`failed to import ${n}: ${I(o)}`)}const g=m.default??m.site;let p,u;g&&"object"==typeof g||S(`${n} does not default-export a site object`);try{p=y(g)}catch(o){S(I(o))}p.origin="extension";try{const o=(e??[]).filter(o=>"--"!==o);u=h(p.positionals,p.parameters,o)}catch(o){S(I(o))}if(u.helpRequested)return void function(o,e){if(console.log(d.bold.green(`\n${o.name} (${o.id})`)+d.gray(`  — ${e}\n`)),console.log(`  ${d.italic(o.description)}\n`),o.positionals.length){console.log(d.bold("Positionals:"));for(const e of o.positionals)console.log(`  ${d.cyan(e.name.padEnd(16))} ${e.description}`);console.log()}console.log(d.bold("Options:"));for(const e of o.parameters){const o=(e.short?`-${e.short}, `:"    ")+`--${e.name}`+("boolean"===e.type?"":" <value>");console.log(`  ${d.yellow(o.padEnd(26))} ${e.description}`)}console.log()}(p,n);console.error(d.gray(`▶ running "${p.id}" from ${n} (not installed)`));const{ctx:$,dispose:b}=f(p,u.options);try{const o=await p.run($),e="string"==typeof o?o:JSON.stringify(o,null,2);u.options.out?(r(u.options.out,e+"\n","utf8"),console.error(d.green(`✓ wrote ${u.options.out}`))):console.log(e)}catch(o){S(I(o))}finally{await b()}}),e.command("search [query]").description("Search configured registries for installable sites").option("--refresh","Bypass the cached index and re-fetch").action(async(o,e)=>{const n=await N(o??"",{refresh:e.refresh});if(0===n.length)return void console.log(d.yellow(`No sites${o?` matching "${o}"`:""} found.`));const t=new m({head:[d.bold.cyan("ID"),d.bold.cyan("Name"),d.bold.cyan("Domain"),d.bold.cyan("Registry"),d.bold.cyan("Description")],colWidths:[16,22,18,14,44],wordWrap:!0,style:{head:[],border:[]}});for(const o of n){const e=[];"browser"===o.transport&&e.push(d.magenta("[p]")),o.auth&&e.push(d.red("[l]"));const n=e.length?`${o.name} ${e.join(" ")}`:o.name;t.push([d.yellow(o.id),n,d.underline(o.domain),o.registry.name,o.description])}console.log(t.toString()),console.log(`\nInstall one with: ${d.bold.cyan("npx website-api ext install <id>")}\n`)}),e.command("info <id>").description("Show full catalog details for a single site").option("--registry <name>","Disambiguate when multiple registries offer the id").action(async(o,e)=>{const{source:n,entry:t}=await v(o,{registryName:e.registry});console.log(d.bold.green(`\n🌐 ${t.name} ${d.yellow(`(${t.id})`)}\n`)),console.log(`  ${d.italic(t.description)}\n`);const i=[["Domain",t.domain],["Registry",`${n.name} (${n.repo})`],["Version",t.version??"—"],["Transport",t.transport??"http"],["Requires login",t.auth?"yes":"no"],["Tags",t.tags?.join(", ")||"—"],["Files",t.files.map(o=>o.name).join(", ")]];for(const[o,e]of i)console.log(`  ${d.bold((o+":").padEnd(16))} ${e}`);console.log(`\nInstall with: ${d.bold.cyan(`npx website-api ext install ${t.id}`)}\n`)}),e.command("install <id>").alias("add-site").description("Download and install a site from a registry into your extensions folder").option("--registry <name>","Disambiguate when multiple registries offer the id").option("-y, --yes","Skip the confirmation prompt").option("--refresh","Bypass the cached index and re-fetch").action(async(o,e)=>{const{source:n,index:t,entry:i}=await v(o,{registryName:e.registry,refresh:e.refresh});console.log(d.bold(`\nAbout to install ${d.yellow(i.id)} — ${i.name}`)),console.log(`  ${d.bold("Domain:")}    ${i.domain}`),console.log(`  ${d.bold("Registry:")}  ${n.name} (${n.repo}@${t.commit.slice(0,10)})`),console.log(`  ${d.bold("Files:")}     ${i.files.map(o=>o.name).join(", ")}`),i.auth&&console.log(d.red(`  ⚠ This site performs a login and will read saved credentials for ${i.domain}.`)),await g();const s=p(i.id);if("bundled"===s?.origin&&console.log(d.yellow(`  ⚠ This will shadow the bundled "${i.id}" site.`)),console.log(d.gray("  ⚠ Installing runs third-party code with your browser session. Only install sites you trust.\n")),!e.yes&&!await D("Install this site?"))return void console.log(d.yellow("Aborted."));const{dir:r}=await $(n,t,i,{refresh:e.refresh});console.log(d.green(`\n✓ Installed ${i.id} → ${r}`)),console.log(`Run it with: ${d.bold.cyan(`npx website-api ${i.id}`)}\n`)}),e.command("list").description("List sites you have installed from registries").action(()=>{const o=b();if(0===o.length)return void console.log(d.yellow("No registry sites installed. Try: ")+d.cyan("npx website-api ext search"));const e=new m({head:[d.bold.cyan("ID"),d.bold.cyan("Version"),d.bold.cyan("Registry"),d.bold.cyan("Commit"),d.bold.cyan("Installed")],style:{head:[],border:[]}});for(const n of o)e.push([d.yellow(n.id),n.version??"—",n.repo,n.commit.slice(0,10),n.installedAt.slice(0,10)]);console.log(e.toString())}),e.command("remove <id>").alias("uninstall").description("Remove an installed registry site").action(o=>{x(o)?console.log(d.green(`✓ Removed ${o}`)):S(`"${o}" is not installed`)}),e.command("update [id]").description("Re-install installed sites whose registry commit has changed").option("-y, --yes","Skip the confirmation prompt").action(async(o,e)=>{const n=b().filter(e=>!o||e.id===o);0===n.length&&S(o?`"${o}" is not installed`:"no registry sites installed");let t=0;for(const o of n){let n;try{n=await v(o.id,{registryName:o.registry,refresh:!0})}catch{console.log(d.yellow(`• ${o.id}: no longer in registry, skipping`));continue}n.index.commit!==o.commit?(console.log(`• ${o.id}: ${o.commit.slice(0,10)} → ${n.index.commit.slice(0,10)}`),(e.yes||await D(`  Update ${o.id}?`))&&(await $(n.source,n.index,n.entry),console.log(d.green(`  ✓ updated ${o.id}`)),t++)):console.log(d.gray(`• ${o.id}: up to date`))}console.log(t?d.green(`\nUpdated ${t} site(s).`):d.gray("\nNothing to update."))});const n=e.command("registry").description("Manage the registries searched for sites");n.command("list").description("List configured registries (in search priority order)").action(()=>{const o=new m({head:[d.bold.cyan("Name"),d.bold.cyan("Repo"),d.bold.cyan("Branch")],style:{head:[],border:[]}});for(const e of R())o.push([e.name,e.repo,e.branch]);console.log(o.toString())}),n.command("add <spec>").description("Add a registry (owner/repo, owner/repo#branch, or a github.com URL)").action(async o=>{const e=u(o);try{const o=await w(e,{refresh:!0});console.log(d.green(`✓ Added registry ${e.name} (${e.repo}) — ${o.sites.length} site(s) available`))}catch(o){console.log(d.yellow(`Added ${e.repo}, but its index.json could not be fetched: ${o instanceof Error?o.message:String(o)}`))}}),n.command("remove <repoOrName>").description("Remove a configured registry").action(o=>{j(o)?console.log(d.green(`✓ Removed registry ${o}`)):S(`registry "${o}" not found in config`)})}
+import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { createContext } from "../core/context.js";
+import { defineSite } from "../core/define-site.js";
+import { addRegistry, installEntry, listInstalled, loadIndex, removeInstalled, removeRegistry, resolveEntry, resolveRegistries, searchRegistries, } from "../core/registry.js";
+import { getSite, loadSites } from "../core/runtime.js";
+import { parseArgsForWebsite } from "../util/args-parser.js";
+/** Asks a yes/no question on the TTY; returns true on "y". */
+async function confirm(question) {
+    if (!stdin.isTTY)
+        return false; // never auto-confirm in a non-interactive shell
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = (await rl.question(`${question} ${chalk.gray("[y/N]")} `)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function fail(message) {
+    console.error(chalk.red(`Error: ${message}`));
+    process.exit(1);
+}
+const errMsg = (err) => (err instanceof Error ? err.message : String(err));
+/** Resolves a path (file or directory) to a loadable site entry file. */
+function resolveLocalEntry(path) {
+    const abs = resolve(process.cwd(), path);
+    if (!existsSync(abs))
+        fail(`path not found: ${path}`);
+    if (statSync(abs).isFile())
+        return abs;
+    const files = readdirSync(abs);
+    for (const candidate of ["index.mjs", "index.js"]) {
+        if (files.includes(candidate))
+            return join(abs, candidate);
+    }
+    const fallback = files.find((f) => /\.(m?js)$/.test(f) && !f.includes(".test."));
+    if (fallback)
+        return join(abs, fallback);
+    fail(`no .js/.mjs entry found in ${path}`);
+}
+/** Prints a compact usage block for a site loaded from disk. */
+function printLocalHelp(site, entry) {
+    console.log(chalk.bold.green(`\n${site.name} (${site.id})`) + chalk.gray(`  — ${entry}\n`));
+    console.log(`  ${chalk.italic(site.description)}\n`);
+    if (site.positionals.length) {
+        console.log(chalk.bold("Positionals:"));
+        for (const p of site.positionals)
+            console.log(`  ${chalk.cyan(p.name.padEnd(16))} ${p.description}`);
+        console.log();
+    }
+    console.log(chalk.bold("Options:"));
+    for (const p of site.parameters) {
+        const flag = (p.short ? `-${p.short}, ` : "    ") + `--${p.name}` + (p.type === "boolean" ? "" : " <value>");
+        console.log(`  ${chalk.yellow(flag.padEnd(26))} ${p.description}`);
+    }
+    console.log();
+}
+/** Registers the `ext` command group on the given Commander program. */
+export function registerExtCommands(program) {
+    // `test` forwards unknown flags (e.g. --limit) to the site being tested, which
+    // requires positional-options mode on its parent commands.
+    program.enablePositionalOptions();
+    const ext = program
+        .command("ext")
+        .description("Discover and install website extensions from a public registry")
+        .enablePositionalOptions();
+    // ── test (run a local file directly, no install) ──
+    ext
+        .command("test <path> [args...]")
+        .description("Load and run a site .js file (or its folder) directly from disk — no install")
+        .allowUnknownOption()
+        .passThroughOptions()
+        .action(async (path, args) => {
+        const entry = resolveLocalEntry(path);
+        let mod;
+        try {
+            mod = await import(pathToFileURL(entry).href);
+        }
+        catch (err) {
+            fail(`failed to import ${entry}: ${errMsg(err)}`);
+        }
+        const def = mod.default ?? mod.site;
+        if (!def || typeof def !== "object")
+            fail(`${entry} does not default-export a site object`);
+        let site;
+        try {
+            site = defineSite(def);
+        }
+        catch (err) {
+            fail(errMsg(err));
+        }
+        site.origin = "extension";
+        let parsed;
+        try {
+            // Drop a standalone "--" separator that passthrough forwards verbatim.
+            const siteArgs = (args ?? []).filter((a) => a !== "--");
+            parsed = parseArgsForWebsite(site.positionals, site.parameters, siteArgs);
+        }
+        catch (err) {
+            fail(errMsg(err));
+        }
+        if (parsed.helpRequested) {
+            printLocalHelp(site, entry);
+            return;
+        }
+        // Status goes to stderr so stdout stays clean (pipeable) data.
+        console.error(chalk.gray(`▶ running "${site.id}" from ${entry} (not installed)`));
+        const { ctx, dispose } = createContext(site, parsed.options);
+        try {
+            const data = await site.run(ctx);
+            const output = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+            if (parsed.options.out) {
+                writeFileSync(parsed.options.out, output + "\n", "utf8");
+                console.error(chalk.green(`✓ wrote ${parsed.options.out}`));
+            }
+            else {
+                console.log(output);
+            }
+        }
+        catch (err) {
+            fail(errMsg(err));
+        }
+        finally {
+            await dispose();
+        }
+    });
+    // ── search ──
+    ext
+        .command("search [query]")
+        .description("Search configured registries for installable sites")
+        .option("--refresh", "Bypass the cached index and re-fetch")
+        .action(async (query, opts) => {
+        const results = await searchRegistries(query ?? "", { refresh: opts.refresh });
+        if (results.length === 0) {
+            console.log(chalk.yellow(`No sites${query ? ` matching "${query}"` : ""} found.`));
+            return;
+        }
+        const table = new Table({
+            head: [
+                chalk.bold.cyan("ID"),
+                chalk.bold.cyan("Name"),
+                chalk.bold.cyan("Domain"),
+                chalk.bold.cyan("Registry"),
+                chalk.bold.cyan("Description"),
+            ],
+            colWidths: [16, 22, 18, 14, 44],
+            wordWrap: true,
+            style: { head: [], border: [] },
+        });
+        for (const r of results) {
+            const markers = [];
+            if (r.transport === "browser")
+                markers.push(chalk.magenta("[p]"));
+            if (r.auth)
+                markers.push(chalk.red("[l]"));
+            const name = markers.length ? `${r.name} ${markers.join(" ")}` : r.name;
+            table.push([chalk.yellow(r.id), name, chalk.underline(r.domain), r.registry.name, r.description]);
+        }
+        console.log(table.toString());
+        console.log(`\nInstall one with: ${chalk.bold.cyan("npx website-api ext install <id>")}\n`);
+    });
+    // ── info ──
+    ext
+        .command("info <id>")
+        .description("Show full catalog details for a single site")
+        .option("--registry <name>", "Disambiguate when multiple registries offer the id")
+        .action(async (id, opts) => {
+        const { source, entry } = await resolveEntry(id, { registryName: opts.registry });
+        console.log(chalk.bold.green(`\n🌐 ${entry.name} ${chalk.yellow(`(${entry.id})`)}\n`));
+        console.log(`  ${chalk.italic(entry.description)}\n`);
+        const rows = [
+            ["Domain", entry.domain],
+            ["Registry", `${source.name} (${source.repo})`],
+            ["Version", entry.version ?? "—"],
+            ["Transport", entry.transport ?? "http"],
+            ["Requires login", entry.auth ? "yes" : "no"],
+            ["Tags", entry.tags?.join(", ") || "—"],
+            ["Files", entry.files.map((f) => f.name).join(", ")],
+        ];
+        for (const [k, v] of rows)
+            console.log(`  ${chalk.bold((k + ":").padEnd(16))} ${v}`);
+        console.log(`\nInstall with: ${chalk.bold.cyan(`npx website-api ext install ${entry.id}`)}\n`);
+    });
+    // ── install ──
+    ext
+        .command("install <id>")
+        .alias("add-site")
+        .description("Download and install a site from a registry into your extensions folder")
+        .option("--registry <name>", "Disambiguate when multiple registries offer the id")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--refresh", "Bypass the cached index and re-fetch")
+        .action(async (id, opts) => {
+        const { source, index, entry } = await resolveEntry(id, {
+            registryName: opts.registry,
+            refresh: opts.refresh,
+        });
+        // Security gate: an installed site runs with the user's decrypted Chrome
+        // cookies and credentials. Surface what it is and where it came from.
+        console.log(chalk.bold(`\nAbout to install ${chalk.yellow(entry.id)} — ${entry.name}`));
+        console.log(`  ${chalk.bold("Domain:")}    ${entry.domain}`);
+        console.log(`  ${chalk.bold("Registry:")}  ${source.name} (${source.repo}@${index.commit.slice(0, 10)})`);
+        console.log(`  ${chalk.bold("Files:")}     ${entry.files.map((f) => f.name).join(", ")}`);
+        if (entry.auth)
+            console.log(chalk.red(`  ⚠ This site performs a login and will read saved credentials for ${entry.domain}.`));
+        // Warn if this would shadow a bundled/site already loaded by the same id.
+        await loadSites();
+        const existing = getSite(entry.id);
+        if (existing?.origin === "bundled") {
+            console.log(chalk.yellow(`  ⚠ This will shadow the bundled "${entry.id}" site.`));
+        }
+        console.log(chalk.gray(`  ⚠ Installing runs third-party code with your browser session. Only install sites you trust.\n`));
+        if (!opts.yes && !(await confirm("Install this site?"))) {
+            console.log(chalk.yellow("Aborted."));
+            return;
+        }
+        const { dir } = await installEntry(source, index, entry, { refresh: opts.refresh });
+        console.log(chalk.green(`\n✓ Installed ${entry.id} → ${dir}`));
+        console.log(`Run it with: ${chalk.bold.cyan(`npx website-api ${entry.id}`)}\n`);
+    });
+    // ── list (installed) ──
+    ext
+        .command("list")
+        .description("List sites you have installed from registries")
+        .action(() => {
+        const installed = listInstalled();
+        if (installed.length === 0) {
+            console.log(chalk.yellow("No registry sites installed. Try: ") + chalk.cyan("npx website-api ext search"));
+            return;
+        }
+        const table = new Table({
+            head: [
+                chalk.bold.cyan("ID"),
+                chalk.bold.cyan("Version"),
+                chalk.bold.cyan("Registry"),
+                chalk.bold.cyan("Commit"),
+                chalk.bold.cyan("Installed"),
+            ],
+            style: { head: [], border: [] },
+        });
+        for (const r of installed) {
+            table.push([
+                chalk.yellow(r.id),
+                r.version ?? "—",
+                r.repo,
+                r.commit.slice(0, 10),
+                r.installedAt.slice(0, 10),
+            ]);
+        }
+        console.log(table.toString());
+    });
+    // ── remove ──
+    ext
+        .command("remove <id>")
+        .alias("uninstall")
+        .description("Remove an installed registry site")
+        .action((id) => {
+        if (removeInstalled(id))
+            console.log(chalk.green(`✓ Removed ${id}`));
+        else
+            fail(`"${id}" is not installed`);
+    });
+    // ── update ──
+    ext
+        .command("update [id]")
+        .description("Re-install installed sites whose registry commit has changed")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .action(async (id, opts) => {
+        const installed = listInstalled().filter((r) => !id || r.id === id);
+        if (installed.length === 0)
+            fail(id ? `"${id}" is not installed` : "no registry sites installed");
+        let updated = 0;
+        for (const record of installed) {
+            let resolved;
+            try {
+                resolved = await resolveEntry(record.id, { registryName: record.registry, refresh: true });
+            }
+            catch {
+                console.log(chalk.yellow(`• ${record.id}: no longer in registry, skipping`));
+                continue;
+            }
+            if (resolved.index.commit === record.commit) {
+                console.log(chalk.gray(`• ${record.id}: up to date`));
+                continue;
+            }
+            console.log(`• ${record.id}: ${record.commit.slice(0, 10)} → ${resolved.index.commit.slice(0, 10)}`);
+            if (!opts.yes && !(await confirm(`  Update ${record.id}?`)))
+                continue;
+            await installEntry(resolved.source, resolved.index, resolved.entry);
+            console.log(chalk.green(`  ✓ updated ${record.id}`));
+            updated++;
+        }
+        console.log(updated ? chalk.green(`\nUpdated ${updated} site(s).`) : chalk.gray("\nNothing to update."));
+    });
+    // ── registry management ──
+    const reg = ext.command("registry").description("Manage the registries searched for sites");
+    reg
+        .command("list")
+        .description("List configured registries (in search priority order)")
+        .action(() => {
+        const table = new Table({
+            head: [chalk.bold.cyan("Name"), chalk.bold.cyan("Repo"), chalk.bold.cyan("Branch")],
+            style: { head: [], border: [] },
+        });
+        for (const r of resolveRegistries())
+            table.push([r.name, r.repo, r.branch]);
+        console.log(table.toString());
+    });
+    reg
+        .command("add <spec>")
+        .description("Add a registry (owner/repo, owner/repo#branch, or a github.com URL)")
+        .action(async (spec) => {
+        const source = addRegistry(spec);
+        try {
+            const index = await loadIndex(source, { refresh: true });
+            console.log(chalk.green(`✓ Added registry ${source.name} (${source.repo}) — ${index.sites.length} site(s) available`));
+        }
+        catch (err) {
+            // Keep it configured but warn the catalog could not be read yet.
+            console.log(chalk.yellow(`Added ${source.repo}, but its index.json could not be fetched: ${err instanceof Error ? err.message : String(err)}`));
+        }
+    });
+    reg
+        .command("remove <repoOrName>")
+        .description("Remove a configured registry")
+        .action((repoOrName) => {
+        if (removeRegistry(repoOrName))
+            console.log(chalk.green(`✓ Removed registry ${repoOrName}`));
+        else
+            fail(`registry "${repoOrName}" not found in config`);
+    });
+}

package/dist/src/core/context.d.ts

@@ -1,6 +1,6 @@
-import type { QueryOptions, Site, SiteContext } from "../types.js";
-import { type CookieProviders } from "../capabilities/cookies.js";
 import { type BrowserConnector } from "../capabilities/browser.js";
+import { type CookieProviders } from "../capabilities/cookies.js";
+import type { QueryOptions, Site, SiteContext } from "../types.js";
 /**
  * Injectable dependencies. In production all default to the real
  * implementations; tests pass fakes to exercise a site or capability without a

package/dist/src/core/context.js

@@ -1 +1,137 @@
-import{resolve as e}from"node:path";import{buildCookieString as i,resolveCookies as o,resolveCredentials as t,resolveUserAgent as r}from"../capabilities/cookies.js";import{createHttp as a}from"../capabilities/http.js";import{applyFingerprint as s}from"../capabilities/fingerprint.js";import{connectChrome as n}from"../capabilities/browser.js";import{createSaver as c}from"../capabilities/download.js";export function createContext(p,d={},l={}){const u=l.env??process.env,g=!!d.debug,m="required"===p.cookies;let w;const b=()=>(void 0===w&&(w=o(p.cookieDomain,d,m,l)),w),f=()=>i(b()),h=()=>r(d,u),k=()=>t(p.domain,d,l),v=a({fetchImpl:l.fetchImpl,cookieString:f,userAgent:h,debug:g}),D=l.connectBrowser??n;let j,y;const I=void 0!==d.close?!!d.close:!(d.keepOpen||p.keepBrowserOpen),x=()=>(y||(y=(async()=>(j=await D(p.landingUrl,{cdpEndpoint:u.CDP_ENDPOINT,close:I,debug:g}),await s(j.page,p.fingerprint,h()),p.auth&&await p.auth.ensureLoggedIn({page:j.page,debug:g,getCredentials:k}),j.page))()),y),C=d.outDir?e(l.cwd??process.cwd(),d.outDir):null,O=c(d.outDir??null,l.cwd);return{ctx:{site:p,domain:p.domain,options:d,debug:g,outDir:C,cookies:b,cookieString:f,credentials:k,userAgent:h,http:v,browser:x,eval:async e=>(await x()).evaluate(e),save:O},async dispose(){if(j)try{await j.dispose()}catch{}}}}
+import { resolve } from "node:path";
+import { connectChrome } from "../capabilities/browser.js";
+import { buildCookieString, resolveCookies, resolveCredentials, resolveUserAgent, } from "../capabilities/cookies.js";
+import { createSaver } from "../capabilities/download.js";
+import { applyFingerprint } from "../capabilities/fingerprint.js";
+import { createHttp } from "../capabilities/http.js";
+/** Treats `1`/`true`/`yes`/`on` (case-insensitive) as truthy for env flags. */
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+/**
+ * The managed browser launches **headless by default**. When a CDP session is
+ * already open, chrome-cdp-manager attaches to it instead of launching — so this
+ * only governs a fresh launch. `--headed` (or `CDP_HEADLESS=false`) forces a
+ * visible window, e.g. to solve a captcha that needs a real press-and-hold.
+ */
+function resolveHeadless(headed, headlessEnv) {
+    if (headed)
+        return false;
+    if (headlessEnv !== undefined)
+        return isTruthyEnv(headlessEnv);
+    return true;
+}
+/**
+ * Builds the lazy capability context handed to `site.run(ctx)`. Nothing
+ * expensive happens until a capability is touched: cookies are read on first
+ * `cookies()`/HTTP call, and Chrome is launched on first `browser()`.
+ */
+export function createContext(site, options = {}, providers = {}) {
+    const env = providers.env ?? process.env;
+    const debug = !!options.debug;
+    const required = site.cookies === "required";
+    // ── memoized session resolution ──
+    let cookieCache;
+    const cookies = () => {
+        if (cookieCache === undefined) {
+            cookieCache = resolveCookies(site.cookieDomain, options, required, providers);
+        }
+        return cookieCache;
+    };
+    const cookieString = () => buildCookieString(cookies());
+    let userAgentCache;
+    const userAgent = () => {
+        if (userAgentCache === undefined) {
+            userAgentCache = resolveUserAgent(options, env);
+        }
+        return userAgentCache;
+    };
+    // Memoized: resolving credentials reads Chrome's password store, which can
+    // trigger a keychain prompt — it must happen at most once per invocation.
+    let credentialsCache;
+    const credentials = () => {
+        if (credentialsCache === undefined) {
+            credentialsCache = resolveCredentials(site.domain, options, providers);
+        }
+        return credentialsCache;
+    };
+    const http = createHttp({ fetchImpl: providers.fetchImpl, cookieString, userAgent, debug });
+    // ── browser capability (lazy + memoized) ──
+    const connect = providers.connectBrowser ?? connectChrome;
+    let session;
+    let pagePromise;
+    // Whether to close a tab we open on teardown. Precedence:
+    //   explicit options.close  →  --keep-open flag  →  the site's keepBrowserOpen
+    const shouldClose = options.close !== undefined ? !!options.close : !(options.keepOpen || site.keepBrowserOpen);
+    // Whether the managed browser should launch headless (default true). An
+    // already-open CDP session is reused regardless; this only affects a fresh launch.
+    const headless = resolveHeadless(options.headed, env.CDP_HEADLESS);
+    const browser = () => {
+        if (!pagePromise) {
+            pagePromise = (async () => {
+                session = await connect(site.landingUrl, {
+                    cdpEndpoint: env.CDP_ENDPOINT,
+                    headless,
+                    close: shouldClose,
+                    debug,
+                });
+                await applyFingerprint(session.page, site.fingerprint, userAgent());
+                if (site.auth) {
+                    await site.auth.ensureLoggedIn({
+                        page: session.page,
+                        debug,
+                        getCredentials: credentials,
+                    });
+                }
+                return session.page;
+            })();
+            // Don't cache a rejected setup: a retry within the same run() should
+            // attempt a fresh connection, with any partial session torn down first.
+            pagePromise = pagePromise.catch(async (err) => {
+                pagePromise = undefined;
+                if (session) {
+                    const partial = session;
+                    session = undefined;
+                    await partial.dispose().catch(() => { });
+                }
+                throw err;
+            });
+        }
+        return pagePromise;
+    };
+    const outDir = options.outDir ? resolve(providers.cwd ?? process.cwd(), options.outDir) : null;
+    const save = createSaver(options.outDir ?? null, providers.cwd);
+    const ctx = {
+        site,
+        domain: site.domain,
+        options,
+        debug,
+        outDir,
+        cookies,
+        cookieString,
+        credentials,
+        userAgent,
+        http,
+        browser,
+        async eval(fn) {
+            const page = await browser();
+            return page.evaluate(fn);
+        },
+        save,
+    };
+    return {
+        ctx,
+        async dispose() {
+            if (session) {
+                try {
+                    await session.dispose();
+                }
+                catch {
+                    // ignore teardown failures
+                }
+            }
+        },
+    };
+}

package/dist/src/core/define-site.js

@@ -1 +1,74 @@
-import{toLoginStrategy as t}from"../capabilities/login/login-strategy.js";export function isSite(t){return"object"==typeof t&&null!==t&&!0===t.__site}export function defineSite(e){if(isSite(e))return e;for(const t of["id","name","domain","description"])if(!e[t]||"string"!=typeof e[t])throw new Error(`Site is missing required string field "${t}"`);const i=Array.isArray(e.endpoints)&&e.endpoints.length>0;if(!e.run&&!i)throw new Error(`Site "${e.id}" must define either "endpoints" or "run"`);const n=e.run?async t=>e.run(t):(r=e.endpoints,async t=>{const e=r[0],i="html"===e.responseType?"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8":"text"===e.responseType?"text/plain,*/*;q=0.8":"application/json, text/plain, */*",n={method:e.method||"GET",headers:{Accept:i,...e.headers}};let o;return o="html"===e.responseType||"text"===e.responseType?await t.http.text(e.url,n):await t.http.json(e.url,n),e.transform?e.transform(o,t):o});var r;return{id:e.id,name:e.name,domain:e.domain,cookieDomain:e.cookieDomain??e.domain,description:e.description,transport:e.transport??"http",cookies:e.cookies??"required",fingerprint:e.fingerprint??"stealth",keepBrowserOpen:e.keepBrowserOpen??!1,auth:e.auth?t(e.auth):void 0,parameters:e.parameters??[],positionals:e.positionals??[],landingUrl:e.endpoints?.[0]?.url??`https://${e.domain}`,run:n,__site:!0}}
+import { toLoginStrategy } from "../capabilities/login/login-strategy.js";
+/** Detects an already-normalized site so loading is idempotent. */
+export function isSite(value) {
+    return typeof value === "object" && value !== null && value.__site === true;
+}
+/** Fetches one declared endpoint and applies its transform. */
+async function fetchEndpoint(endpoint, ctx) {
+    const accept = endpoint.responseType === "html"
+        ? "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+        : endpoint.responseType === "text"
+            ? "text/plain,*/*;q=0.8"
+            : "application/json, text/plain, */*";
+    const init = {
+        method: endpoint.method || "GET",
+        headers: { Accept: accept, ...endpoint.headers },
+    };
+    let body;
+    if (endpoint.responseType === "html" || endpoint.responseType === "text") {
+        body = await ctx.http.text(endpoint.url, init);
+    }
+    else {
+        body = await ctx.http.json(endpoint.url, init);
+    }
+    return endpoint.transform ? endpoint.transform(body, ctx) : body;
+}
+/**
+ * Builds the default `run` for a declarative, endpoint-based site. One
+ * endpoint returns its (transformed) body; several are fetched concurrently
+ * and returned as an array in declaration order.
+ */
+function endpointRun(endpoints) {
+    return async (ctx) => {
+        if (endpoints.length === 1)
+            return fetchEndpoint(endpoints[0], ctx);
+        return Promise.all(endpoints.map((endpoint) => fetchEndpoint(endpoint, ctx)));
+    };
+}
+/**
+ * Normalizes a minimal {@link SiteDef} into a fully-defaulted {@link Site}.
+ * Accepts a plain object (the common external-extension case), an already
+ * normalized site, or a class instance / factory result with the same fields.
+ */
+export function defineSite(def) {
+    if (isSite(def))
+        return def;
+    for (const field of ["id", "name", "domain", "description"]) {
+        if (!def[field] || typeof def[field] !== "string") {
+            throw new Error(`Site is missing required string field "${field}"`);
+        }
+    }
+    const hasEndpoints = Array.isArray(def.endpoints) && def.endpoints.length > 0;
+    if (!def.run && !hasEndpoints) {
+        throw new Error(`Site "${def.id}" must define either "endpoints" or "run"`);
+    }
+    const run = def.run ? async (ctx) => def.run(ctx) : endpointRun(def.endpoints);
+    return {
+        id: def.id,
+        name: def.name,
+        domain: def.domain,
+        cookieDomain: def.cookieDomain ?? def.domain,
+        description: def.description,
+        transport: def.transport ?? "http",
+        cookies: def.cookies ?? "required",
+        fingerprint: def.fingerprint ?? "stealth",
+        keepBrowserOpen: def.keepBrowserOpen ?? false,
+        auth: def.auth ? toLoginStrategy(def.auth) : undefined,
+        parameters: def.parameters ?? [],
+        positionals: def.positionals ?? [],
+        landingUrl: def.endpoints?.[0]?.url ?? `https://${def.domain}`,
+        endpoints: def.endpoints,
+        run,
+        __site: true,
+    };
+}