@gi4nks/ph 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

package/README.md

@@ -14,8 +14,15 @@
 
 ## 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
@@ -23,11 +30,6 @@ make build
 make install
 ```
 
-Or install from npm:
-```bash
-npm install -g @gi4nks/ph
-```
-
 ## Quick Start
 
 ```bash
@@ -63,6 +65,127 @@ ph config set remote-url http://server:3001  # remote sync target
 
 Environment variable `PH_REMOTE_URL` takes precedence over config.
 
+| 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) |
+
+## Remote Server Setup
+
+### Ubuntu (systemd)
+
+Install ph on your remote server:
+
+```bash
+sudo npm install -g @gi4nks/ph
+```
+
+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
+sudo systemctl daemon-reload
+sudo systemctl enable --now ph.service
+sudo ufw allow 3001/tcp   # if firewall is active
+```
+
+### 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 configuration
+
+```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
+```
+
+## How Releases Work
+
+Releases are automated via **semantic-release** on push to `main`:
+
+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
+
+The published package is signed with provenance — you can verify it with:
+
+```bash
+npm audit signatures
+```
+
 ## Storage
 
 | Item | Default Path | Description |

package/dist/cli.js

@@ -485,6 +485,17 @@ var PhDB = class {
       last_accessed: row.last_accessed
     };
   }
+  getAllPromptsByProject(project) {
+    return this.db.prepare(`
+        SELECT * FROM prompts
+        WHERE json_extract(metadata, '$.project') = ?
+        ORDER BY timestamp ASC
+      `).all(project);
+  }
+  getAllMemoriesByProject(project) {
+    const rows = this.db.prepare("SELECT * FROM memories WHERE project = ? ORDER BY created_at ASC").all(project);
+    return rows.map((r) => this.hydrateMemory(r));
+  }
   close() {
     this.db.close();
   }
@@ -886,6 +897,30 @@ async function runMCPServer() {
             },
             required: ["query"]
           }
+        },
+        {
+          name: "get_project_timeline",
+          description: "Get full chronological timeline of a project: all prompts, analysis summaries, key insights, and technical decisions in sequence.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "The project name" }
+            },
+            required: ["project"]
+          }
+        },
+        {
+          name: "check_project_knowledge",
+          description: "Before implementing a feature, check if it already exists in project history. Searches memories and prompts for previous implementations, discussions, and technical decisions related to a task.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              project: { type: "string", description: "The project name" },
+              task: { type: "string", description: "Description of the feature or task to check" },
+              limit: { type: "number", description: "Max results per search (default 5)", default: 5 }
+            },
+            required: ["project", "task"]
+          }
         }
       ]
     };
@@ -1045,6 +1080,144 @@ async function runMCPServer() {
           content: [{ type: "text", text: formatPromptList(filtered, query) }]
         };
       }
+      if (name === "get_project_timeline") {
+        const { project } = z.object({
+          project: z.string()
+        }).parse(args);
+        const prompts = db.getAllPromptsByProject(project);
+        const memories = db.getAllMemoriesByProject(project);
+        if (prompts.length === 0 && memories.length === 0) {
+          return {
+            content: [{ type: "text", text: `No history found for project "${project}".` }]
+          };
+        }
+        const events = [];
+        for (const p of prompts) {
+          let meta = {};
+          try {
+            meta = JSON.parse(p.metadata);
+          } catch {
+          }
+          events.push({
+            timestamp: p.timestamp,
+            text: [
+              `### #${p.id} \u2014 ${p.tool}`,
+              meta.role ? `Role: ${meta.role}` : "",
+              meta.title ? `Title: ${meta.title}` : "",
+              meta.tags?.length ? `Tags: ${meta.tags.join(", ")}` : "",
+              meta.summary ? `Summary: ${meta.summary}` : "",
+              `Prompt: ${p.prompt.slice(0, 500)}${p.prompt.length > 500 ? "..." : ""}`,
+              p.response ? `Response: ${p.response.slice(0, 300)}${p.response.length > 300 ? "..." : ""}` : "",
+              meta.key_insights?.length ? `Insights:
+${meta.key_insights.map((i) => `- ${i}`).join("\n")}` : ""
+            ].filter(Boolean).join("\n")
+          });
+        }
+        for (const m of memories) {
+          events.push({
+            timestamp: m.created_at,
+            text: [
+              `\u{1F4CC} Memory #${m.id}`,
+              m.prompt_ids.length > 0 ? `From prompts: #${m.prompt_ids.join(", #")}` : "",
+              m.summary ? `Summary: ${m.summary}` : "",
+              m.key_insights.length > 0 ? `Key Insights:
+${m.key_insights.map((i) => `- ${i}`).join("\n")}` : "",
+              m.technical_decisions.length > 0 ? `Technical Decisions:
+${m.technical_decisions.map((d) => `- ${d}`).join("\n")}` : ""
+            ].filter(Boolean).join("\n")
+          });
+        }
+        events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+        const header = `# Timeline: ${project}
+
+${prompts.length} prompts \xB7 ${memories.length} memory entries
+
+`;
+        const body = events.map((e) => {
+          const date = new Date(e.timestamp).toLocaleDateString("en-CA");
+          const time = new Date(e.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+          return `## ${date} ${time}
+
+${e.text}
+`;
+        }).join("---\n");
+        return {
+          content: [{ type: "text", text: header + body }]
+        };
+      }
+      if (name === "check_project_knowledge") {
+        const { project, task, limit = 5 } = z.object({
+          project: z.string(),
+          task: z.string(),
+          limit: z.number().optional()
+        }).parse(args);
+        const parts = [];
+        parts.push(`# Knowledge Check: "${task}" in ${project}
+`);
+        const memories = db.searchMemories(project, limit);
+        const relevantMemories = memories.filter(
+          (m) => m.summary.toLowerCase().includes(task.toLowerCase()) || m.key_insights.some((k) => k.toLowerCase().includes(task.toLowerCase())) || m.technical_decisions.some((d) => d.toLowerCase().includes(task.toLowerCase()))
+        );
+        if (relevantMemories.length > 0) {
+          parts.push(`## Found in Project Memories
+`);
+          for (const m of relevantMemories) {
+            parts.push(`### Memory #${m.id}`);
+            if (m.summary) parts.push(`Summary: ${m.summary}`);
+            if (m.key_insights.length > 0) {
+              parts.push(`Key Insights:
+${m.key_insights.map((i) => `- ${i}`).join("\n")}`);
+            }
+            if (m.technical_decisions.length > 0) {
+              parts.push(`Technical Decisions:
+${m.technical_decisions.map((d) => `- ${d}`).join("\n")}`);
+            }
+            parts.push("");
+          }
+        }
+        const ollamaUrl = cfg.ollamaUrl ?? "http://localhost:11434";
+        const embedModel = cfg.ollamaEmbedModel ?? "nomic-embed-text-v2-moe";
+        try {
+          const [queryVec] = await getEmbeddings([`${project}: ${task}`], ollamaUrl, embedModel, 1);
+          if (queryVec) {
+            const results = db.searchSemantic(queryVec, limit * 3);
+            const projectPrompts = results.filter((e) => {
+              try {
+                const meta = JSON.parse(e.metadata);
+                return meta.project === project;
+              } catch {
+                return false;
+              }
+            }).slice(0, limit);
+            if (projectPrompts.length > 0) {
+              parts.push(`## Related Prompts
+`);
+              for (const p of projectPrompts) {
+                let meta = {};
+                try {
+                  meta = JSON.parse(p.metadata);
+                } catch {
+                }
+                parts.push(`### #${p.id} \u2014 ${p.tool} (${new Date(p.timestamp).toLocaleDateString()})`);
+                if (meta.role) parts.push(`Role: ${meta.role}`);
+                if (meta.summary) parts.push(`Summary: ${meta.summary}`);
+                parts.push(`Prompt: ${p.prompt.slice(0, 400)}${p.prompt.length > 400 ? "..." : ""}`);
+                parts.push("");
+              }
+            }
+          }
+        } catch {
+          parts.push("(Semantic search unavailable \u2014 Ollama may not be running)\n");
+        }
+        if (relevantMemories.length === 0 && !parts.some((p) => p.startsWith("## Related Prompts"))) {
+          parts.push("No existing knowledge found for this task. This appears to be new work.\n");
+        }
+        parts.push("---\n");
+        parts.push("**Recommendation**: Review the above before implementing. If a previous implementation exists, consider reusing or adapting it.\n");
+        return {
+          content: [{ type: "text", text: parts.join("\n") }]
+        };
+      }
       throw new Error(`Unknown tool: ${name}`);
     } catch (error) {
       return {
@@ -1479,7 +1652,7 @@ import { AppHeader, THEMES } from "@gi4nks/ink";
 // package.json
 var package_default = {
   name: "@gi4nks/ph",
-  version: "2.0.1",
+  version: "1.4.0",
   description: "Transparent CLI wrapper that captures and indexes AI prompts",
   type: "module",
   license: "MIT",
@@ -5022,6 +5195,103 @@ Deleted ${deleted} prompts, freed ~${(totalToFree / 1024 / 1024).toFixed(1)} MB`
   console.log("Database vacuumed.");
 }
 
+// src/commands/timeline.ts
+async function cmdTimeline(db, cfg, args) {
+  const { flags, positional } = parseFlags(args);
+  const project = flags["project"] || positional.join(" ") || detectProject(process.cwd()).projectName;
+  if (!project) {
+    process.stderr.write("ph: could not detect project. Use --project <name> or pass a project name.\n");
+    process.exit(1);
+  }
+  const prompts = db.getAllPromptsByProject(project);
+  const memories = db.getAllMemoriesByProject(project);
+  if (prompts.length === 0 && memories.length === 0) {
+    process.stdout.write(`No history found for project "${project}".
+`);
+    return;
+  }
+  const output = [];
+  output.push(`# Timeline: ${project}
+`);
+  output.push(`**${prompts.length} prompts** \xB7 **${memories.length} memory entries**
+`);
+  const events = [
+    ...prompts.map((p) => ({ type: "prompt", timestamp: p.timestamp, prompt: p })),
+    ...memories.map((m) => ({ type: "memory", timestamp: m.created_at, memory: m }))
+  ];
+  events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  let currentDate = "";
+  for (const event of events) {
+    const date = new Date(event.timestamp).toLocaleDateString("en-CA");
+    if (date !== currentDate) {
+      currentDate = date;
+      output.push(`
+## ${date}
+`);
+    }
+    if (event.type === "prompt" && event.prompt) {
+      output.push(formatPromptEntry(event.prompt));
+    }
+    if (event.type === "memory" && event.memory) {
+      output.push(formatMemoryEntry(event.memory));
+    }
+  }
+  process.stdout.write(output.join("\n"));
+}
+function formatPromptEntry(e) {
+  let meta = {};
+  try {
+    meta = JSON.parse(e.metadata);
+  } catch {
+  }
+  const time = new Date(e.timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  const lines = [];
+  lines.push(`### #${e.id} \u2014 ${e.tool} \u2014 ${time}`);
+  if (meta.role) lines.push(`**Role**: ${meta.role}`);
+  if (meta.title) lines.push(`**Title**: ${meta.title}`);
+  if (meta.tags?.length) lines.push(`**Tags**: ${meta.tags.join(", ")}`);
+  if (meta.summary) lines.push(`**Summary**: ${meta.summary}`);
+  if (meta.relevance !== void 0) lines.push(`**Relevance**: ${meta.relevance}/10`);
+  lines.push("");
+  lines.push("**Prompt**:");
+  lines.push("```");
+  lines.push(e.prompt.slice(0, 500) + (e.prompt.length > 500 ? "\n..." : ""));
+  lines.push("```");
+  if (e.response) {
+    lines.push("");
+    lines.push("**Response**:");
+    lines.push("```");
+    lines.push(e.response.slice(0, 300) + (e.response.length > 300 ? "\n..." : ""));
+    lines.push("```");
+  }
+  if (meta.key_insights?.length) {
+    lines.push("");
+    lines.push("**Insights**:");
+    for (const i of meta.key_insights) lines.push(`- ${i}`);
+  }
+  lines.push("---\n");
+  return lines.join("\n");
+}
+function formatMemoryEntry(m) {
+  const time = new Date(m.created_at).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  const lines = [];
+  lines.push(`> \u{1F4CC} **Memory #${m.id} \u2014 ${time}**`);
+  if (m.prompt_ids.length > 0) {
+    lines.push(`> _Derived from prompts: #${m.prompt_ids.join(", #")}_`);
+  }
+  if (m.summary) lines.push(`> **Summary**: ${m.summary}`);
+  if (m.key_insights.length > 0) {
+    lines.push(`> **Insights**:`);
+    for (const i of m.key_insights) lines.push(`> - ${i}`);
+  }
+  if (m.technical_decisions.length > 0) {
+    lines.push(`> **Technical Decisions**:`);
+    for (const d of m.technical_decisions) lines.push(`> - ${d}`);
+  }
+  lines.push("---\n");
+  return lines.join("\n");
+}
+
 // src/commands/wrap.ts
 import path8 from "path";
 import os9 from "os";
@@ -5190,6 +5460,7 @@ USAGE:
   ph analyze [--limit n] [--force] [--prune] [--dry-run]  Analyze prompts with LLM
   ph mcp                                Start MCP server (Stdio)
   ph server [--port 3001]               Start HTTP REST server for remote sync
+  ph timeline [project]                 Show full project history with prompts and memories
   ph remote push|pull|status            Sync prompts with remote ph server
   ph cleanup [--dry-run] [--min-length N] [--min-score N]  Remove useless prompts
   ph cleanup-reusability [--dry-run] [--threshold 0.7] [--force]  Cleanup based on reusability
@@ -5508,6 +5779,12 @@ async function main() {
       await cmdChat(dbPath, cfg, cmdArgs);
       break;
     }
+    case "timeline": {
+      const db = new PhDB(dbPath);
+      await cmdTimeline(db, cfg, cmdArgs);
+      db.close();
+      break;
+    }
     case "ollama-models": {
       const ollamaUrl = cfg.ollamaUrl ?? "http://localhost:11434";
       try {