@ulpi/cli 0.1.0 → 0.1.1

package/README.md

@@ -40,20 +40,19 @@ cd your-project
 ulpi init
 ```
 
-That's it. ULPI detects your stack — language, framework, package manager, test runner, linter — and generates a tailored rules configuration. Hooks are installed into Claude Code automatically.
+ULPI detects your stack — language, framework, package manager, test runner, linter — and generates a tailored rules configuration. Hooks are installed into Claude Code automatically.
 
 Next time you start a Claude Code session, ULPI is active.
 
 ### Try it without installing
 
 ```bash
-cd your-project
 npx @ulpi/cli init
 ```
 
 ---
 
-## What You Get
+## Features
 
 ### Automatic Permissions
 
@@ -66,6 +65,12 @@ permissions:
     matcher: Bash
     command_pattern: "npm test|pnpm test|yarn test"
     decision: allow
+
+  auto-approve-git-read:
+    trigger: PermissionRequest
+    matcher: Bash
+    command_pattern: "git (status|log|diff|branch)"
+    decision: allow
 ```
 
 ### Guardrails
@@ -83,33 +88,140 @@ preconditions:
     matcher: "Write|Edit"
     message: "Read the file before editing it."
     requires_read: true
+
+  test-before-commit:
+    trigger: PreToolUse
+    matcher: Bash
+    command_pattern: "git commit"
+    message: "Run tests before committing."
+    requires:
+      tests_run: true
+```
+
+### Pipelines
+
+Chain multiple steps into automated workflows that run after tool execution.
+
+```yaml
+pipelines:
+  pre-commit-checks:
+    trigger: PostToolUse
+    matcher: Bash
+    command_pattern: "git commit"
+    steps:
+      - name: build
+        command: "pnpm -r build"
+      - name: test
+        command: "pnpm test"
+    block_on_failure: true
 ```
 
 ### Session Tracking
 
-ULPI knows what happened in your session — which files were read, which were written, which commands ran. Rules can use this context to make smarter decisions.
+ULPI tracks every action in real time — files read and written, commands executed, rules enforced, tests passed or failed. Session state powers smarter rule evaluation and feeds into history, memory, and the web dashboard.
+
+Each session follows a state machine (`idle` -> `active` -> `active_committed` -> `ended`) and logs up to 10,000 events as an append-only JSONL file.
 
 ### Web Dashboard
 
-A full web UI for managing rules, viewing live sessions, reviewing AI-generated plans, and browsing session history.
+A full web UI for managing rules, monitoring live sessions, reviewing plans and code, and browsing history.
 
 ```bash
 ulpi ui
 ```
 
-<!-- TODO: Add screenshot -->
+The dashboard shows:
+
+- **Guards** — Active rule counts, enforcement stats, rule breakdown by type
+- **Session** — Live session state with real-time event timeline (WebSocket)
+- **Review** — Pending plan and code reviews
+- **CodeMap** — Index status, file and chunk counts
+- **Memory** — Memory count, classified sessions, importance breakdown
+- **History** — Captured entries with AI enrichment status
+- **Skills** — Available bundled, project, and global skills
+- **Responses** — Notification channel configuration
 
 ### Plan & Code Review
 
-Review AI-generated plans and code changes in a dedicated UI before they execute. Annotate, approve, or reject with feedback that gets sent back to the agent.
+Review AI-generated plans and code changes in a browser-based UI before they execute.
+
+**Plan review** intercepts `ExitPlanMode` — the plan is parsed into sections, scored across 8 quality dimensions (test coverage, error handling, rollback strategy, scope clarity, and more), and presented for your review. You can annotate sections, assign priorities and risk levels, add per-section instructions, or make inline edits. Approve or deny with feedback that goes directly back to the agent.
+
+**Code review** intercepts `git commit` — the staged diff and commit message are shown for review with line-level annotation tools.
+
+Both flows use long-poll HTTP transport with a 10-minute timeout. If the server isn't running, the agent continues normally (fail-open).
 
-### Semantic Code Search
+### Semantic Code Search (CodeMap)
 
-ULPI indexes your codebase and exposes it as MCP tools that Claude Code can use for smarter, context-aware search — beyond simple grep.
+ULPI indexes your entire codebase using hybrid vector + BM25 search with AST-aware chunking. The agent gets smarter search than grep — it understands code semantics, symbol names, and file context.
+
+- **AST chunking** aligns chunks to function and class boundaries
+- **Symbol extraction** identifies functions, classes, interfaces, and types
+- **Hybrid ranking** fuses vector similarity (60%), keyword matching (25%), symbol boost (10%), and path relevance (5%)
+- **Incremental indexing** — only re-indexes changed files
+- **Per-branch indexes** — each git branch gets its own index
+- **Shadow branch export** — share indexes across machines via git
+
+Exposed to Claude Code as MCP tools: `search_code`, `search_symbols`, `get_file_summary`, `get_index_stats`, and `reindex`.
+
+```bash
+ulpi codemap init       # Index your codebase
+ulpi codemap search "authentication middleware"
+```
 
 ### Agent Memory
 
-Captures decisions, patterns, and lessons learned across sessions. Your AI agent builds institutional knowledge over time instead of starting fresh every conversation.
+Your AI agent builds institutional knowledge across sessions instead of starting fresh every conversation.
+
+ULPI captures session events, classifies them with an LLM into 8 memory types — **decisions**, **patterns**, **bug root causes**, **preferences**, **constraints**, **context**, **lessons**, and **relationships** — then stores them with vector embeddings for semantic search.
+
+At the start of each session, the most relevant memories are surfaced to the agent automatically.
+
+- **Deduplication** — new memories are compared against existing ones (0.92 similarity threshold) to prevent redundancy
+- **Importance-weighted ranking** — critical memories never decay; low-importance ones fade over time
+- **Redaction** — API keys, tokens, and secrets are stripped before storage
+- **Soft delete** — memories can be superseded rather than permanently removed
+
+Exposed as MCP tools: `search_memory`, `save_memory`, `get_timeline`, `get_session_context`, `forget`, and `memory_stats`.
+
+```bash
+ulpi memory search "authentication approach"
+ulpi memory status
+```
+
+### Session History
+
+Every coding session is recorded on a per-user orphan git branch (`ulpi/history-<username>`) — separate from your code, never touching your working tree.
+
+Each commit gets a structured JSON entry with:
+
+- Git metadata (SHA, message, author, branch, parents)
+- Diff statistics (files changed, insertions, deletions, per-file breakdown)
+- Session summary (files read/written, commands run, rules enforced)
+- Hook-derived analytics (rule evaluations, permission decisions, tool usage)
+- AI enrichment (summary, intent, challenges, learnings, recommendations)
+- Review plan snapshots and session transcripts
+
+```bash
+ulpi history init         # Create the history branch
+ulpi history list         # Browse captured sessions
+ulpi history enrich --all # AI-enrich all entries
+```
+
+### Notifications
+
+Route events to desktop notifications, webhooks, terminal bells, or log files based on classification rules. Built-in deduplication prevents notification storms.
+
+### Templates & Skills
+
+ULPI ships with **28 built-in templates** for popular stacks — Node.js, Python, Go, Rust, Next.js, Express, Laravel, Django, FastAPI, Prisma, Docker, and more.
+
+**Skills** are injectable markdown guides that ULPI attaches to blocked tool messages — teaching the agent how to fix the issue instead of just blocking it.
+
+```bash
+ulpi templates list
+ulpi skills list
+```
 
 ---
 
@@ -143,12 +255,12 @@ permissions:
     matcher: Bash
     command_pattern: "git (status|log|diff|branch)"
     decision: allow
-```
-
-ULPI ships with **28 built-in templates** for popular stacks — Node.js, Python, Go, Rust, Next.js, Laravel, Django, FastAPI, and more.
 
