pi-openspec-context 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-15
+
+### Added
+
+- **Initial Release**: Lightweight Pi extension for automatic OpenSpec context injection
+- **Core Feature**: Single-responsibility automatic context extraction and system prompt injection at `before_agent_start` hook
+- **Smart Detection**: Two-tier detection strategy
+  - Traverses upward to find `openspec/root` directories
+  - Queries `openspec store list` to match registered stores
+- **Flexible Context Extraction**:
+  - Supports both OpenSpec roots (`openspec context`)
+  - Supports OpenSpec stores (`openspec context --store <id>`)
+- **In-Memory Caching**: Per-workspace context caching to minimize CLI invocations
+  - Root targets cached by absolute path
+  - Store targets cached by ID
+- **Resilient Execution**: Hardened with timeouts and error handling
+  - 10-second default timeout (configurable via `OPENSPEC_CONTEXT_TIMEOUT_MS`)
+  - Graceful fallback on missing `openspec` CLI
+  - Graceful fallback on timeouts and CLI errors
+  - Graceful fallback on empty output
+- **Output Sanitization**: ANSI color code stripping for clean context injection
+- **Type Safety**: Fully typed TypeScript with strict mode
+  - Discriminated unions for target types
+  - Strict null checks enabled
+  - No implicit `any` types
+- **Complete Test Coverage**: 85+ unit, integration, and E2E tests
+  - Unit tests for core modules (cache, detector, runner)
+  - Extension lifecycle tests with mock Pi API
+  - In-process harness tests with TestSession
+  - Docker-based E2E tests simulating real Pi environment
+  - Resilience tests for timeout, error, and missing CLI scenarios
+- **Documentation**: 
+  - Comprehensive README with architecture, installation, and troubleshooting
+  - API reference for extension and cache usage
+  - Development guide with build/test/lint commands
+  - SOLID principles documentation
+- **Package Metadata**:
+  - MIT License with attribution to tobias-weiss-ai-xr/pi-openspec
+  - Keywords: pi-package, pi, openspec, extension, context, spec-driven-development
+  - Pi package configuration for automatic discovery
+
+### Technical Details
+
+- **Target Platform**: Node.js with ES2022 module support
+- **Module System**: TypeScript NodeNext ESM with .js import extensions
+- **Parser**: TypeScript with strict mode enabled
+- **Linting**: ESLint with TypeScript support
+- **Testing**: Vitest with Docker-based E2E capabilities
+- **Architecture**: Single-responsibility modules (types, runner, detector, cache, index)
+
+### Breaking Changes
+
+None (initial release)
+
+### Migration Guide
+
+None (initial release)

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Raphael Bahat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Based on work from tobias-weiss-ai-xr/pi-openspec

package/README.md

