@groeponline/pi-missions 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,150 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-22
+
+### Added
+- Release flow: `scripts/release.mjs` (auto bump from conventional commit subjects, CHANGELOG roll, annotated tag), idempotent `scripts/npm-publish.sh`, idempotent `scripts/github-release.sh`, and `.github/workflows/release.yml` that cuts the tag and publishes on merge to main.
+- `npm run verify:package` catalog contract: package identity, discovery keywords, shipped files, npmjs registry, and the pi peer range.
+
+### Changed
+- Publishes to npmjs.org as a public package instead of GitHub Packages, so `pi install npm:@groeponline/pi-missions` works and the pi.dev catalog card resolves.
+- Pi peer ranges widened to `>=0.74.0 <0.85.0`; `^0.74.0` pinned a single 0.x minor and failed installs on pi 0.84.
+- `pi.image` points at the repository banner for the catalog card.
+
+## [0.1.3] - 2026-05-29
+
+### Changed
+- Migrated package scope from `@devctx/pi-missions` to `@groeponline/pi-missions`.
+- Added `publishConfig` for GitHub Packages.
+- Updated test count badges: 834 → 892.
+- Added license badge to README.
+- Updated wiki references.
+
+## [0.1.2] - 2026-05-29
+
+### Changed
+- Migrated peer dependencies from `@mariozechner/pi-*` to `@earendil-works/pi-*` scope.
+- Optimized hot-path array allocations and iterations in state management.
+- Hardened database initialization with dual driver detection (better-sqlite3 / node:sqlite).
+- Added CI smoke test script for build artifact verification.
+- Improved schema path resolution for ESM and packaged builds.
+
+### Fixed
+- SQL injection prevention via column name whitelist validation in update methods.
+- Coverage thresholds adjusted to match current test coverage levels.
+
+## [0.1.1] - 2026-05-22
+
+### Fixed
+- Fixed strict TypeScript errors around feature token accounting and test fixtures.
+- Hardened SQLite initialization for ESM and packaged builds.
+- Removed the default native SQLite install path; database loading now uses an optional `better-sqlite3` driver when present or Node.js `node:sqlite` otherwise.
+- Added a real CLI build entry and package `bin` mapping.
+- Copied database schema assets into `dist/` during build.
+- Updated README and CI to match the implemented feature set.
+
+## [0.1.0] - 2026-05-19
+
+### Added
+
+#### Core Features
+- **Long-running missions** across multiple Pi sessions
+- **Durable local state** in `~/.pi/missions/<mission-id>/`
+- **Smart feature queue** (`pending` → `active` → `blocked` → `done`)
+- **Phase-aware tool policy** — read-only bash in planning, full access in execution
+- **Evidence capture** for completed work
+- **Append-only history** (JSONL) for full audit trail
+- **Session handoff** – attach/detach across sessions
+
+#### Commands (19 total)
+- `/mission start <goal>` — Create a new mission (alias for `/mission new`)
+- `/mission new <title>` — Create a new mission with planning wizard
+- `/mission list` — List all missions
+- `/mission load <id>` — Load a mission into the current session
+- `/mission status` — Show current status & active feature
+- `/mission dashboard` — Open Mission Control dashboard widget
+- `/mission next` — Advance to the next unblocked feature
+- `/mission done [evidence]` — Mark active feature done + attach evidence
+- `/mission block <reason>` — Block the current feature
+- `/mission pause` / `resume` — Pause or resume the mission
+- `/mission fork <reason>` — Fork active feature into a new session
+- `/mission debug [id]` — Inspect recent history and events
+- `/mission metrics` — Show mission/session metrics
+- `/mission export [filename]` — Export mission to Markdown report
+- `/mission templates` — List and use mission templates
+- `/mission clear` — Detach mission from this session
+- `/mission edit <feature-id>` — Edit a feature
+- `/mission history [feature_id|event|search]` — View mission history
+- `/mission migrate [id]` — Migrate mission schema
+
+#### Agent Tools (10 total)
+- `mission_feature_done` — Mark the active feature complete with evidence
+- `mission_next_feature` — Automatically advance to the next pending feature
+- `mission_ask_user` — Ask for clarification when a safe assumption isn't enough
+- `mission_block_self` — Self-block when stuck instead of looping
+- `mission_fork` — Split a risky or parallel approach into a linked fork
+- `mission_error_status` — Inspect error recovery state
+- `mission_retry_error` — Retry a recorded error
+- `mission_spawn_worker` — Spawn a child pi process to work on a feature autonomously
+- `mission_worker_status` — Check running worker process status
+- `mission_kill_worker` — Kill a runaway worker process
+
+#### Engines
+- **Autopilot** — Autonomous feature advancement
+- **Completion Detection** — Auto-detects feature completion from agent output
+- **Error Recovery** — Retry/ask_user/block on tool failures
+- **Metrics** — Session metrics collection
+- **Worker** — Child process worker spawning
+
+#### UI
+- **Factory Droid Dashboard** — Milestone progress bars, feature hierarchy, acceptance criteria inline
+- **Phase line** — Shows current tool phase in dashboard
+- **Footer status** — `🎯 title [done/total %] — active feature`
+
+#### Safety & Reliability
+- **Crash-safe writes** (EXDEV-safe temp + rename)
+- **File locking** — Prevents concurrent modification conflicts
+- **Schema validation** — Ensures data integrity with TypeBox schemas
+- **Structured logging** — Detailed debug logs for troubleshooting
+- **Graceful degradation** — Continues working with degraded functionality when errors occur
+- **Stuck detection** — Auto-blocks features when agent is stuck
+
+#### Templates (9 total)
+- `refactor`, `fix-bug`, `add-feature`, `docs`, `investigate`, `auth`, `ci-cd`, `security-audit`, `performance-opt`
+
+#### Documentation
+- Comprehensive README with architecture overview
+- Detailed implementation plan (PLAN.md)
+- Documentation plan (DOCUMENTATION_PLAN.md)
+- Improvement tracking (IMPROVEMENTS.md)
+- UI reference (UI_REFERENCE.md)
+
+#### Testing
+- 522 unit tests across 19 test files
+- End-to-end test runner script
+- TypeScript type checking
+- Vitest for testing and benchmarking
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A (initial release)
+
+### Removed
+- N/A (initial release)
+
+### Fixed
+- N/A (initial release)
+
+### Security
+- Path traversal protection via `sanitizeMissionId()`
+- Tool whitelist per phase (planning=read-only, execution=write)
+- Budget exhaustion protection via `maxToolCallsPerFeature` and `tokensBudget`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevCTX
+
+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.

