@gi4nks/ph 1.3.2 → 1.5.0

package/docs/hooks.md

@@ -1,83 +1,45 @@
-# ph Implementation Status — Complete Report
+# ph Hook System — Status Report
 
-    ✅ Completed
+## Completed Hooks
 
-    ┌───────────────────────────────────────────────────────────┬────────────────────────────┬────────┐
-    │                          Feature                          │            File            │ Status │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Git Context Snapshot                                      │ src/runner/git-context.ts  │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Background Analysis                                       │ src/background/analyzer.ts │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Work Sessions (ph sessions)                               │ src/sessions/index.ts      │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Prompt Rerunning (TUI r)                                  │ src/ui/BrowseApp.tsx       │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Ollama embeddings (nomic-embed-text-v2-moe)               │ src/embedding/index.ts     │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Response column in DB + FTS5 migration                    │ src/db/index.ts            │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ ph log command (flag + stdin JSON)                        │ src/cli.ts                 │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ TUI detail view with response                             │ src/ui/BrowseApp.tsx       │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Export markdown with response + git context               │ src/cli.ts                 │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Gemini importer response capture                          │ src/importer/gemini.ts     │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Claude importer from transcript files                     │ src/importer/claude.ts     │ ✅     │
-    ├───────────────────────────────────────────────────────────┼────────────────────────────┼────────┤
-    │ Documentation (README, CLAUDE.md, GEMINI.md, ROADMAP.md)  │ various                    │ ✅     │
-    └───────────────────────────────────────────────────────────┴────────────────────────────┴────────┘
+| Tool | Type | File | Status |
+|------|------|------|--------|
+| Claude Code | Shell script (Stop hook) | `hooks/claude/ph-hook.sh` | ✅ |
+| Gemini CLI | Shell script (AfterAgent hook) | `hooks/gemini/ph-hook.sh` | ✅ |
+| OpenCode | JS/TS Plugin | `hooks/opencode/ph-plugin.ts` | ✅ |
 
-    🔄 In Progress (background agent)
+## How Hooks Work
 
-    - Claude Code hook (~/.claude/settings.json + ~/.claude/ph-hook.sh): Stop hook that calls ph log after each response
-    - Gemini CLI skill/hook: similar integration for the Gemini CLI
+Each supported AI CLI tool exposes a native hook mechanism:
 
-    📋 Hook Architecture (being implemented)
+- **Claude Code** — `Stop` hook, triggered after each agent session completes.
+  Reads the JSONL transcript, extracts last user prompt + assistant response, pipes to `ph log`.
 
-    Claude finishes a response
-      → Stop hook in settings.json
-      → ~/.claude/ph-hook.sh receives JSON on stdin
-      → jq extracts last user prompt + assistant response text
-      → ph log --tool claude --prompt "..." --response "..."
-      → record inserted into DB with background analysis
+- **Gemini CLI** — `AfterAgent` hook, triggered after each agent turn.
+  Receives JSON with `prompt` and `prompt_response` fields directly, pipes to `ph log`.
 
-    ⏳ Still To Do (after hooks)
+- **OpenCode** — Plugin system with `chat.message` + `experimental.text.complete` hooks.
+  Intercepts messages, pairs user prompts with streamed assistant responses, pipes to `ph log`.
 
-    - Claude importer from history.jsonl: already replaced by the new transcript importer — ✅ covered
-    - End-to-end testing of hooks in a real session
-    - ph import claude update in cli.ts: verify that cmdImport calls the new importer correctly (the file was rewritten but the caller in cli.ts might still reference history.jsonl in the output log)
+All hooks run in the background (`& + disown` for shell scripts; Promise fire-and-forget for the plugin).
+Never block the AI tool from exiting.
 
-    Final Data Flow
+## Data Flow
 
-    Gemini CLI / Claude Code
-        ↓ (automatic hook after each exchange)
-    ph log (stdin JSON)
-        ↓
-    SQLite (~/.prompt_history.db)
-        ↓
-    background analysis (Ollama gemma3:1b)
-        ↓
-    metadata: project, language, role, tags, relevance
-        ↓
-    ph browse / ph search / ph sessions
+```
+AI CLI Tool
+    ↓ (automatic hook after each exchange)
+ph log (stdin JSON)
+    ↓
+SQLite (~/.prompt_history.db)
+    ↓
+background analysis (Ollama)
+    ↓
+metadata: project, language, role, tags, relevance
+    ↓
+ph browse / ph search / ph sessions
+```
 
-    The main agent is completing the hook part — once finished you will have the completely automatic system without having to use ph as a wrapper.
+## Installation
 