@@ -0,0 +1,242 @@
+# pi-openspec-context
+
+A lightweight Pi extension that automatically injects OpenSpec context into system prompts at the start of each agent session.
+
+## Overview
+
+`pi-openspec-context` enhances the Pi coding agent by seamlessly integrating OpenSpec specification data into the system prompt. This enables the AI agent to understand project structure, APIs, data models, and other specification-driven context without explicit user prompts.
+
+### Key Features
+
+- **Automatic Context Injection**: Detects OpenSpec projects and injects context into `before_agent_start` hook
+- **Smart Caching**: Caches extracted context per workspace to minimize CLI calls
+- **Flexible Detection**: Works with both OpenSpec roots and registered OpenSpec stores
+- **Resilient Fallback**: Gracefully handles missing `openspec` CLI, timeouts, and errors
+- **ANSI Sanitization**: Strips color codes from context output for clean integration
+- **Type-Safe**: Fully typed TypeScript implementation with strict mode enabled
+
+## Installation
+
+### As a Pi Package
+
+```bash
+pi install pi-openspec-context
+```
+
+### Global Installation (for local development)
+
+```bash
+npm install -g pi-openspec-context
+```
+
+Then add to your Pi configuration:
+
+```json
+{
+  "extensions": [
+    "pi-openspec-context"
+  ]
+}
+```
+
+### Project-Local Installation
+
+```bash
+npm install --save-dev pi-openspec-context
+```
+
+## Prerequisites
+
+### Required
+- **openspec CLI**: Must be installed and accessible in your PATH
+  - Installation: `npm install -g @tobias-weiss-ai-xr/openspec` or `pip install openspec`
+  - Verify: `openspec --version`
+
+### Optional
+- Pi coding agent v0.84.0 or later (typically included with Pi installation)
+
+## Architecture & Behavior
+
+### Detection Strategy
+
+The extension uses a two-tier detection approach:
+
+1. **OpenSpec Root Detection**: Traverses upward from the current working directory looking for `openspec/config.yaml`
+2. **Store Detection**: If no root is found, queries `openspec store list --json` to match the current directory against registered stores
+
+### Context Extraction
+
+Once a target is detected:
+- **Root Target**: Executes `openspec context` at the root path
+- **Store Target**: Executes `openspec context --store <store-id>` from the current directory
+
+### Caching
+
+Extracted context is cached in-memory per target:
+- Root targets are keyed by absolute path
+- Store targets are keyed by store ID
+- Cache persists for the lifetime of the Pi session
+
+### Injection
+
+The cleaned context is injected into the system prompt using a marker:
+
+```
+[OpenSpec context]
+<extracted context data>
+```
+
+## Configuration
+
+The extension works with zero configuration. Simply install and enable it.
+
+### Environment Variables
+
+Optional environment variable to override the default timeout:
+- `OPENSPEC_CONTEXT_TIMEOUT_MS`: Timeout for `openspec` CLI execution (default: 10000ms)
+
+## Troubleshooting
+
+### "openspec: command not found"
+
+**Problem**: The extension runs but no context is injected.
+
+**Solution**:
+1. Verify OpenSpec is installed: `which openspec`
+2. Install if missing: `npm install -g @tobias-weiss-ai-xr/openspec`
+3. Check PATH is configured: `echo $PATH`
+4. Restart Pi after installing OpenSpec
+
+### Context Not Appearing in Prompts
+
+**Problem**: Extension is loaded but context not injected.
+
+**Checklist**:
+1. Confirm you're in an OpenSpec root or registered store: `openspec store list`
+2. Verify OpenSpec can extract context: `openspec context`
+3. Check extension is loaded: Look for "pi-openspec-context" in Pi logs
+4. Inspect cache behavior: Add debug logging to extension
+
+### Timeout Errors
+
+**Problem**: Extension times out and falls back silently.
+
+**Solution**:
+1. Test OpenSpec manually: `time openspec context`
+2. Increase timeout if needed: Set `OPENSPEC_CONTEXT_TIMEOUT_MS=30000`
+3. Check for hung `openspec` processes: `ps aux | grep openspec`
+
+### Empty or Whitespace-Only Context
+
+**Problem**: OpenSpec runs but returns empty output.
+
+**Solution**:
+1. Verify OpenSpec project is valid: `openspec validate`
+2. Check for malformed YAML in `openspec/` directory
+3. Try manual context extraction: `openspec context`
+
+## API Reference
+
+### Extension Export
+
+The package exports a default extension factory:
+
+```typescript
+import extension from 'pi-openspec-context';
+
+// Used automatically by Pi's extension loader
+extension(pi);
+```
+
+### Custom Cache Usage
+
+For advanced use cases, you can create an extension with a custom cache:
+
+```typescript
+import { createExtension, contextCache } from 'pi-openspec-context';
+
+// Use default shared cache
+const ext = createExtension();
+ext(pi);
+
+// Or provide custom cache
+import { OpenSpecContextCache } from 'pi-openspec-context/cache';
+const customCache = new OpenSpecContextCache();
+const extWithCustomCache = createExtension(customCache);
+extWithCustomCache(pi);
+```
+
+### Cache Methods
+
+- `get(target): string | null` - Retrieve cached context
+- `set(target, context): void` - Store context in cache
+- `has(target): boolean` - Check if target is cached
+- `delete(target): boolean` - Remove specific target from cache
+- `clear(): void` - Clear all cached contexts
+- `size(): number` - Get cache entry count
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm run test           # Run all tests
+npm run test:watch    # Watch mode
+npm run test:e2e      # Docker E2E tests only
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+### Linting
+
+```bash
+npm run lint
+```
+
+## Architecture Notes
+
+### Modules
+
+- **`src/types.ts`**: Core type definitions (discriminated unions, interfaces)
+- **`src/runner.ts`**: OpenSpec CLI execution and ANSI sanitization
+- **`src/detector.ts`**: Root and store detection logic
+- **`src/cache.ts`**: In-memory caching with path normalization
+- **`src/index.ts`**: Pi extension lifecycle hook implementation
+
+### SOLID Principles
+
+- **Single Responsibility**: Each module has one clear purpose
+- **Open/Closed**: Extension logic is frozen but cacheable via factory function
+- **Liskov Substitution**: Cache implements a standard interface
+- **Interface Segregation**: Types are minimal and focused
+- **Dependency Inversion**: Depends on `PiExecContext` interface, not concrete implementations
+
+### Error Handling
+
+All errors are caught and logged silently. The extension falls back gracefully:
+- Missing `openspec` CLI → returns `{}`
+- CLI errors → returns `{}`
+- Timeout → returns `{}`
+- Empty output → returns `{}`
+
+This ensures the extension never breaks the agent workflow.
+
+## License
+
+MIT License
+
+## Attribution
+
+Based on original work by [tobias-weiss-ai-xr/pi-openspec](https://github.com/tobias-weiss-ai-xr/pi-openspec)
+
+Created by [Raphael Bahat](https://earendil.works)

package/dist/cache.d.ts

@@ -0,0 +1,11 @@
+import type { OpenSpecTarget } from "./types.js";
+export declare function targetToKey(target: OpenSpecTarget): string;
+export declare class OpenSpecContextCache {
+    private map;
+    get(target: OpenSpecTarget): string | null;
+    set(target: OpenSpecTarget, context: string): void;
+    has(target: OpenSpecTarget): boolean;
+    delete(target: OpenSpecTarget): boolean;
+    clear(): void;
+    size(): number;
+}

package/dist/cache.js

@@ -0,0 +1,38 @@
+import * as path from "path";
+export function targetToKey(target) {
+    switch (target.type) {
+        case "root":
+            return "root:" + path.resolve(target.path);
+        case "store":
+            return "store:" + target.id;
+        default:
+            // Exhaustiveness check: if we reach here, there's an unhandled case
+            const exhaustiveCheck = target;
+            throw new Error(`Unknown target type: ${exhaustiveCheck}`);
+    }
+}
+export class OpenSpecContextCache {
+    map = new Map();
+    get(target) {
+        const key = targetToKey(target);
+        return this.map.get(key) ?? null;
+    }
+    set(target, context) {
+        const key = targetToKey(target);
+        this.map.set(key, context);
+    }
+    has(target) {
+        const key = targetToKey(target);
+        return this.map.has(key);
+    }
+    delete(target) {
+        const key = targetToKey(target);
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+    size() {
+        return this.map.size;
+    }
+}

package/dist/detector.d.ts

@@ -0,0 +1,15 @@
+import * as fs from "fs";
+import type { OpenSpecTarget, PiExecContext } from "./types.js";
+/**
+ * Finds the OpenSpec root directory by traversing upwards from cwd
+ * looking for openspec/config.yaml
+ */
+export declare function findOpenSpecRoot(cwd: string, existsFn?: typeof fs.existsSync): string | null;
+/**
+ * Finds a store ID that matches the given cwd by querying openspec store list
+ */
+export declare function findStoreId(pi: PiExecContext, cwd: string): Promise<string | null>;
+/**
+ * Detects the OpenSpec target (root or store) for the given directory
+ */
+export declare function detectOpenSpecTarget(pi: PiExecContext, cwd: string): Promise<OpenSpecTarget | null>;

package/dist/detector.js

@@ -0,0 +1,83 @@
+import * as path from "path";
+import * as fs from "fs";
+import { runOpenSpec } from "./runner.js";
+/**
+ * Finds the OpenSpec root directory by traversing upwards from cwd
+ * looking for openspec/config.yaml
+ */
+export function findOpenSpecRoot(cwd, existsFn = fs.existsSync) {
+    let current = path.resolve(cwd);
+    while (true) {
+        const configPath = path.join(current, "openspec", "config.yaml");
+        if (existsFn(configPath)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            // Reached root directory (/ on Unix, C:\ on Windows)
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Finds a store ID that matches the given cwd by querying openspec store list
+ */
+export async function findStoreId(pi, cwd) {
+    // Execute openspec store list --json command
+    const output = await runOpenSpec(pi, ["store", "list", "--json"], cwd);
+    if (output === null) {
+        return null;
+    }
+    // Parse JSON output
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch {
+        return null;
+    }
+    // Verify stores is an array
+    if (!Array.isArray(parsed.stores)) {
+        return null;
+    }
+    // Resolve cwd to absolute path
+    const resolvedCwd = path.resolve(cwd);
+    // Match against each store's root/path/dir
+    for (const store of parsed.stores) {
+        const storeRoot = store.root || store.path || store.dir;
+        if (!storeRoot)
+            continue;
+        const resolvedRoot = path.resolve(storeRoot);
+        // Check for exact match or subdirectory match
+        if (resolvedCwd === resolvedRoot ||
+            resolvedCwd.startsWith(resolvedRoot + path.sep)) {
+            return store.id || null;
+        }
+    }
+    return null;
+}
+/**
+ * Detects the OpenSpec target (root or store) for the given directory
+ */
+export async function detectOpenSpecTarget(pi, cwd) {
+    // First try to find an OpenSpec root
+    const root = findOpenSpecRoot(cwd);
+    if (root) {
+        return {
+            type: "root",
+            path: root,
+        };
+    }
+    // Then try to find a store ID
+    const storeId = await findStoreId(pi, cwd);
+    if (storeId) {
+        return {
+            type: "store",
+            id: storeId,
+            cwd,
+        };
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { OpenSpecContextCache } from "./cache.js";
+export declare const contextCache: OpenSpecContextCache;
+/**
+ * Creates an extension factory with optional custom cache
+ * @param cache Optional custom cache instance (defaults to shared contextCache)
+ */
+export declare function createExtension(cache?: OpenSpecContextCache): (pi: ExtensionAPI) => void;
+/**
+ * Default extension function that registers the before_agent_start listener
+ */
+export default function (pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,69 @@
+import { detectOpenSpecTarget } from "./detector.js";
+import { runOpenSpec, sanitizeContext } from "./runner.js";
+import { OpenSpecContextCache } from "./cache.js";
+// Global cache instance for the extension
+export const contextCache = new OpenSpecContextCache();
+/**
+ * Creates a before_agent_start handler with the given cache and PI instance
+ * @param pi The ExtensionAPI instance
+ * @param cache The cache instance to use
+ */
+function createBeforeAgentStartHandler(pi, cache) {
+    return async (event, ctx) => {
+        // Get working directory with fallback chain
+        const cwd = event.systemPromptOptions?.cwd ||
+            ctx?.cwd ||
+            process.cwd();
+        // Detect OpenSpec target (root or store)
+        const target = await detectOpenSpecTarget(pi, cwd);
+        if (!target) {
+            return {};
+        }
+        // Check cache first
+        let contextText = cache.get(target);
+        // If not cached, run openspec to retrieve context
+        if (!contextText) {
+            if (target.type === "root") {
+                contextText = await runOpenSpec(pi, ["context"], target.path);
+            }
+            else if (target.type === "store") {
+                contextText = await runOpenSpec(pi, ["context", "--store", target.id], target.cwd);
+            }
+            // Cache the result if we got one
+            if (contextText) {
+                cache.set(target, contextText);
+            }
+        }
+        // Return empty if no context available
+        if (!contextText) {
+            return {};
+        }
+        // Sanitize the context (strip ANSI codes, trim whitespace)
+        const cleaned = sanitizeContext(contextText);
+        // Return empty if sanitized content is empty
+        if (!cleaned) {
+            return {};
+        }
+        // Inject context into system prompt
+        return {
+            systemPrompt: event.systemPrompt + "\n\n[OpenSpec context]\n" + cleaned,
+        };
+    };
+}
+/**
+ * Creates an extension factory with optional custom cache
+ * @param cache Optional custom cache instance (defaults to shared contextCache)
+ */
+export function createExtension(cache) {
+    const cacheInstance = cache || contextCache;
+    return (pi) => {
+        pi.on("before_agent_start", createBeforeAgentStartHandler(pi, cacheInstance));
+    };
+}
+/**
+ * Default extension function that registers the before_agent_start listener
+ */
+export default function (pi) {
+    const handler = createBeforeAgentStartHandler(pi, contextCache);
+    pi.on("before_agent_start", handler);
+}

package/dist/runner.d.ts

@@ -0,0 +1,14 @@
+import type { PiExecContext } from "./types.js";
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Strips ANSI color/control codes and trims whitespace
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Sanitizes context output for injection (alias for stripAnsi)
+ */
+export declare function sanitizeContext(text: string): string;
+/**
+ * Executes openspec CLI command and returns output or null on failure
+ */
+export declare function runOpenSpec(pi: PiExecContext, args: string[], cwd: string, timeoutMs?: number): Promise<string | null>;

package/dist/runner.js

@@ -0,0 +1,39 @@
+export const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Strips ANSI color/control codes and trims whitespace
+ */
+export function stripAnsi(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, "").trim();
+}
+/**
+ * Sanitizes context output for injection (alias for stripAnsi)
+ */
+export function sanitizeContext(text) {
+    return stripAnsi(text);
+}
+/**
+ * Executes openspec CLI command and returns output or null on failure
+ */
+export async function runOpenSpec(pi, args, cwd, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    try {
+        const result = await pi.exec("openspec", args, {
+            timeout: timeoutMs,
+            cwd,
+        });
+        // Return null if exit code is not 0
+        if (result.code !== 0) {
+            return null;
+        }
+        // Strip ANSI codes and trim
+        const cleaned = stripAnsi(result.stdout);
+        // Return null if output is empty
+        if (!cleaned) {
+            return null;
+        }
+        return cleaned;
+    }
+    catch {
+        // Catch all exceptions (ENOENT, timeout, etc.) and return null
+        return null;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export type OpenSpecTarget = {
+    type: "root";
+    path: string;
+} | {
+    type: "store";
+    id: string;
+    cwd: string;
+};
+export interface OpenSpecStoreEntry {
+    id?: string;
+    root?: string;
+    path?: string;
+    dir?: string;
+}
+export interface OpenSpecStoreListOutput {
+    stores?: OpenSpecStoreEntry[];
+}
+export interface OpenSpecExecutionResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface PiExecContext {
+    exec(cmd: string, args: string[], opts?: {
+        timeout?: number;
+        cwd?: string;
+    }): Promise<OpenSpecExecutionResult>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "type": "module",
+  "name": "pi-openspec-context",
+  "version": "0.1.0",
+  "description": "Lightweight Pi extension for automatic OpenSpec context injection into system prompts",
+  "license": "MIT",
+  "author": "Raphael Bahat <raphael@earendil.works>",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "openspec",
+    "extension",
+    "context",
+    "spec-driven-development"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run docker/test-e2e.test.ts",
+    "lint": "eslint ."
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "@gaodes/pi-test-harness": "file:../pi-test-harness"
+  }
+}