opencode-tsift 0.1.63

package/README.md

@@ -0,0 +1,94 @@
+# opencode-tsift
+
+OpenCode command shortcuts for `tsift`.
+
+Install the plugin from npm:
+
+```sh
+opencode plugin opencode-tsift
+```
+
+OpenCode installs npm plugins with Bun at startup and loads plugins listed in
+the `plugin` config array. This package writes marker-owned project commands
+into `.opencode/commands/` when the plugin loads, so the following commands are
+available in a project without cloning the `tsift` repository:
+
+- `/tsift-status`
+- `/tsift-session-review`
+- `/tsift-context-pack`
+- `/tsift-memory-status`
+- `/tsift-memory-search`
+- `/tsift-memory-guard`
+- `/tsift-diff-digest`
+- `/tsift-test-digest`
+- `/tsift-log-digest`
+- `/tsift-rewrite-run`
+
+The commands shell out to the `tsift` binary. Install `tsift` first:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/btakita/tsift/main/scripts/install.sh | sh
+```
+
+You can also install or refresh the command files directly:
+
+```sh
+npx opencode-tsift .
+```
+
+Existing command files with the same names are only replaced when they already
+contain the `tsift:opencode-command` ownership marker.
+
+## Permissions
+
+All commands shell out to the `tsift` binary via Bash. Without
+`--dangerously-skip-permissions`, OpenCode will prompt for approval on each
+shell invocation. The required permissions break down by command:
+
+| Command | Bash execution | File read | File write |
+|---|---|---|---|
+| `/tsift-status` | `tsift status --fix` | `.tsift/`, source tree | `.tsift/`, AGENTS.md, CLAUDE.md |
+| `/tsift-session-review` | `tsift --envelope session-review` | `.tsift/`, agent-doc logs | — |
+| `/tsift-context-pack` | `tsift --envelope context-pack` | `.tsift/`, source files | — |
+| `/tsift-memory-status` | `tsift memory status` | `.tsift/`, `.claude-mem/` fallback import source | — |
+| `/tsift-memory-search` | `tsift graph-db --path . --json related` | `.tsift/graph.db`, `.tsift/memory.db` projected rows | — |
+| `/tsift-memory-guard` | `tsift memory budget-guard` | target payload | — |
+| `/tsift-diff-digest` | `tsift diff-digest` | `.tsift/`, git working tree | — |
+| `/tsift-test-digest` | `tsift --envelope digest-runner --kind test` | `.tsift/`, test output | — |
+| `/tsift-log-digest` | `tsift --envelope digest-runner --kind log` | `.tsift/`, build output | — |
+| `/tsift-rewrite-run` | `tsift rewrite --run` | `.tsift/`, command-dependent input | command-dependent |
+
+`/tsift-status` is the only command that writes files (index, instructions).
+`/tsift-rewrite-run` has the same read/write profile as the rewritten command it
+executes. The other commands are read-only.
+
+## Troubleshooting
+
+**`tsift: command not found`** — Install the tsift binary first:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/btakita/tsift/main/scripts/install.sh | sh
+```
+
+**`tsift status` reports stale index** — Run `/tsift-status` again; it passes
+`--fix` which reindexes automatically.
+
+**Command files conflict with existing files** — If `.opencode/commands/tsift-*.md`
+exists without the `tsift:opencode-command` marker, the installer refuses to
+overwrite it. Move or rename the conflicting file, then reinstall.
+
+**Plugin does not install commands at startup** — Verify the plugin is listed in
+your OpenCode config:
+
+```json
+{
+  "plugin": ["opencode-tsift"]
+}
+```
+
+OpenCode installs and loads plugins with Bun on startup. Check that Bun can
+resolve the package by running `opencode plugin opencode-tsift` again.
+
+**`npx opencode-tsift .` does nothing** — If the command files are already
+current, the tool reports `already present` for each file. This is the expected
+idempotent behavior.

package/bin/opencode-tsift.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { installFromCli } from "../src/install.js";
+
+installFromCli().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/commands/tsift-context-pack.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-context-pack -->
+---
+description: Build a bounded tsift context pack
+---
+
+Run `tsift --envelope context-pack <target> --budget normal`, where `<target>` is `$ARGUMENTS` or `.` when no argument is provided. Use source handles and expansion commands from the packet before reading whole files.

