opencode-sessions-forever 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinXuan
+
+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,170 @@
-# Temporary Holding Version
+# Sessions Forever
 
-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.
+> Have you ever been frustrated because a conversation context could not be
+> passed between friends?
+> Have you ever cried because you could not find an important context again?
+> Have you ever suffered because a context could only ever exist as a single
+> instance?
+
+**Today, this plugin is here — built specifically to solve this problem.**
+
+Sessions Forever exports a single conversation into one file that you can pass
+around freely. One archive can be opened as multiple instances, it can live
+right inside your project, and it never pollutes the main database.
+**OpenCode v2 only.**
+
+Concretely: save any [OpenCode](https://opencode.ai) conversation as a single
+portable `.sf` file — and restore it later, or on another machine, as a real
+native session that opens in its own tab with the complete history intact.
+
+## Why
+
+OpenCode v2 stores **every** conversation of **every** project in one global
+SQLite database (`~/.local/share/opencode/opencode.db`). Over time this creates
+three problems:
+
+- Old conversations get buried under newer ones and are hard to find.
+- There is no per-conversation artifact you can keep, move, or back up.
+- Sharing the full context of a conversation with someone else is practically
+  impossible.
+
+Sessions Forever gives every conversation you care about a **single
+self-contained file** with the `.sf` extension. Copy it anywhere, send it to
+anyone, and load it back as a first-class OpenCode session whenever you want.
+
+## What is a `.sf` file?
+
+A `.sf` file is a **genuine OpenCode database** — a standard SQLite file
+containing exactly one session, written by OpenCode's own storage engine (not
+by third-party code). You can open it with any SQLite tool and inspect the
+`session_v2`, `session_message`, and `project` tables.
+
+The custom `.sf` extension keeps archives instantly recognizable and prevents
+unrelated `.db`/`.sqlite` files from interfering.
+
+The archive contains the **complete projected transcript**: every user and
+assistant message, code blocks, tool calls and their outputs, reasoning blocks,
+token/cost statistics, and timestamps — byte-identical to what OpenCode itself
+stores.
+
+## Features
+
+- **`/session-save [name]`** — archive the current conversation into
+  `<session directory>/<name>.sf` (default name: `<title>-<YYYYMMDD-HHMM>.sf`).
+- **`/session-load [index | filename]`** — scan the current directory for
+  `*.sf` archives and show a native picker dialog (title, message count, date).
+  An argument skips the dialog.
+- **Native restore** — the selected archive is rebuilt as a real session in
+  your live OpenCode and **opens automatically in a new tab**, exactly like
+  picking a conversation from `/session`. You can keep chatting in it.
+- **Portable** — archives work on any machine with OpenCode v2 and this
+  plugin. Re-importing the same archive twice (or on the original machine)
+  never conflicts: ids are regenerated on every load.
+- **Full fidelity** — restore round-trips have been verified byte-identical.
+- **Zero dependencies** — uses only OpenCode built-ins (`bun:sqlite`,
+  `node:child_process`) and official OpenCode mechanisms. Nothing to install.
+- **Safe** — the live database is never touched directly; every write goes
+  through OpenCode's own import path (foreign keys, uniqueness constraints,
+  and cross-version migrations are all handled by official code). No model
+  calls are made, so saving/loading costs no tokens.
+
+## How it works
+
+Everything is built from official mechanisms — the plugin never writes SQL to
+your live database.
+
+### Save
+
+```
+current session (router.current)
+  → client.session.export                    official transcript projection {info, messages}
+  → temp JSON file
+  → XDG_DATA_HOME=<tmp> opencode session import --standalone <json> --directory <dir>
+      (a disposable official instance builds a fresh database from scratch
+       and writes only this conversation into it)
+  → WAL checkpoint guard (data-loss protection on abnormal exit)
+  → the resulting opencode.db is moved to <name>.sf
+```
+
+Key details:
+
+- `XDG_DATA_HOME` redirection + `--standalone` = "the official automatic save,
+  triggered manually, at a path you choose". The disposable instance never
+  connects to your running service.
+- The CLI reads/writes transcripts through **files and pipes**, so there is no
+  argument-size limit — archives of any size work.
+
+### Load
+
+```
+scan *.sf in the current directory
+  → fast read-only SQLite peek for labels (id/title/count), file name as fallback
+  → native select dialog (or direct argument: index / file name)
+  → copy the .sf into a disposable instance's data dir
+  → opencode session export --standalone <id>   (official projection reads it back;
+      old archives are auto-migrated by the disposable instance on startup)
+  → regenerate session + message ids (UNIQUE constraints are global) and
+      replace cross-references; drop parentID/fork links
+  → client.session.import into the live service   (official code does the writing)
+  → router.navigate → the restored session opens in a new tab
+```
+
+## Installation
+
+From npm (recommended):
+
+```
+opencode plugin add opencode-sessions-forever
+```
+
+Or drop this folder into either location manually, then restart OpenCode
+(or run `opencode service restart`):
+
+```
+~/.config/opencode/plugins/sessions-forever/     # global (all projects)
+<project>/.opencode/plugins/sessions-forever/    # per-project
+```
+
+The package contains:
+
+| File       | Role                                                              |
+| ---------- | ----------------------------------------------------------------- |
+| `index.ts` | Server-side stub so the server loads the package (TUI part follows) |
+| `tui.ts`   | All logic: slash commands, dialogs, archives, restore              |
+
+## Usage
+
+```
+/session-save                  # archive as <title>-<timestamp>.sf in the session directory
+/session-save release-plan     # archive as release-plan.sf
+
+/session-load                  # picker dialog listing all *.sf in the current directory
+/session-load 2                # load the 2nd archive from the list
+/session-load release-plan     # load release-plan.sf (extension optional)
+```
+
+Both commands are also available in the command palette.
+
+## Requirements
+
+- OpenCode **v2** with the terminal UI (developed and tested against **2.1.3**).
+- The `opencode` executable (the plugin reuses the running binary via
+  `process.execPath`).
+
+## Notes & limitations
+
+- Each save/load spawns a disposable OpenCode instance: expect **1–3 seconds**
+  per operation. This is the price of 100% official writes.
+- The quick label peek reads `session_v2`/`session_message` directly. If a
+  future OpenCode version renames those tables, the plugin degrades gracefully
+  (file-name labels + official `session list` fallback for the id).
+- Archives are written to the **session's project directory**.
+- Scratch directories are created under the system temp dir
+  (`sessions-forever-*`) and removed automatically after each operation.
+- **Privacy:** a `.sf` contains the entire transcript, including reasoning
+  blocks and tool outputs (file contents, command results). Review an archive
+  before sharing it.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "opencode-sessions-forever",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "OpenCode plugin: save any conversation as a single portable .sf archive (a real OpenCode database) and restore it later as a native session — on any machine, as many instances as you like. /session-save + /session-load with a native picker and auto tab open.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "LinXuan"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linxuan-sys/opencode-session-forever.git"
+  },
+  "homepage": "https://github.com/linxuan-sys/opencode-session-forever#readme",
+  "bugs": {
+    "url": "https://github.com/linxuan-sys/opencode-session-forever/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "session",
+    "archive",
+    "export",
+    "import",
+    "sqlite",
+    "portable"
+  ],
+  "engines": {
+    "opencode": ">=2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui.ts"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+import { Plugin } from "@opencode/plugin"
+
+// Server-side stub: makes the server load this package as a plugin so the
+// TUI part (tui.ts) is loaded along with it. All logic lives in tui.ts.
+export default Plugin.define({
+  id: "sessions-forever",
+  setup() {},
+})

package/src/tui.ts

@@ -0,0 +1,275 @@
+// Sessions Forever — TUI part.
+// Saves the current conversation as a single portable .sf archive (a genuine
+// OpenCode database written by official code) and restores archives as native
+// sessions. All logic runs through official mechanisms: the session export /
+// import transcript APIs, plus disposable `opencode --standalone` instances
+// redirected via XDG_DATA_HOME. The main database is never touched directly.
+import { Plugin } from "@opencode/plugin/tui"
+import { Database } from "bun:sqlite"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import * as fs from "node:fs"
+import * as fsp from "node:fs/promises"
+import * as os from "node:os"
+import * as path from "node:path"
+
+const execFileAsync = promisify(execFile)
+const B62 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+const MAX_BUF = 512 * 1024 * 1024 // the official export streams through a stdout pipe; large sessions can reach tens of MB
+
+function opencodeBin(): string {
+  // The TUI process itself is the opencode binary
+  try {
+    if (process.execPath && fs.existsSync(process.execPath)) return process.execPath
+  } catch {}
+  return "opencode"
+}
+
+// Random id with the same prefix and length as official ids (verified to pass format checks and uniqueness constraints)
+function rid(old: string): string {
+  const i = old.indexOf("_")
+  const prefix = i >= 0 ? old.slice(0, i + 1) : ""
+  let s = ""
+  for (let j = 0; j < old.length - prefix.length; j++) s += B62[Math.floor(Math.random() * B62.length)]
+  return prefix + s
+}
+
+function sanitize(name: string): string {
+  return name.replace(/[\/\\:*?"<>|\s]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "session"
+}
+
+function stamp(d = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`
+}
+
+// Spawn a disposable official instance (isolated via XDG_DATA_HOME + --standalone)
+async function disposable<T>(fn: (env: NodeJS.ProcessEnv, bin: string) => Promise<T>): Promise<T> {
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "sessions-forever-"))
+  try {
+    return await fn({ ...process.env, XDG_DATA_HOME: path.join(tmp, "data") }, opencodeBin())
+  } finally {
+    // Only cleans up scratch directories the plugin itself created under the system temp dir
+    await fsp.rm(tmp, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+// Read-only quick peek at the session label inside a .sf (id/title/count); falls back to the file name
+function peek(file: string): { id?: string; title?: string; count?: number; created?: number } {
+  try {
+    const db = new Database(file, { readOnly: true, readonly: true } as any)
+    try {
+      const row: any = db.query("select id, title, time_created from session_v2 limit 1").get()
+      const cnt: any = db.query("select count(*) as n from session_message").get()
+      return { id: row?.id, title: row?.title, count: Number(cnt?.n ?? 0), created: Number(row?.time_created ?? 0) }
+    } finally {
+      db.close()
+    }
+  } catch {
+    return {}
+  }
+}
+
+export default Plugin.define({
+  id: "sessions-forever-tui",
+  setup(context: any) {
+    const toast = (message: string) => context.ui.toast.show({ title: "Sessions Forever", message })
+    const fail = async (e: any) => {
+      const msg = String(e?.message ?? e)
+      try {
+        await context.ui.dialog.alert({ title: "Sessions Forever error", message: msg })
+      } catch {
+        toast(msg)
+      }
+    }
+
+    async function currentSessionDir(): Promise<{ sessionID?: string; dir: string }> {
+      const route = context.ui.router.current()
+      if (route?.type === "session") {
+        try {
+          const info = await context.client.session.get({ sessionID: route.sessionID })
+          const dir = info?.location?.directory
+          if (dir) return { sessionID: route.sessionID, dir }
+        } catch {}
+      }
+      return { dir: context.location?.directory ?? process.cwd() }
+    }
+
+    async function save(input?: string) {
+      const route = context.ui.router.current()
+      if (route?.type !== "session") {
+        await context.ui.dialog.alert({ title: "Sessions Forever", message: "Open a session first before saving." })
+        return
+      }
+      const sessionID = route.sessionID
+      const info = await context.client.session.get({ sessionID })
+      const dir: string = info?.location?.directory ?? context.location?.directory ?? process.cwd()
+
+      // File name: argument wins, default is title-timestamp
+      const arg = (input ?? "").trim().replace(/\.sf$/i, "")
+      const name = arg ? sanitize(arg) : `${sanitize(info?.title ?? "session")}-${stamp()}`
+      const target = path.join(dir, `${name}.sf`)
+      if (fs.existsSync(target)) {
+        const ok = await context.ui.dialog.confirm({
+          title: "Sessions Forever",
+          message: `${name}.sf already exists. Overwrite it?`,
+        })
+        if (!ok) return
+      }
+
+      toast("Exporting conversation…")
+      const transcript = await context.client.session.export({ sessionID })
+
+      await disposable(async (env, bin) => {
+        const tmpRoot = path.dirname(env.XDG_DATA_HOME!) // mkdtemp root (XDG_DATA_HOME=tmp/data)
+        const tjson = path.join(tmpRoot, "transcript.json")
+        await fsp.writeFile(tjson, JSON.stringify({ info: transcript.info, messages: transcript.messages }))
+        // Official disposable instance: builds a fresh database from scratch and writes this conversation into it
+        await execFileAsync(bin, ["session", "import", "--standalone", tjson, "--directory", dir], {
+          env,
+          maxBuffer: MAX_BUF,
+          timeout: 180_000,
+        })
+        const dbPath = path.join(env.XDG_DATA_HOME!, "opencode", "opencode.db")
+        if (!fs.existsSync(dbPath)) throw new Error("The disposable instance did not produce a database file")
+        // Data-loss guard: merge any leftover WAL (abnormal exit) back into the main file
+        if (fs.existsSync(dbPath + "-wal")) {
+          const db = new Database(dbPath)
+          try {
+            db.exec("PRAGMA wal_checkpoint(TRUNCATE)")
+          } finally {
+            db.close()
+          }
+        }
+        await fsp.copyFile(dbPath, target)
+      })
+
+      const size = (fs.statSync(target).size / 1024).toFixed(0)
+      toast(`Saved ${transcript.messages.length} messages → ${target} (${size}KB)`)
+    }
+
+    async function load(input?: string) {
+      const { dir } = await currentSessionDir()
+      let files = (await fsp.readdir(dir)).filter((f) => f.toLowerCase().endsWith(".sf")).sort()
+      if (!files.length) {
+        await context.ui.dialog.alert({ title: "Sessions Forever", message: `No .sf archives in the current directory: ${dir}` })
+        return
+      }
+
+      const metas = files.map((f) => ({ file: f, ...peek(path.join(dir, f)) }))
+
+      // Direct selection by argument: index or file name
+      const arg = (input ?? "").trim()
+      let picked: (typeof metas)[number] | undefined
+      if (arg) {
+        if (/^\d+$/.test(arg)) {
+          const n = parseInt(arg, 10)
+          if (n < 1 || n > metas.length) {
+            await context.ui.dialog.alert({ title: "Sessions Forever", message: `Index out of range (1-${metas.length})` })
+            return
+          }
+          picked = metas[n - 1]
+        } else {
+          const want = arg.toLowerCase().endsWith(".sf") ? arg.toLowerCase() : arg.toLowerCase() + ".sf"
+          picked = metas.find((m) => m.file.toLowerCase() === want)
+          if (!picked) {
+            await context.ui.dialog.alert({ title: "Sessions Forever", message: `Archive not found: ${arg}` })
+            return
+          }
+        }
+      } else {
+        const value = await context.ui.dialog.select<string>({
+          title: "Choose an archive to load",
+          placeholder: "Type to filter…",
+          options: metas.map((m) => ({
+            value: m.file,
+            title: m.title ? `"${m.title}"` : m.file,
+            description: [m.count ? `${m.count} messages` : "", m.created ? new Date(m.created).toLocaleString() : "", m.file].filter(Boolean).join(" · "),
+            category: "Sessions Forever",
+          })),
+        })
+        if (!value) return
+        picked = metas.find((m) => m.file === value)
+      }
+      if (!picked) return
+
+      toast(`Reading ${picked.file} …`)
+      const sfPath = path.join(dir, picked.file)
+
+      // Mount the .sf into a disposable instance; the official export reads the transcript back
+      const transcript = await disposable(async (env, bin) => {
+        const dbDir = path.join(env.XDG_DATA_HOME!, "opencode")
+        await fsp.mkdir(dbDir, { recursive: true })
+        await fsp.copyFile(sfPath, path.join(dbDir, "opencode.db"))
+
+        let sid = picked!.id
+        if (!sid) {
+          // Official fallback when the quick peek fails: session list
+          const { stdout } = await execFileAsync(bin, ["session", "list", "--standalone", "--format", "json"], {
+            env,
+            cwd: dir,
+            maxBuffer: MAX_BUF,
+            timeout: 120_000,
+          })
+          const list = JSON.parse(stdout)
+          const arr = Array.isArray(list) ? list : list?.data ?? list?.sessions ?? []
+          sid = arr[0]?.id ?? arr[0]?.sessionID
+          if (!sid) throw new Error("No session found in the archive (session list is empty)")
+        }
+        const { stdout } = await execFileAsync(bin, ["session", "export", "--standalone", sid!], {
+          env,
+          cwd: dir,
+          maxBuffer: MAX_BUF,
+          timeout: 120_000,
+        })
+        return JSON.parse(stdout)
+      })
+
+      if (!transcript?.info || !Array.isArray(transcript?.messages)) throw new Error("The archive does not contain a valid session transcript")
+
+      // Regenerate session and message ids (including cross-references inside the JSON) and drop parent-session links
+      let blob = JSON.stringify(transcript.messages)
+      for (const m of transcript.messages) {
+        if (m?.id) blob = blob.split(`"${m.id}"`).join(`"${rid(m.id)}"`)
+      }
+      const messages = JSON.parse(blob)
+      const info: any = { ...transcript.info, id: rid(transcript.info.id) }
+      delete info.parentID
+      delete info.fork
+
+      const created = await context.client.session.import({
+        info,
+        messages,
+        location: { directory: dir },
+      })
+
+      // Automatically open the new tab, just like opening a conversation via /session
+      context.ui.router.navigate({ type: "session", sessionID: created.id })
+      toast(`Loaded "${created.title ?? picked.file}"`)
+    }
+
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "sessions-forever.save",
+          title: "Save the current conversation as a .sf archive",
+          description: "Export the current session into a single .sf database file (official storage format); movable and shareable",
+          group: "Sessions Forever",
+          palette: true,
+          slash: { name: "session-save", arguments: true },
+          run: (input?: string) => save(input).catch(fail),
+        },
+        {
+          id: "sessions-forever.load",
+          title: "Load a .sf archive",
+          description: "List .sf archives in the current directory; the selected one is restored as a new session and opened automatically",
+          group: "Sessions Forever",
+          palette: true,
+          slash: { name: "session-load", arguments: true },
+          run: (input?: string) => load(input).catch(fail),
+        },
+      ],
+    }))
+  },
+})