-
-    ⏺ Everything is set. Summary of what has been done:
-
-  ---
-  Claude Code — Stop hook registered in ~/.claude/settings.json:
-  - Reads the session's JSONL transcript
-  - Extracts the last user prompt (those with promptId, not tool-result) and the last assistant response
-  - Calls ph log in the background (disown) → never blocks Claude
-
-  Gemini CLI — AfterAgent hook registered in ~/.gemini/settings.json:
-  - Directly receives the JSON payload containing prompt and prompt_response from Gemini CLI
-  - Extracts the user prompt and the assistant response
-  - Calls ph log in the background → never blocks Gemini
-
-  From this moment, every exchange in Claude Code or Gemini CLI is automatically saved in ph without the need to use it as a wrapper.
+See `docs/ph-manual.md` for detailed installation instructions per tool.

package/docs/ph-manual.md

@@ -165,16 +165,94 @@ ln -sf /path/to/ph/hooks/gemini/ph-hook.sh ~/.gemini/ph-hook.sh
 
 ---
 
+### OpenCode Hook
+
+OpenCode uses a JavaScript/TypeScript **plugin** system (rather than shell scripts). The `ph` integration is a plugin that hooks into OpenCode's message lifecycle to capture prompts and responses.
+
+#### How the plugin captures data
+
+The plugin registers two hooks inside OpenCode's runtime:
+
+| Hook | Purpose |
+|------|---------|
+| `chat.message` | Intercepts every message in the conversation. User messages become prompts; assistant messages become response snapshots. |
+| `experimental.text.complete` | Fires after streaming completes. Replaces the snapshot with the full, final response text. |
+
+**Data flow:**
+
+```
+User types prompt
+  → chat.message fires (role: user)
+  → plugin stores the prompt text + metadata (agent, model, workdir)
+
+Assistant streams response
+  → experimental.text.complete fires for each text part
+  → plugin accumulates the complete response text
+
+Next user message or session end
+  → plugin pairs prompt + accumulated response
+  → pipes {"tool":"opencode","prompt":"...","response":"..."} to ph log
+  → runs in background — never blocks OpenCode
+```
+
+#### Hook installation — OpenCode
+
+OpenCode loads plugins from two directories:
+- `~/.config/opencode/plugins/` — global (all projects)
+- `.opencode/plugins/` — per-project
+
+**Option A: Quick install (global)**
+
+```bash
+# Link the plugin into OpenCode's global plugin directory
+mkdir -p ~/.config/opencode/plugins
+ln -sf /path/to/ph/hooks/opencode/ph-plugin.ts ~/.config/opencode/plugins/ph-plugin.ts
+```
+
+Or use the install script:
+
+```bash
+./hooks/opencode/install.sh              # global (default)
+./hooks/opencode/install.sh --project    # current project only
+```
+
+**Option B: Manual copy**
+
+```bash
+cp hooks/opencode/ph-plugin.ts ~/.config/opencode/plugins/
+```
+
+The plugin is automatically loaded on the next OpenCode startup. No config changes needed — Bun handles TypeScript natively.
+
+**Verify:**
+
+```bash
+# Start OpenCode — the plugin loads silently
+opencode
+
+# Check that prompts are being captured
+ph search --tool opencode --limit 3
+```
+
+**Uninstall:**
+
+```bash
+rm ~/.config/opencode/plugins/ph-plugin.ts
+```
+
+---
+
 ### Hook Comparison
 
-| Aspect | Claude Code | Gemini CLI |
-|--------|------------|------------|
-| Hook name | `Stop` | `AfterAgent` |
-| Data delivery | `transcript_path` (JSONL file) | Direct JSON on stdin |
-| Prompt extraction | Parse JSONL with `jq` slurp | `jq .prompt` field |
-| Response extraction | Last assistant text block | `jq .prompt_response` field |
-| Async support | Yes (`async: true` in config) | Yes (`& + disown` in script) |
-| Blocks AI exit? | Never (exits `0`) | Never (exits `0`) |
+| Aspect | Claude Code | Gemini CLI | OpenCode |
+|--------|------------|------------|----------|
+| Hook mechanism | `Stop` shell script | `AfterAgent` shell script | JS/TS plugin |
+| Data delivery | `transcript_path` (JSONL) | Direct JSON on stdin | Event hooks (`chat.message`, `experimental.text.complete`) |
+| Prompt extraction | Parse JSONL with `jq` slurp | `jq .prompt` | `message.role === 'user'` parts |
+| Response extraction | Last assistant text block | `jq .prompt_response` | `experimental.text.complete` accumulation |
+| Async support | Yes (`async: true`) | Yes (`& + disown`) | Yes (Promise fire-and-forget) |
+| Blocks AI exit? | Never | Never | Never |
+| Install method | Symlink + settings.json | Symlink + settings.json | Copy plugin file to `plugins/` dir |
 
 ---
 