package/commands/tsift-diff-digest.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-diff-digest -->
+---
+description: Digest current or requested git diff
+---
+
+Run `tsift diff-digest <target>`, where `<target>` is `$ARGUMENTS` or `.` when no argument is provided. Summarize changed paths, high-signal hunks, and any follow-up expansion commands instead of pasting the raw diff.

package/commands/tsift-explain.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-explain -->
+---
+description: Explain a symbol via callers, callees, and community preview
+---
+
+Explain the symbol named by `$ARGUMENTS` using `tsift --envelope explain '<symbol>' --budget normal`. Prefer this when you need callers, callees, or community context for a function, struct, or type. The envelope returns ranked caller/callee lists with file locations, community membership, and expansion commands for graph traversal. When the report includes a `scale_guard`, run one of its `narrow_commands` before dispatching parallel agents. Use `tsift graph '<symbol>' --callers` or `--callees` for full call-graph navigation. Fall back to `tsift --envelope search '<symbol>' --budget normal` when the symbol is not found in the index.

package/commands/tsift-graph.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-graph -->
+---
+description: Call graph navigation via tsift graph
+---
+
+Navigate the call graph for the symbol named by `$ARGUMENTS` using `tsift graph '<symbol>' --callers` or `tsift graph '<symbol>' --callees`. Use `--callers` to find who calls the symbol, `--callees` to find what the symbol calls. The output lists edges with file locations, edge kinds, and navigation hints. Adjust `--limit` (default 20) to cap edges per direction. For a broader overview including community membership, prefer `tsift --envelope explain '<symbol>' --budget normal`. Fall back to `tsift --envelope search '<symbol>' --budget normal` when the symbol is not found in the index.

package/commands/tsift-log-digest.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-log-digest -->
+---
+description: Run a verbose command through the bounded log digest
+---
+
+Run a bounded log digest. If `$ARGUMENTS` names a build, install, or verification command, run `tsift --envelope digest-runner --kind log --path . --shell-command '<command>'`; otherwise ask for the command before running. Summarize compact output, failures, and artifact handles.

package/commands/tsift-memory-guard.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-memory-guard -->
+---
+description: Guard a memory or tool payload before model handoff
+---
+
+Run `tsift memory budget-guard --file <target> --json` when `$ARGUMENTS` names a file, or `tsift memory budget-guard --text '<payload>' --json` for inline payload text. Summarize whether the payload is allowed, the estimated token count, replacement digest/context commands, and retryable chunk commands; file retry commands may include `--byte-start` / `--byte-end`. Do not send the raw payload to a model when the guard returns `blocked_split_required`.

package/commands/tsift-memory-search.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-memory-search -->
+---
+description: Search first-party tsift memory graph
+---
+
+Run `tsift graph-db --path . --json related '<query>'`, where `<query>` is `$ARGUMENTS`; ask for a query if `$ARGUMENTS` is empty. Summarize semantic readiness, useful memory/source hits, and any refresh/import fallback commands. Prefer tsift-memory/graph-db retrieval and do not call direct claude-mem or `/mem-search`; claude-mem remains only a fallback import source through `tsift memory import-claude-mem` when graph memory is missing.

package/commands/tsift-memory-status.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-memory-status -->
+---
+description: Inspect first-party tsift memory readiness
+---
+
+Run `tsift memory status <target> --json`, where `<target>` is `$ARGUMENTS` or `.` when no argument is provided. Summarize schema initialization, agent-doc hook contract, graph-db retrieval readiness, the claude-mem retirement gate, and rollback commands. Do not import data unless the user explicitly asks for `--apply`.

package/commands/tsift-rewrite-run.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-rewrite-run -->
+---
+description: Run a shell command through tsift rewrite
+---
+
+Run the shell command named by `$ARGUMENTS` through `tsift rewrite --run '<command>'`. Use this for broad `rg`/recursive `grep`, raw transcript/session/log reads, `git diff`/`git show`/single-patch `git log`, `cargo test`/`pytest`, and cargo build/check/clippy/install commands so Codex/OpenCode get the same bounded search, session-digest, diff-digest, and digest-runner path as the Claude hook. If tsift reports no rewrite, do not retry automatically; summarize the reason and run the original command only when the user still needs exact raw output.

