npm - prjct-cli - Versions diffs - 1.52.3 → 1.54.0 - Mend

prjct-cli 1.52.3 → 1.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +21 -0
package/README.md +180 -166
package/dist/bin/prjct-core.mjs +304 -295
package/dist/daemon/entry.mjs +328 -319
package/dist/mcp/server.mjs +145 -141
package/package.json +2 -2

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,26 @@
 # Changelog
+## [1.54.0] - 2026-04-05
+### Features
+- multi-agent parallel sessions with auto-worktree isolation (#237)
+### Bug Fixes
+- guard feedback array spreads preventing s.push crash (#236)
+## [1.53.1] - 2026-04-04
+### Docs
+- update README with full command reference, Windsurf support, MCP server, parallel sessions, code intelligence, web dashboard, cloud sync, and architecture overview
+## [1.52.4] - 2026-03-26
+### Bug Fixes
+- fix: guard feedback array spreads with `Array.isArray()` in `getAggregatedFeedback` — prevents `s.push is not a function` crash when stored feedback contains non-array values
 ## [1.52.3] - 2026-03-08
 ### Bug Fixes

package/README.md CHANGED Viewed

@@ -2,13 +2,14 @@
 **Context layer for AI coding agents.**
-Works with Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, and more.
+Works with Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, Windsurf, and more.
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Ready-6366f1)](CLAUDE.md)
 [![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Ready-4285F4)]()
 [![OpenAI Codex](https://img.shields.io/badge/OpenAI%20Codex-Ready-10A37F)]()
 [![Antigravity](https://img.shields.io/badge/Antigravity-Ready-EA4335)]()
 [![Cursor IDE](https://img.shields.io/badge/Cursor%20IDE-Ready-00D4AA)]()
+[![Windsurf](https://img.shields.io/badge/Windsurf-Ready-7C3AED)]()
 [![npm](https://img.shields.io/npm/v/prjct-cli)](https://www.npmjs.com/package/prjct-cli)
 ## What is prjct?
@@ -17,18 +18,18 @@ prjct gives AI coding agents the context they need about your project. It mainta
 ```
 Your AI Agent                              prjct
-(Claude/Gemini/Antigravity/Cursor)           │
-         │                                   │
-         │  "What am I working on?"          │
-         │ ────────────────────────────────► │
-         │                                   │ Reads project context
-         │  Task: "Add user auth"            │
-         │  Branch: feature/auth             │
-         │  Subtask 2/5: API routes          │
-         │ ◄──────────────────────────────── │
-         │                                   │
-         ▼                                   │
-    Writes code with full context            │
+(Claude/Gemini/Codex/Cursor/Windsurf)        |
+         |                                   |
+         |  "What am I working on?"          |
+         | --------------------------------> |
+         |                                   | Reads project context
+         |  Task: "Add user auth"            |
+         |  Branch: feature/auth             |
+         |  Subtask 2/5: API routes          |
+         | <-------------------------------- |
+         |                                   |
+         v                                   |
+    Writes code with full context            |
 ```
 ## Install
@@ -52,232 +53,245 @@ prjct init
 # 3. Open in Claude Code, Gemini CLI, or Codex and use:
 p. sync                    # Analyze project
 p. task "add user auth"    # Start a task
-p. done                    # Complete subtask
+p. done                    # Complete task
 p. ship                    # Ship with PR
 ```
-> **Note (Codex):** `prjct sync` generates `AGENTS.md` for project-level Codex context, `prjct start` installs `~/.codex/skills/prjct/SKILL.md`, and `prjct doctor` validates the `p.` router health.
-### Google Antigravity
-```bash
-# 1. One-time global setup (installs prjct as a skill)
-prjct start
-# 2. Initialize your project
-cd my-project
-prjct init
-# 3. Open in Antigravity and use:
-p. sync                    # Analyze project
-p. task "add user auth"    # Start a task
-p. done                    # Complete subtask
-p. ship                    # Ship with PR
-```
-> **Note:** prjct integrates as a Skill (not MCP server) for zero-overhead operation.
-### Cursor IDE
+### Cursor IDE / Windsurf
 ```bash
 # 1. Initialize your project (no global setup needed)
 cd my-project
 prjct init
-# 2. Open in Cursor and use:
+# 2. Open in Cursor or Windsurf and use:
 /sync                      # Analyze project
 /task "add user auth"      # Start a task
-/done                      # Complete subtask
+/done                      # Complete task
 /ship                      # Ship with PR
 ```
-> **Note:** Cursor uses `/command` syntax. Commands are installed per-project in `.cursor/commands/`. If deleted, run `/sync` to regenerate.
+> Cursor uses `.cursor/commands/`, Windsurf uses `.windsurf/` with YAML frontmatter. Run `/sync` to regenerate if deleted.
 ### Core Workflow
 ```
-Claude/Gemini/Codex/Antigravity:  p. sync  →  p. task "..."  →  [code]  →  p. done  →  p. ship
-Cursor:                     /sync    →  /task "..."    →  [code]  →  /done    →  /ship
+Claude/Gemini/Codex:  p. sync  ->  p. task "..."  ->  [code]  ->  p. done  ->  p. ship
+Cursor/Windsurf:      /sync    ->  /task "..."    ->  [code]  ->  /done    ->  /ship
 ```
 ## How It Works
-| Component | Claude Code | Gemini CLI | OpenAI Codex | Antigravity | Cursor IDE |
-|-----------|-------------|------------|--------------|-------------|------------|
-| Router | `~/.claude/commands/p.md` | `~/.gemini/commands/p.toml` | Skill (`~/.codex/skills/prjct/SKILL.md`) | Skill | `.cursor/commands/*.md` |
-| Config | `~/.claude/CLAUDE.md` | `~/.gemini/GEMINI.md` | `AGENTS.md` | `~/.gemini/antigravity/skills/prjct/` | `.cursor/rules/prjct.mdc` |
-| Storage | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` |
-| Scope | Global | Global | Project + Global skill | Global | Per-project |
-| Syntax | `p. command` | `p. command` | `p. command` | `p. command` | `/command` |
+| Component | Claude Code | Gemini CLI | OpenAI Codex | Antigravity | Cursor IDE | Windsurf |
+|-----------|-------------|------------|--------------|-------------|------------|----------|
+| Router | `~/.claude/commands/p.md` | `~/.gemini/commands/p.toml` | `~/.codex/skills/prjct/SKILL.md` | Skill | `.cursor/commands/*.md` | `.windsurf/*.md` |
+| Config | `~/.claude/CLAUDE.md` | `~/.gemini/GEMINI.md` | `AGENTS.md` | `~/.gemini/antigravity/skills/prjct/` | `.cursor/rules/prjct.mdc` | `.windsurf/` (YAML) |
+| Storage | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` |
+| Syntax | `p. command` | `p. command` | `p. command` | `p. command` | `/command` | `/command` |
-All agents share the same project storage, so you can switch between them freely.
+All agents share the same SQLite-backed project storage, so you can switch between them freely.
 ## Commands
-| Claude/Gemini | Cursor | Description |
-|---------------|--------|-------------|
-| `p. sync` | `/sync` | Analyze project, generate domain agents |
+### Core Workflow
+| Claude/Gemini | Cursor/Windsurf | Description |
+|---------------|-----------------|-------------|
+| `p. sync` | `/sync` | Analyze project, build indexes, generate skills |
 | `p. task "desc"` | `/task "desc"` | Start task with auto-classification |
-| `p. done` | `/done` | Complete current subtask |
+| `p. done` | `/done` | Complete current task |
 | `p. ship "name"` | `/ship "name"` | Ship feature with PR + version bump |
 | `p. pause` | `/pause` | Pause current task |
 | `p. resume` | `/resume` | Resume paused task |
-| `p. bug "desc"` | `/bug "desc"` | Report a bug |
-| `p. linear` | - | Linear integration |
-| `p. github` | - | GitHub Issues integration |
+| `p. next` | `/next` | Show priority queue or roadmap |
+| `p. bug "desc"` | `/bug "desc"` | Report and track a bug |
+| `p. idea "desc"` | `/idea "desc"` | Transform idea into technical architecture |
+| `p. spec` | `/spec` | Create detailed spec for complex features |
+| `p. dash` | `/dash` | Unified dashboard (status, progress, roadmap) |
+| `p. suggest` | `/suggest` | Smart recommendations based on project state |
-## Task History
+### Analysis & Performance
-prjct automatically tracks your completed tasks to help AI agents learn from patterns and make better decisions across sessions.
-### How It Works
+| Command | Description |
+|---------|-------------|
+| `p. status` | Check if context is stale |
+| `p. perf` | Performance dashboard (startup, memory, context) |
+| `p. velocity` | Sprint-based velocity with trend detection |
+| `p. tokens <in> <out>` | Record token usage on active task |
+| `p. stats` | Value dashboard (token savings, impact) |
+| `p. sessions` | Show recent sessions across projects |
+| `p. diff` | Diff between draft and sealed analysis |
+| `p. seal` | Seal analysis with commit-hash signature |
+| `p. verify` | Verify integrity (cryptographic or `--semantic`) |
+| `p. rollback` | Rollback to previous sealed analysis |
+### Advanced
-When you complete a task (`p. done` / `/done`), prjct stores:
-- Task description and classification (feature, bug, improvement, chore)
-- Start and completion timestamps
-- Number of subtasks and their summaries
-- Git branch name and Linear issue ID (if linked)
-- PR URL (if shipped)
+| Command | Description |
+|---------|-------------|
+| `p. design` | Design system architecture, APIs, components |
+| `p. enrich "issue"` | Build enrichment context for an issue |
+| `p. workflow` | Configure workflow hooks via natural language |
+| `p. git` | Smart git operations with context |
+| `p. test` | Run tests with auto-fix |
+| `p. undo` / `p. redo` | Snapshot-based undo/redo |
+| `p. recover` | Recover abandoned session with context |
+| `p. linear` | Linear integration via MCP |
+| `p. jira` | Jira integration via MCP |
-This history is:
-- **Bounded**: Maximum 20 entries with FIFO (First-In-First-Out) eviction
-- **Contextual**: Filtered by task type when starting similar work
-- **Persistent**: Survives across sessions and agent types
+### Parallel Agent Sessions
-### Context Injection
+Run multiple AI agents on different tasks simultaneously, each in an isolated git worktree.
-Task history is automatically injected into the AI agent's context:
-- When **starting a task**: Shows 3 most recent tasks of the same type (e.g., recent bug fixes when starting a new bug)
-- When **idle**: Shows 5 most recent tasks across all types
-- **Purpose**: Helps agents identify patterns, avoid repeating mistakes, and build on previous solutions
+| Command | Description |
+|---------|-------------|
+| `p. parallel spawn "task"` | Spawn agent in isolated worktree |
+| `p. parallel status` | Show all active agents |
+| `p. parallel join` | Merge completed branches back |
+| `p. worktree create` | Create worktree (auto-copies .env, installs deps) |
+| `p. worktree list` | List active worktrees |
+| `p. worktree remove` | Clean up completed worktrees |
+| `p. conductor init` | Scaffold Conductor.build integration |
-### Accessor Methods (for developers)
+## CLI Commands
-```typescript
-import { stateStorage } from './storage/state-storage'
+Commands you run directly in the terminal (outside your AI agent):
-// Get full task history (max 20 entries, newest first)
-const history = await stateStorage.getTaskHistory(projectId)
+```bash
+prjct start              # First-time setup wizard
+prjct init               # Initialize project
+prjct sync               # Analyze project and build indexes
+prjct doctor             # Check system health and dependencies
+prjct serve              # Start web dashboard (port 3478)
+prjct watch              # Auto-sync on file changes
+prjct hooks              # Manage git hooks for auto-sync
+prjct context            # Smart context filtering tools
+prjct enrich             # Prepare issue enrichment context
+prjct linear             # Linear MCP gateway
+prjct jira               # Jira MCP gateway
+prjct login              # Authenticate with prjct cloud (opens browser)
+prjct logout             # Sign out from prjct cloud
+prjct update             # Update CLI system-wide
+prjct stop               # Stop the background daemon
+prjct restart            # Restart the background daemon
+prjct uninstall          # Complete system removal
+prjct --version          # Show version + provider status
+prjct --help             # Show help
+```
-// Get most recent completed task
-const recent = await stateStorage.getMostRecentTask(projectId)
+## Code Intelligence
-// Get tasks by classification
-const bugs = await stateStorage.getTaskHistoryByType(projectId, 'bug')
-const features = await stateStorage.getTaskHistoryByType(projectId, 'feature')
-```
+`prjct sync` builds a triple-index system over your codebase:
-## CLI Commands
+| Index | Purpose |
+|-------|---------|
+| **BM25** | Full-text search over file names, symbols, comments |
+| **Import Graph** | Dependency graph with forward and reverse edges |
+| **Git Co-change** | Files that frequently change together |
-```bash
-prjct start          # First-time setup (Claude/Gemini/Codex skill install)
-prjct init           # Initialize project (+ AI tool setup)
-prjct sync           # Analyze project and generate context
-prjct verify         # Verify analysis integrity (cryptographic)
-prjct verify --semantic  # Verify analysis consistency (semantic)
-prjct --version      # Show version + provider status
-prjct --help         # Show help
-```
+These indexes power file ranking, impact analysis, and related-context suggestions for your AI agent.
-### Analysis Verification
+## MCP Server
-prjct provides two types of analysis verification to ensure data integrity and logical consistency:
+prjct exposes an MCP server with tools that AI agents can call directly:
-#### Cryptographic Verification (Default)
-```bash
-prjct verify [--json]
-```
+| Category | Tools | Examples |
+|----------|-------|---------|
+| **Memory** | 8 | Save/search memories, record decisions, manage preferences |
+| **Session** | 4 | Start sessions, recover context, record outcomes |
+| **Code Intelligence** | 3 | Impact analysis, related files, staleness check |
+| **Workflow** | 4 | Task and session management |
+| **File** | 3 | File reading and filtering |
+| **Pattern** | 3 | Pattern extraction and matching |
+| **Review** | 3 | Code review context |
+| **Project** | 4 | Project-level operations |
-Verifies the integrity of sealed analysis results using cryptographic signatures. This ensures:
-- Analysis data hasn't been tampered with
-- Sealed analysis matches the original analysis
-- Hash signatures are valid
+The memory system uses FTS5 full-text search, tracks decision outcomes ("did this work before?"), and auto-captures patterns during normal workflow.
-**When to use:** After sealing an analysis (`prjct seal`) to confirm data integrity.
+## Web Dashboard
-#### Semantic Verification (PRJ-270)
 ```bash
-prjct verify --semantic [--json]
+prjct serve
 ```
-Validates that analysis results match the actual project state. This checks:
-- ✓ **Frameworks** exist in `package.json` dependencies
-- ✓ **Languages** match actual file extensions (.ts → TypeScript)
-- ✓ **Pattern locations** reference real files in the project
-- ✓ **File count** is accurate (within 10% tolerance)
-- ✓ **Anti-pattern files** exist when referenced
+Starts an HTTP server on port 3478 with:
-**When to use:** Before sealing an analysis to catch logical inconsistencies or after project changes to validate analysis accuracy.
+- REST API for project state, task queue, ideas, roadmap, shipped features
+- SSE (Server-Sent Events) for real-time updates
+- Status bar endpoint for IDE integration (`/api/status-bar/compact`)
+- Global statistics across all projects
-**Example output:**
-```
-Semantic Verification Report
-────────────────────────────
-  ✓ Framework verification: passed (2 frameworks validated)
-  ✓ Language verification: passed (1 language validated)
-  ✓ Pattern locations: passed (12 patterns verified)
-  ✓ File count verification: passed (324 files, within tolerance)
-  ✓ Anti-pattern files: passed (3 anti-patterns verified)
-Result: PASSED (5/5 checks)
-Total time: 145ms
-```
-Both verification modes support `--json` flag for programmatic use.
+Built with Hono, supports both Bun and Node.js runtimes.
-## Environment Variables
+## Cloud Sync
-### Configuration
+```bash
+prjct login              # Browser-based OTP authentication
+prjct sync               # Bidirectional push/pull with prjct cloud
+```
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PRJCT_CLI_HOME` | `~/.prjct-cli` | Override global storage location. Useful for tests or sandboxed environments. |
-| `PRJCT_DEBUG` | _(unset)_ | Enable debug logging. Values: `1`, `true`, or a log level (`error`, `warn`, `info`, `debug`). |
-| `DEBUG` | _(unset)_ | Fallback debug flag (used if `PRJCT_DEBUG` is not set). Values: `1`, `true`, or `prjct`. |
-| `CI` | _(unset)_ | Set automatically in CI environments. Skips interactive prompts. |
+Cloud sync enables:
+- Cross-device project state synchronization
+- Event-sourced bidirectional push/pull
+- Automatic sync on task completion
-### Issue Tracker MCP (Linear + Jira)
+## Issue Tracker Integration
 Issue trackers are configured via MCP (OAuth in your AI client), not API tokens.
-| Command | Description |
-|---------|-------------|
-| `prjct linear setup` | Configure Linear MCP server in `~/.claude/mcp.json`. |
-| `prjct linear status` | Verify Linear MCP config. |
-| `prjct linear <sync|list|get|create|update|start|done|comment>` | Delegate Linear operation to MCP tools in your AI client. |
-| `prjct jira setup` | Configure Jira MCP server in `~/.claude/mcp.json`. |
-| `prjct jira status` | Verify Jira MCP config. |
-| `prjct jira <sync|list|get|create|update|start|done|transition|comment>` | Delegate Jira operation to MCP tools in your AI client. |
+```bash
+# Linear
+prjct linear setup       # Configure Linear MCP server
+prjct linear status      # Verify config
+# Then use: p. linear sync|list|get|create|update|start|done|comment
+# Jira
+prjct jira setup         # Configure Jira MCP server
+prjct jira status        # Verify config
+# Then use: p. jira sync|list|get|create|update|start|done|transition|comment
+```
-### Agent Detection (Auto-set)
+## Analysis Verification
-These are typically set by the AI agent runtime, not by users:
+```bash
+prjct verify             # Cryptographic: hash signature integrity
+prjct verify --semantic  # Semantic: frameworks, languages, file counts match reality
+```
-| Variable | Description |
-|----------|-------------|
-| `CLAUDE_AGENT` | Set when running inside Claude Code. |
-| `ANTHROPIC_CLAUDE` | Alternative Claude environment indicator. |
-| `MCP_AVAILABLE` | Set when MCP (Model Context Protocol) is available. |
-| `HOME` / `USERPROFILE` | Standard OS home directory (used for path resolution). |
+Both modes support `--json` for programmatic use.
-### Usage Examples
+## Environment Variables
-```bash
-# Enable debug logging
-PRJCT_DEBUG=1 prjct sync
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PRJCT_CLI_HOME` | `~/.prjct-cli` | Override global storage location |
+| `PRJCT_DEBUG` | _(unset)_ | Enable debug logging (`1`, `true`, or log level) |
+| `DEBUG` | _(unset)_ | Fallback debug flag (`1`, `true`, or `prjct`) |
+| `CI` | _(unset)_ | Set in CI environments; skips interactive prompts |
-# Use a custom storage location
-PRJCT_CLI_HOME=/tmp/prjct-test prjct init
+## Architecture
-# Configure Linear + Jira via MCP
-prjct linear setup
-prjct jira setup
+```
+prjct-cli/
+  core/
+    commands/       # CLI command handlers
+    domain/         # BM25, import graph, co-change, velocity
+    infrastructure/ # Config, path manager, AI provider detection
+    mcp/            # MCP server (48 tools)
+    schemas/        # Zod schemas (PRD, model, etc.)
+    server/         # Hono HTTP server + SSE
+    services/       # Memory, sync, code intel, skills, doctor
+    storage/        # SQLite via better-sqlite3
+    sync/           # Cloud sync client + event mapping
+    types/          # TypeScript type definitions
+    utils/          # Shared utilities
+  templates/        # Skill templates per editor
 ```
 ## Requirements
 - Node.js 18+ or Bun 1.0+
-- One of: Claude Code, Gemini CLI, Antigravity, or Cursor IDE
+- One of: Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, or Windsurf
 ## Links