@rengler33/prov 0.1.1

package/README.md

@@ -0,0 +1,314 @@
+# prov
+
+**Provenance-first planning CLI for AI agent workflows**
+
+Prov creates and maintains an *intent graph* that tracks the complete provenance chain from high-level specifications through implementation decisions, plans, and code artifacts. When code becomes cheap to generate, the economics of software shift dramatically. Prov captures what matters most: the intent behind your system.
+
+## Philosophy
+
+This project is inspired by [The Phoenix Architecture](https://aicoding.leaflet.pub/3mcbiyal7jc2y), which argues that in an era of generative AI, code is no longer scarce—it's abundant, fast, and increasingly disposable. The true assets become specifications, evaluations, and decision records, not the implementation itself.
+
+**Core principles:**
+
+- **Regenerable Systems**: Components can be deleted and recreated from stored intent while maintaining behavior guarantees
+- **Provenance Over Code**: Specifications, constraints, and decisions are the durable artifacts; code is derived
+- **Intent Graphs**: Meaning is encoded in content-addressed graphs capturing requirements, constraints, plans, and decisions
+- **Evaluation-First**: Behavior is specified through durable evaluations (property tests, invariants, contracts) that survive implementation changes
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g prov
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-org/prov.git
+cd prov
+npm install
+npm run build
+```
+
+### Single executable (Bun)
+
+```bash
+npm run build:bun
+# Creates ./bin/prov - a standalone executable
+```
+
+**Requirements:** Node.js 18+
+
+## Quick Start
+
+```bash
+# Initialize provenance tracking in your project
+prov init
+
+# Add a specification
+prov spec add --file spec/authentication.spec.yaml
+
+# Add constraints that must always hold
+prov constraint add --file constraints/security.constraints.yaml
+
+# Create a plan derived from specs
+prov plan create --from spec:authentication --title "Implement OAuth2 flow"
+
+# Execute plan steps and trace artifacts back to their origins
+prov trace add --file src/auth/oauth.ts --step plan:abc123:step-1
+```
+
+## Core Concepts
+
+### Specifications
+Declarative descriptions of *what* your system should do. Specs contain requirements that drive implementation.
+
+```yaml
+# spec/authentication.spec.yaml
+id: spec:authentication:v1
+title: User Authentication
+requirements:
+  - id: req:auth:1
+    description: Users must authenticate via OAuth2 or password
+  - id: req:auth:2
+    description: Sessions expire after 24 hours of inactivity
+```
+
+### Constraints
+Invariants that must *always* hold, regardless of which requirements are being implemented.
+
+```yaml
+# constraints/security.constraints.yaml
+id: constraint:security:v1
+invariants:
+  - id: inv:sec:1
+    description: Passwords must never be logged or stored in plaintext
+  - id: inv:sec:2
+    description: All API endpoints must require authentication
+```
+
+### Plans
+Implementation roadmaps derived from specifications. Plans contain steps that can be executed and tracked.
+
+```bash
+prov plan create --from spec:authentication --title "Implement OAuth2"
+prov plan show plan:abc123
+prov plan next plan:abc123  # Get the next step to work on
+```
+
+### Traces
+Links between code artifacts and the plan steps (and ultimately specs/constraints) they implement.
+
+```bash
+# Trace a file to a plan step
+prov trace add --file src/auth/oauth.ts --step plan:abc123:step-1
+
+# See why an artifact exists
+prov trace why src/auth/oauth.ts
+
+# Scan for untraced files
+prov trace scan
+```
+
+### The Intent Graph
+All entities form a directed acyclic graph (DAG) with cryptographic content addressing:
+
+```
+Specifications ──→ Requirements
+       │                │
+       ↓                ↓
+Constraints ───→ Plans ──→ Steps ──→ Traces ──→ Artifacts
+       │                      │
+       ↓                      ↓
+Invariants              Decisions
+```
+
+## Commands
+
+For the complete CLI reference with all options and examples, see [docs/CLI.md](docs/CLI.md).
+
+### Initialization
+
+| Command | Description |
+|---------|-------------|
+| `prov init` | Initialize provenance tracking in current directory |
+| `prov init --force` | Reinitialize (recreates `.prov/` directory) |
+
+### Specifications
+
+| Command | Description |
+|---------|-------------|
+| `prov spec add --file <path>` | Add a specification from YAML file |
+| `prov spec list` | List all specifications |
+| `prov spec validate` | Validate all specs against schema |
+
+### Constraints
+
+| Command | Description |
+|---------|-------------|
+| `prov constraint add --file <path>` | Add constraints from YAML file |
+| `prov constraint list` | List all constraints and invariants |
+| `prov constraint check` | Check constraint compliance |
+
+### Plans
+
+| Command | Description |
+|---------|-------------|
+| `prov plan create --from <spec-id> --title <title>` | Create a new plan |
+| `prov plan show <plan-id>` | Show plan details and steps |
+| `prov plan validate <plan-id>` | Validate plan structure |
+| `prov plan next <plan-id>` | Get next incomplete step |
+| `prov plan remaining <plan-id>` | List remaining steps |
+| `prov plan progress <plan-id>` | Show completion progress |
+
+### Traces
+
+| Command | Description |
+|---------|-------------|
+| `prov trace add --file <path> --step <step-id>` | Trace artifact to plan step |
+| `prov trace show <file>` | Show trace information for a file |
+| `prov trace why <file>` | Explain why an artifact exists |
+| `prov trace scan` | Find untraced files in project |
+
+### Graph
+
+| Command | Description |
+|---------|-------------|
+| `prov graph show` | Display the intent graph |
+| `prov graph export --format <dot\|json>` | Export graph for visualization |
+| `prov graph orphans` | Find disconnected nodes |
+
+### Analysis
+
+| Command | Description |
+|---------|-------------|
+| `prov impact <entity-id>` | Analyze impact of changes to an entity |
+| `prov stale` | Find artifacts that may be stale |
+
+### AI Agent Integration
+
+| Command | Description |
+|---------|-------------|
+| `prov agent context` | Get context for AI agent consumption |
+| `prov mcp` | Start Model Context Protocol server |
+
+## Output Formats
+
+All commands support multiple output formats:
+
+```bash
+prov spec list                    # Auto-detect (table for TTY, YAML for pipe)
+prov spec list --format table     # Human-readable table
+prov spec list --format yaml      # YAML for processing
+prov spec list --format json      # JSON for programmatic use
+```
+
+## MCP Server Integration
+
+Prov includes a [Model Context Protocol](https://modelcontextprotocol.io) server for AI agent integration:
+
+```bash
+prov mcp
+```
+
+This exposes tools that allow AI agents to:
+- Query the intent graph for context
+- Create and manage plans
+- Trace artifacts to their origins
+- Check constraint compliance
+- Identify stale or orphaned artifacts
+
+### MCP Configuration
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "prov": {
+      "command": "prov",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│      CLI Commands (commands/)        │
+│  spec, constraint, plan, trace, etc  │
+└────────────┬────────────────────────┘
+             │
+┌────────────▼────────────────────────┐
+│    Intent Graph (graph.ts)           │
+│  DAG of specs, plans, traces, etc    │
+└────────────┬────────────────────────┘
+             │
+┌────────────▼────────────────────────┐
+│    Storage Layer (storage.ts)        │
+│  File I/O, locking, persistence      │
+└────────────┬────────────────────────┘
+             │
+┌────────────▼────────────────────────┐
+│    Core Types & Utilities            │
+│  types.ts, hash.ts, output.ts        │
+└─────────────────────────────────────┘
+```
+
+**Key design decisions:**
+- **Content addressing**: All entities use SHA-256 hashes for change detection
+- **File-based storage**: Graph persisted to `.prov/graph.json` for simplicity and git compatibility
+- **Strict typing**: Full TypeScript with comprehensive type definitions
+- **Schema validation**: Zod schemas ensure data integrity
+
+## Project Structure
+
+```
+.prov/                  # Provenance data directory (git-tracked)
+├── graph.json          # The intent graph
+└── mappings/           # File-to-trace mappings
+
+spec/                   # Your specifications (YAML)
+constraints/            # Your constraints (YAML)
+plans/                  # Generated/managed plans
+```
+
+## Development
+
+```bash
+npm run dev           # Watch mode compilation
+npm run test          # Run tests in watch mode
+npm run test:run      # Run tests once
+npm run lint          # Lint code
+npm run typecheck     # Type check without emitting
+npm run docs          # Generate API documentation
+npm run docs:watch    # Generate docs in watch mode
+```
+
+### API Documentation
+
+Generate API documentation from TypeScript source:
+
+```bash
+npm run docs
+```
+
+Documentation is output to `docs/api/`. Open `docs/api/index.html` in a browser to view.
+
+## Why Provenance?
+
+When AI generates code, you need to know:
+- **What** specification drove this implementation?
+- **Why** was this decision made?
+- **What** constraints must this code respect?
+- **What** breaks if this spec changes?
+
+Prov answers these questions by maintaining the complete derivation chain from intent to artifact. When your specs change, you know exactly which code needs regeneration.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * prov CLI entry point
+ *
+ * A provenance-first planning CLI for AI agent workflows.
+ * This CLI serves two audiences: human developers managing specs
+ * and AI agents creating/executing plans.
+ *
+ * @see spec:cli-interface:v1
+ * @see dec:cli-framework (Commander.js)
+ */
+import { type OutputFormat } from './output.js';
+/**
+ * Global CLI options that apply to all commands.
+ */
+export interface GlobalOptions {
+    /** Output format: table, yaml, or json */
+    format?: OutputFormat;
+    /** Enable verbose output */
+    verbose?: boolean;
+    /** Suppress non-essential output */
+    quiet?: boolean;
+    /** Project directory (defaults to cwd) */
+    dir?: string;
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAIH,OAAO,EAAE,KAAK,YAAY,EAAgC,MAAM,aAAa,CAAC;AAkB9E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}