opencode-sessions-explorer 0.1.1 → 0.1.2

package/docs/install.md

@@ -0,0 +1,140 @@
+# Install
+
+## Purpose
+
+Register `opencode-sessions-explorer` in OpenCode, optionally pin a version, and
+grant the one permission it needs to read the OpenCode session database.
+
+## Prerequisites
+
+| Area | Requirement |
+| --- | --- |
+| OpenCode | A working OpenCode install with plugin host compatibility for `@opencode-ai/plugin >= 1.15.0` |
+| Bun | `>= 1.0`; bundled with OpenCode, needed standalone only to run the CLIs directly. The plugin uses `bun:sqlite`, which should include SQLite `json1`; `check-deps` / `db-stats` verify it. |
+| `ck` (optional) | `>= 0.7`, only for `search-text` and `grep-session` |
+
+## Steps
+
+1. Add the plugin to the `plugin` array in `~/.config/opencode/opencode.json`:
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["opencode-sessions-explorer"]
+   }
+   ```
+
+   OpenCode auto-installs npm plugins with Bun on startup and caches them under
+   `~/.cache/opencode/node_modules`, so there is no separate install command.
+
+1. (Optional) Pin a version to avoid surprise upgrades by appending the version to
+   the package spec (for example, the current latest):
+
+   ```jsonc
+   {
+     "plugin": ["opencode-sessions-explorer@0.1.1"]
+   }
+   ```
+
+1. Grant access to the OpenCode data directory. This is required because the
+   database lives outside your project workspace:
+
+   ```jsonc
+   {
+     "permission": {
+       "external_directory": {
+         "~/.local/share/opencode/**": "allow"
+       }
+     }
+   }
+   ```
+
+   This default snippet covers the common macOS/Linux path. If `$XDG_DATA_HOME`,
+   Windows `%LOCALAPPDATA%`, or `OPENCODE_SESSIONS_EXPLORER_DB` points elsewhere,
+   allow the actual containing directory and restart OpenCode. Some current global
+   configs may use `external_directory: "allow"`; that works, but the scoped path
+   rule above is preferred for normal users.
+
+1. Quit and restart OpenCode. All 18 tools auto-register on the next launch.
+
+### From Source (Dev)
+
+To run a local checkout instead of the published package, install dependencies in
+the checkout first:
+
+```bash
+bun install --frozen-lockfile
+```
+
+Then choose one source-dev mode.
+
+#### Option A: Source TypeScript For Iteration
+
+Point the `plugin` array at the source entrypoint using an absolute path:
+
+```jsonc
+{
+  "plugin": ["/absolute/path/to/opencode-sessions-explorer/src/plugin.ts"]
+}
+```
+
+This is the fastest iteration path because there is no `dist/` rebuild step, but a
+full OpenCode restart is still required after config or code changes. Do not assume
+hot reload.
+
+#### Option B: Built JavaScript
+
+Build the bundle, then point OpenCode at the built entrypoint:
+
+```bash
+bun run build
+```
+
+```jsonc
+{
+  "plugin": ["/absolute/path/to/opencode-sessions-explorer/dist/plugin.js"]
+}
+```
+
+When using `dist/`, rebuild and fully restart OpenCode after code changes. There is
+no hot reload guarantee for local plugin paths.
+
+For contributor commands, quality gates, and source-dev maintenance pointers, see
+the [Development Guide](maintainers/development.md).
+
+## Validate
+
+Confirm the install resolved and the database is reachable:
+
+```bash
+bunx opencode-sessions-explorer-check-deps
+```
+
+For source checkouts, run local checkout commands instead of `bunx` while iterating:
+
+```bash
+bun src/bin/check-deps.ts
+bun src/bin/bulk-export.ts
+```
+
+If you selected the built-JS option and have already run `bun run build`, you can
+also validate the built CLI:
+
+```bash
+bun dist/bin/check-deps.js
+```
+
+A `0` exit code is all green; `1` flags optional pieces (such as a missing export
+tree or `ck`); `2` means a hard failure that must be fixed before the tools work.
+
+## Next Steps
+
+Continue with [getting-started.md](getting-started.md) to materialize the search
+export and run a first query.
+
+## Related Docs
+
+- [Getting Started](getting-started.md)
+- [Configuration reference](reference/configuration.md)
+- [Development Guide](maintainers/development.md)
+- [Troubleshooting](support/troubleshooting.md)

package/docs/maintainers/development.md

@@ -0,0 +1,140 @@
+# Development Guide
+
+## Purpose
+
+Define the local contributor workflow, quality gates, and project-specific
+gotchas for `opencode-sessions-explorer`.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0. OpenCode ships Bun; install it standalone only if
+  you run the bundled CLIs directly. The runtime is Bun, not Node — the plugin
+  uses `bun:sqlite`, which should include SQLite `json1`; `check-deps` / `db-stats`
+  verify it.
+- An OpenCode plugin host compatible with `@opencode-ai/plugin >= 1.15.0`.
+- [`ck`](https://github.com/BeaconBay/ck) >= 0.7 — required only when working on
+  `search-text` / `grep-session`; the other 16 tools work without it.
+- A populated OpenCode SQLite DB at `~/.local/share/opencode/opencode.db` —
+  required only for live testing and the end-to-end verifier.
+
+## Local Setup
+
+```bash
+bun install --frozen-lockfile
+```
+
+Load the plugin into a running OpenCode while iterating by pointing the config at
+your local checkout. Use the source TypeScript or built JavaScript options in
+[Install: From Source (Dev)](../install.md#from-source-dev); that page is the
+authoritative source-dev registration flow, including the full-restart requirement.
+
+## Local Dev Loop
+
+```bash
+bun run typecheck   # tsc --noEmit (strict mode)
+bun test            # hermetic by default
+bun run build       # bundle to dist/
+```
+
+For changes that affect tool output, also run the end-to-end verifier, which
+compares each tool against ground-truth SQL (this one needs a live DB):
+
+```bash
+bun tests/verify-end-to-end.ts
+```
+
+Check install health any time:
+
+```bash
+bun src/bin/check-deps.ts
+```
+
+For source-dev first-run validation, use the local checkout CLIs from
+[Install](../install.md#validate) (`bun src/bin/check-deps.ts`,
+`bun src/bin/bulk-export.ts`, or `bun dist/bin/check-deps.js` after a build) rather
+than `bunx`, which exercises the published npm package.
+
+## Architecture (pointer)
+
+The plugin is a 4-layer pipeline:
+
+```
+SQLite DB (read-only source of truth)
+  -> filesystem export tree (~/.local/share/opencode-sessions-explorer; by-session + by-channel)
+  -> ck index (.ck/; BM25 + embeddings; optional)
+  -> enriched response (re-fetches session/part metadata from SQLite per hit)
+```
+
+See the [Architecture Reference](../reference/architecture.md) for the full layer
+diagram and read-only / single-writer invariants, and the
+[Export And Maintenance Guide](../guides/export-and-maintenance.md) for export/index
+operations. `AGENTS.md` holds the authoritative per-tool contract.
+
+## Environment Overrides
+
+All paths are env-overridable, which is the easiest way to point tests or a dev
+session at non-default locations:
+
+| Env var | Purpose |
+| --- | --- |
+| `OPENCODE_SESSIONS_EXPLORER_DB` | Path to the OpenCode SQLite DB |
+| `OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT` | Where searchable session content is materialized |
+| `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` | Whitelist root for `get-part` dereference |
+| `OPENCODE_SESSIONS_EXPLORER_CK_BIN` | Override the `ck` binary location |
+
+## Tests: Hermetic vs Live
+
+- `bun test` is **hermetic by default** — it runs against a synthetic fixture DB
+  and does not need your real history. This is what CI runs.
+- To exercise the suite against your real `~/.local/share/opencode/opencode.db`,
+  opt in:
+
+  ```bash
+  OPENCODE_SESSIONS_EXPLORER_LIVE=1 bun test
+  # or
+  bun run test:live
+  ```
+
+  Live runs read real `ses_/msg_/prt_` IDs and minimum counts from your OpenCode
+  database; failures there reflect your own data, not necessarily a regression.
+
+## The `.js`-Import Gotcha (do not "fix" it)
+
+Inside `src/`, sibling imports use a **`.js`** extension even though the files are
+`.ts`:
+
+```ts
+import { stmt } from "../lib/db.js"; // the file is db.ts — this is correct
+```
+
+This is required by `tsc` (`moduleResolution: bundler`) and `bun build`. Rewriting
+these to `.ts` will break typecheck and the build. Files under `tests/` import
+`src` with `.ts`; that is fine, because Bun runs them unbuilt.
+
+## Adding or Editing a Tool
+
+- One tool per file in `src/tools/`, exported as a **named const** (not default).
+- Register it in `src/tools/index.ts` under the
+  `opencode-sessions-explorer-<name>` key and the re-export block.
+- Wrap the body in `runWithEnvelope("<fn_name>", capKb, async (ctx) => { … })`.
+- Raise recoverable errors via `fail(code, msg, hint)` using a code from
+  `src/lib/errors.ts`; do not invent ad-hoc error shapes.
+- Wrap list-shaped results in `table(records, { dict: [...] })` (lossless
+  columnar + interning).
+
+See `AGENTS.md` for the authoritative, fully detailed version of this contract.
+
+## Change Checklist
+
+- Run `bun run typecheck`, `bun test`, and `bun run build` locally.
+- For tool-output changes, run `bun tests/verify-end-to-end.ts`.
+- Update [`README.md`](../../README.md) for any user-facing change.
+- Add a note under `## [Unreleased]` in [`CHANGELOG.md`](../../CHANGELOG.md).
+- Keep commit scope focused.
+
+## Related Docs
+
+- [Docs Writing Standard](docs-writing.md)
+- [Install Guide](../install.md)
+- [Release Guide](release.md)
+- [Triage Guide](triage.md)

