website-api 1.1.3 → 1.1.4

package/dist/src/core/loader.js

@@ -1 +1,142 @@
-import{existsSync as t,readdirSync as o,statSync as n}from"node:fs";import{homedir as r}from"node:os";import{dirname as e,join as s}from"node:path";import{fileURLToPath as i,pathToFileURL as c}from"node:url";import{defineSite as f,isSite as u}from"./define-site.js";const d=e(i(import.meta.url));export const BUNDLED_SITES_DIR=s(d,"..","sites");export function extensionRoots(t=process.env){const o=[],n=t.XDG_CONFIG_HOME||s(r(),".config");if(o.push(s(n,"website-api","extensions")),t.WEBSITE_API_EXTENSIONS)for(const n of t.WEBSITE_API_EXTENSIONS.split(":"))n.trim()&&o.push(n.trim());return o}function p(t){return!(!t.endsWith(".js")&&!t.endsWith(".mjs"))&&(!t.includes(".test.")&&!t.includes(".d.")&&!/(^|[-.])helper(s)?\.(m?js)$/i.test(t))}function a(t){const n=o(t);for(const o of["index.mjs","index.js"])if(n.includes(o))return s(t,o);const r=n.find(p);return r?s(t,r):null}function l(t){const r=[];let e;try{e=o(t)}catch{return r}for(const o of e){const e=s(t,o);let i;try{i=n(e)}catch{continue}if(i.isDirectory()){const t=a(e);t&&r.push(t)}else p(o)&&r.push(e)}return r}async function m(t,o){const n=await import(c(t).href);let r=n.default??n.site??n.sites;if(null==r)return[];if("function"==typeof r&&!u(r))try{r=new r}catch{try{r=r()}catch{return[]}}const e=Array.isArray(r)?r:[r],s=[];for(const t of e){if(!t||"object"!=typeof t)continue;const n=f(t);n.origin=o,s.push(n)}return s}export async function discoverSites(o={}){const n=o.env??process.env,r=[{dir:o.bundledDir??BUNDLED_SITES_DIR,origin:"bundled"},...(o.roots??extensionRoots(n)).map(t=>({dir:t,origin:"extension"}))],e=new Map;for(const{dir:o,origin:s}of r)if(t(o))for(const t of l(o))try{for(const o of await m(t,s))e.set(o.id,o)}catch(o){n.WEBSITE_API_DEBUG&&console.error(`[loader] failed to load ${t}:`,o)}return Array.from(e.values())}
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { defineSite, isSite } from "./define-site.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const errMessage = (err) => (err instanceof Error ? err.message : String(err));
+/** Bundled sites ship inside the package (dist/src/sites). */
+export const BUNDLED_SITES_DIR = join(__dirname, "..", "sites");
+/**
+ * Resolves the extension roots searched in addition to bundled sites:
+ *   1. <config>/website-api/extensions   (XDG_CONFIG_HOME or ~/.config)
+ *   2. each dir in $WEBSITE_API_EXTENSIONS (colon-separated)
+ *
+ * These hold the user's own sites, kept entirely outside the source tree.
+ */
+export function extensionRoots(env = process.env) {
+    const roots = [];
+    const configHome = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    roots.push(join(configHome, "website-api", "extensions"));
+    if (env.WEBSITE_API_EXTENSIONS) {
+        for (const dir of env.WEBSITE_API_EXTENSIONS.split(":")) {
+            if (dir.trim())
+                roots.push(dir.trim());
+        }
+    }
+    return roots;
+}
+function isLoadableSiteFile(name) {
+    if (!name.endsWith(".js") && !name.endsWith(".mjs"))
+        return false;
+    if (name.includes(".test.") || name.includes(".d."))
+        return false;
+    if (/(^|[-.])helper(s)?\.(m?js)$/i.test(name))
+        return false;
+    return true;
+}
+/** Picks the entry file inside a site directory (prefers `index`). */
+function entryFileIn(dir) {
+    const files = readdirSync(dir);
+    for (const candidate of ["index.mjs", "index.js"]) {
+        if (files.includes(candidate))
+            return join(dir, candidate);
+    }
+    const fallback = files.find(isLoadableSiteFile);
+    return fallback ? join(dir, fallback) : null;
+}
+/** Collects candidate entry files in a root: subdir entries + top-level files. */
+function collectSiteFiles(root) {
+    const files = [];
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return files;
+    }
+    for (const name of entries) {
+        const full = join(root, name);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            const entry = entryFileIn(full);
+            if (entry)
+                files.push(entry);
+        }
+        else if (isLoadableSiteFile(name)) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+/** Imports one file and normalizes any site(s) it default-exports. */
+async function loadSiteFile(filePath, origin) {
+    const mod = await import(pathToFileURL(filePath).href);
+    let exported = mod.default ?? mod.site ?? mod.sites;
+    if (exported == null)
+        return [];
+    // A class or factory function → instantiate/call.
+    if (typeof exported === "function" && !isSite(exported)) {
+        try {
+            exported = new exported();
+        }
+        catch (constructErr) {
+            try {
+                exported = exported();
+            }
+            catch (callErr) {
+                console.error(`[website-api] skipping ${filePath}: export is a function but failed as both ` +
+                    `a constructor (${errMessage(constructErr)}) and a factory (${errMessage(callErr)})`);
+                return [];
+            }
+        }
+    }
+    const list = Array.isArray(exported) ? exported : [exported];
+    const sites = [];
+    for (const item of list) {
+        if (!item || typeof item !== "object")
+            continue;
+        const site = defineSite(item);
+        site.origin = origin;
+        sites.push(site);
+    }
+    return sites;
+}
+/**
+ * Discovers and loads all sites from the bundled dir and every extension root.
+ * Later roots override earlier ones by `id`, so a user extension can shadow a
+ * bundled site. Failures in one file never abort the whole load.
+ */
+export async function discoverSites(options = {}) {
+    const env = options.env ?? process.env;
+    const searchRoots = [
+        { dir: options.bundledDir ?? BUNDLED_SITES_DIR, origin: "bundled" },
+        ...(options.roots ?? extensionRoots(env)).map((dir) => ({ dir, origin: "extension" })),
+    ];
+    const byId = new Map();
+    for (const { dir, origin } of searchRoots) {
+        if (!existsSync(dir))
+            continue;
+        for (const file of collectSiteFiles(dir)) {
+            try {
+                for (const site of await loadSiteFile(file, origin)) {
+                    byId.set(site.id, site);
+                }
+            }
+            catch (err) {
+                // A broken site must never abort the others, but it must not vanish
+                // silently either — extension authors need the one-liner to diagnose.
+                console.error(`[website-api] failed to load site ${file}: ${errMessage(err)}`);
+                if (env.WEBSITE_API_DEBUG)
+                    console.error(err);
+            }
+        }
+    }
+    return Array.from(byId.values());
+}