-```bash
-ulpi templates list
+review:
+  enabled: true
+  plan_review: true
+  code_review: true
+  auto_open_browser: true
 ```
 
 ---
@@ -179,12 +291,19 @@ ulpi templates list
 
 ## How It Works
 
-ULPI uses [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) — lifecycle events that fire before and after every tool execution:
+ULPI uses [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) — lifecycle events that fire before and after every tool execution.
+
+Seven hooks intercept the full session lifecycle:
 
-1. **Before a tool runs**, ULPI checks your rules. Should this file edit be allowed? Has the file been read first? Is this command safe?
-2. **When a permission is requested**, ULPI decides automatically based on your rules — allow, deny, or ask the user.
-3. **After a tool runs**, ULPI updates session state and runs any postconditions you've defined.
-4. **At session boundaries**, ULPI captures history, classifies memories, and indexes code changes.
+| Hook | When | What ULPI Does |
+|------|------|----------------|
+| **SessionStart** | Claude Code session begins | Detect stack, capture branch/HEAD, surface memories, import CodeMap index |
+| **PreToolUse** | Before any tool runs | Evaluate preconditions, block dangerous commands, intercept git commits for code review |
+| **PostToolUse** | After a tool completes | Track files/commands, run postconditions, capture history on new commits, export CodeMap on git push |
+| **PermissionRequest** | Tool needs approval | Auto-approve or deny based on rules, intercept ExitPlanMode for plan review |
+| **Notification** | Event notification | Classify and route to desktop, webhook, terminal, or log channels |
+| **Stop** | Session stopping | Final checks (warn about missing tests/lint) |
+| **SessionEnd** | Session complete | Persist summary, capture commits to history, classify memories, export indexes |
 
 If ULPI ever encounters an error, it fails open — Claude Code continues normally. Your agent is never blocked by a bug in ULPI.
 