package/docs/maintainers/docs-writing.md

@@ -0,0 +1,86 @@
+# Docs Writing Standard
+
+## Purpose
+
+Define consistent structure, markdown style, and explanation patterns for
+project docs.
+
+## Core Principles
+
+- Lead with user outcome, then steps, then edge cases.
+- One page should have one clear intent.
+- Prefer short concrete statements over broad prose.
+- Use stable terms (`search-text`, `unarchive-session`, `OPENCODE_SESSIONS_EXPLORER_DB`)
+  consistently.
+
+## Page Type Templates
+
+### Start Pages
+
+Use sections in this order:
+
+1. `Purpose`
+1. `Prerequisites`
+1. `Setup` or `Steps`
+1. `Validate` (how to confirm success)
+1. `Next steps`
+
+### Guides
+
+Use sections in this order:
+
+1. `Purpose`
+1. `Default behavior` or `Mental model`
+1. `Controls` or `Entry points`
+1. `Recommended flow`
+1. `Related docs`
+
+### Reference Pages
+
+Use sections in this order:
+
+1. `Scope`
+1. `Definitions/Tables`
+1. `Examples`
+1. `Related docs`
+
+### Troubleshooting Pages
+
+Use sections in this order:
+
+1. `How to use this page`
+1. `Baseline checks`
+1. Symptom blocks (`Quick checks`, `Fix`)
+1. `Related docs`
+
+## Markdown Conventions
+
+- Keep headings concise and in Title Case.
+- Use numbered lists (`1.` style) for procedures.
+- Use tables for command/option/tool inventories.
+- Wrap commands, paths, options, env vars, and tool names in backticks.
+- Prefer fenced code blocks with language identifiers.
+- End pages with a `Related Docs` section.
+
+## Explanation Pattern
+
+Use this order for each important concept:
+
+1. What it is
+1. Why it matters
+1. How to use it
+1. How to validate it
+1. Where to go next
+
+## Link Policy
+
+- Keep canonical maintainer pages under `docs/maintainers/`.
+- Use relative links between docs and back to root files (`../../README.md`).
+- Update the "Maintainer Docs" list in [`CONTRIBUTING.md`](../../CONTRIBUTING.md)
+  whenever docs paths or ownership change.
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Release Guide](release.md)
+- [Triage Guide](triage.md)

