@soffits/opencode-rummage 0.0.0-stage → 0.2.0

package/index.js

@@ -0,0 +1,78 @@
+// OpenCode plugin for rummage: recall from the user's files on each prompt, plus the rummage skill.
+//
+// The prompt hook runs `rummage recall` once per prompt and keeps the block in the message's metadata, so it is
+// stored with the message and never re-run. The context hook adds that block to its user message in every model
+// request, so the system prompt stays the same and the request prefix stays cacheable. A recall that fails or
+// takes longer than `timeout` adds nothing.
+
+import { execFile } from "node:child_process"
+import { readFileSync } from "node:fs"
+
+const KEY = "rummage.recall"
+
+function recall(command, args, prompt, sessionID, cwd, timeout) {
+  return new Promise((resolve) => {
+    const child = execFile(
+      command,
+      ["recall", "--hook", ...args],
+      { timeout, maxBuffer: 1 << 20, windowsHide: true },
+      (error, stdout) => {
+        if (error || !stdout.trim()) return resolve("")
+        try {
+          resolve(JSON.parse(stdout).hookSpecificOutput?.additionalContext ?? "")
+        } catch {
+          resolve("")
+        }
+      },
+    )
+    child.stdin.on("error", () => {})
+    child.stdin.end(JSON.stringify({ prompt, session_id: sessionID, cwd, harness: "opencode" }))
+  })
+}
+
+function bundledSkill() {
+  try {
+    const path = new URL("./skills/rummage/SKILL.md", import.meta.url)
+    const text = readFileSync(path, "utf8")
+    const [, front = "", body = text] = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/) ?? []
+    const field = (name) => front.match(new RegExp(`^${name}:\\s*(.*)$`, "m"))?.[1].trim()
+    return { id: field("name") ?? "rummage", description: field("description"), path: path.pathname, content: body }
+  } catch {
+    return undefined
+  }
+}
+
+export default {
+  id: "rummage",
+  async setup(ctx) {
+    const options = ctx.options ?? {}
+    const command = options.command ?? "rummage"
+    const args = options.args ?? []
+    const timeout = options.timeout ?? 5000
+
+    await ctx.session.hook("prompt", async (event) => {
+      const text = event.prompt.text ?? ""
+      if (!text.trim()) return
+      const cwd = ctx.location?.directory ?? process.cwd()
+      const block = await recall(command, args, text, String(event.sessionID), cwd, timeout)
+      if (block) event.metadata = { ...event.metadata, [KEY]: block }
+    })
+
+    await ctx.session.hook("context", (event) => {
+      event.messages.forEach((message, index) => {
+        const block = message.role === "user" && message.metadata?.[KEY]
+        if (typeof block !== "string") return
+        event.messages[index] = Object.assign(Object.create(Object.getPrototypeOf(message)), message, {
+          content: [...message.content, { type: "text", text: block }],
+        })
+      })
+    })
+
+    const skill = options.skill === false ? undefined : bundledSkill()
+    if (skill) {
+      await ctx.skill.transform((editor) => {
+        if (!editor.get(skill.id)) editor.add({ ...skill, name: skill.id })
+      })
+    }
+  },
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@soffits/opencode-rummage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCode plugin for rummage: recall from your own files on each prompt, a skill for searching them, and indexing progress in the footer.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Sakina",
+  "homepage": "https://github.com/soffits/rummage/blob/main/docs/integrations.md#opencode",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soffits/rummage.git",
+    "directory": "integrations/opencode"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "memory",
+    "recall",
+    "search"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./tui": "./tui.js"
+  },
+  "files": [
+    "index.js",
+    "tui.js",
+    "skills"
+  ],
+  "scripts": {
+    "prepack": "node -e \"require('fs').cpSync('../../skills/rummage', 'skills/rummage', { recursive: true })\""
+  },
+  "peerDependencies": {
+    "@opentui/solid": ">=0.6.6",
+    "solid-js": ">=1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  }
+}

package/skills/rummage/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: rummage
+description: Search the user's own local files (notes, documents, PDFs, pictures, chats) by meaning or exact words with the rummage CLI, then open the passages it finds. Use when the answer may be in the user's files and you don't know where, or the exact words.
+---
+
+# rummage
+
+`rummage` keeps a local index of the user's files and finds things by what they mean and by the exact words in
+them. It runs on the user's machine; nothing is sent anywhere.
+
+## Search
+
+```bash
+rummage search "what the user is looking for, in their own words" --json -n 10
+rummage search "INV-20931" --words-only --json          # names, IDs, numbers: exact words, no model, instant
+rummage search "..." --json --path notes/work --glob '*.md' -s notes   # narrow by folder, pattern, source
+rummage search "..." --json --since 2026-10-01 --until 2026-10-31      # a time window (dates you work out)
+rummage search "Ana Souza" --json --sort newest -n 30                  # the newest matches first
+rummage search "..." --json --budget-tokens 1500                       # shorter output
+```
+
+The JSON has `status`:
+
+- `ok`: `results` are ranked. `summary.strong` says how many score near the top; the rest are weak.
+- `no_results`: nothing matched. Rephrase by meaning, try exact words with `--words-only`, or drop a scope
+  filter.
+- `empty_index` or an error with status `index_missing`: nothing is indexed yet (`rummage index`).
+
+Each result has `id`, `source`, `title`, `ref` (where it is), `lines` for text files, `score`, `snippet`.
+`next_actions` holds the commands that show what the output left out (masked credentials, the rest of a partially
+indexed file); the next query is yours to choose.
+
+## Open what you found
+
+```bash
+rummage get '#3f2a9c01be'            # the whole item's text
+rummage get '#3f2a9c01be' --loc 1800  # only the matched passage (a result's `loc`)
+rummage get 'notes/lease.md' --head 40
+```
+
+For a chat result, `rummage get '#id' --around 3` shows the turns before and after it; for a file passage it shows
+the lines around it. `rummage recent --minutes 30 --json` lists what was said or changed lately, newest first.
+
+Credentials in results print as `[secret]`. Add `--show-secrets` only when the user asks for a value.
+
+Quote the file and lines you relied on. A miss doesn't prove the thing isn't there: try other words, exact
+names, or the folder directly before saying so.