package/dist/{chunk-PKD4ASEM.js → chunk-4KRVDKGB.js}

@@ -13,7 +13,7 @@ var REGISTRY_URL = CLI_REGISTRY_URL;
 var FETCH_TIMEOUT_MS = 5e3;
 function getCurrentVersion() {
   try {
-    return "0.1.0";
+    return "0.1.1";
   } catch {
     return "0.0.0";
   }

package/dist/{history-ATTUKOHO.js → history-Q2LDADFW.js}

@@ -412,7 +412,7 @@ async function initSubcommand(projectDir) {
   }
   const projectName = path2.basename(projectDir);
   try {
-    initHistoryBranch(projectDir, projectName, "0.1.0");
+    initHistoryBranch(projectDir, projectName, "0.1.1");
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.log(chalk.red(`Error: ${message}`));

package/dist/index.js

@@ -138,7 +138,7 @@ async function handleSessionStart(ctx) {
   if (shouldPromptForGeneration(projectDir2)) {
     outputGenerationPrompt();
   }
-  import("./version-checker-ANCS3IHR.js").then((m) => m.checkForUpdates()).catch(() => {
+  import("./version-checker-M37KI7DY.js").then((m) => m.checkForUpdates()).catch(() => {
   });
   try {
     const { isMemoryEnabled, loadMemoryConfig, getTopMemories, formatMemoriesForAgent } = await import("./dist-R5F4MX3I.js");
@@ -2043,9 +2043,9 @@ async function main() {
     case "ui":
       return (await import("./ui-L7UAWXDY.js")).runUI(args.slice(1), projectDir);
     case "update":
-      return (await import("./update-M2B4RLGH.js")).runUpdate(args.slice(1));
+      return (await import("./update-DJ227LL3.js")).runUpdate(args.slice(1));
     case "history":
-      return (await import("./history-ATTUKOHO.js")).runHistory(args.slice(1), projectDir);
+      return (await import("./history-Q2LDADFW.js")).runHistory(args.slice(1), projectDir);
     case "review":
       return (await import("./review-ADUPV3PN.js")).runReview(args.slice(1), projectDir);
     case "config":
@@ -2058,7 +2058,7 @@ async function main() {
       return (await import("./projects-ATHDD3D6.js")).runProjects(args.slice(1));
     case "--version":
     case "-v":
-      console.log("0.1.0");
+      console.log("0.1.1");
       return;
     case "--help":
     case "-h":

package/dist/{update-M2B4RLGH.js → update-DJ227LL3.js}

@@ -1,6 +1,6 @@
 import {
   checkForUpdates
-} from "./chunk-PKD4ASEM.js";
+} from "./chunk-4KRVDKGB.js";
 import {
   CLI_BIN_NAME,
   CLI_NPM_PACKAGE

package/dist/{version-checker-ANCS3IHR.js → version-checker-M37KI7DY.js}

@@ -1,7 +1,7 @@
 import {
   checkForUpdates,
   getCurrentVersion
-} from "./chunk-PKD4ASEM.js";
+} from "./chunk-4KRVDKGB.js";
 import "./chunk-7LXY5UVC.js";
 import "./chunk-4VNS5WPM.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "bin": {
     "ulpi": "./dist/index.js"
@@ -43,22 +43,22 @@
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@ulpi/guards-engine": "0.1.0",
     "@ulpi/contracts": "0.1.0",
     "@ulpi/config": "0.1.0",
+    "@ulpi/guards-engine": "0.1.0",
     "@ulpi/session-engine": "0.1.0",
     "@ulpi/templates-engine": "0.1.0",
     "@ulpi/notifications-engine": "0.1.0",
-    "@ulpi/history-engine": "0.1.0",
+    "@ulpi/stack-engine": "0.1.0",
     "@ulpi/projects-engine": "0.1.0",
+    "@ulpi/history-engine": "0.1.0",
+    "@ulpi/review-engine": "0.1.0",
     "@ulpi/review-runtime": "0.1.0",
     "@ulpi/codemap-engine": "0.1.0",
-    "@ulpi/review-engine": "0.1.0",
-    "@ulpi/api": "0.1.0",
-    "@ulpi/memory-mcp": "0.1.0",
     "@ulpi/depgraph-engine": "0.1.0",
     "@ulpi/memory-engine": "0.1.0",
-    "@ulpi/stack-engine": "0.1.0",
+    "@ulpi/api": "0.1.0",
+    "@ulpi/memory-mcp": "0.1.0",
     "@ulpi/codemap-mcp": "0.1.0"
   },
   "publishConfig": {