package/commands/tsift-search.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-search -->
+---
+description: AST-aware content search via tsift search
+---
+
+Search code using `tsift --envelope search '<query>' --budget normal`, where `<query>` is `$ARGUMENTS`. Prefer this over grep/rg for content search in indexed projects. The envelope returns ranked search hits with symbol families, file previews, AST-aware scoring, and expansion commands. When the report includes a `scale_guard`, run one of its `narrow_commands` before dispatching parallel agents. Use `tsift workflow search` for the ordered exact/search/explain/summarize/digest recipe that preserves result handles across expansions. Fall back to grep/rg only when the project is not indexed or for non-code file patterns (e.g. glob-only searches).

package/commands/tsift-session-review.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-session-review -->
+---
+description: Summarize bounded agent session context
+---
+
+Run `tsift --envelope session-review <target> --next-context --budget normal`, where `<target>` is `$ARGUMENTS` or `.` when no argument is provided. Summarize prompt targets, unresolved failures, touched files/symbols, and next digest commands. Do not replay raw transcripts.

package/commands/tsift-source-read.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-source-read -->
+---
+description: AST-aware source code reading via tsift source-read
+---
+
+Read source code using `tsift --envelope source-read <file> --start <n> --lines <n> --budget normal`, where `<file>` is `$ARGUMENTS` or the file the user wants to inspect. Prefer this over the raw Read tool for source code files (Rust, TypeScript, JavaScript, Python, Markdown, and other indexed languages). The envelope returns a bounded source window with AST symbol metadata, line previews, and expansion commands for before/after/full-file ranges. When `$ARGUMENTS` includes a line range, parse `start` and `lines` from it; otherwise default to `--start 1 --lines 80`. Use the returned `expand` commands to read adjacent ranges instead of re-reading the entire file. Fall back to the raw Read tool only for non-indexed files or binary assets.

package/commands/tsift-status.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-status -->
+---
+description: Refresh and summarize tsift index status
+---
+
+Run `tsift status --fix` from the project root, then summarize index freshness, instruction freshness, summary-cache state, and any recommended `use:` or `run:` commands. Stop and report the exact failure if the command fails.

package/commands/tsift-symbol-read.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-symbol-read -->
+---
+description: Read symbol body with AST metadata via tsift symbol-read
+---
+
+Read the symbol named by `$ARGUMENTS` using `tsift --envelope symbol-read '<symbol>' --budget normal`. Prefer this over reading entire source files when you need a specific function, struct, or type definition. The envelope returns the symbol body, AST span metadata, child references, and expansion commands for graph/source navigation. When `$ARGUMENTS` includes a file hint, pass it as `--file '<path>'` to disambiguate duplicate names. Use the returned `expand` commands to inspect callers, callees, or the full source file. Fall back to `tsift --envelope source-read '<file>' --start <n> --lines <n> --budget normal` when the symbol is not found or when you need raw source without AST context.

package/commands/tsift-test-digest.md