package/tui.js

@@ -0,0 +1,108 @@
+// OpenCode TUI part of the rummage plugin: shows rummage's index state in the footer while it is building, paused
+// or broken, and a toast when indexing starts, finishes or fails.
+//
+// All state comes from `rummage status --line --json`, which reads one small progress file. Between runs this part
+// only checks that file's modification time, so an idle index costs a stat every few seconds. Written as plain JS
+// (no JSX): OpenCode does not transpile JSX in packages installed under node_modules.
+
+import { execFile } from "node:child_process"
+import { stat } from "node:fs/promises"
+import { createElement, effect, insert, setProp } from "@opentui/solid"
+import { createSignal } from "solid-js"
+
+const CHECK_MS = 2000
+const RECHECK_BUSY_MS = 30000
+const FOOTER_CHARS = 60
+const KEY = Symbol.for("rummage.opencode.tui")
+
+function run(command, args, timeout) {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout, maxBuffer: 1 << 20, windowsHide: true }, (error, stdout, stderr) =>
+      resolve({ ok: !error, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }),
+    )
+  })
+}
+
+export default {
+  id: "rummage.tui",
+  setup(context) {
+    // The TUI may set a plugin up again while an older instance lives; only the newest one polls and renders.
+    globalThis[KEY]?.()
+    const options = context.options ?? {}
+    const command = options.command ?? "rummage"
+    const [info, setInfo] = createSignal({ state: "complete", line: "" })
+    const started = Date.now()
+    let file, mtime = 0, checked = 0, timer, stopped = false
+
+    async function refresh() {
+      const result = await run(command, ["status", "--line", "--json"], 10000)
+      checked = Date.now()
+      if (!result.ok) return
+      let next
+      try {
+        next = JSON.parse(result.stdout)
+      } catch {
+        return
+      }
+      const before = info()
+      file = next.file ?? file
+      setInfo(next)
+      if (before.state !== next.state && checked > started + 1000) {
+        if (next.state === "complete" && before.state === "building")
+          context.ui.toast.show({ title: "rummage", message: "index complete", variant: "success" })
+        else if (next.state === "error" || next.state === "stopped")
+          context.ui.toast.show({ title: "rummage", message: next.note || next.line, variant: "warning" })
+        else if (next.state === "building" && before.state === "complete")
+          context.ui.toast.show({ title: "rummage", message: next.line, variant: "info" })
+      }
+    }
+
+    async function tick() {
+      if (stopped) return
+      try {
+        const now = Date.now()
+        let changed = false
+        if (file) {
+          const seen = await stat(file).then((s) => s.mtimeMs, () => 0)
+          changed = seen !== mtime
+          mtime = seen
+        }
+        const busy = info().state !== "complete" || info().line
+        if (!file || changed || (busy && now - checked > RECHECK_BUSY_MS)) await refresh()
+      } finally {
+        if (!stopped) timer = setTimeout(tick, CHECK_MS)
+      }
+    }
+
+    void tick()
+
+    function label() {
+      const el = createElement("text")
+      insert(el, () => {
+        const line = info().line || ""
+        return line.length > FOOTER_CHARS ? line.slice(0, FOOTER_CHARS - 3) + "..." : line
+      })
+      effect((prev) => {
+        const bad = ["error", "stopped", "paused"].includes(info().state)
+        const theme = context.theme.text
+        return setProp(el, "fg", bad ? (theme.feedback?.warning?.base ?? theme.base) : theme.muted, prev)
+      })
+      return el
+    }
+
+    const unslot = [
+      context.ui.slot({ append: "prompt.footer.status", render: label }),
+      context.ui.slot({ append: "home.footer.status", render: label }),
+    ]
+
+    const dispose = () => {
+      if (stopped) return
+      stopped = true
+      clearTimeout(timer)
+      for (const off of unslot) off?.()
+      if (globalThis[KEY] === dispose) delete globalThis[KEY]
+    }
+    globalThis[KEY] = dispose
+    return dispose
+  },
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.