@@ -278,6 +356,166 @@ ph treats your prompt history as a first-class artifact: searchable, annotated,
 
 ---
 
+---
+
+## 7. Remote Server Setup
+
+ph can act as a central sync hub for prompt history across multiple machines.
+
+### Server Installation
+
+```bash
+# Install globally
+sudo npm install -g @gi4nks/ph
+
+# Verify
+ph --help
+```
+
+### Ubuntu (systemd service)
+
+Create `/etc/systemd/system/ph.service`:
+
+```ini
+[Unit]
+Description=ph remote sync server
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=<path-to-ph> server --port 3001 --host 0.0.0.0
+Restart=always
+RestartSec=5
+User=<your-user>
+Environment=NODE_ENV=production
+StandardOutput=append:/var/log/ph-server.log
+StandardError=append:/var/log/ph-server.log
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Replace `<path-to-ph>` with the output of `which ph` on the server, and `<your-user>` with the user running the service.
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now ph.service
+sudo systemctl status ph.service
+sudo ufw allow 3001/tcp   # if firewall is enabled
+```
+
+### macOS (launchd)
+
+Create `~/Library/LaunchAgents/com.gi4nks.ph.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.gi4nks.ph</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/ph</string>
+        <string>server</string>
+        <string>--port</string>
+        <string>3001</string>
+        <string>--host</string>
+        <string>0.0.0.0</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/ph-server.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/ph-server.err</string>
+</dict>
+</plist>
+```
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.gi4nks.ph.plist
+```
+
+### Client Setup
+
+```bash
+# Configure remote server URL
+ph config set remote-url http://<server-ip>:3001
+# Or via env var (takes precedence)
+export PH_REMOTE_URL=http://<server-ip>:3001
+
+# Sync commands
+ph remote push    # send unsynced local prompts to server
+ph remote pull    # fetch remote prompts since last pull
+ph remote status  # show sync state
+```
+
+After `ph remote-url` is configured, every `ph log` automatically does a background push to the server (fire-and-forget, never blocks).
+
+### Logs
+
+```bash
+# systemd
+sudo journalctl -u ph.service -f
+
+# launchd
+cat /tmp/ph-server.log
+```
+
+---
+
+## 8. Release Process
+
+Releases are fully automated via **semantic-release** using conventional commits.
+
+### How it works
+
+1. All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+   ```
+   feat: add new feature          → minor release (1.x.0)
+   fix: resolve bug               → patch release (1.0.x)
+   chore: bump deps               → no release
+   BREAKING CHANGE: ...           → major release (x.0.0)
+   ```
+
+2. Push to `main` triggers GitHub Actions workflow `.github/workflows/release.yml`
+
+3. The workflow runs:
+   - `actions/checkout@v4` with full git history (`fetch-depth: 0`)
+   - `actions/setup-node@v4` with Node 22
+   - `npm ci` — clean install
+   - `npm run build` — tsup bundle
+   - `npx semantic-release` — analyzes commits, bumps version, updates CHANGELOG.md, creates git tag, publishes to npm
+
+### npm publish details
+
+- **OIDC Trusted Publishing**: Package is signed with provenance attestation via GitHub Actions OIDC token
+- **Publisher identity**: `GitHub Actions <npm-oidc-no-reply@github.com>`
+- **Registry**: `https://registry.npmjs.org/`
+- **Access**: public
+
+### Verify provenance
+
+```bash
+npm audit signatures
+```
+
+### Manual release (emergency)
+
+Create a tag manually and push:
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+---
+
 ## Repository
 
 [https://github.com/gi4nks/ph](https://github.com/gi4nks/ph)

package/hooks/opencode/install.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# install.sh — Install the ph OpenCode plugin
+#
+# Usage: ./install.sh [--global|--project]
+#   --global   Install in ~/.config/opencode/plugins/ (default)
+#   --project  Install in .opencode/plugins/ (current directory)
+
+set -euo pipefail
+
+PLUGIN_SOURCE="$(cd "$(dirname "$0")" && pwd)/ph-plugin.ts"
+MODE="${1:---global}"
+
+case "$MODE" in
+  --global)
+    TARGET_DIR="$HOME/.config/opencode/plugins"
+    ;;
+  --project)
+    TARGET_DIR=".opencode/plugins"
+    mkdir -p "$TARGET_DIR"
+    TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+    ;;
+  *)
+    echo "Usage: $0 [--global|--project]"
+    exit 1
+    ;;
+esac
+
+mkdir -p "$TARGET_DIR"
+
+TARGET_FILE="$TARGET_DIR/ph-plugin.ts"
+
+if [ -f "$TARGET_FILE" ]; then
+  echo "Updating existing plugin at $TARGET_FILE"
+else
+  echo "Installing plugin to $TARGET_FILE"
+fi
+
+cp "$PLUGIN_SOURCE" "$TARGET_FILE"
+echo "✅ ph OpenCode plugin installed at $TARGET_FILE"
+
+echo ""
+echo "Plugin will be loaded automatically on next OpenCode startup."
+echo "To verify: opencode config will show it in the plugin list."
+echo ""
+echo "To uninstall: rm $TARGET_FILE"

