@ulpi/cli 0.1.5 → 0.1.7

package/README.md

@@ -1,8 +1,8 @@
 # ULPI
 
-**Take control of your AI coding agent.**
+**Your Autonomous Engineering Fleet.**
 
-ULPI sits between you and Claude Code, automatically approving safe operations, blocking dangerous ones, and enforcing your project's rules — so you spend less time clicking "Allow" and more time building.
+Dynamic hooks that govern any AI coding agent in real time. Centralized one-click MCP servers per project. Semantic code search, persistent memory, and a full visual dashboard — locally or in the cloud. Upload a sprint and watch your fleet execute dozens of tasks in parallel.
 
 [![npm version](https://img.shields.io/npm/v/@ulpi/cli.svg)](https://www.npmjs.com/package/@ulpi/cli)
 [![license](https://img.shields.io/npm/l/@ulpi/cli.svg)](https://opensource.org/licenses/MIT)
@@ -10,309 +10,238 @@ ULPI sits between you and Claude Code, automatically approving safe operations,
 
 ---
 
-## Why ULPI?
-
-Without ULPI, every Claude Code session is a stream of permission prompts. You click "Allow" for `npm test`. Allow for `git status`. Allow for reading a file. Over and over.
-
-With ULPI:
-
-- `npm test` runs automatically — you defined it as safe
-- `rm -rf /` gets blocked — before Claude can execute it
-- Editing a file requires reading it first — because you set that rule
-- Your session history is preserved — decisions, patterns, and context carry over
-
-You write the rules once. ULPI enforces them every session.
-
----
-
 ## Install
 
 ```bash
 npm install -g @ulpi/cli
-```
-
-Requires **Node.js 20** or later.
-
-## Get Started
-
-```bash
-cd your-project
 ulpi init
 ```
 
-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
-npx @ulpi/cli init
-```
+Requires **Node.js 20+**. `init` detects your stack, generates rules with AI, installs hooks, starts the daemon, and registers your project. Use `--no-ai` for template-only generation, or `--model=<id>` to pick a specific model.
 
 ---
 
-## Features
-
-### Automatic Permissions
-
-Stop clicking "Allow" for every safe command. Define what's safe once, and ULPI handles the rest.
-
-```yaml
-permissions:
-  auto-approve-tests:
-    trigger: PermissionRequest
-    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
-
-Block destructive operations before they execute. ULPI ships with built-in protection against `rm -rf`, `git push --force`, `DROP TABLE`, and more — plus you can add your own.
-
-### Preconditions
-
-Enforce good practices automatically. Require files to be read before editing. Require tests to pass before committing. Require linting before pushing.
-
-```yaml
-preconditions:
-  read-before-edit:
-    trigger: PreToolUse
-    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
+## Commands
 
-Chain multiple steps into automated workflows that run after tool execution.
+### Core
 
-```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
-```
+| Command | What it does |
+|---------|-------------|
+| `ulpi init` | Detect stack, generate guards, install hooks |
+| `ulpi start` | Start ULPI daemon (API server + codemap watcher + portal) |
+| `ulpi run` | Start execution engine loop (`--prd`, `--agent`, `--tasks`) |
 
-### Session Tracking
+### Management
 
-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.
+| Command | What it does |
+|---------|-------------|
+| `ulpi repos` | Manage registered repos (list/add/remove/default) |
+| `ulpi rules` | List, add, enable, disable, or validate rules |
+| `ulpi templates` | Browse, apply, save, export, or import templates |
+| `ulpi skills` | List, add, get, or attach skills |
+| `ulpi config` | Manage settings and API keys |
+| `ulpi prd` | PRD management (create/convert/show) |
+| `ulpi job` | Manage execution jobs (create/list/status/cancel/logs) |
 
-Each session follows a state machine (`idle` -> `active` -> `active_committed` -> `ended`) and logs up to 10,000 events as an append-only JSONL file.
+### Monitoring
 
-### Web Dashboard
+| Command | What it does |
+|---------|-------------|
+| `ulpi status` | Show current session state |
+| `ulpi log` | View activity log |
+| `ulpi history` | Shadow branch history (init/capture/list/show/enrich/backfill) |
+| `ulpi tui` | Terminal UI client (connects to daemon) |
+| `ulpi portal` | Start Portal dashboard in local mode |
+| `ulpi doctor` | System health check (agents, MCP, hooks, intelligence) |
 
-A full web UI for managing rules, monitoring live sessions, reviewing plans and code, and browsing history.
+### Data & Intelligence
 
-```bash
-ulpi ui
-```
+| Command | What it does |
+|---------|-------------|
+| `ulpi codemap` | Semantic code indexing (init/search/status/reindex/watch) |
+| `ulpi memory` | Agent memory (init/search/remember/status/export/import) |
+| `ulpi mcp` | MCP management (gateway/list/add/remove/enable/disable/catalog/setup) |
+| `ulpi cloud` | Connect to Cloud MCP Gateway (connect/status/disconnect) |
 
-The dashboard shows:
+### Agent Integrations
 
-- **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
+| Command | What it does |
+|---------|-------------|
+| `ulpi kiro` | Manage Kiro CLI integration (install/convert/uninstall/status) |
+| `ulpi codex` | Manage Codex CLI integration (install/convert/uninstall/status) |
 
-### Plan & Code Review
+### Utility
 
-Review AI-generated plans and code changes in a browser-based UI before they execute.
+| Command | What it does |
+|---------|-------------|
+| `ulpi export` | Export rules configuration |
+| `ulpi import` | Import rules configuration |
+| `ulpi update` | Check for and install updates |
+| `ulpi ci` | Run in CI/PR worker mode (used inside worker containers) |
+| `ulpi auth` | Manage AI agent credentials for CI workers |
+| `ulpi uninstall` | Remove hooks and ULPI from a project |
 
-**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.
+Run `ulpi --help` for the full list, or use `-p <project>` to target a specific registered project.
 
-**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).
+## Five Pillars
 
-### Semantic Code Search (CodeMap)
+### Govern
 
-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.
+Define what your AI agent can and cannot do. Four rule types — preconditions, permissions, postconditions, and pipelines — work together for layered enforcement. 28 bundled templates auto-selected for your detected stack. Auto-approve safe operations, block dangerous commands, enforce read-before-write. Session-aware — tracks reads, writes, tests, and lints across the entire session. Fail-open — if ULPI errors, your agent continues unblocked.
 
-- **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
+### Understand
 
-Exposed to Claude Code as MCP tools: `search_code`, `search_symbols`, `get_file_summary`, `get_index_stats`, and `reindex`.
+Your agent understands your entire codebase. CodeMap provides hybrid vector + BM25 semantic search with AST-aware chunking. DepGraph uses tree-sitter entity mapping across 35 languages to build dependency graphs with PageRank importance ranking, cycle detection, and coupling metrics. 18 MCP tools exposed directly to your agent. Stack detection with 10 detectors: runtime, language, framework, package manager, formatter, linter, test runner, ORM, git workflow, features.
 
-```bash
-ulpi codemap init       # Index your codebase
-ulpi codemap search "authentication middleware"
-```
-
-### Agent Memory
+### Remember
 
-Your AI agent builds institutional knowledge across sessions instead of starting fresh every conversation.
+Your agent learns from every session instead of starting fresh. 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. Relevant memories are surfaced automatically at the start of each new session. Deduplication, importance-weighted ranking, and redaction of secrets.
 
-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.
+### Record
 
-At the start of each session, the most relevant memories are surfaced to the agent automatically.
+Complete audit trail of every AI action. Per-user shadow git branches (`ulpi/history-<user>`) store structured records without touching your working tree. Commit diffs, session analytics, metadata, full transcripts, and AI enrichment (summary, intent, challenges, learnings, recommendations). No database — everything lives in git and travels with your repo.
 
-- **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
+### Orchestrate
 
-Exposed as MCP tools: `search_memory`, `save_memory`, `get_timeline`, `get_session_context`, `forget`, and `memory_stats`.
+From PRD to production. The execution engine (`ulpi run`) parses a PRD into structured tasks, builds a dependency graph, schedules parallel work across multiple agents, and auto-commits results. 6 agent adapters, 5 task trackers, configurable retries, branch management, and team delegation.
 
 ```bash
-ulpi memory search "authentication approach"
-ulpi memory status
+ulpi run --prd feature.md --agent claude --auto-commit
+ulpi run --tracker jira --agent gemini --branch feat/new-feature
+ulpi run --tasks tasks.json --agent claude --parallel
 ```
 
-### 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:
+## Supported Agents
 
-- 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
+| Agent | Hook Support | MCP Support | Execution Engine |
+|-------|-------------|-------------|-----------------|
+| Claude Code | Full (7 hooks) | Full (18 tools) | `--agent claude` |
+| Gemini CLI | Full (7 hooks) | Full (18 tools) | `--agent gemini` |
+| OpenCode | Full (7 hooks) | Full (18 tools) | `--agent opencode` |
+| Kiro CLI | Full (4 hooks) | Full (18 tools) | `--agent kiro` |
+| Codex | Prompt governance | Full (18 tools) | `--agent codex` |
+| Factory Droid | MCP only | Full (18 tools) | `--agent factory-droid` |
 
 ```bash
-ulpi history init         # Create the history branch
-ulpi history list         # Browse captured sessions
-ulpi history enrich --all # AI-enrich all entries
+ulpi kiro install       # Install ULPI governance for Kiro CLI
+ulpi codex install      # Install ULPI governance for Codex CLI
+ulpi doctor             # Check which agents are installed and configured
 ```
 
-### 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.
+## MCP Integration
 
-**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.
+- **18 MCP tools** — CodeMap (12 tools) and Memory (6 tools) exposed via stdio transport
+- **MCP gateway** — multiplexing proxy that aggregates third-party MCP backends through a single connection
+- **MCP catalog** — curated registry of MCP server definitions installable with one command
+- **Per-repo MCP** — enable or disable specific MCP servers per repository
+- **Hot reload** — automatic tool list updates when MCP configuration changes
+- **Crash recovery** — automatic backend restart on failure
 
 ```bash
-ulpi templates list
-ulpi skills list
+ulpi mcp catalog        # Browse available MCP servers
+ulpi mcp add <server>   # Add an MCP server
+ulpi mcp setup          # Auto-configure MCP connections
+ulpi mcp gateway        # Start MCP gateway
 ```
 
 ---
 
 ## Configuration
 
-Rules live in `.ulpi/guards.yml` at your project root:
+Rules live in `.ulpi/guards.yml` — plain YAML, auto-generated based on your stack:
 
 ```yaml
-project:
-  name: my-app
-  runtime: node
-  package_manager: pnpm
-  test_command: pnpm test
-
 preconditions:
-  read-before-edit:
-    trigger: PreToolUse
+  read-before-write:
     matcher: "Write|Edit"
-    message: "Read the file before editing it."
     requires_read: true
+    message: "Read the file before editing it."
 
 permissions:
   auto-approve-tests:
-    trigger: PermissionRequest
     matcher: Bash
     command_pattern: "pnpm test"
     decision: allow
 
-  auto-approve-git-read:
-    trigger: PermissionRequest
-    matcher: Bash
-    command_pattern: "git (status|log|diff|branch)"
-    decision: allow
+postconditions:
+  run-tests-after-edit:
+    matcher: "Write|Edit"
+    file_pattern: "src/**/*.ts"
+    command: "pnpm test"
 
-review:
-  enabled: true
-  plan_review: true
-  code_review: true
-  auto_open_browser: true
+pipelines:
+  pre-commit-checks:
+    matcher: Bash
+    command_pattern: "git commit"
+    steps:
+      - name: build
+        command: "pnpm -r build"
+      - name: test
+        command: "pnpm test"
 ```
 
 ---
 
-## Commands
+## Interfaces
 
-| Command | Description |
-|---------|-------------|
-| `ulpi init` | Detect your stack and install hooks |
-| `ulpi rules` | Manage rules (list, add, enable, disable, validate) |
-| `ulpi templates` | Browse and apply rule templates |
-| `ulpi skills` | Manage injectable skills |
-| `ulpi status` | Show current session state |
-| `ulpi log` | View activity log |
-| `ulpi ui` | Launch web dashboard |
-| `ulpi projects` | Manage multiple projects |
-| `ulpi history` | Browse session history |
-| `ulpi review` | Plan and code review management |
-| `ulpi codemap` | Semantic code search and indexing |
-| `ulpi memory` | Agent memory management |
-| `ulpi config` | View and update settings |
-| `ulpi update` | Check for and install updates |
-| `ulpi export` | Export your rules configuration |
-| `ulpi import` | Import a rules configuration |
-| `ulpi uninstall` | Remove ULPI hooks from project |
+- **Portal** — Next.js dashboard for rules, sessions, code search, memory, history, review, and execution monitoring (`ulpi start` or `ulpi portal`)
+- **Terminal UI** — ink-based TUI client for live session monitoring (`ulpi tui`)
+- **REST API** — modular HTTP server with WebSocket for live updates and SSE for event streaming
+- **macOS LaunchAgent** — automatic background startup for daemon and codemap watcher
 
 ---
 
 ## 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.
-
-Seven hooks intercept the full session lifecycle:
+ULPI uses hook protocols — lifecycle events that fire before and after every tool execution in your AI agent.
 
 | 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 |
+| **SessionStart** | Agent session begins | Detect stack, capture branch/HEAD, surface memories, import CodeMap index |
+| **PreToolUse** | Before any tool runs | Evaluate preconditions, block dangerous commands |
+| **PostToolUse** | After a tool completes | Track files/commands, run postconditions, capture history on new commits |
+| **PermissionRequest** | Tool needs approval | Auto-approve or deny based on rules, plan review on ExitPlanMode |
 | **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.
+If ULPI ever encounters an error, it fails open — your AI agent continues normally.
+
+---
+
+## Embedding Providers
+
+| Provider | Setup | Cost | Data |
+|----------|-------|------|------|
+| **ULPI Cloud** (recommended) | No setup, use `ULPI_API_KEY` | Free tier included | Sent to ULPI servers |
+| **Ollama** | Install Ollama locally | Free | Stays on your machine |
+| **OpenAI** | Use your `OPENAI_API_KEY` | Per-token pricing | Sent to OpenAI |
+
+Configure via `ulpi config set embedding.provider <ulpi|ollama|openai>`.
+
+---
+
+## Cloud
+
+Upload a sprint with dozens of tasks — or import directly from Jira. ULPI Cloud spawns isolated Docker workers, each with a full AI agent, to execute them in parallel. GitHub webhooks trigger automated code review on PRs. Per-org quotas, member roles, API keys, and audit logs.
+
+```bash
+ulpi cloud connect      # Connect to ULPI Cloud
+ulpi cloud status       # Check connection status
+```
 
 ---
 
 ## Requirements
 
 - **Node.js** >= 20
-- **Claude Code** with [hooks support](https://docs.anthropic.com/en/docs/claude-code/hooks)
+- An AI coding agent: Claude Code, Gemini CLI, OpenCode, Kiro, Codex, or Factory Droid
 
 ## License
 

package/dist/{auth-PN7TMQHV-2W4ICG64.js → auth-FWM7MM4Q-VZC3U2XZ.js}

@@ -4,7 +4,7 @@ import {
   setApiSecret,
   validateAuth,
   validateLoopback
-} from "./chunk-MIAQVCFW.js";
+} from "./chunk-Z53CAR7G.js";
 import "./chunk-4VNS5WPM.js";
 export {
   generateApiSecret,

package/dist/{auth-BFFBUJUC.js → auth-HDK7ECJL.js}

@@ -2,7 +2,8 @@ import {
   extractCredentials,
   getCredentialExpiry,
   validateCredentials
-} from "./chunk-AV5RB3N2.js";
+} from "./chunk-76D3BYJD.js";
+import "./chunk-KIKPIH6N.js";
 import "./chunk-4VNS5WPM.js";
 
 // src/commands/auth.ts