package/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+![Pi Missions Banner](docs/images/missions_banner.png)
+
+# 🚀 @groeponline/pi-missions
+
+**Durable mission orchestration + task queues + state handoffs for the Pi coding agent**
+
+---
+
+</div>
+
+`pi-missions` turns short-lived Pi sessions into long-running execution tracks. It gives an agent a durable mission plan, feature queue, history log, evidence folder, and session handoff layer so multi-step work can survive restarts, context resets, forks, and interruptions.
+
+[![npm](https://img.shields.io/npm/v/@groeponline/pi-missions.svg)](https://www.npmjs.com/package/@groeponline/pi-missions) ![Tests](https://img.shields.io/badge/tests-892%20passing-brightgreen.svg) ![Pi Extension](https://img.shields.io/badge/Pi-Extension-9b59b6.svg) ![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+## Status
+
+This repository is a hardened `0.1.x` release candidate, not a finished marketplace platform. The extension entrypoint, state management, mission commands, tools, analytics dashboard, CLI, database repositories, and tests are wired. Integration classes for GitHub/Slack/webhooks are still lightweight scaffolding and should not be advertised as production integrations yet.
+
+Verified in this snapshot:
+
+- `npm run check` passes.
+- `npm test` passes: 31 test files, 892 tests.
+- `npm run build` produces `dist/index.js`, `dist/index.d.ts`, `dist/cli/index.js`, and copied database schema assets.
+- `./scripts/smoke-test.sh` confirms the Pi extension exports the default `piMissions` function.
+- `node dist/cli/index.js doctor` works on Node.js 22 using `node:sqlite`.
+
+## Requirements
+
+- Node.js `>=22.5.0` for the built-in `node:sqlite` database driver.
+- Pi coding agent packages compatible with the peer dependencies in `package.json`.
+- Optional: install `better-sqlite3` manually in the host project if you prefer that native SQLite driver. Pi Missions will use it when available and fall back to `node:sqlite` otherwise.
+
+## Quick Start
+
+```bash
+# Install the extension
+pi install npm:@groeponline/pi-missions
+
+# Start a mission
+/mission start "Implement user auth"
+
+# Check progress
+/mission status
+
+# Mark features done
+/mission done "Login form works, tests pass"
+```
+
+## Install and local development
+
+```bash
+npm ci
+npm run check
+npm test
+npm run build
+./scripts/smoke-test.sh
+
+# Run locally in Pi after build
+pi -e ./dist/index.js
+
+# CLI diagnostics
+node dist/cli/index.js doctor
+```
+
+## Pi slash commands
+
+| Command | Description |
+| --- | --- |
+| `/mission new <title>` / `/mission start <title>` | Create a new mission. |
+| `/mission list` | List saved missions. |
+| `/mission load <id>` | Load a mission into the current session. |
+| `/mission status` | Show current mission status and progress. |
+| `/mission dashboard` | Render the mission dashboard. |
+| `/mission metrics` | Show metrics overview. |
+| `/mission next` | Advance to the next ready feature. |
+| `/mission done [evidence]` | Mark the active feature done with evidence. |
+| `/mission block <reason>` | Block the active feature. |
+| `/mission pause` / `/mission resume` / `/mission stop` | Control mission execution. |
+| `/mission fork <reason>` | Fork the active feature into a separate track. |
+| `/mission templates` | List or use built-in templates. |
+| `/mission history` | Show mission history. |
+| `/mission worker`, `/mission worker-status`, `/mission kill-worker` | Worker controls. |
+| `/mission migrate` | Inspect or migrate old mission state. |
+| `/mission debug` | Inspect debug information. |
+
+## Agent tools
+
+The extension registers these mission tools for agent workflows:
+
+- `mission_feature_done`
+- `mission_next_feature`
+- `mission_ask_user`
+- `mission_block_self`
+- `mission_fork`
+- `mission_error_status`
+- `mission_retry_error`
+- `mission_spawn_worker`
+- `mission_worker_status`
+- `mission_kill_worker`
+
+## Architecture
+
+```text
+src/
+├── core/        # Extension runtime, state, migrations, mission transitions
+├── commands/    # /mission command registration and handlers
+├── tools/       # Agent-facing mission tools
+├── engines/     # Autopilot, completion detection, recovery, metrics, workers
+├── database/    # SQLite schema and repository layer
+├── templates/   # Built-in mission templates
+├── ui/          # Dashboard and terminal UI helpers
+├── utils/       # Filesystem, context, markdown, logging, feedback helpers
+└── cli/         # pi-missions CLI
+```
+
+## Database
+
+Pi Missions stores structured data in SQLite. The schema includes missions, milestones, features, acceptance criteria, history, learnings, patterns, predictions, templates, sessions, metrics, plugins, and summary views. The source schema is copied into `dist/database/schema.sql` during build so the packaged CLI can initialize cleanly.
+
+## Package notes
+
+The original native `better-sqlite3` hard dependency was removed from the default install path because it can fail or hang in restricted environments when prebuilt binaries or Node headers are unavailable. Runtime database loading now tries `better-sqlite3` first if the host has installed it, then falls back to Node.js `node:sqlite`.
+
+## State Model
+
+![Pi Missions State Model](docs/images/missions_state_model.png)
+
+Mission state is stored locally under `~/.pi/missions/<mission-id>/`:
+- `plan.json`: Current mission plan, feature list, and active pointer.
+- `plan.json.bak`: Backup copy for recovery.
+- `history.jsonl`: Append-style event log for transitions.
+- `evidence/`: Completion proof and artifacts.
+- `sessions/`: Session attachment and handoff metadata.
+
+## Typical Workflow
+
+![Pi Missions Typical Workflow](docs/images/missions_workflow.png)
+
+1. Create a mission with `/mission new <title>`.
+2. Break the mission into features or load an existing plan.
+3. Advance to the next unblocked feature with `/mission next`.
+4. Let the agent work on the current feature.
+5. Capture proof with `/mission done [evidence]`.
+
+## License
+
+MIT © OnlineChef

package/dist/cli/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+interface CLICommand {
+    name: string;
+    description: string;
+    execute(args: string[]): Promise<string>;
+}
+declare class CLI {
+    private commands;
+    constructor();
+    registerCommand(cmd: CLICommand): void;
+    execute(args: string[]): Promise<string>;
+    showHelp(): string;
+    private registerDefaultCommands;
+}
+declare function createCLI(): CLI;
+
+export { CLI, type CLICommand, createCLI };