@gi4nks/ph 1.3.2 → 1.5.0

package/CHANGELOG.md

@@ -1,20 +1,55 @@
+# [1.5.0](https://github.com/gi4nks/ph/compare/v1.4.0...v1.5.0) (2026-05-16)
+
+
+### Features
+
+* add timeline CLI command and two new MCP tools (get_project_timeline, check_project_knowledge) ([12d667c](https://github.com/gi4nks/ph/commit/12d667c69e35f4aff31a2e13018a00949587fb55))
+
+# [1.4.0](https://github.com/gi4nks/ph/compare/v1.3.2...v1.4.0) (2026-05-16)
+
+
+### Bug Fixes
+
+* remove provenance from publishConfig, restore scope+npm ci in release workflow ([734df6c](https://github.com/gi4nks/ph/commit/734df6cf53b15ff661ad95c530a897a802571ecc))
+
+
+### Features
+
+* v2.0.0 — HTTP server, remote sync, MCP prompt tools, OpenCode plugin ([a9c0b03](https://github.com/gi4nks/ph/commit/a9c0b032b91275edfb8948c7d136d93eb734fa12))
+
 # Changelog
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-### [1.3.2](https://github.com/gi4nks/ph/compare/v1.3.1...v1.3.2) (2026-04-17)
-
-### [1.3.1](https://github.com/gi4nks/ph/compare/v1.3.0...v1.3.1) (2026-04-13)
+### [2.0.1](https://github.com/gi4nks/ph/compare/v1.3.2...v2.0.1) (2026-05-16)
 
 
 ### Features
 
-* **ui:** major redesign of browse view with split-pane and topic extraction ([53d9008](https://github.com/gi4nks/ph/commit/53d90087709ffda5913fc3026b6554f0aae4ddf4))
+* v2.0.0 — HTTP server, remote sync, MCP prompt tools, OpenCode plugin ([a9c0b03](https://github.com/gi4nks/ph/commit/a9c0b032b91275edfb8948c7d136d93eb734fa12))
 
 
 ### Bug Fixes
 
-* resolve npm publish auth error and bin path warning ([5dfe49a](https://github.com/gi4nks/ph/commit/5dfe49ab6c169ec2eed8c16fe73139381efdf0ed))
+* remove provenance from publishConfig, restore scope+npm ci in release workflow ([734df6c](https://github.com/gi4nks/ph/commit/734df6cf53b15ff661ad95c530a897a802571ecc))
+
+## [2.0.0](https://github.com/gi4nks/ph/compare/v1.3.2...v2.0.0) (2026-05-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cli:** major refactor of cli.ts into command modules. All commands keep the same interface but the internal architecture changed significantly.
+
+### Features
+
+* **server:** `ph server` — HTTP REST server (zero deps, Node http module). Endpoints: /health, /api/prompts/search, /api/prompts/by-id, /api/prompts/semantic, /api/sync/push, /api/sync/pull, /api/memories/search, /api/memories/summary, /api/stats
+* **remote:** `ph remote push|pull|status` — sync prompts across laptops. Dedup via sha256(tool|prompt|response). Background push on each `ph log`.
+* **mcp:** `search_prompts`, `get_prompt`, `search_prompts_semantic` tools for querying raw prompt history via MCP
+* **config:** `remote-url`, `remote-api-key` config keys + `PH_REMOTE_URL` env var support
+* **opencode:** native importer (`ph import opencode`) + real-time plugin hook
+
+### (prima di continuare con il commit fammi vedere se ti piace la situazione ) vabene?  
+
 
 ## [1.3.0](https://github.com/gi4nks/ph/compare/v1.2.0...v1.3.0) (2026-04-12)
 

package/README.md

@@ -1,146 +1,227 @@
 # ph — Prompt History & Analysis Tool
 
-`ph` is a transparent wrapper for AI CLI tools (such as Gemini CLI, Claude CLI, etc.). It captures every prompt into a local SQLite database, providing full-text and semantic search, automatic background analysis, and Git context snapshots.
+`ph` is a transparent observability layer for AI CLI tools. It captures every prompt+response into a local SQLite database with full-text and semantic search, automatic LLM analysis, interactive TUI browser, MCP server, and optional remote sync for cross-laptop memory sharing.
 
 ## Key Features
 
-- 📥 **Automatic Capture**: Saves prompts, output (if non-interactive), and metadata.
-- 🌳 **Git Context**: Saves branch, modified files, and diff at the time of the prompt.
-- 🔍 **Advanced Search**: Textual search (FTS5) and semantic search (vectorial).
-- 🧠 **Background Analysis**: Automatic prompt analysis (role, tags, relevance) via Ollama or Gemini.
-- 🖥️ **Interactive TUI**: Interactive browser (`ph browse`) to manage history.
+- 📥 **Automatic Capture**: Wrapper mode (`ph claude "..."`), hook mode (Claude/Gemini/OpenCode), or direct (`ph log`).
+- 🔍 **Advanced Search**: FTS5 full-text search and sqlite-vec semantic search with rich filters (tool, project, role, tag, date range).
+- 🧠 **Background Analysis**: Automatic prompt classification (role, tags, relevance) via Ollama or Gemini — builds project-level memories.
+- 🖥️ **Interactive TUI**: Full-screen browser with filter panel, preview pane, project memory viewer, and session grouping.
+- 🔌 **MCP Server**: Exposes prompt history and project knowledge as MCP tools (`search_prompts`, `get_prompt`, `search_project_memory`, etc.) — usable by any MCP client including OpenCode.
+- 🌐 **HTTP Server & Remote Sync**: `ph server` starts a REST API. `ph remote push|pull` syncs prompts across laptops. Background push after each `ph log`.
+- 🔗 **OpenCode Plugin**: Native plugin for real-time capture via OpenCode hooks.
 
 ## Installation
 
+### From npm
+
+```bash
+npm install -g @gi4nks/ph
+```
+
+### From source
+
 ```bash
-# Clone and local build
 git clone git@github.com:gi4nks/ph.git
 cd ph
 npm install
 make build
-make install # Installs the global 'ph' link
+make install
+```
+
+## Quick Start
+
+```bash
+# Wrap an AI tool
+ph claude "explain goroutines"
+
+# Search history
+ph search "goroutines"
+ph search --semantic "concurrency patterns"
+ph search --tool claude --role debug --since 2026-01-01
+
+# Browse with TUI
+ph browse
+
+# Start HTTP server for remote sync
+ph server --port 3001
+
+# Sync with another machine
+export PH_REMOTE_URL=http://my-server:3001
+ph remote push   # push local prompts to server
+ph remote pull   # pull remote prompts into local DB
 ```
 
 ## Configuration
 
-The tool uses a configuration file at `~/.ph_config.json`.
+Config file at `~/.ph_config.json`:
 
 ```bash
-ph config set gemini-api-key "YOUR_KEY"
-ph config set analyze-provider gemini # or 'ollama' (default)
-ph config set background-analysis true  # Enable auto-analysis
+ph config set analyze-provider ollama    # or 'gemini' (default: ollama)
+ph config set background-analysis true    # auto-analyze after each log
+ph config set remote-url http://server:3001  # remote sync target
 ```
 
-## Storage & Architecture
+Environment variable `PH_REMOTE_URL` takes precedence over config.
 
-`ph` stores its data locally to ensure privacy and fast access.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `analyze-provider` | `ollama` | LLM provider for analysis (`ollama` or `gemini`) |
+| `gemini-api-key` | — | API key for Gemini provider |
+| `ollama-url` | `http://localhost:11434` | Ollama server URL |
+| `ollama-model` | `llama3.1:latest` | Ollama model for analysis |
+| `ollama-embed-model` | `nomic-embed-text-v2-moe` | Ollama model for embeddings |
+| `background-analysis` | `false` | Auto-analyze after each `ph log` |
+| `remote-url` | — | HTTP URL of remote ph server |
+| `remote-api-key` | — | Optional API key for remote server |
+| `db-path` | `~/.prompt_history.db` | Custom database path |
+| `filter-min-length` | `15` | Ignore prompts shorter than N chars |
+| `filter-min-relevance` | `3` | Minimum relevance score (0–10) |
 
-### Files and Locations
+## Remote Server Setup
 
-| Item | Default Path | Description |
-|------|--------------|-------------|
-| **Database** | `~/.prompt_history.db` | SQLite database with FTS5 and vector embeddings. |
-| **Config** | `~/.ph_config.json` | JSON configuration file (stored with `0o600` permissions). |
+### Ubuntu (systemd)
 
-### Customizing the Database Path
-You can move your database to a different location (e.g., an external drive or a cloud-synced folder):
+Install ph on your remote server:
 
 ```bash
-ph config set db-path "/path/to/your/custom.db"
+sudo npm install -g @gi4nks/ph
 ```
 
-### Database Maintenance
-As you use `ph`, the database might grow due to Git diffs and metadata. Use these commands to keep it lean:
+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
+```
+
+Find `<path-to-ph>` with `which ph` on the server. Start the service:
 
 ```bash
-# Remove prompts shorter than 20 chars or older than 30 days
-ph cleanup --min-length 20 --days 30
+sudo systemctl daemon-reload
+sudo systemctl enable --now ph.service
+sudo ufw allow 3001/tcp   # if firewall is active
+```
 
-# Compact the database file to reclaim disk space
-ph vacuum
+### 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>
+```
 
-# Run a dry-run to see what would be deleted
-ph cleanup --dry-run --days 60
+```bash
+launchctl load ~/Library/LaunchAgents/com.gi4nks.ph.plist
 ```
 
-### Database Security
-The database uses **WAL (Write-Ahead Logging)** mode, which allows concurrent read and write operations. This is crucial for the **Background Analysis** system to work without locking your CLI session.
+### Client configuration
 
-## Hooks (Integration with AI CLI)
+```bash
+# Set remote URL (config or env)
+ph config set remote-url http://your-server:3001
+# export PH_REMOTE_URL=http://your-server:3001
+
+# Sync
+ph remote push   # send local prompts to server
+ph remote pull   # fetch server prompts locally
+ph remote status # check sync state
+```
 
-Hooks allow `ph` to automatically capture prompts and responses from other AI CLI tools by integrating directly with their native hook systems.
+## How Releases Work
 
-### How they work
-Hooks are located in the `hooks/` folder. Instead of wrapping the execution, they act as post-action handlers (e.g., `AfterAgent` in Gemini CLI or `Stop` in Claude Code) that send the prompt and response to `ph log` in the background.
+Releases are automated via **semantic-release** on push to `main`:
 
-### Hook Installation
+1. Push conventional commits (`feat:`, `fix:`, `chore:`, etc.) to `main`
+2. GitHub Actions runs `npx semantic-release`
+3. Semantic-release analyzes commits since last release
+4. Bumps version automatically (major/minor/patch)
+5. Generates `CHANGELOG.md`
+6. Creates a git tag
+7. Publishes to npm with **OIDC trusted publishing** (provenance attestation)
+8. Creates a GitHub Release
 
-#### Gemini CLI
-1. Link the hook script to your `.gemini` folder:
-   ```bash
-   ln -sf /path/to/ph/hooks/gemini/ph-hook.sh ~/.gemini/ph-hook.sh
-   ```
-2. Register the hook in `~/.gemini/settings.json`:
-   ```json
-   {
-     "hooks": { "AfterAgent": [ { "hooks": [ { "type": "command", "command": "~/.gemini/ph-hook.sh" } ] } ] }
-   }
-   ```
+The published package is signed with provenance — you can verify it with:
 
-#### Claude Code
-1. Link the hook script to your `.claude` folder:
-   ```bash
-   ln -sf /path/to/ph/hooks/claude/ph-hook.sh ~/.claude/ph-hook.sh
-   ```
-2. Register the hook in `~/.claude/settings.json`:
-   ```json
-   {
-     "hooks": { "Stop": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "~/.claude/ph-hook.sh", "async": true } ] } ] }
-   }
-   ```
+```bash
+npm audit signatures
+```
 
-The hooks will automatically send every interaction to `ph` without requiring any shell aliases or manual capture commands.
+## Storage
 
-## Usage
+| Item | Default Path | Description |
+|------|--------------|-------------|
+| Database | `~/.prompt_history.db` | SQLite with FTS5 + sqlite-vec |
+| Config | `~/.ph_config.json` | JSON with 0o600 permissions |
 
-### Search
-```bash
-ph search "how to refactor"        # Textual search
-ph search --semantic "refactoring" # Semantic search
-```
+## Architecture
 
-### TUI Browser
-```bash
-ph browse
 ```
-*Hotkeys:* `f` (filters), `e` (edit metadata), `r` (rerun prompt), `y` (copy), `x` (delete).
+Capture modes: wrapper → hook → direct → OpenCode plugin
+     |
+     v
+Local SQLite (FTS5 + vec0 + memories)
+     |
+     ├── MCP server (stdio)  →  OpenCode / any MCP client
+     ├── HTTP server (REST)  →  remote ph instances
+     └── Background analysis →  memories table (append-only per project)
+```
 
-## Releases and Versioning
+## Hooks
 
-The project follows **Semantic Versioning (SemVer)** and uses [Conventional Commits](https://www.conventionalcommits.org/). Releases are managed via `standard-version`.
+Hooks in `hooks/` integrate with AI CLI tools natively:
 
-### Release Commands
-To create a new version (updates `package.json`, generates `CHANGELOG.md`, and creates a Git tag):
+- **Claude Code**: `hooks/claude/ph-hook.sh` — Stop hook
+- **Gemini CLI**: `hooks/gemini/ph-hook.sh` — AfterAgent hook
+- **OpenCode**: `hooks/opencode/ph-plugin.ts` — native plugin (captures streaming responses)
 
-```bash
-make release-patch  # Increments: 0.1.0 -> 0.1.1 (fixes and small changes)
-make release-minor  # Increments: 0.1.1 -> 0.2.0 (new compatible features)
-make release-major  # Increments: 0.2.0 -> 1.0.0 (breaking changes)
-```
+## Development
 
-After the release, remember to push the tags to trigger the **GitHub Action** for publication:
 ```bash
-git push --follow-tags origin main
+make build    # tsup build
+make test     # vitest
+make lint     # eslint
 ```
-The package will be automatically built and published to [npmjs.org](https://www.npmjs.com/package/@gi4nks/ph).
 
-### Installation via npm
-Install globally with:
-```bash
-npm install -g @gi4nks/ph
-```
+## License
 
-## Export
-```bash
-ph export --format md --limit 5 > prompts.md
-```
+MIT