@sudosandwich/limps 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Breuler
+
+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,190 @@
+# MCP Planning Server
+
+MCP server for managing planning documents, agent coordination, and task tracking.
+
+## Installation
+
+### Global Install (Recommended)
+
+```bash
+npm install -g mcp-planning-server
+```
+
+The server automatically finds configuration at OS-specific locations:
+
+| OS | Config Location |
+|----|-----------------|
+| macOS | `~/Library/Application Support/mcp-planning-server/config.json` |
+| Linux | `~/.config/mcp-planning-server/config.json` |
+| Windows | `%APPDATA%\mcp-planning-server\config.json` |
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/mcp-planning-server.git
+cd mcp-planning-server
+npm install
+npm run build
+```
+
+## Configuration
+
+Create a `config.json` at the OS-specific location or specify a path:
+
+```json
+{
+  "plansPath": "~/Documents/my-plans",
+  "docsPaths": ["~/Documents/my-plans"],
+  "fileExtensions": [".md"],
+  "dataPath": "~/Library/Application Support/mcp-planning-server/data",
+  "coordinationPath": "~/Library/Application Support/mcp-planning-server/coordination.json",
+  "heartbeatTimeout": 300000,
+  "debounceDelay": 200,
+  "maxHandoffIterations": 3
+}
+```
+
+**Config priority:**
+1. CLI: `mcp-planning-server --config /path/to/config.json`
+2. Environment: `MCP_PLANNING_CONFIG=/path/to/config.json`
+3. OS-specific default location
+
+**Path options:**
+- Tilde expansion: `~/Documents/plans`
+- Absolute: `/Users/john/Documents/plans`
+- Relative (to config file): `./plans`
+
+## Cursor Setup
+
+Add to Cursor settings (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
+
+```json
+{
+  "mcp.servers": {
+    "mcp-planning-server": {
+      "command": "mcp-planning-server"
+    }
+  }
+}
+```
+
+With explicit config:
+```json
+{
+  "mcp.servers": {
+    "mcp-planning-server": {
+      "command": "mcp-planning-server",
+      "args": ["--config", "/path/to/config.json"]
+    }
+  }
+}
+```
+
+From source:
+```json
+{
+  "mcp.servers": {
+    "mcp-planning-server": {
+      "command": "node",
+      "args": ["/path/to/mcp-planning-server/dist/index.js"],
+      "cwd": "/path/to/mcp-planning-server"
+    }
+  }
+}
+```
+
+## Features
+
+### Document Management (14 Tools)
+
+| Tool | Description |
+|------|-------------|
+| `read_doc` | Read full document content |
+| `create_doc` | Create new documents |
+| `update_doc` | Update with optimistic concurrency |
+| `delete_doc` | Delete documents |
+| `list_docs` | List files and directories |
+| `search_docs` | Full-text search (SQLite FTS5) |
+| `rlm_query` | JavaScript filter/transform on documents |
+| `rlm_multi_query` | Cross-document analysis with globs |
+| `create_plan` | Create feature plans with structure |
+| `update_task_status` | Update task status (GAP → WIP → PASS) |
+| `claim_task` | Claim tasks with file locks |
+| `release_task` | Release tasks and locks |
+| `get_next_task` | Get highest-priority available task |
+| `open_document_in_cursor` | Open files in Cursor editor |
+
+### Resources (Progressive Disclosure)
+
+- `plans://index` — List of all plans (minimal)
+- `plans://summary` — Plan summaries (key info)
+- `plans://full` — Full plan documents
+- `decisions://log` — Decision log entries
+- `agents://status` — Agent status and tasks
+
+## Development
+
+```bash
+npm install       # Install dependencies
+npm test          # Run tests
+npm run build     # Build TypeScript
+npm run dev       # Watch mode
+npm run lint      # ESLint check
+npm run format    # Prettier format
+```
+
+Pre-commit hooks run lint-staged, build, and tests automatically.
+
+## Releasing
+
+```bash
+# Update version in package.json, then:
+git tag v0.2.1
+git push origin v0.2.1
+```
+
+GitHub Actions automatically builds, tests, and creates releases with changelogs.
+
+## Architecture
+
+- **SQLite + FTS5** — Full-text search with auto-updates
+- **File Watching** — Real-time indexing (Chokidar)
+- **Multi-Agent Coordination** — File-based with heartbeats
+- **RLM Sandbox** — Secure JavaScript execution (QuickJS)
+
+### Principles
+
+1. Simplicity over complexity
+2. Local-first, no external dependencies
+3. Progressive disclosure (index → summary → full)
+4. Optimistic concurrency
+5. Scoring-based task selection
+
+## Adapting for Other Uses
+
+The server is designed for planning documents but the core is generic:
+
+**Configuration-only:**
+```json
+{
+  "plansPath": "./your-docs",
+  "docsPaths": ["./content", "./docs"],
+  "fileExtensions": [".md", ".txt", ".rst"]
+}
+```
+
+**For different domains** (wikis, knowledge bases):
+- Replace/remove planning-specific tools
+- Customize document extractors in `src/rlm/extractors.ts`
+- Modify coordination patterns or remove if single-agent
+
+## What is MCP?
+
+**MCP (Model Context Protocol)** is a standardized protocol for AI applications to connect to external systems. Launched by Anthropic (Nov 2024), now part of the Linux Foundation's Agentic AI Foundation.
+
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [MCP Documentation](https://modelcontextprotocol.io/docs)
+
+## License
+
+MIT

package/dist/agent-parser.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Agent file parser for MCP planning tools.
+ *
+ * Agent files use YAML frontmatter as the single source of truth for task state.
+ * This module provides functions to parse, update, and query agent files.
+ *
+ * Task ID Format: `<plan-folder>#<agent-number>` (e.g., "0022-datagrid-stories#000")
+ */
+/**
+ * Agent file frontmatter interface.
+ * This is the authoritative source of truth for agent/task state.
+ */
+export interface AgentFrontmatter {
+    status: 'GAP' | 'WIP' | 'PASS' | 'BLOCKED';
+    persona: 'coder' | 'reviewer' | 'pm' | 'customer';
+    claimedBy: string | null;
+    dependencies: string[];
+    blocks: string[];
+    files: string[];
+}
+/**
+ * Parsed agent file with frontmatter and metadata.
+ */
+export interface ParsedAgentFile {
+    /** Task ID: planFolder#agentNumber */
+    taskId: string;
+    /** Plan folder name (e.g., "0022-datagrid-stories") */
+    planFolder: string;
+    /** Agent number (e.g., "000") */
+    agentNumber: string;
+    /** Full path to the agent file */
+    path: string;
+    /** Parsed frontmatter */
+    frontmatter: AgentFrontmatter;
+    /** Content after frontmatter */
+    content: string;
+    /** File modification time (for stale detection) */
+    mtime: Date;
+    /** Title extracted from first # heading */
+    title: string;
+}
+/**
+ * Extract agent number from filename.
+ *
+ * @example
+ * extractAgentNumber("000_agent_sticky_header.agent.md") // "000"
+ * extractAgentNumber("001_agent_navigation.agent.md") // "001"
+ * extractAgentNumber("signalbadge.agent.md") // null (no number prefix)
+ *
+ * @param filename - Agent filename (not full path)
+ * @returns Agent number or null if not found
+ */
+export declare function extractAgentNumber(filename: string): string | null;
+/**
+ * Extract plan folder from agent file path.
+ *
+ * @example
+ * extractPlanFolder("/path/to/plans/0022-datagrid-stories/agents/000_agent.agent.md")
+ * // "0022-datagrid-stories"
+ *
+ * @param path - Full path to agent file
+ * @returns Plan folder name or null if not found
+ */
+export declare function extractPlanFolder(path: string): string | null;
+/**
+ * Build task ID from plan folder and agent number.
+ *
+ * @example
+ * buildTaskId("0022-datagrid-stories", "000") // "0022-datagrid-stories#000"
+ *
+ * @param planFolder - Plan folder name
+ * @param agentNumber - Agent number
+ * @returns Task ID in format planFolder#agentNumber
+ */
+export declare function buildTaskId(planFolder: string, agentNumber: string): string;
+/**
+ * Parse task ID to extract plan folder and agent number.
+ *
+ * @example
+ * parseTaskId("0022-datagrid-stories#000")
+ * // { planFolder: "0022-datagrid-stories", agentNumber: "000" }
+ *
+ * @param taskId - Task ID
+ * @returns Parsed components or null if invalid format
+ */
+export declare function parseTaskId(taskId: string): {
+    planFolder: string;
+    agentNumber: string;
+} | null;
+/**
+ * Parse an agent file and extract frontmatter and metadata.
+ *
+ * @param path - Full path to agent file
+ * @param content - File content
+ * @returns Parsed agent file or null if not a valid agent file
+ */
+export declare function parseAgentFile(path: string, content: string): ParsedAgentFile | null;
+/**
+ * Read and parse an agent file from disk.
+ *
+ * @param path - Full path to agent file
+ * @returns Parsed agent file or null if not found or invalid
+ */
+export declare function readAgentFile(path: string): ParsedAgentFile | null;
+/**
+ * Update agent file frontmatter on disk.
+ *
+ * @param path - Full path to agent file
+ * @param updates - Partial frontmatter updates
+ * @returns Updated parsed agent file or null on error
+ */
+export declare function updateAgentFrontmatter(path: string, updates: Partial<AgentFrontmatter>): ParsedAgentFile | null;
+/**
+ * Add frontmatter to a legacy agent file (migration helper).
+ * Extracts state from content and adds proper YAML frontmatter.
+ *
+ * @param path - Full path to agent file
+ * @returns Updated parsed agent file or null on error
+ */
+export declare function migrateAgentFile(path: string): ParsedAgentFile | null;
+/**
+ * Check if an agent is stale (WIP status but mtime > threshold).
+ *
+ * @param agent - Parsed agent file
+ * @param thresholdMinutes - Stale threshold in minutes (default 10)
+ * @returns true if agent is stale
+ */
+export declare function isAgentStale(agent: ParsedAgentFile, thresholdMinutes?: number): boolean;
+/**
+ * Find agent file path by task ID.
+ *
+ * @param plansPath - Base path to plans directory
+ * @param taskId - Task ID in format planFolder#agentNumber
+ * @returns Full path to agent file or null if not found
+ */
+export declare function findAgentFilePath(plansPath: string, taskId: string): string | null;
+/**
+ * Resolve a dependency reference to a full task ID.
+ * Handles both agent numbers ("000") and full task IDs ("0022-plan#000").
+ *
+ * @param dep - Dependency reference
+ * @param currentPlanFolder - Current plan folder for relative references
+ * @returns Full task ID or null if invalid
+ */
+export declare function resolveDependency(dep: string, currentPlanFolder: string): string | null;
+//# sourceMappingURL=agent-parser.d.ts.map

package/dist/agent-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-parser.d.ts","sourceRoot":"","sources":["../src/agent-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,GAAG,UAAU,CAAC;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,IAAI,CAAC;IACZ,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS9F;AA4JD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA8DpF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAOlE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,eAAe,GAAG,IAAI,CAkCxB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAsCrE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,gBAAgB,SAAK,GAAG,OAAO,CAUnF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBlF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYvF"}