package/hooks/opencode/ph-plugin.ts

@@ -0,0 +1,101 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+interface PendingPrompt {
+  text: string;
+  timestamp: string;
+  agent?: string;
+  model?: string;
+}
+
+/** Per-session state for pairing user prompts with assistant responses */
+const sessions = new Map<string, {
+  prompt: PendingPrompt | null;
+  response: string;
+}>();
+
+function textFromParts(parts: { type?: string; text?: string }[]): string {
+  return parts
+    .filter(p => p.type === 'text')
+    .map(p => p.text || '')
+    .join('')
+    .trim();
+}
+
+async function callPhLog(
+  $: any,
+  prompt: PendingPrompt,
+  response: string,
+  workdir: string,
+): Promise<void> {
+  if (!prompt.text || !response) return;
+
+  const payload: Record<string, unknown> = {
+    tool: 'opencode',
+    prompt: prompt.text,
+    response,
+    workdir,
+  };
+
+  const meta: Record<string, unknown> = { source: 'plugin' };
+  if (prompt.agent) meta.agent = prompt.agent;
+  if (prompt.model) meta.model = prompt.model;
+  payload.metadata = JSON.stringify(meta);
+
+  const json = JSON.stringify(payload);
+  const _ = $`echo ${json} | ph log > /dev/null 2>&1`;
+  _.then(() => {}).catch(() => {});
+}
+
+export const PhOpenCodePlugin: Plugin = async ({ directory, $ }) => {
+  return {
+    "chat.message": async (input, output) => {
+      const { sessionID, agent, model } = input;
+      const { message, parts } = output;
+      const role = (message as Record<string, unknown>).role;
+
+      if (role === 'user') {
+        const existing = sessions.get(sessionID);
+        const prompt = existing?.prompt;
+        const response = existing?.response;
+
+        // Log previous turn if we have both parts
+        if (prompt && response) {
+          await callPhLog($, prompt, response, directory);
+        }
+
+        // Store new prompt, reset response
+        const text = textFromParts(parts);
+        if (text) {
+          sessions.set(sessionID, {
+            prompt: {
+              text,
+              timestamp: new Date().toISOString(),
+              agent,
+              model: model ? `${model.providerID}/${model.modelID}` : undefined,
+            },
+            response: '',
+          });
+        }
+      } else if (role === 'assistant') {
+        const existing = sessions.get(sessionID);
+        if (!existing?.prompt) return;
+
+        // Snapshot whatever text is available (non-streaming or initial frame)
+        const text = textFromParts(parts);
+        if (text) {
+          sessions.set(sessionID, { ...existing, response: text });
+        }
+      }
+    },
+
+    "experimental.text.complete": async (input, output) => {
+      const session = sessions.get(input.sessionID);
+      if (!session?.prompt) return;
+
+      // Replace with complete text (handles streaming: this fires after streaming ends)
+      if (output.text) {
+        sessions.set(input.sessionID, { ...session, response: output.text });
+      }
+    },
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gi4nks/ph",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Transparent CLI wrapper that captures and indexes AI prompts",
   "type": "module",
   "license": "MIT",
@@ -19,25 +19,55 @@
     "type": "git",
     "url": "git+https://github.com/gi4nks/ph.git"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "CHANGELOG.md"
+          ],
+          "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "test": "vitest run",
-    "lint": "eslint src",
-    "release:patch": "standard-version --release-as patch",
-    "release:minor": "standard-version --release-as minor",
-    "release:major": "standard-version --release-as major"
+    "lint": "eslint src"
   },
   "dependencies": {
     "@gi4nks/ink": "^1.5.0",
     "@lydell/node-pty": "^1.2.0-beta.3",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.8.0",
     "ink": "^6.8.0",
     "react": "^19.2.4",
+    "sqlite-vec": "^0.1.9",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/npm": "^13.1.5",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
@@ -46,6 +76,7 @@
     "eslint": "^9.39.4",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
+    "semantic-release": "^25.0.3",
     "standard-version": "^9.5.0",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",