package/docs/maintainers/release.md

@@ -0,0 +1,72 @@
+# Release Guide
+
+## Purpose
+
+Define repeatable steps to cut and publish a release of
+`opencode-sessions-explorer` to npm and GitHub.
+
+## Versioning
+
+Use [SemVer](https://semver.org/spec/v2.0.0.html):
+
+- Major: breaking changes
+- Minor: new features
+- Patch: fixes and docs
+
+## Release Checklist
+
+1. Bump the version in `package.json` to the target `x.y.z`.
+1. Move the `## [Unreleased]` notes in `CHANGELOG.md` into a new
+   `## [x.y.z] - YYYY-MM-DD` section, and leave an empty `## [Unreleased]`
+   above it for the next cycle.
+1. Run the quality gates locally and confirm they pass:
+
+   ```bash
+   bun run typecheck
+   bun test
+   bun run build
+   ```
+
+1. Confirm the **CI** workflow (`.github/workflows/ci.yml`) is green on the
+   commit you intend to tag.
+1. Commit the version bump and changelog (for example
+   `chore(release): vX.Y.Z`).
+1. Create an annotated tag and push it:
+
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+Pushing a `vX.Y.Z` tag triggers `.github/workflows/publish.yml`, which publishes
+the package to npm with provenance and creates the GitHub Release from the
+changelog entry.
+
+## Publish Bootstrap (first release only)
+
+The publish workflow is configured for npm
+[Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers), which
+needs the package to already exist on npm before OIDC can be linked. Bootstrap it
+once:
+
+1. Create a short-lived **automation** npm token and add it to the repository as
+   the `NPM_TOKEN` secret.
+1. Cut the first release (`v0.1.0`) so `publish.yml` publishes the initial
+   version to npm using that token.
+1. In the npm package settings, configure **Trusted Publishing** for this repo's
+   `.github/workflows/publish.yml`.
+1. **Revoke** the `NPM_TOKEN` secret and the npm token. Subsequent releases
+   authenticate via OIDC with no long-lived secret.
+
+## Post-Release
+
+- Verify the new version is live on
+  [npm](https://www.npmjs.com/package/opencode-sessions-explorer) and that the
+  GitHub Release was created.
+- Monitor issues for regressions.
+- Triage and label follow-up reports (see [Triage Guide](triage.md)).
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Triage Guide](triage.md)

package/docs/maintainers/triage.md

@@ -0,0 +1,55 @@
+# Triage Guide
+
+## Purpose
+
+Define issue intake, labeling, and follow-up policy. The canonical label
+definitions live in [`.github/labels.yml`](../../.github/labels.yml); this guide
+documents how they are applied.
+
+## Intake Flow
+
+1. Confirm issue template quality (clear repro, version, environment).
+1. Reproduce the issue when possible.
+1. Apply labels for type, status, and scope.
+
+## Label Set
+
+Issue type:
+
+- `bug` — something is not working
+- `enhancement` — new feature or request
+- `documentation` — documentation updates
+- `security` — security related issues
+- `question` — further information requested
+
+Contributor signals:
+
+- `help wanted` — extra attention is needed
+- `good first issue` — good for newcomers
+
+Implementation focus:
+
+- `tests` — test coverage or fixes
+- `refactor` — refactoring or cleanup
+- `chore` — maintenance tasks
+
+Triage status:
+
+- `triage/needs-info` — needs more information from the reporter
+- `triage/confirmed` — repro confirmed by maintainers
+- `triage/blocked` — blocked on an external dependency or upstream (e.g.
+  OpenCode or `ck`)
+- `triage/duplicate` — duplicate of an existing issue
+- `triage/wontfix` — will not be addressed
+
+## Follow-Up Policy
+
+- Close `triage/needs-info` after 14 days without a response.
+- For `triage/blocked`, document the blocker and a recheck date.
+- Close `triage/duplicate` with a link to the canonical issue.
+- Close `triage/wontfix` with a concise rationale and alternatives when possible.
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Release Guide](release.md)

