@homescriptone/opencode-viewer-extender 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 homescriptone Solutions Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# opencode-viewer-extender
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@homescriptone/opencode-viewer-extender.svg)](https://www.npmjs.com/package/@homescriptone/opencode-viewer-extender)
+[![license](https://img.shields.io/npm/l/@homescriptone/opencode-viewer-extender.svg)](LICENSE)
+
+Local GUI to **browse, edit, and export** your [OpenCode](https://opencode.ai) sessions, messages, and tool calls from the SQLite database — with a small **plugin API** you can extend.
+
+Reads and writes `~/.local/share/opencode/opencode.db`. Everything stays on your machine.
+
+```bash
+bunx @homescriptone/opencode-viewer-extender
+```
+
+> On npm: [`@homescriptone/opencode-viewer-extender`](https://www.npmjs.com/package/@homescriptone/opencode-viewer-extender) · Desktop builds (`.dmg`, Linux, Windows) are published on the [releases page](https://github.com/homescriptone/opencode-viewer-extended/releases).
+
+## Features
+
+- **Three-panel UI** — projects, sessions, and the full message thread
+- **Every part type rendered** — text (markdown-lite), reasoning, tool calls with input/output, patches, file attachments, images (click-to-expand), agent pills, step-finish costs, compaction markers
+- **Subagents** — interleaved in the timeline; click to drill in, back to return
+- **Search** — cross-project session search scoped to all / user / model messages
+- **Export** — a session as Markdown or JSON, or **select many** projects/sessions and export a single `.zip`
+- **Edit mode** — opt-in create/update/delete (projects, sessions, messages, parts)
+- **Plugins** — drop a `.js` file in `public/plugins/` to add renderers, export formats, and bulk actions; toggle them on/off from the UI
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime (`curl -fsSL https://bun.sh/install | bash`), or a desktop build
+- [OpenCode](https://opencode.ai) installed and used at least once
+
+## Usage
+
+```bash
+# Run it (auto-opens the browser)
+bunx @homescriptone/opencode-viewer-extender
+
+# Custom port
+bunx @homescriptone/opencode-viewer-extender -p 8080
+
+# Custom database path
+bunx @homescriptone/opencode-viewer-extender --db /path/to/opencode.db
+
+# Enable edit mode (create/update/delete)
+bunx @homescriptone/opencode-viewer-extender --write
+
+# Don't open the browser
+bunx @homescriptone/opencode-viewer-extender --no-open
+```
+
+Default port is `3456` when launched via the CLI. Set `OCV_PORT`, `OCV_DB_PATH`, or `OCV_WRITE=1` to override.
+
+## Edit mode
+
+The database is opened **read-only** by default. Writes only become available when you start with `--write` (or `OCV_WRITE=1`); the server then exposes the write API and the UI shows an **Edit** toggle.
+
+> **Warning:** edits and deletes hit your real OpenCode database, and deletes **cascade** (deleting a project removes its sessions, messages, and parts). There is no undo. Back up `opencode.db` before making changes.
+
+## Export
+
+- **Single session** — the **Export ▾** menu in the message header offers Markdown (`.md`) and JSON (`.json`), served by `GET /api/sessions/:id/export?format=md|json`.
+- **Bulk** — turn on **Select**, pick multiple projects/sessions, and choose **Export selected (.zip)**. The archive contains a `project.json` per project, each session as `sessions/<id>.json`, and a `manifest.json`.
+
+## Plugins
+
+Plugins are plain ES scripts discovered at startup from `public/plugins/` (listed by `GET /api/plugins`) and loaded before the UI renders. Enable/disable them from the **Plugins** button; disabled plugins are remembered in `localStorage`.
+
+See [`public/plugins/example.js`](public/plugins/example.js) for a complete example.
+
+### Authoring
+
+```js
+OCV.define({
+  id: "my-plugin",
+  name: "My plugin",
+  description: "What it does",
+
+  setup(api) {
+    // Render a custom part type -> HTML string (return falsy to fall back)
+    api.registerPartRenderer("snapshot", (part, helpers) => `...`);
+
+    // Add an export format to the Export menu (built in the browser)
+    api.registerExportFormat({
+      id: "txt", label: "Plain text (.txt)", extension: "txt", mime: "text/plain",
+      build: ({ session, messages }) => "..."
+    });
+
+    // Add a button in the session header
+    api.registerSessionAction({ id: "copy", label: "Copy ID", handler: ({ session }) => {} });
+
+    // Add a bulk action shown when items are selected
+    api.registerBulkAction({
+      id: "wipe", label: "Delete selected", danger: true, write: true, // write:true => only in Edit mode
+      handler: async ({ projectIds, sessionIds, host }) => { /* ... */ }
+    });
+  }
+});
+```
+
+Every `register*` call returns an unregister function, and registrations are removed automatically when the plugin is disabled.
+
+### Host bridge
+
+`api.host` (also `OCV.host`) exposes data and actions:
+
+```js
+host.getProjects()                       // [{ id, name, worktree }]
+host.getSessions()                       // current session list
+host.getSelection()                      // { projectIds, sessionIds }
+host.clearSelection()
+host.api.getProjectSessions(projectId)   // all sessions for a project
+host.api.getSessionDetail(sessionId)     // { session, messages }
+host.api.deleteProject(id)
+host.api.deleteSession(id)
+host.download(name, content, mime)       // save a Blob/string
+host.createZip([{ name, data }])         // -> Blob (store method, no deps)
+host.refresh()                           // reload projects/sessions
+```
+
+## How it works
+
+```
+bin/cli.ts            → CLI args, env setup, opens the browser
+server/launch.ts      → Bun.serve HTTP server, routing, static files, export
+server/database.ts    → SQLite connection, prepared statements, write layer
+public/index.html     → Page shell (loads plugin-api.js + script.js)
+public/script.js      → Single-page app (vanilla JS, no framework)
+public/plugin-api.js  → window.OCV plugin registry (+ zip helper)
+public/plugins/*.js   → Drop-in plugins
+public/styles.css     → Styles
+```
+
+1. Opens `opencode.db` (read-only unless `--write`).
+2. Starts a Bun server on `localhost:3456`.
+3. Serves the static SPA and a small JSON REST API.
+4. All data stays local — nothing leaves your machine.
+
+### REST API
+
+Reads: `GET /api/projects` · `GET /api/projects/:id/sessions` · `GET /api/sessions/search` · `GET /api/sessions/:id` · `GET /api/sessions/:id/subagents` · `GET /api/sessions/:id/export` · `GET /api/parts/:id/image` · `GET /api/plugins` · `GET /api/config`
+
+Writes (require `--write`): `POST/PATCH/PUT/DELETE` on `/api/projects`, `/api/sessions`, `/api/sessions/:id/messages`, `/api/messages/:id/parts`.
+
+## Development
+
+```bash
+bun run dev     # watch mode (server/launch.ts)
+bun run start   # production
+bun run typecheck
+```
+
+## Releasing
+
+Publishing to npm is automated: pushing to `main`/`master` runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which type-checks and publishes the current `package.json` version (skipping if that version already exists). Add an `NPM_TOKEN` repository secret (an npm automation token) for it to publish. Bumping the version is all you need to ship a release.
+
+## Desktop app
+
+A Tauri wrapper lives in [`src-tauri/`](src-tauri/) and bundles the Bun server as a sidecar; installers are produced by CI and attached to releases.
+
+## Credits
+
+Maintained by [homescriptone Solutions Ltd](https://github.com/homescriptone). Built on
+[opencode-viewer](https://github.com/leeweisern/opencode-viewer) by its original author
+[leeweisern](https://github.com/leeweisern) — thank you.
+
+## License
+
+MIT © 2026 homescriptone Solutions Ltd. See [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import("./cli.ts");

package/bin/cli.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+
+const { values } = parseArgs({
+  options: {
+    port: { type: "string", short: "p", default: "3456" },
+    "no-open": { type: "boolean", default: false },
+    write: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    db: { type: "string" },
+  },
+  strict: false,
+});
+
+if (values.help) {
+  console.log(`
+  opencode-viewer — Browse your OpenCode sessions locally
+
+  Usage:
+    bunx opencode-viewer [options]
+
+  Options:
+    -p, --port <port>   Port to listen on (default: 3456)
+    --db <path>         Custom path to opencode.db
+    --write             Enable edit mode (create/update/delete). Off by default.
+    --no-open           Don't auto-open browser
+    -h, --help          Show this help
+
+  Requires Bun runtime (uses bun:sqlite).
+`);
+  process.exit(0);
+}
+
+const port = Number(values.port) || 3456;
+const dbPath =
+  (values.db as string) ||
+  join(homedir(), ".local", "share", "opencode", "opencode.db");
+
+if (!existsSync(dbPath)) {
+  console.error(`\n  ✗ OpenCode database not found at: ${dbPath}\n`);
+  console.error(
+    "  Make sure OpenCode is installed and has been run at least once.",
+  );
+  console.error("  Or specify a custom path: bunx opencode-viewer --db /path/to/opencode.db\n");
+  process.exit(1);
+}
+
+// Set env vars for the server to pick up
+process.env.OCV_PORT = String(port);
+process.env.OCV_DB_PATH = dbPath;
+if (values.write) process.env.OCV_WRITE = "1";
+
+// Import and start server
+const serverPath = join(import.meta.dir, "..", "server", "launch.ts");
+await import(serverPath);
+
+// Auto-open browser
+if (!values["no-open"]) {
+  const url = `http://localhost:${port}`;
+  const { platform } = process;
+  const cmd =
+    platform === "darwin"
+      ? ["open", url]
+      : platform === "win32"
+        ? ["cmd", "/c", "start", url]
+        : ["xdg-open", url];
+
+  Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@homescriptone/opencode-viewer-extender",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Local GUI to browse, edit, and export your OpenCode sessions, messages, and tool calls from the SQLite database, with a plugin API",
+  "bin": {
+    "opencode-viewer": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "public/",
+    "server/"
+  ],
+  "scripts": {
+    "dev": "bun run --watch server/launch.ts",
+    "start": "bun run server/launch.ts",
+    "typecheck": "bun check",
+    "prepublishOnly": "bun check",
+    "deploy": "npm version patch --no-git-tag-version && git add -A && git commit -m \"v$(node -p require('./package.json').version)\" && git push && npm publish --access public"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-viewer",
+    "viewer",
+    "sqlite",
+    "sessions",
+    "ai",
+    "cli",
+    "bun",
+    "plugins"
+  ],
+  "author": "Homescriptone Solutions Ltd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homescriptone/opencode-viewer-extended.git"
+  },
+  "homepage": "https://homescriptone.github.io/opencode-viewer-extended/",
+  "bugs": {
+    "url": "https://github.com/homescriptone/opencode-viewer-extended/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3",
+    "@types/node": "^26.6.5"
+  }
+}

package/public/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OpenCode Session Viewer</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <div id="app">
+    <aside id="projects-panel" class="panel"></aside>
+    <section id="sessions-panel" class="panel"></section>
+    <main id="messages-panel" class="panel"></main>
+  </div>
+  <div id="bulk-bar" class="bulk-bar" hidden></div>
+  <div id="modal-root"></div>
+  <script src="plugin-api.js"></script>
+  <script src="script.js"></script>
+</body>
+</html>

package/public/plugin-api.js

@@ -0,0 +1,260 @@
+(function () {
+  "use strict";
+
+  const STORAGE_KEY = "ocv.plugins.disabled";
+
+  const plugins = new Map();
+  const partRenderers = new Map();
+  const exportFormats = [];
+  const sessionActions = [];
+  const bulkActions = [];
+
+  let hostImpl = {};
+  let readyResolve = null;
+  const readyPromise = new Promise((resolve) => {
+    readyResolve = resolve;
+  });
+
+  function readDisabled() {
+    try {
+      const parsed = JSON.parse(localStorage.getItem(STORAGE_KEY) || "[]");
+      return new Set(Array.isArray(parsed) ? parsed : []);
+    } catch {
+      return new Set();
+    }
+  }
+
+  const disabled = readDisabled();
+
+  function persistDisabled() {
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify([...disabled]));
+    } catch {
+      /* storage unavailable */
+    }
+  }
+
+  function makeApi(id) {
+    const cleanups = [];
+
+    const track = (arr, item) => {
+      const remove = () => {
+        const index = arr.indexOf(item);
+        if (index >= 0) arr.splice(index, 1);
+      };
+      cleanups.push(remove);
+      return remove;
+    };
+
+    return {
+      id,
+      get host() {
+        return hostImpl;
+      },
+      registerPartRenderer(type, renderer) {
+        const key = String(type ?? "").toLowerCase();
+        partRenderers.set(key, renderer);
+        const remove = () => {
+          if (partRenderers.get(key) === renderer) partRenderers.delete(key);
+        };
+        cleanups.push(remove);
+        return remove;
+      },
+      registerExportFormat(format) {
+        if (!format || typeof format.build !== "function") return () => {};
+        exportFormats.push(format);
+        return track(exportFormats, format);
+      },
+      registerSessionAction(action) {
+        if (!action || typeof action.handler !== "function") return () => {};
+        sessionActions.push(action);
+        return track(sessionActions, action);
+      },
+      registerBulkAction(action) {
+        if (!action || typeof action.handler !== "function") return () => {};
+        bulkActions.push(action);
+        return track(bulkActions, action);
+      },
+      _cleanups: cleanups,
+    };
+  }
+
+  function define(def) {
+    if (!def || typeof def.id !== "string" || typeof def.setup !== "function") {
+      console.warn("[OCV] define() ignored: needs { id, name?, setup }", def);
+      return;
+    }
+    plugins.set(def.id, { def, enabled: false, cleanups: [], api: null });
+  }
+
+  function enable(id) {
+    const entry = plugins.get(id);
+    if (!entry || entry.enabled) return;
+    const api = makeApi(id);
+    entry.api = api;
+    entry.enabled = true;
+    try {
+      const extra = entry.def.setup(api);
+      if (Array.isArray(extra)) api._cleanups.push(...extra);
+    } catch (error) {
+      console.error(`[OCV] plugin "${id}" setup failed:`, error);
+    }
+    entry.cleanups = api._cleanups;
+  }
+
+  function disable(id) {
+    const entry = plugins.get(id);
+    if (!entry || !entry.enabled) return;
+    for (const cleanup of entry.cleanups) {
+      try {
+        cleanup();
+      } catch (error) {
+        console.error(`[OCV] plugin "${id}" cleanup failed:`, error);
+      }
+    }
+    entry.cleanups = [];
+    try {
+      entry.def.teardown?.(entry.api);
+    } catch (error) {
+      console.error(`[OCV] plugin "${id}" teardown failed:`, error);
+    }
+    entry.enabled = false;
+    entry.api = null;
+  }
+
+  function setEnabled(id, value) {
+    if (value) {
+      disabled.delete(id);
+      enable(id);
+    } else {
+      disabled.add(id);
+      disable(id);
+    }
+    persistDisabled();
+    hostImpl.onPluginsChanged?.();
+  }
+
+  function listPlugins() {
+    return [...plugins.values()].map((entry) => ({
+      id: entry.def.id,
+      name: entry.def.name || entry.def.id,
+      description: entry.def.description || "",
+      enabled: entry.enabled,
+    }));
+  }
+
+  function activateAll() {
+    for (const [id] of plugins) {
+      if (!disabled.has(id)) enable(id);
+    }
+  }
+
+  // Minimal ZIP writer (store method, no compression) so plugins can bundle
+  // multiple JSON files into one download without any dependency.
+  const crcTable = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      table[n] = c >>> 0;
+    }
+    return table;
+  })();
+
+  function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) c = crcTable[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  }
+
+  function createZip(entries) {
+    const encoder = new TextEncoder();
+    const chunks = [];
+    const central = [];
+    let offset = 0;
+
+    for (const entry of entries) {
+      const nameBytes = encoder.encode(String(entry.name));
+      const dataBytes = typeof entry.data === "string" ? encoder.encode(entry.data) : entry.data;
+      const crc = crc32(dataBytes);
+
+      const local = new Uint8Array(30 + nameBytes.length);
+      const lv = new DataView(local.buffer);
+      lv.setUint32(0, 0x04034b50, true);
+      lv.setUint16(4, 20, true);
+      lv.setUint16(6, 0x0800, true);
+      lv.setUint16(8, 0, true);
+      lv.setUint16(10, 0, true);
+      lv.setUint16(12, 0, true);
+      lv.setUint32(14, crc, true);
+      lv.setUint32(18, dataBytes.length, true);
+      lv.setUint32(22, dataBytes.length, true);
+      lv.setUint16(26, nameBytes.length, true);
+      lv.setUint16(28, 0, true);
+      local.set(nameBytes, 30);
+      chunks.push(local, dataBytes);
+
+      const record = new Uint8Array(46 + nameBytes.length);
+      const cv = new DataView(record.buffer);
+      cv.setUint32(0, 0x02014b50, true);
+      cv.setUint16(4, 20, true);
+      cv.setUint16(6, 20, true);
+      cv.setUint16(8, 0x0800, true);
+      cv.setUint16(10, 0, true);
+      cv.setUint16(12, 0, true);
+      cv.setUint16(14, 0, true);
+      cv.setUint32(16, crc, true);
+      cv.setUint32(20, dataBytes.length, true);
+      cv.setUint32(24, dataBytes.length, true);
+      cv.setUint16(28, nameBytes.length, true);
+      cv.setUint16(30, 0, true);
+      cv.setUint16(32, 0, true);
+      cv.setUint16(34, 0, true);
+      cv.setUint16(36, 0, true);
+      cv.setUint32(38, 0, true);
+      cv.setUint32(42, offset, true);
+      record.set(nameBytes, 46);
+      central.push(record);
+
+      offset += local.length + dataBytes.length;
+    }
+
+    let centralSize = 0;
+    for (const record of central) centralSize += record.length;
+
+    const end = new Uint8Array(22);
+    const ev = new DataView(end.buffer);
+    ev.setUint32(0, 0x06054b50, true);
+    ev.setUint16(4, 0, true);
+    ev.setUint16(6, 0, true);
+    ev.setUint16(8, central.length, true);
+    ev.setUint16(10, central.length, true);
+    ev.setUint32(12, centralSize, true);
+    ev.setUint32(16, offset, true);
+    ev.setUint16(20, 0, true);
+
+    return new Blob([...chunks, ...central, end], { type: "application/zip" });
+  }
+
+  window.OCV = {
+    version: "2",
+    define,
+    setEnabled,
+    isEnabled: (id) => Boolean(plugins.get(id)?.enabled),
+    list: listPlugins,
+    ready: () => readyPromise,
+    get host() {
+      return hostImpl;
+    },
+    getPartRenderer: (type) => partRenderers.get(String(type ?? "").toLowerCase()) || null,
+    listExportFormats: () => exportFormats.slice(),
+    listSessionActions: () => sessionActions.slice(),
+    listBulkActions: () => bulkActions.slice(),
+    helpers: { createZip },
+    _registerHost(impl) {
+      hostImpl = impl;
+    },
+    _activateAll: activateAll,
+    _markReady: () => readyResolve(),
+  };
+})();