@@ -0,0 +1,6 @@
+<!-- tsift:opencode-command v=0.1.63 name=tsift-test-digest -->
+---
+description: Run tests through the bounded digest runner
+---
+
+Run a bounded test digest. If `$ARGUMENTS` names a test command, run `tsift --envelope digest-runner --kind test --path . --shell-command '<command>'`; otherwise choose the project test command from the local instructions and wrap it the same way. Summarize failing tests, failure lines, and artifact handles.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "opencode-tsift",
+  "version": "0.1.63",
+  "description": "OpenCode command shortcuts for tsift bounded code navigation and session evidence",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/index.js"
+  },
+  "bin": {
+    "opencode-tsift": "bin/opencode-tsift.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "publish:check": "npm publish --access public --dry-run"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tsift",
+    "agent",
+    "commands"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/btakita/tsift.git",
+    "directory": "packages/opencode-tsift"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,92 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { installCommands } from "./install.js";
+
+const execFileAsync = promisify(execFile);
+
+async function resolveTsiftBin() {
+  const binName = process.platform === "win32" ? "tsift.exe" : "tsift";
+  try {
+    const { stdout } = await execFileAsync("which", [binName], { timeout: 5000 });
+    return stdout.trim();
+  } catch {
+    return binName;
+  }
+}
+
+export const TsiftOpenCodePlugin = async (ctx = {}) => {
+  const projectDir = ctx.directory || ctx.worktree || process.cwd();
+  const log = ctx.client?.app?.log?.bind(ctx.client.app) ?? (() => {});
+
+  async function ensureInstalled() {
+    const updates = await installCommands(projectDir);
+    const changed = updates.filter((update) => update.action !== "already present");
+    if (changed.length > 0) {
+      await log({
+        body: {
+          service: "opencode-tsift",
+          level: "info",
+          message: "tsift OpenCode commands installed",
+          extra: {
+            projectDir,
+            files: changed.map((update) => update.name),
+          },
+        },
+      });
+    }
+  }
+
+  async function ensureIndexFresh() {
+    let tsiftBin;
+    try {
+      tsiftBin = await resolveTsiftBin();
+    } catch {
+      return;
+    }
+
+    let report;
+    try {
+      const { stdout } = await execFileAsync(tsiftBin, ["status", "--json", projectDir], { timeout: 15000 });
+      report = JSON.parse(stdout);
+    } catch {
+      return;
+    }
+
+    const state = report?.index?.state;
+    if (state !== "stale" && state !== "missing") return;
+
+    try {
+      await execFileAsync(tsiftBin, ["status", "--fix", projectDir], { timeout: 120000 });
+      await log({
+        body: {
+          service: "opencode-tsift",
+          level: "info",
+          message: "tsift auto-reindex completed",
+          extra: { projectDir, previousState: state },
+        },
+      });
+    } catch (error) {
+      await log({
+        body: {
+          service: "opencode-tsift",
+          level: "warn",
+          message: `tsift auto-reindex failed: ${error.message}`,
+          extra: { projectDir },
+        },
+      });
+    }
+  }
+
+  await ensureInstalled();
+  await ensureIndexFresh();
+
+  return {
+    "installation.updated": async () => {
+      await ensureInstalled();
+      await ensureIndexFresh();
+    },
+  };
+};
+
+export default TsiftOpenCodePlugin;

package/src/install.js

@@ -0,0 +1,71 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const COMMAND_MARKER = "<!-- tsift:opencode-command";
+
+function packageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+async function readIfPresent(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+export async function installCommands(projectDir = process.cwd()) {
+  const root = resolve(projectDir);
+  const sourceDir = join(packageRoot(), "commands");
+  const targetDir = join(root, ".opencode", "commands");
+  await mkdir(targetDir, { recursive: true });
+
+  const files = (await readdir(sourceDir))
+    .filter((file) => file.endsWith(".md"))
+    .sort();
+
+  const updates = [];
+  for (const file of files) {
+    const content = await readFile(join(sourceDir, file), "utf8");
+    const target = join(targetDir, file);
+    const existing = await readIfPresent(target);
+    let action = "created";
+
+    if (existing !== undefined) {
+      if (existing === content) {
+        action = "already present";
+      } else if (!existing.includes(COMMAND_MARKER)) {
+        throw new Error(
+          `${target} already exists and is not managed by tsift; move it or add the tsift marker before installing opencode-tsift`,
+        );
+      } else {
+        action = "updated";
+      }
+    }
+
+    if (action !== "already present") {
+      await writeFile(target, content);
+    }
+
+    updates.push({
+      action,
+      file: target,
+      name: file.replace(/\.md$/, ""),
+    });
+  }
+
+  return updates;
+}
+
+export async function installFromCli(args = process.argv.slice(2)) {
+  const projectDir = resolve(args[0] ?? process.cwd());
+  const updates = await installCommands(projectDir);
+  for (const update of updates) {
+    console.log(`${relative(projectDir, update.file)}: ${update.action} (OpenCode /${update.name} tsift shortcut)`);
+  }
+}