backpack-viewer 0.6.0 → 0.7.1

package/dist/server-api-routes.js

@@ -0,0 +1,460 @@
+import { listBackpacks, getActiveBackpack, setActiveBackpack, registerBackpack, unregisterBackpack, } from "backpack-ontology";
+// --- Small HTTP helpers (used only inside this module) ---
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, value) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(value));
+}
+function sendErr(res, status, message) {
+    sendJson(res, status, { error: message });
+}
+function urlPath(req) {
+    return (req.url ?? "/").replace(/\?.*$/, "");
+}
+// --- Main dispatcher ---
+/**
+ * Try to match and handle an API request. Returns true if the request
+ * was handled (response written), false if no route matched and the
+ * caller should fall through to its own handlers (e.g., static files).
+ *
+ * Errors that escape route handlers result in a 500 with a JSON body.
+ */
+export async function handleApiRequest(req, res, ctx) {
+    const method = req.method ?? "GET";
+    const url = urlPath(req);
+    try {
+        // --- /api/config ---
+        if (url === "/api/config" && method === "GET") {
+            sendJson(res, 200, ctx.viewerConfig);
+            return true;
+        }
+        // --- /api/version-check ---
+        if (url === "/api/version-check" && method === "GET") {
+            const result = await ctx.versionCheck();
+            sendJson(res, 200, result);
+            return true;
+        }
+        // --- /api/remotes (read-only) ---
+        if (url === "/api/remotes" && method === "GET") {
+            const remotes = await ctx.remoteRegistry.list();
+            const summaries = await Promise.all(remotes.map(async (r) => {
+                let nodeCount = 0;
+                let edgeCount = 0;
+                try {
+                    const data = await ctx.remoteRegistry.loadCached(r.name);
+                    nodeCount = data.nodes.length;
+                    edgeCount = data.edges.length;
+                }
+                catch {
+                    /* keep counts at 0 */
+                }
+                return {
+                    name: r.name,
+                    url: r.url,
+                    source: r.source,
+                    addedAt: r.addedAt,
+                    lastFetched: r.lastFetched,
+                    pinned: r.pinned,
+                    sizeBytes: r.sizeBytes,
+                    nodeCount,
+                    edgeCount,
+                };
+            }));
+            sendJson(res, 200, summaries);
+            return true;
+        }
+        const remoteItem = url.match(/^\/api\/remotes\/(.+)$/);
+        if (remoteItem && method === "GET") {
+            const name = decodeURIComponent(remoteItem[1]);
+            try {
+                const data = await ctx.remoteRegistry.loadCached(name);
+                sendJson(res, 200, data);
+            }
+            catch (err) {
+                sendErr(res, 404, err.message);
+            }
+            return true;
+        }
+        // --- /api/graphs/<name>/branches/* ---
+        const branchSwitch = url.match(/^\/api\/graphs\/(.+)\/branches\/switch$/);
+        if (branchSwitch && method === "POST") {
+            const graphName = decodeURIComponent(branchSwitch[1]);
+            const body = await readBody(req);
+            try {
+                const { name: branchName } = JSON.parse(body);
+                await ctx.storage.current.switchBranch(graphName, branchName);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        const deleteBranch = url.match(/^\/api\/graphs\/(.+)\/branches\/(.+)$/);
+        if (deleteBranch && method === "DELETE") {
+            const graphName = decodeURIComponent(deleteBranch[1]);
+            const branchName = decodeURIComponent(deleteBranch[2]);
+            try {
+                await ctx.storage.current.deleteBranch(graphName, branchName);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        const branches = url.match(/^\/api\/graphs\/(.+)\/branches$/);
+        if (branches && method === "GET") {
+            const graphName = decodeURIComponent(branches[1]);
+            try {
+                const list = await ctx.storage.current.listBranches(graphName);
+                sendJson(res, 200, list);
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        if (branches && method === "POST") {
+            const graphName = decodeURIComponent(branches[1]);
+            const body = await readBody(req);
+            try {
+                const { name: branchName, from } = JSON.parse(body);
+                await ctx.storage.current.createBranch(graphName, branchName, from);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        // --- /api/graphs/<name>/snapshots ---
+        const snapshots = url.match(/^\/api\/graphs\/(.+)\/snapshots$/);
+        if (snapshots && method === "GET") {
+            const graphName = decodeURIComponent(snapshots[1]);
+            try {
+                const list = await ctx.storage.current.listSnapshots(graphName);
+                sendJson(res, 200, list);
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        if (snapshots && method === "POST") {
+            const graphName = decodeURIComponent(snapshots[1]);
+            const body = await readBody(req);
+            try {
+                const { label } = JSON.parse(body);
+                await ctx.storage.current.createSnapshot(graphName, label);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        // --- /api/graphs/<name>/rollback ---
+        const rollback = url.match(/^\/api\/graphs\/(.+)\/rollback$/);
+        if (rollback && method === "POST") {
+            const graphName = decodeURIComponent(rollback[1]);
+            const body = await readBody(req);
+            try {
+                const { version } = JSON.parse(body);
+                await ctx.storage.current.rollback(graphName, version);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        // --- /api/graphs/<name>/diff/<version> ---
+        const diff = url.match(/^\/api\/graphs\/(.+)\/diff\/(\d+)$/);
+        if (diff && method === "GET") {
+            const graphName = decodeURIComponent(diff[1]);
+            const version = parseInt(diff[2], 10);
+            try {
+                const current = await ctx.storage.current.loadOntology(graphName);
+                const snapshot = await ctx.storage.current.loadSnapshot(graphName, version);
+                const currentNodeIds = new Set(current.nodes.map((n) => n.id));
+                const snapshotNodeIds = new Set(snapshot.nodes.map((n) => n.id));
+                const currentEdgeIds = new Set(current.edges.map((e) => e.id));
+                const snapshotEdgeIds = new Set(snapshot.edges.map((e) => e.id));
+                sendJson(res, 200, {
+                    nodesAdded: current.nodes.filter((n) => !snapshotNodeIds.has(n.id)).length,
+                    nodesRemoved: snapshot.nodes.filter((n) => !currentNodeIds.has(n.id)).length,
+                    edgesAdded: current.edges.filter((e) => !snapshotEdgeIds.has(e.id)).length,
+                    edgesRemoved: snapshot.edges.filter((e) => !currentEdgeIds.has(e.id)).length,
+                });
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        // --- /api/graphs/<name>/snippets/<id> ---
+        const snippetItem = url.match(/^\/api\/graphs\/(.+)\/snippets\/(.+)$/);
+        if (snippetItem && method === "GET") {
+            const graphName = decodeURIComponent(snippetItem[1]);
+            const snippetId = decodeURIComponent(snippetItem[2]);
+            try {
+                const snippet = await ctx.storage.current.loadSnippet(graphName, snippetId);
+                sendJson(res, 200, snippet);
+            }
+            catch {
+                sendErr(res, 404, "Snippet not found");
+            }
+            return true;
+        }
+        if (snippetItem && method === "DELETE") {
+            const graphName = decodeURIComponent(snippetItem[1]);
+            const snippetId = decodeURIComponent(snippetItem[2]);
+            try {
+                await ctx.storage.current.deleteSnippet(graphName, snippetId);
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        const snippets = url.match(/^\/api\/graphs\/(.+)\/snippets$/);
+        if (snippets && method === "GET") {
+            const graphName = decodeURIComponent(snippets[1]);
+            try {
+                const list = await ctx.storage.current.listSnippets(graphName);
+                sendJson(res, 200, list);
+            }
+            catch {
+                sendJson(res, 200, []);
+            }
+            return true;
+        }
+        if (snippets && method === "POST") {
+            const graphName = decodeURIComponent(snippets[1]);
+            const body = await readBody(req);
+            try {
+                const { label, description, nodeIds, edgeIds } = JSON.parse(body);
+                const id = await ctx.storage.current.saveSnippet(graphName, {
+                    label,
+                    description,
+                    nodeIds,
+                    edgeIds: edgeIds ?? [],
+                });
+                sendJson(res, 200, { ok: true, id });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        // --- /api/backpacks (meta: list, active, register, switch, unregister) ---
+        if (url === "/api/backpacks" && method === "GET") {
+            try {
+                const list = await listBackpacks();
+                const active = await getActiveBackpack();
+                sendJson(res, 200, list.map((b) => ({ ...b, active: b.name === active.name })));
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        if (url === "/api/backpacks/active" && method === "GET") {
+            try {
+                const active = await getActiveBackpack();
+                sendJson(res, 200, active);
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        if (url === "/api/backpacks/switch" && method === "POST") {
+            const body = await readBody(req);
+            try {
+                const { name } = JSON.parse(body);
+                await setActiveBackpack(name);
+                const swapped = await ctx.makeBackend();
+                ctx.storage.current = swapped.backend;
+                ctx.storage.activeEntry = swapped.entry;
+                ctx.onActiveBackpackChange?.();
+                sendJson(res, 200, { ok: true, active: ctx.storage.activeEntry });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        if (url === "/api/backpacks" && method === "POST") {
+            const body = await readBody(req);
+            try {
+                const { name, path: p, activate } = JSON.parse(body);
+                // registerBackpack only takes a path; the name is derived by
+                // backpack-ontology from the directory. Pre-existing call sites
+                // pass `name` as a hint but it's not used by the function.
+                void name;
+                const entry = await registerBackpack(p);
+                if (activate) {
+                    await setActiveBackpack(name);
+                    const swapped = await ctx.makeBackend();
+                    ctx.storage.current = swapped.backend;
+                    ctx.storage.activeEntry = swapped.entry;
+                    ctx.onActiveBackpackChange?.();
+                }
+                sendJson(res, 200, { ok: true, entry });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        const backpackDelete = url.match(/^\/api\/backpacks\/(.+)$/);
+        if (backpackDelete && method === "DELETE") {
+            const name = decodeURIComponent(backpackDelete[1]);
+            try {
+                await unregisterBackpack(name);
+                if (ctx.storage.activeEntry && ctx.storage.activeEntry.name === name) {
+                    const swapped = await ctx.makeBackend();
+                    ctx.storage.current = swapped.backend;
+                    ctx.storage.activeEntry = swapped.entry;
+                    ctx.onActiveBackpackChange?.();
+                }
+                sendJson(res, 200, { ok: true });
+            }
+            catch (err) {
+                sendErr(res, 400, err.message);
+            }
+            return true;
+        }
+        // --- /api/locks ---
+        if (url === "/api/locks" && method === "GET") {
+            try {
+                const summaries = await ctx.storage.current.listOntologies();
+                const result = {};
+                const storage = ctx.storage.current;
+                if (typeof storage.readLock === "function") {
+                    await Promise.all(summaries.map(async (s) => {
+                        try {
+                            result[s.name] = await storage.readLock(s.name);
+                        }
+                        catch {
+                            result[s.name] = null;
+                        }
+                    }));
+                }
+                sendJson(res, 200, result);
+            }
+            catch {
+                sendJson(res, 200, {});
+            }
+            return true;
+        }
+        const lock = url.match(/^\/api\/graphs\/(.+)\/lock$/);
+        if (lock && method === "GET") {
+            const graphName = decodeURIComponent(lock[1]);
+            try {
+                const storage = ctx.storage.current;
+                const lockInfo = typeof storage.readLock === "function"
+                    ? await storage.readLock(graphName)
+                    : null;
+                sendJson(res, 200, lockInfo);
+            }
+            catch {
+                sendJson(res, 200, null);
+            }
+            return true;
+        }
+        // --- /api/ontologies/* ---
+        if (url === "/api/ontologies" && method === "GET") {
+            try {
+                const summaries = await ctx.storage.current.listOntologies();
+                sendJson(res, 200, summaries);
+            }
+            catch {
+                sendJson(res, 200, []);
+            }
+            return true;
+        }
+        // /api/ontologies/<name>/rename — must match before /api/ontologies/<name>
+        const rename = url.match(/^\/api\/ontologies\/(.+)\/rename$/);
+        if (rename && method === "POST") {
+            const oldName = decodeURIComponent(rename[1]);
+            const body = await readBody(req);
+            try {
+                const { name: newName } = JSON.parse(body);
+                await ctx.storage.current.renameOntology(oldName, newName);
+                sendJson(res, 200, { ok: true, name: newName });
+            }
+            catch (err) {
+                sendErr(res, 500, err.message);
+            }
+            return true;
+        }
+        if (url.startsWith("/api/ontologies/")) {
+            const name = decodeURIComponent(url.replace("/api/ontologies/", ""));
+            if (!name)
+                return false;
+            if (method === "PUT") {
+                const body = await readBody(req);
+                try {
+                    const data = JSON.parse(body);
+                    await ctx.storage.current.saveOntology(name, data);
+                    sendJson(res, 200, { ok: true });
+                }
+                catch (err) {
+                    sendErr(res, 500, err.message);
+                }
+                return true;
+            }
+            if (method === "GET") {
+                try {
+                    const data = await ctx.storage.current.loadOntology(name);
+                    sendJson(res, 200, data);
+                }
+                catch {
+                    sendErr(res, 404, "Ontology not found");
+                }
+                return true;
+            }
+        }
+        // --- /oauth/callback (for Share extension OAuth popup) ---
+        if (url.startsWith("/oauth/callback") && method === "GET") {
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<!DOCTYPE html><html><body><script>
+        var params = new URLSearchParams(window.location.search);
+        var code = params.get("code");
+        var state = params.get("state");
+        if (window.opener && code) {
+          window.opener.postMessage({
+            type: "backpack-oauth-callback",
+            code: code,
+            returnedState: state
+          }, "*");
+        }
+        window.close();
+      </script></body></html>`);
+            return true;
+        }
+        return false;
+    }
+    catch (err) {
+        if (!res.headersSent) {
+            sendErr(res, 500, err.message);
+        }
+        else {
+            res.end();
+        }
+        return true;
+    }
+}

package/dist/server-extensions.d.ts

@@ -0,0 +1,126 @@
+import { configDir, dataDir } from "backpack-ontology";
+import { type ExtensionManifest } from "./extensions/manifest.js";
+/**
+ * Server-side extension infrastructure shared by `bin/serve.js` (prod)
+ * and `vite.config.ts` (dev). Both entry files import these helpers and
+ * keep only thin HTTP wiring.
+ *
+ * Responsibilities:
+ *   - Resolve enabled extensions from config + first-party in-tree dirs
+ *   - Parse and validate each manifest
+ *   - Provide handlers for the generic extension endpoints:
+ *       GET  /api/extensions
+ *       POST /api/extensions/<name>/fetch
+ *       GET  /api/extensions/<name>/settings
+ *       PUT  /api/extensions/<name>/settings/<key>
+ *       DELETE /api/extensions/<name>/settings/<key>
+ *
+ * Static file serving (`/extensions/<name>/<file>`) is handled by each
+ * entry file because the static-file plumbing differs between Vite and
+ * the raw http server.
+ */
+export interface LoadedExtension {
+    manifest: ExtensionManifest;
+    /** Absolute path to the extension's directory on disk. */
+    rootDir: string;
+    /** Whether this extension shipped with the viewer (in-tree). */
+    firstParty: boolean;
+}
+export interface ExtensionConfigEntry {
+    /** Extension name (must match the manifest and the directory). */
+    name: string;
+    /**
+     * Source. Either:
+     *   - "first-party" — load from <viewer-dist>/extensions/<name> or
+     *     <viewer-src>/extensions/<name> in dev
+     *   - { path: "/abs/path" } — load from a user-specified absolute path
+     */
+    source: "first-party" | {
+        path: string;
+    };
+    enabled?: boolean;
+}
+/**
+ * Resolve enabled extensions. Reads:
+ *   1. The list of first-party extensions bundled with the viewer
+ *      (default-enabled unless the user disabled them)
+ *   2. The list of external extensions from the user's viewer config
+ *
+ * For each one: locates the manifest, validates it, and returns the
+ * loaded extension. Errors are logged but don't crash the server —
+ * a malformed extension is skipped, others keep working.
+ *
+ * @param firstPartyDir absolute path to the directory containing
+ *                      bundled first-party extensions (typically
+ *                      `<dist>/extensions/` in prod or
+ *                      `<repo>/extensions/` in dev)
+ * @param userExtensions list from viewer config; same shape regardless of source
+ * @param disabledFirstParty names of first-party extensions the user disabled
+ */
+export declare function loadExtensions(firstPartyDir: string, userExtensions: {
+    name: string;
+    path: string;
+}[], disabledFirstParty: Set<string>): LoadedExtension[];
+/**
+ * Per-extension settings file path. Each extension gets its own file
+ * under `~/.config/backpack/extensions/<name>/settings.json`. The file
+ * is created on first write.
+ */
+export declare function extensionSettingsPath(extName: string): string;
+export declare function readExtensionSettings(extName: string): Promise<Record<string, unknown>>;
+export declare function writeExtensionSetting(extName: string, key: string, value: unknown): Promise<void>;
+export declare function deleteExtensionSetting(extName: string, key: string): Promise<void>;
+/**
+ * Result of an extension fetch proxy call. Either an error JSON to send
+ * back to the client, or an upstream body for the caller to pipe through.
+ */
+export interface ExtensionFetchResult {
+    status: number;
+    errorJson?: string;
+    upstreamHeaders?: Headers;
+    upstreamBody?: ReadableStream<Uint8Array>;
+}
+/**
+ * Forward an extension fetch request to its declared upstream.
+ *
+ * Validates that the requested URL's origin is in the extension's
+ * manifest network allowlist. Injects headers (env-var or literal) per
+ * the manifest's `injectHeaders` config. Returns either a structured
+ * error or a ReadableStream the caller pipes back to the browser.
+ *
+ * The browser-side `viewer.fetch(url, init)` POSTs to
+ * `/api/extensions/<name>/fetch` with a JSON body matching
+ * ProxyRequestPayload. The caller (serve.js / vite plugin) handles the
+ * raw HTTP wiring; this function handles validation, secret injection,
+ * and the upstream call.
+ */
+export declare function proxyExtensionFetch(ext: LoadedExtension, rawJsonBody: string): Promise<ExtensionFetchResult>;
+/**
+ * Look up a loaded extension by name. Used by the per-extension
+ * endpoints to resolve which extension a request is targeting.
+ */
+export declare function findExtension(extensions: LoadedExtension[], name: string): LoadedExtension | null;
+/**
+ * Public manifest serialization — what `GET /api/extensions` returns.
+ * Strips no fields currently but exists as the boundary in case we want
+ * to filter (e.g., redact env-var names) in the future.
+ */
+export declare function publicExtensionInfo(ext: LoadedExtension): {
+    name: string;
+    version: string;
+    viewerApi: string;
+    displayName: string | undefined;
+    description: string | undefined;
+    entry: string;
+    stylesheet: string | undefined;
+    permissions: import("./extensions/manifest.js").ManifestPermissions | undefined;
+    firstParty: boolean;
+};
+/**
+ * Resolve the on-disk file path for a request like
+ * `/extensions/<name>/<sub-path>`. Validates the sub-path stays within
+ * the extension's root dir (no path traversal). Returns null if the
+ * extension is unknown or the path escapes.
+ */
+export declare function resolveExtensionFile(extensions: LoadedExtension[], extName: string, subPath: string): string | null;
+export { configDir, dataDir };