package/docs/reference/architecture.md

@@ -0,0 +1,112 @@
+# Architecture Reference
+
+## Scope
+
+This page describes the four-layer pipeline that turns the OpenCode session
+database into enriched, searchable tool responses, and the single-writer exception
+to the otherwise read-only design. It is a conceptual reference; for the
+contributor-facing build and code layout, see the
+[Development Guide](../maintainers/development.md).
+
+## The Four Layers
+
+```
+L1  SQLite DB (read-only source of truth)
+      | PRAGMA query_only = 1; opened readonly
+      v
+L2  filesystem export tree (~/.local/share/opencode-sessions-explorer)
+      | by-session/<ses_id>/...  +  by-channel/<channel>/by-session/<ses_id>/...
+      | delta-synced before each search call
+      v
+L3  ck index (.ck/, BM25 + embeddings; optional)
+      | incremental; built by the ck CLI
+      v
+L4  enriched response
+      | re-fetches session/part metadata from SQLite per hit
+      v
+    { ok, data, meta, warnings } envelope
+```
+
+### L1 — SQLite Source Of Truth
+
+The OpenCode database is the authoritative source. The shared handle opens it
+read-only and sets `PRAGMA query_only = 1` as a belt-and-braces guard, so any
+accidental write through that handle throws. The live OpenCode process may be
+writing concurrently — the database runs in WAL mode and multiple readers plus a
+writer is safe, with a `busy_timeout` covering rare lock collisions. All metadata,
+counts, and message/part bodies ultimately come from here.
+
+### L2 — Filesystem Export Tree
+
+Searchable content is materialized to a filesystem tree (default
+`~/.local/share/opencode-sessions-explorer`, overridable via
+`OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT`). It has two arms:
+
+- `by-session/<ses_id>/` — the raw, lossless per-part export plus `meta.json`.
+- `by-channel/<channel>/by-session/<ses_id>/` — curated channel views derived from
+  the raw parts (see [search-surfaces.md](search-surfaces.md)).
+
+The tree is built once by `opencode-sessions-explorer-bulk-export` and then
+delta-synced automatically before each `search-text` / `grep-session` call, so new
+parts become searchable without a manual re-export. Sync is cursor-based on
+`(time_updated, id)`, which also re-exports parts whose status mutated since the last
+pass.
+
+### L3 — ck Index (Optional)
+
+`search-text` and `grep-session` shell out to the [`ck`](https://github.com/BeaconBay/ck)
+CLI, which walks the export tree. `ck` supports plain regex with no index, a BM25
+full-text index, and semantic embeddings; the index lives under `.ck/` in the export
+root and is incremental. `ck` is optional: when it is absent these two tools return
+`CK_NOT_FOUND` cleanly and the other 16 tools are unaffected.
+
+### L4 — Enriched Response
+
+Search hits from `ck` carry file paths, not domain objects. The final layer parses
+the session and part ids out of each hit path and re-fetches fresh metadata from
+SQLite (session title, agent, model, part type, message role) before returning
+results. Every tool wraps its payload in a uniform `{ ok, data, meta, warnings }`
+envelope; list-shaped data inside `data` uses the compact format described in
+[response-format.md](response-format.md).
+
+## Single-Writer Exception
+
+The plugin is read-only with exactly one sanctioned write: `unarchive-session`.
+Reads never write through the shared read-only handle. The write goes through a
+separate, short-lived read-write connection that performs a single statement —
+`UPDATE session SET time_archived = NULL, time_updated = <now>` — and closes
+immediately.
+
+Both fields are updated deliberately. OpenCode loads sessions ordered by
+`time_updated DESC` with a default limit per directory, so clearing `time_archived`
+alone would leave a long-archived session buried below that window, and opening it
+would fail with "Unable to retrieve session". Refreshing `time_updated` resurfaces
+the session at the top of the list, which is also the intuitive meaning of
+"restore". OpenCode exposes no HTTP or SDK endpoint that can *clear* the archived
+flag, so the direct database write is the only mechanism.
+
+## Examples
+
+Materialize the export tree (L2), then build the optional `ck` index (L3):
+
+```bash
+bunx opencode-sessions-explorer-bulk-export
+cd ~/.local/share/opencode-sessions-explorer
+ck --index .   # run in the export root, not the repository checkout
+```
+
+Verify all four layers are healthy:
+
+```bash
+bunx opencode-sessions-explorer-check-deps
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Compact result format: [response-format.md](response-format.md)
+- Configuration and environment overrides: [configuration.md](configuration.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Development Guide: [../maintainers/development.md](../maintainers/development.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)