greprag 5.31.1 → 5.34.0

package/dist/opencode-plugin-helpers.d.ts

@@ -0,0 +1,200 @@
+/** GrepRAG opencode plugin — test-friendly helpers.
+ *
+ * Pure functions and type definitions extracted from `opencode-plugin.ts` so
+ * the deployed plugin file can use a single `export = { id, server }` shape
+ * (no `__esModule: true` wrapper, no `__test` helper export). The opencode
+ * legacy plugin loader iterates `Object.values(mod)` and rejects any value
+ * that isn't a function or `{ server: function }`; an `__esModule: true`
+ * boolean in that iteration throws "Plugin export is not a function" and the
+ * plugin registers zero hooks. See `adr/opencode-monitor-relay.md` 2026-06-06
+ * entries (e) and (f) for the full diagnosis.
+ *
+ * Three callers, all out-of-band of opencode's loader:
+ *   - `opencode-plugin.ts` — the deployed plugin source imports these for use
+ *     inside the V1 server function (recap renderer + anchor + lockfile).
+ *   - `hook.ts` — Claude/Codex SessionStart hook imports the recap renderer
+ *     so the recap body pushed to the system prompt is identical between
+ *     harnesses. The hook keeps its own preamble (setup warning, checkpoint
+ *     hint) — those are session-start UX concerns, not recap content.
+ *   - `tests/test-opencode-plugin.cjs` and `tests/test-opencode-relay-spawn.cjs`
+ *     — unit tests pull the same helpers by `require()` to exercise envelope
+ *     construction, anchor resolution, and lockfile dedup without booting
+ *     opencode.
+ *
+ * opencode never loads this file directly. Its presence at
+ * `~/.config/opencode/plugins/greprag-memory-helpers.js` is incidental to the
+ * deploy step; only `greprag-memory.js` is registered in the user's
+ * `opencode.json` plugin list.
+ */
+declare const HOME: string;
+interface TextPart {
+    type: 'text';
+    text: string;
+    synthetic?: boolean;
+    ignored?: boolean;
+}
+type ToolState = {
+    status: 'pending';
+    input: Record<string, unknown>;
+} | {
+    status: 'running';
+    input: Record<string, unknown>;
+    title?: string;
+} | {
+    status: 'completed';
+    input: Record<string, unknown>;
+    output: string;
+    title: string;
+} | {
+    status: 'error';
+    input: Record<string, unknown>;
+    error: string;
+};
+interface ToolPart {
+    type: 'tool';
+    callID: string;
+    tool: string;
+    state: ToolState;
+}
+interface GenericPart {
+    type: string;
+    [key: string]: unknown;
+}
+type Part = TextPart | ToolPart | GenericPart;
+interface ProjectAnchor {
+    projectId: string;
+    projectName: string;
+    memoryCapture: boolean;
+    sessionStartRecap: boolean;
+    inboxNotify: 'every_turn' | 'session_start_only' | 'off';
+}
+/** Parsed `.greprag/project.json` contents. `project_id` and `project_name` are
+ *  both optional after v0.7 — a file may carry per-project settings only and
+ *  let identity flow from git derivation. */
+interface AnchorFile {
+    projectId?: string;
+    projectName?: string;
+    memoryCapture: boolean;
+    sessionStartRecap: boolean;
+    inboxNotify: 'every_turn' | 'session_start_only' | 'off';
+}
+declare function readAnchorFile(filePath: string): AnchorFile | null;
+/** Walk up from cwd looking for an anchor file. Checks canonical `.greprag/`
+ *  first, then legacy `.claude/` and `.opencode/` at each level. Returns the
+ *  first hit. Skips home-level globals; those are reserved for the
+ *  ephemeral-cwd path of the cascade. */
+declare function findExistingAnchorFile(startDir: string): string | null;
+/** Format the SHA-256 of an input string into a deterministic UUID v4-shape
+ *  string. Must match the algorithm in packages/cli/src/project-anchor.ts so
+ *  the plugin resolves identical IDs to the Claude Code CLI. */
+declare function formatUuid(hashHex: string): string;
+/** Derive a stable project_id from the repo's root commit SHA. Sorted +
+ *  hashed so disjoint-history merges produce one deterministic id everywhere.
+ *  Returns null when cwd isn't a git repo or has no commits yet. */
+declare function computeGitDerivedProjectId(cwd: string): string | null;
+/** Hash the cwd path into a stable UUID. Last-resort fallback — when no git
+ *  history and no anchor file exist, this keeps capture flowing under a
+ *  per-path identity that `greprag doctor` can later consolidate. */
+declare function deterministicProjectId(cwd: string): string;
+/** True when cwd is an ephemeral session path (Cowork, tmp dirs). The
+ *  deterministic-hash fallback would mint a fresh id every session in those
+ *  paths, so we prefer the global anchor instead. */
+declare function isEphemeralCwd(cwd: string): boolean;
+/** Resolve the project anchor for `worktree` using the same 4-level cascade
+ *  the Claude Code CLI uses (packages/cli/src/project-anchor.ts). Settings
+ *  always come from the nearest repo-level file when one exists, regardless
+ *  of which identity level resolved.
+ *
+ *    1. Anchor file with explicit `project_id` → file-based identity
+ *    2. Git repo with at least one commit → root-commit-derived UUID
+ *    3. Ephemeral cwd + ~/.greprag/project.json exists → global anchor
+ *    4. Path-hash fallback (never returns null; lets capture flow until
+ *       `greprag init` runs and `greprag doctor` consolidates) */
+declare function readAnchor(worktree: string): ProjectAnchor;
+declare function extractText(parts: Part[]): string;
+interface ToolCallSummary {
+    name: string;
+    target?: string;
+    brief?: string;
+}
+/** Pull a one-line summary out of each tool call: name + a target string + an
+ *  optional brief for shell commands. Mirrors the shape the Claude Code hook
+ *  posts so server-side compaction sees identical structure regardless of
+ *  client origin. */
+declare function extractToolCalls(parts: Part[]): ToolCallSummary[];
+declare function extractFilesTouched(parts: Part[]): string[];
+type TurnProvenance = 'session-turn' | 'skill-injection' | 'continuation-summary' | 'chip-prompt';
+declare function classifyUserText(text: string): TurnProvenance;
+declare function provenanceElisionMarker(p: TurnProvenance, text: string): string;
+interface Envelope {
+    userPrompt: string;
+    agentResponse: string;
+    toolCalls: ToolCallSummary[];
+    filesTouched: string[];
+    status: 'completed' | 'errored';
+    provenance: TurnProvenance;
+}
+declare function buildEnvelope(userParts: Part[], assistantParts: Part[], errored: boolean): Envelope;
+/** True when the OS reports `pid` as a running process. Used to decide whether
+ *  a stale-lockfile check should trust the recorded PID or treat the file as
+ *  abandoned. */
+export declare function isPidAlive(pid: number): boolean;
+declare function relayLockPath(sessionId: string): string;
+declare function tryClaimRelayLock(lockPath: string): {
+    ok: true;
+    fd: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/** One row from `/v1/memory/by-period`. Mirrors hook.ts ByPeriodRow — kept
+ *  in sync intentionally so the two paths fetch the same shape. */
+interface ByPeriodRow {
+    id: string;
+    projectId: string | null;
+    projectName: string | null;
+    crystallization: string;
+    content: string;
+    wordCount: number;
+    windowStart: string | null;
+    windowEnd: string | null;
+    branch: string | null;
+    artifactType: string | null;
+    artifactId: string | null;
+    artifactUrl: string | null;
+    createdAt: string;
+}
+/** Cap on the number of hourlies surfaced in the recap body. 3 — the hook's
+ *  established value; if the user wants more they pull on demand via
+ *  `greprag memory recap`. adr: adr/memory-recap-pyramid.md. */
+declare const HOURLY_CAP = 3;
+/** Strip noise blocks from compacted content before injection.
+ *  Compactor contract: numbered items end with a trailer ("Open: ..." for
+ *  hourly, "Shipped: ..." for daily) which may span multiple lines. Trailers
+ *  always come AFTER the numbered list — so we drop from the trigger line
+ *  through end-of-string.
+ *
+ *  - daily: drop the deterministic "Shipped: <UUID-list>" trailer (useful for
+ *    /greprag deep-dive, but a wall of IDs at session start)
+ *  - hourly: drop the per-hour "Open:" block (stale snapshot of open items
+ *    that were resolved or superseded in later hours) */
+declare function stripRecapNoise(content: string, type: 'daily' | 'hourly'): string;
+/** Render an hourly window's recency: "5 hours ago", "1 hour ago",
+ *  "30 min ago", "just now". Reference is the end of the window — when the
+ *  hour wrapped up. */
+declare function fmtHoursAgo(windowEndIso: string, now: Date): string;
+/** Build the recap body — hourlies-only render. Recap is hourlies-only by
+ *  design: daily summaries used to render here (one prose paragraph per
+ *  daily window) but added ~1500 tokens to every SessionStart for marginal
+ *  value. Dailies still exist in the DB; agents who want historic context
+ *  pull on demand via `greprag memory recap` (or
+ *  `greprag memory search "<query>"` for a specific topic). Pull, don't push.
+ *
+ *  Window: 2 days back to now (50-row pull), filtered to last 24h, sliced
+ *  to HOURLY_CAP most-recent.
+ *
+ *  Returns "" when there are no recent hourlies — caller treats that as
+ *  "no recap block". Empty body is not an error; the query itself is the
+ *  only network call and any failure is swallowed (returns ""). */
+declare function buildRecapBody(apiUrl: string, apiKey: string, anchor: ProjectAnchor, now?: Date): Promise<string>;
+export { HOME, type Part, type TextPart, type ToolPart, type ToolState, type GenericPart, type ProjectAnchor, type AnchorFile, type ToolCallSummary, type Envelope, type TurnProvenance, type ByPeriodRow, formatUuid, computeGitDerivedProjectId, deterministicProjectId, isEphemeralCwd, readAnchorFile, findExistingAnchorFile, readAnchor, extractText, extractToolCalls, extractFilesTouched, classifyUserText, provenanceElisionMarker, buildEnvelope, relayLockPath, tryClaimRelayLock, stripRecapNoise, fmtHoursAgo, buildRecapBody, HOURLY_CAP, };