package/dist/src/core/registry.js

@@ -1 +1,332 @@
-import{createHash as e}from"node:crypto";import{existsSync as t,mkdirSync as r,readdirSync as n,readFileSync as o,rmSync as i,statSync as s,writeFileSync as c}from"node:fs";import{homedir as a}from"node:os";import{dirname as f,join as p}from"node:path";import{pathToFileURL as u}from"node:url";import{defineSite as l}from"./define-site.js";import{extensionRoots as d}from"./loader.js";export const DEFAULT_REGISTRY={name:"guocity",repo:"guocity/website-api-list",branch:"main"};function h(e){return e.XDG_CONFIG_HOME||p(a(),".config")}export function configPath(e=process.env){return p(h(e),"website-api","config.json")}function m(e){return d(e)[0]}export function parseRepoSpec(e){let t=e.trim();t=t.replace(/^https?:\/\/github\.com\//i,"").replace(/^github:/i,""),t=t.replace(/\.git$/i,"").replace(/\/$/,"");let r="main";const n=t.indexOf("#");n>=0&&(r=t.slice(n+1)||"main",t=t.slice(0,n));const o=t.split("/").filter(Boolean);if(o.length<2)throw new Error(`Invalid registry spec "${e}" (expected owner/repo)`);const i=`${o[0]}/${o[1]}`;return{name:o[0],repo:i,branch:r}}function g(e){const r=configPath(e);if(!t(r))return{};try{return JSON.parse(o(r,"utf8"))}catch{return{}}}function w(e,t){const n=configPath(t);r(f(n),{recursive:!0}),c(n,JSON.stringify(e,null,2)+"\n","utf8")}export function resolveRegistries(e=process.env){const t=[],r=new Set,n=e=>{r.has(e.repo)||(r.add(e.repo),t.push(e))};if(e.WEBSITE_API_REGISTRY)for(const t of e.WEBSITE_API_REGISTRY.split(","))t.trim()&&n(parseRepoSpec(t));for(const t of g(e).registries??[])n(t);return n(DEFAULT_REGISTRY),t}export function addRegistry(e,t=process.env){const r=parseRepoSpec(e),n=g(t);return n.registries=(n.registries??[]).filter(e=>e.repo!==r.repo),n.registries.push(r),w(n,t),r}export function removeRegistry(e,t=process.env){const r=g(t),n=r.registries?.length??0;return r.registries=(r.registries??[]).filter(t=>t.repo!==e&&t.name!==e),w(r,t),(r.registries?.length??0)<n}function y(e,t,r){return`https://raw.githubusercontent.com/${e}/${t}/${r}`}function v(){return e=>fetch(e)}async function $(e,t){const r=await t(e);if(!r.ok)throw new Error(`GET ${e} → HTTP ${r.status}`);return Buffer.from(await r.arrayBuffer())}function E(t){return e("sha256").update(t).digest("hex")}export async function loadIndex(e,n={}){const i=n.env??process.env,s=n.fetchImpl??v(),a=n.ttlMs??36e5,u=function(e,t){const r=e.replace(/[^a-z0-9._-]+/gi,"_");return p(h(t),"website-api","cache",`${r}.json`)}(e.repo,i);if(!n.refresh&&t(u))try{const{fetchedAt:e,index:t}=JSON.parse(o(u,"utf8"));if("number"==typeof e&&Date.now()-e<a)return t}catch{}const l=await async function(e,t){const r=await t(e);if(!r.ok)throw new Error(`GET ${e} → HTTP ${r.status}`);return r.text()}(y(e.repo,e.branch,"index.json"),s),d=JSON.parse(l);if(!d||!Array.isArray(d.sites))throw new Error(`Registry ${e.repo} has no valid index.json`);try{r(f(u),{recursive:!0}),c(u,JSON.stringify({fetchedAt:Date.now(),index:d}),"utf8")}catch{}return d}export async function searchRegistries(e,t={}){const r=t.env??process.env,n=e.trim().toLowerCase(),o=[];for(const e of resolveRegistries(r)){let r;try{r=await loadIndex(e,t)}catch{continue}for(const t of r.sites){const r=[t.id,t.name,t.domain,t.description,...t.tags??[]].join(" ").toLowerCase();n&&!r.includes(n)||o.push({...t,registry:e})}}return o}export async function resolveEntry(e,t={}){const r=t.env??process.env,n=[];for(const o of resolveRegistries(r)){if(t.registryName&&o.name!==t.registryName&&o.repo!==t.registryName)continue;let r;try{r=await loadIndex(o,t)}catch{continue}const i=r.sites.find(t=>t.id===e);i&&n.push({source:o,index:r,entry:i})}if(0===n.length)throw new Error(`Site "${e}" not found in any registry`);if(n.length>1){const t=n.map(e=>e.source.name).join(", ");throw new Error(`Site "${e}" is offered by multiple registries (${t}); pass --registry <name>`)}return n[0]}export async function installEntry(e,t,n,o={}){const s=o.env??process.env,a=o.fetchImpl??v();if(!n.files?.length)throw new Error(`Catalog entry "${n.id}" lists no files`);const d=p(m(s),n.id),h=[];for(const r of n.files){const o=y(e.repo,t.commit,`${n.path}/${r.name}`),i=await $(o,a),s=E(i);if(s!==r.sha256)throw new Error(`Integrity check failed for ${n.id}/${r.name} (expected ${r.sha256.slice(0,12)}…, got ${s.slice(0,12)}…)`);h.push({name:r.name,buf:i})}i(d,{recursive:!0,force:!0}),r(d,{recursive:!0});for(const{name:e,buf:t}of h){const n=p(d,e);r(f(n),{recursive:!0}),c(n,t)}await async function(e,t){let r;try{r=await import(u(e).href)}catch(e){throw new Error(`Downloaded site failed to import: ${e instanceof Error?e.message:String(e)}`)}const n=r.default??r.site;if(!n||"object"!=typeof n)throw new Error(`Downloaded ${e} does not default-export a site object`);const o=l(n);if(o.id!==t)throw new Error(`Catalog id "${t}" does not match the site's own id "${o.id}"`)}(p(d,n.files[0].name),n.id);const g={id:n.id,registry:e.name,repo:e.repo,commit:t.commit,version:n.version,installedAt:(new Date).toISOString()};return c(p(d,".source.json"),JSON.stringify(g,null,2)+"\n","utf8"),{dir:d,record:g}}export function listInstalled(e=process.env){const r=m(e);if(!t(r))return[];const i=[];for(const e of n(r)){const t=p(r,e,".source.json");try{s(t).isFile()&&i.push(JSON.parse(o(t,"utf8")))}catch{}}return i}export function removeInstalled(e,r=process.env){const n=p(m(r),e);return!!t(n)&&(i(n,{recursive:!0,force:!0}),!0)}
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { defineSite } from "./define-site.js";
+import { extensionRoots } from "./loader.js";
+/** Built-in default registry, used when the user has configured none. */
+export const DEFAULT_REGISTRY = {
+    name: "guocity",
+    repo: "guocity/website-api-list",
+    branch: "main",
+};
+const INDEX_TTL_MS = 60 * 60 * 1000; // 1h cache for the catalog
+// ───────────────────────────── paths ─────────────────────────────
+function configHome(env) {
+    return env.XDG_CONFIG_HOME || join(homedir(), ".config");
+}
+/** `~/.config/website-api/config.json` */
+export function configPath(env = process.env) {
+    return join(configHome(env), "website-api", "config.json");
+}
+function cachePath(repo, env) {
+    const safe = repo.replace(/[^a-z0-9._-]+/gi, "_");
+    return join(configHome(env), "website-api", "cache", `${safe}.json`);
+}
+/** Install destination: the first (XDG) extensions root. */
+function installRoot(env) {
+    return extensionRoots(env)[0];
+}
+// ───────────────────────────── config / sources ─────────────────────────────
+/** Parses "owner/repo", "owner/repo#branch", or a github.com URL. */
+export function parseRepoSpec(spec) {
+    let s = spec.trim();
+    s = s.replace(/^https?:\/\/github\.com\//i, "").replace(/^github:/i, "");
+    s = s.replace(/\.git$/i, "").replace(/\/$/, "");
+    let branch = "main";
+    const hash = s.indexOf("#");
+    if (hash >= 0) {
+        branch = s.slice(hash + 1) || "main";
+        s = s.slice(0, hash);
+    }
+    const parts = s.split("/").filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error(`Invalid registry spec "${spec}" (expected owner/repo)`);
+    }
+    const repo = `${parts[0]}/${parts[1]}`;
+    return { name: parts[0], repo, branch };
+}
+function readConfig(env) {
+    const path = configPath(env);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(cfg, env) {
+    const path = configPath(env);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/**
+ * The registries to search, in priority order:
+ *   1. $WEBSITE_API_REGISTRY (one-off override; may be a comma list)
+ *   2. configured registries in config.json
+ *   3. the built-in DEFAULT_REGISTRY (always present as a fallback)
+ * Later duplicates by `repo` are dropped.
+ */
+export function resolveRegistries(env = process.env) {
+    const out = [];
+    const seen = new Set();
+    const push = (s) => {
+        if (!seen.has(s.repo)) {
+            seen.add(s.repo);
+            out.push(s);
+        }
+    };
+    if (env.WEBSITE_API_REGISTRY) {
+        for (const spec of env.WEBSITE_API_REGISTRY.split(",")) {
+            if (spec.trim())
+                push(parseRepoSpec(spec));
+        }
+    }
+    for (const s of readConfig(env).registries ?? [])
+        push(s);
+    push(DEFAULT_REGISTRY);
+    return out;
+}
+/** Adds a registry to config.json (idempotent by repo). Returns the source. */
+export function addRegistry(spec, env = process.env) {
+    const source = parseRepoSpec(spec);
+    const cfg = readConfig(env);
+    cfg.registries = (cfg.registries ?? []).filter((r) => r.repo !== source.repo);
+    cfg.registries.push(source);
+    writeConfig(cfg, env);
+    return source;
+}
+/** Removes a registry from config.json by repo or name. Returns true if removed. */
+export function removeRegistry(repoOrName, env = process.env) {
+    const cfg = readConfig(env);
+    const before = cfg.registries?.length ?? 0;
+    cfg.registries = (cfg.registries ?? []).filter((r) => r.repo !== repoOrName && r.name !== repoOrName);
+    writeConfig(cfg, env);
+    return (cfg.registries?.length ?? 0) < before;
+}
+// ───────────────────────────── fetching ─────────────────────────────
+function rawUrl(repo, ref, path) {
+    return `https://raw.githubusercontent.com/${repo}/${ref}/${path}`;
+}
+function defaultFetch() {
+    return (url) => fetch(url);
+}
+async function getText(url, fetchImpl) {
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new Error(`GET ${url} → HTTP ${res.status}`);
+    return res.text();
+}
+async function getBuffer(url, fetchImpl) {
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new Error(`GET ${url} → HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+function sha256(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+/**
+ * Validates a fetched index.json before anything downstream trusts its shape.
+ * Registries live on the open internet — a malformed catalog must fail here
+ * with a pointed message, not at install time with a TypeError.
+ */
+function validateIndex(data, repo) {
+    const bad = (detail) => {
+        throw new Error(`Registry ${repo} has an invalid index.json: ${detail}`);
+    };
+    if (!data || typeof data !== "object")
+        bad("not an object");
+    const index = data;
+    if (typeof index.commit !== "string" || !index.commit)
+        bad(`missing "commit"`);
+    if (!Array.isArray(index.sites))
+        bad(`"sites" is not an array`);
+    index.sites.forEach((entry, i) => {
+        for (const field of ["id", "name", "domain", "description", "path"]) {
+            if (typeof entry?.[field] !== "string" || !entry[field])
+                bad(`sites[${i}].${field} is missing`);
+        }
+        if (!Array.isArray(entry.files) || entry.files.length === 0)
+            bad(`sites[${i}].files is empty`);
+        entry.files.forEach((file, j) => {
+            if (typeof file?.name !== "string" || !file.name)
+                bad(`sites[${i}].files[${j}].name is missing`);
+            if (typeof file?.sha256 !== "string" || !/^[0-9a-f]{64}$/i.test(file.sha256)) {
+                bad(`sites[${i}].files[${j}].sha256 is not a sha256 hex digest`);
+            }
+        });
+    });
+    return index;
+}
+/** Loads (and disk-caches with a TTL) one registry's index.json. */
+export async function loadIndex(source, opts = {}) {
+    const env = opts.env ?? process.env;
+    const fetchImpl = opts.fetchImpl ?? defaultFetch();
+    const ttl = opts.ttlMs ?? INDEX_TTL_MS;
+    const cache = cachePath(source.repo, env);
+    if (!opts.refresh && existsSync(cache)) {
+        try {
+            const { fetchedAt, index } = JSON.parse(readFileSync(cache, "utf8"));
+            if (typeof fetchedAt === "number" && Date.now() - fetchedAt < ttl) {
+                return index;
+            }
+        }
+        catch {
+            // fall through to a fresh fetch
+        }
+    }
+    const text = await getText(rawUrl(source.repo, source.branch, "index.json"), fetchImpl);
+    const index = validateIndex(JSON.parse(text), source.repo);
+    try {
+        mkdirSync(dirname(cache), { recursive: true });
+        writeFileSync(cache, JSON.stringify({ fetchedAt: Date.now(), index }), "utf8");
+    }
+    catch {
+        // a non-writable cache must not break the install
+    }
+    return index;
+}
+/** Searches every configured registry; optional free-text query over id/name/domain/tags. */
+export async function searchRegistries(query, opts = {}) {
+    const env = opts.env ?? process.env;
+    const q = query.trim().toLowerCase();
+    const out = [];
+    for (const source of resolveRegistries(env)) {
+        let index;
+        try {
+            index = await loadIndex(source, opts);
+        }
+        catch {
+            continue; // an unreachable registry never aborts the search
+        }
+        for (const entry of index.sites) {
+            const haystack = [entry.id, entry.name, entry.domain, entry.description, ...(entry.tags ?? [])]
+                .join(" ")
+                .toLowerCase();
+            if (!q || haystack.includes(q))
+                out.push({ ...entry, registry: source });
+        }
+    }
+    return out;
+}
+/**
+ * Resolves a single id to its catalog entry. If `registryName` is omitted and
+ * more than one registry offers the id, throws and asks the caller to choose.
+ */
+export async function resolveEntry(id, opts = {}) {
+    const env = opts.env ?? process.env;
+    const matches = [];
+    for (const source of resolveRegistries(env)) {
+        if (opts.registryName && source.name !== opts.registryName && source.repo !== opts.registryName)
+            continue;
+        let index;
+        try {
+            index = await loadIndex(source, opts);
+        }
+        catch {
+            continue;
+        }
+        const entry = index.sites.find((s) => s.id === id);
+        if (entry)
+            matches.push({ source, index, entry });
+    }
+    if (matches.length === 0)
+        throw new Error(`Site "${id}" not found in any registry`);
+    if (matches.length > 1) {
+        const names = matches.map((m) => m.source.name).join(", ");
+        throw new Error(`Site "${id}" is offered by multiple registries (${names}); pass --registry <name>`);
+    }
+    return matches[0];
+}
+// ───────────────────────────── install / list / remove ─────────────────────────────
+/**
+ * Downloads one site's files (pinned to `index.commit`), verifies each against
+ * its sha256, writes them to the extensions root, validates the entry actually
+ * loads as a site, and records provenance. Returns the install directory.
+ */
+export async function installEntry(source, index, entry, opts = {}) {
+    const env = opts.env ?? process.env;
+    const fetchImpl = opts.fetchImpl ?? defaultFetch();
+    if (!entry.files?.length)
+        throw new Error(`Catalog entry "${entry.id}" lists no files`);
+    const dir = join(installRoot(env), entry.id);
+    const staged = [];
+    // Download + verify everything before writing anything, so a bad hash
+    // mid-download never leaves a half-installed site behind.
+    for (const file of entry.files) {
+        const url = rawUrl(source.repo, index.commit, `${entry.path}/${file.name}`);
+        const buf = await getBuffer(url, fetchImpl);
+        const got = sha256(buf);
+        if (got !== file.sha256) {
+            throw new Error(`Integrity check failed for ${entry.id}/${file.name} (expected ${file.sha256.slice(0, 12)}…, got ${got.slice(0, 12)}…)`);
+        }
+        staged.push({ name: file.name, buf });
+    }
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    for (const { name, buf } of staged) {
+        const target = join(dir, name);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, buf);
+    }
+    // Validate it loads as a site whose id matches the catalog.
+    await assertLoadsAsSite(join(dir, entry.files[0].name), entry.id);
+    const record = {
+        id: entry.id,
+        registry: source.name,
+        repo: source.repo,
+        commit: index.commit,
+        version: entry.version,
+        installedAt: new Date().toISOString(),
+    };
+    writeFileSync(join(dir, ".source.json"), JSON.stringify(record, null, 2) + "\n", "utf8");
+    return { dir, record };
+}
+/** Imports a downloaded entry file and confirms it normalizes to the expected id. */
+async function assertLoadsAsSite(filePath, expectedId) {
+    let mod;
+    try {
+        mod = await import(pathToFileURL(filePath).href);
+    }
+    catch (err) {
+        throw new Error(`Downloaded site failed to import: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const exported = mod.default ?? mod.site;
+    if (!exported || typeof exported !== "object") {
+        throw new Error(`Downloaded ${filePath} does not default-export a site object`);
+    }
+    const site = defineSite(exported); // throws on missing required fields
+    if (site.id !== expectedId) {
+        throw new Error(`Catalog id "${expectedId}" does not match the site's own id "${site.id}"`);
+    }
+}
+/** Lists locally installed registry sites (those carrying a `.source.json`). */
+export function listInstalled(env = process.env) {
+    const root = installRoot(env);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const name of readdirSync(root)) {
+        const meta = join(root, name, ".source.json");
+        try {
+            if (statSync(meta).isFile())
+                out.push(JSON.parse(readFileSync(meta, "utf8")));
+        }
+        catch {
+            // not a registry-installed site; ignore
+        }
+    }
+    return out;
+}
+/** Removes an installed site directory. Returns true if something was removed. */
+export function removeInstalled(id, env = process.env) {
+    const dir = join(installRoot(env), id);
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}

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

@@ -1,8 +1,9 @@
-import type { QueryOptions, Site } from "../types.js";
+import type { QueryOptions, Site, SiteDef } from "../types.js";
 import { type ContextProviders } from "./context.js";
 /** The loaded site registry, populated by {@link loadSites}. */
 export declare let sites: Site[];
-/** Auto-discovers and loads all sites (bundled + extensions). Idempotent. */
+/** Auto-discovers and loads all sites (bundled + extensions). Idempotent —
+ * concurrent callers share one in-flight discovery. */
 export declare function loadSites(force?: boolean): Promise<Site[]>;
 /** Test/embedding hook: replace the registry with an explicit set. */
 export declare function setSites(next: Site[]): void;
@@ -14,7 +15,14 @@ export declare function getSite(id: string): Site | null;
  */
 export declare function createUniversalSite(websiteId: string): Site | null;
 /**
- * Resolves a site (dedicated or universal), runs it with a fresh capability
- * context, and guarantees teardown of any browser session.
+ * Runs a single site (or plain site definition) with a fresh capability
+ * context and guaranteed teardown. This is the embedding API for other
+ * packages: import a bundled site via `website-api/sites/<dir>` (or bring
+ * your own definition) and execute it directly — no registry involved.
+ */
+export declare function runSite(siteOrDef: Site | SiteDef, options?: QueryOptions, providers?: ContextProviders): Promise<unknown>;
+/**
+ * Resolves a site by id from the loaded registry (or falls back to a
+ * universal GET for unknown domains/URLs) and runs it.
  */
 export declare function queryWebsite(websiteId: string, options?: QueryOptions, providers?: ContextProviders): Promise<unknown>;

package/dist/src/core/runtime.js

@@ -1 +1,98 @@
-import{defineSite as t}from"./define-site.js";import{discoverSites as e}from"./loader.js";import{createContext as o}from"./context.js";export let sites=[];let r=!1;export async function loadSites(t=!1){return r&&!t||(sites=await e(),r=!0),sites}export function setSites(t){sites=t,r=!0}export function getSite(t){if(!t)return null;const e=t.toLowerCase().trim();return sites.find(t=>t.id.toLowerCase()===e||t.id.toLowerCase().replace(".com","")===e||t.domain.toLowerCase()===e||t.domain.toLowerCase().replace(".com","")===e)??null}export function createUniversalSite(e){let o=e;o.startsWith("http://")||o.startsWith("https://")||(o="https://"+o);try{const r=new URL(o);return t({id:e,name:e,domain:r.hostname,description:`Universal site for ${r.hostname}`,cookies:"optional",endpoints:[{url:r.href}]})}catch{return null}}export async function queryWebsite(t,e={},r={}){await loadSites();let i=getSite(t);if(!i){if(!function(t){return t.startsWith("http://")||t.startsWith("https://")||t.includes(".")||t.includes("/")||t.includes(":")}(t))throw new Error("command not found");if(i=createUniversalSite(t),!i)throw new Error("command not found")}const{ctx:n,dispose:s}=o(i,e,r);try{return await i.run(n)}finally{await s()}}
+import { createContext } from "./context.js";
+import { defineSite } from "./define-site.js";
+import { discoverSites } from "./loader.js";
+/** The loaded site registry, populated by {@link loadSites}. */
+export let sites = [];
+let loadPromise;
+/** Auto-discovers and loads all sites (bundled + extensions). Idempotent —
+ * concurrent callers share one in-flight discovery. */
+export async function loadSites(force = false) {
+    if (!loadPromise || force) {
+        loadPromise = discoverSites().then((found) => {
+            sites = found;
+            return sites;
+        });
+        loadPromise.catch(() => {
+            loadPromise = undefined; // allow retry after a failed discovery
+        });
+    }
+    return loadPromise;
+}
+/** Test/embedding hook: replace the registry with an explicit set. */
+export function setSites(next) {
+    sites = next;
+    loadPromise = Promise.resolve(next);
+}
+/** Finds a site by exact id/domain or a `.com`-insensitive match. */
+export function getSite(id) {
+    if (!id)
+        return null;
+    const normalized = id.toLowerCase().trim();
+    return (sites.find((s) => s.id.toLowerCase() === normalized ||
+        s.id.toLowerCase().replace(".com", "") === normalized ||
+        s.domain.toLowerCase() === normalized ||
+        s.domain.toLowerCase().replace(".com", "") === normalized) ?? null);
+}
+function isLikelyDomainOrUrl(websiteId) {
+    return (websiteId.startsWith("http://") ||
+        websiteId.startsWith("https://") ||
+        websiteId.includes(".") ||
+        websiteId.includes("/") ||
+        websiteId.includes(":"));
+}
+/**
+ * Creates a fallback site for any URL/domain without a dedicated definition:
+ * a single GET to the URL with optional cookies.
+ */
+export function createUniversalSite(websiteId) {
+    let urlStr = websiteId;
+    if (!urlStr.startsWith("http://") && !urlStr.startsWith("https://")) {
+        urlStr = "https://" + urlStr;
+    }
+    try {
+        const url = new URL(urlStr);
+        return defineSite({
+            id: websiteId,
+            name: websiteId,
+            domain: url.hostname,
+            description: `Universal site for ${url.hostname}`,
+            cookies: "optional",
+            endpoints: [{ url: url.href }],
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runs a single site (or plain site definition) with a fresh capability
+ * context and guaranteed teardown. This is the embedding API for other
+ * packages: import a bundled site via `website-api/sites/<dir>` (or bring
+ * your own definition) and execute it directly — no registry involved.
+ */
+export async function runSite(siteOrDef, options = {}, providers = {}) {
+    const site = defineSite(siteOrDef);
+    const { ctx, dispose } = createContext(site, options, providers);
+    try {
+        return await site.run(ctx);
+    }
+    finally {
+        await dispose();
+    }
+}
+/**
+ * Resolves a site by id from the loaded registry (or falls back to a
+ * universal GET for unknown domains/URLs) and runs it.
+ */
+export async function queryWebsite(websiteId, options = {}, providers = {}) {
+    await loadSites();
+    let site = getSite(websiteId);
+    if (!site) {
+        if (!isLikelyDomainOrUrl(websiteId))
+            throw new Error("command not found");
+        site = createUniversalSite(websiteId);
+        if (!site)
+            throw new Error("command not found");
+    }
+    return runSite(site, options, providers);
+}

package/dist/src/env.js

@@ -1 +1,34 @@
-import{readFileSync as t,existsSync as n}from"node:fs";import{dirname as o,resolve as r}from"node:path";import{fileURLToPath as s}from"node:url";const i=o(s(import.meta.url));export function loadEnv(){try{const o=r(i,"../../.env");if(!n(o))return;const s=t(o,"utf8");for(const t of s.split(/\r?\n/)){const n=t.trim();if(!n||n.startsWith("#"))continue;const o=n.indexOf("=");if(o<=0)continue;const r=n.substring(0,o).trim();let s=n.substring(o+1).trim();(s.startsWith('"')&&s.endsWith('"')||s.startsWith("'")&&s.endsWith("'"))&&(s=s.substring(1,s.length-1)),process.env[r]=s}}catch{}}
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Loads environment variables from the project root .env file.
+ * Silently skips if the file doesn't exist.
+ */
+export function loadEnv() {
+    try {
+        const envPath = resolve(__dirname, "../../.env");
+        if (!existsSync(envPath))
+            return;
+        const content = readFileSync(envPath, "utf8");
+        for (const line of content.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIndex = trimmed.indexOf("=");
+            if (eqIndex <= 0)
+                continue;
+            const key = trimmed.substring(0, eqIndex).trim();
+            let val = trimmed.substring(eqIndex + 1).trim();
+            // Strip surrounding quotes
+            if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+                val = val.substring(1, val.length - 1);
+            }
+            process.env[key] = val;
+        }
+    }
+    catch {
+        // Fail silently
+    }
+}

package/dist/src/sites/bloomberg.com/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The page embeds the entire ranking inline as a global:
+ *   `window.top500 = [ ...500 objects... ];`
+ * Each entry carries rank, worth/fWorth, biography, netWorthSummary, milestones,
+ * public/private/cash assets, schools, industry, etc. There is no JSON API — the
+ * data lives in the HTML — and the site is fronted by PerimeterX, so a plain
+ * fetch gets flagged. We drive the CDP-attached Chrome, clear any PerimeterX
+ * challenge automatically, then read the global out of the page.
+ */
+declare const _default: import("../../types.js").Site;
+export default _default;