sudocode 1.0.0 → 1.1.1

package/README.md

@@ -0,0 +1,222 @@
+# sudocode
+
+Git-native spec and issue management for AI-assisted software development.
+
+## Overview
+
+Sudocode is a git-native workflow tool designed for AI-assisted development. It stores specs and issues as JSONL files alongside your code, enabling version control, branching, and merging of your project management data just like code.
+
+**Key Features:**
+- **Git-native** - All data stored in `.sudocode/` as JSONL, versioned with your code
+- **Anchored feedback** - Link issues to specific lines in specs with smart relocation
+- **Relationship tracking** - Model dependencies, blockers, and implementations
+- **MCP integration** - Works seamlessly with Claude and other AI assistants
+- **Fast local cache** - SQLite for instant queries without parsing JSONL
+- **Bidirectional sync** - Export to markdown, edit, import back
+
+## What's Included
+
+This meta-package bundles all sudocode components:
+
+- **@sudocode-ai/cli** - Command-line interface (`sudocode` command)
+- **@sudocode-ai/mcp** - Model Context Protocol server for AI assistants
+- **@sudocode-ai/types** - TypeScript type definitions
+
+## Installation
+
+```bash
+npm install -g sudocode
+```
+
+After installation, both `sudocode` (also aliased as `sdc`) commands will be available.
+
+## Quick Start
+
+```bash
+# Initialize in your project
+sudocode init
+
+# Create your first spec
+sudocode spec create "User authentication system" -p 4
+
+# Create an issue
+sudocode issue create "Implement OAuth login" -p 3 -a alice
+
+# Link the issue to the spec
+sudocode link ISSUE-1 SPEC-1 --type implements
+
+# Show what's ready to work on
+sudocode ready
+
+# Update issue status
+sudocode issue update ISSUE-1 --status in_progress
+
+# View project status
+sudocode status
+```
+
+## Core Commands
+
+```bash
+# Initialization
+sudocode init                                    # Set up .sudocode/ directory
+
+# Specs (specifications/requirements)
+sudocode spec create <title> [options]           # Create a spec
+sudocode spec list                               # List all specs
+sudocode spec show <id>                          # Show spec details
+
+# Issues (tasks/bugs)
+sudocode issue create <title> [options]          # Create an issue
+sudocode issue list [options]                    # List issues
+sudocode issue update <id> [options]             # Update issue
+sudocode issue close <id>                        # Close issue
+
+# Relationships
+sudocode link <from> <to> --type <type>          # Link entities
+sudocode ready                                   # Show unblocked work
+sudocode blocked                                 # Show blocked issues
+
+# Feedback (link issues to spec lines)
+sudocode feedback add <issue> <spec> [options]   # Add anchored feedback
+sudocode feedback list                           # List feedback
+
+# Status
+sudocode status                                  # Quick status
+sudocode stats                                   # Detailed statistics
+
+# Sync
+sudocode sync                                    # Sync JSONL with database
+sudocode sync --watch                            # Auto-sync on changes
+```
+
+For full command documentation, see [@sudocode-ai/cli](https://github.com/sudocode-ai/sudocode/tree/main/cli).
+
+## MCP Integration
+
+Sudocode includes an MCP server for seamless AI assistant integration. To use with Claude Code, you can either:
+
+1. Add sudocode as a plugin:
+
+```bash
+# In Claude Code
+/plugin marketplace add sudocode-ai/sudocode
+/plugin install sudocode
+```
+
+2. Configure Claude Code MCP server:
+
+```json
+{
+  "mcpServers": {
+    "sudocode": {
+      "command": "sudocode-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code to apply changes.
+
+For full MCP documentation, see [@sudocode-ai/mcp](https://github.com/sudocode-ai/sudocode/tree/main/mcp).
+
+## Example Workflow
+
+### Creating a Feature
+
+```bash
+# Create a spec for the feature
+sudocode spec create "OAuth2 Authentication" -p 4 --tags auth,security
+
+# Create implementation issues
+sudocode issue create "Set up OAuth provider configuration" -p 3 -a alice
+sudocode issue create "Implement login endpoint" -p 3 -a bob
+sudocode issue create "Add token refresh logic" -p 2 -a alice
+
+# Link issues to spec
+sudocode link ISSUE-1 SPEC-1 --type implements
+sudocode link ISSUE-2 SPEC-1 --type implements
+sudocode link ISSUE-3 SPEC-1 --type implements
+
+# Model dependencies
+sudocode link ISSUE-2 ISSUE-1 --type depends-on
+
+# Check what's ready
+sudocode ready
+# Shows: ISSUE-1 (no dependencies)
+
+# Start work
+sudocode issue update ISSUE-1 --status in_progress
+```
+
+### Adding Feedback to Specs
+
+```bash
+# Add feedback at a specific line
+sudocode feedback add ISSUE-4 SPEC-1 \
+  --line 42 \
+  --content "Should we support 2FA?" \
+  --type suggestion
+
+# Or search for text
+sudocode feedback add ISSUE-5 SPEC-1 \
+  --text "password requirements" \
+  --content "Consider adding passwordless options" \
+  --type comment
+
+# View feedback
+sudocode feedback list --spec SPEC-1
+```
+
+## File Structure
+
+After `sudocode init`, your project will have:
+
+```
+.sudocode/
+├── meta.json         # Config & ID counters (git tracked)
+├── specs.jsonl       # All specs (git tracked)
+├── issues.jsonl      # All issues (git tracked)
+├── cache.db          # SQLite cache (gitignored)
+├── specs/            # Generated markdown that you can edit (gitignored)
+├── issues/           # Generated markdown that you can edit (gitignored)
+└── .gitignore        # Ignores cache and generated files
+```
+
+The JSONL files are designed to be merged in git like code - each line is a complete entity.
+
+## Why Git-Native?
+
+**Traditional approach:** Project management data lives in external tools (Jira, Linear, etc.), disconnected from your code.
+
+**Sudocode approach:** Project management data lives alongside your code in git, enabling:
+- **Branch specs/issues** with your code branches
+- **Merge specs/issues** when merging branches
+- **Revert specs/issues** along with code changes
+- **Review specs/issues** in pull requests
+- **Version specs/issues** with release tags
+- **AI assistants** can read and modify directly
+
+## Use Cases
+
+- **AI-assisted development** - Let AI agents manage issues and provide spec feedback
+- **Spec-driven development** - Write specs, generate issues, track implementation
+- **Context management** - Store project context that moves with your code
+- **Local-first workflow** - No external services required, works offline
+- **Team coordination** - Share specs/issues through git, merge like code
+
+## Documentation
+
+- **CLI Reference:** [@sudocode-ai/cli](https://github.com/sudocode-ai/sudocode/tree/main/cli)
+- **MCP Server:** [@sudocode-ai/mcp](https://github.com/sudocode-ai/sudocode/tree/main/mcp)
+- **Type Definitions:** [@sudocode-ai/types](https://github.com/sudocode-ai/sudocode/tree/main/types)
+
+## Individual Package Installation
+
+You can also install packages individually:
+
+```bash
+npm install -g @sudocode-ai/cli       # CLI only
+npm install -g @sudocode-ai/mcp       # MCP server only
+npm install @sudocode-ai/types        # Types only (for development)
+```

package/build.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Build script for sudocode meta-package
+ * Copies workspace packages to node_modules for bundleDependencies
+ */
+
+import { cpSync, mkdirSync, existsSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "..");
+
+console.log("Building sudocode meta-package...");
+
+// Create node_modules/@sudocode-ai/
+const nodeModulesDir = join(__dirname, "node_modules");
+const scopeDir = join(nodeModulesDir, "@sudocode-ai");
+
+if (existsSync(nodeModulesDir)) {
+  rmSync(nodeModulesDir, { recursive: true, force: true });
+}
+mkdirSync(scopeDir, { recursive: true });
+
+// Copy workspace packages
+const packages = [
+  { name: "types", dir: "types" },
+  { name: "cli", dir: "cli" },
+  { name: "mcp", dir: "mcp" },
+  { name: "local-server", dir: "server" },
+];
+
+for (const pkg of packages) {
+  console.log(`  - Copying @sudocode-ai/${pkg.name}...`);
+
+  const srcDir = join(rootDir, pkg.dir);
+  const destDir = join(scopeDir, pkg.name);
+
+  // Copy only the files that would be published (dist/, package.json, README, LICENSE)
+  cpSync(srcDir, destDir, {
+    recursive: true,
+    filter: (src) => {
+      const relativePath = src.substring(srcDir.length + 1);
+
+      // Include the directory itself
+      if (!relativePath) return true;
+
+      const parts = relativePath.split("/");
+      const firstPart = parts[0];
+
+      // Always include package.json, README, LICENSE
+      if (
+        firstPart === "package.json" ||
+        firstPart === "README.md" ||
+        firstPart === "LICENSE"
+      ) {
+        return true;
+      }
+
+      // Include dist directory and its contents
+      if (firstPart === "dist") {
+        return true;
+      }
+
+      // Exclude everything else (src, node_modules, tests, etc.)
+      return false;
+    },
+  });
+
+  console.log(`    ✓ Copied`);
+}
+
+console.log("");
+console.log("✓ Meta-package ready!");
+console.log("  All workspace packages copied to node_modules/@sudocode-ai/");

package/node_modules/@sudocode-ai/cli/README.md

@@ -0,0 +1,330 @@
+# @sudocode-ai/cli
+
+Command-line interface for [sudocode](https://github.com/sudocode-ai/sudocode) - Git-native spec and issue management for AI-assisted software development.
+
+## Overview
+
+The sudocode CLI provides a complete toolkit for managing specifications and issues in a git-native workflow. All data is stored in `.sudocode/` as JSONL files that can be versioned alongside your code, with a local SQLite cache for fast queries.
+
+## Features
+
+- **Git-native workflow** - All specs and issues stored as JSONL in `.sudocode/`
+- **Fast local cache** - SQLite database for instant queries
+- **Bidirectional sync** - Export to markdown for editing, import back to database
+- **Relationship tracking** - Link specs and issues with typed relationships
+- **Cross-references** - Add inline Obsidian-style `[[ID]]` references in markdown
+- **Anchored feedback** - Attach issue feedback to specific lines in specs
+- **Priority management** - 5-level priority system (0-4)
+- **Flexible queries** - Filter by status, assignee, priority, or grep content
+- **Watch mode** - Auto-sync markdown changes to database
+
+## Installation
+
+```bash
+npm install -g @sudocode-ai/cli
+```
+
+Or install the meta-package that includes the CLI:
+
+```bash
+npm install -g sudocode
+```
+
+## Quick Start
+
+```bash
+# Initialize sudocode in your project
+sudocode init
+
+# Create a spec
+sudocode spec create "User authentication system" -p 4
+
+# Create an issue
+sudocode issue create "Implement login endpoint" -p 3 -a alice
+
+# Link issue to spec
+sudocode link ISSUE-1 SPEC-1 --type implements
+
+# Show ready work
+sudocode ready
+
+# Update issue status
+sudocode issue update ISSUE-1 --status in_progress
+```
+
+## Commands
+
+### Initialization
+
+```bash
+sudocode init [options]
+```
+
+Initialize `.sudocode/` directory structure with database, JSONL files, and configuration.
+
+**Options:**
+- `--spec-prefix <prefix>` - ID prefix for specs (default: "SPEC")
+- `--issue-prefix <prefix>` - ID prefix for issues (default: "ISSUE")
+
+**Creates:**
+- `.sudocode/cache.db` - SQLite database (gitignored)
+- `.sudocode/specs.jsonl` - Spec storage (versioned)
+- `.sudocode/issues.jsonl` - Issue storage (versioned)
+- `.sudocode/config.json` - Metadata config (versioned)
+- `.sudocode/.gitignore` - Ignores cache and markdown files
+
+### Spec Management
+
+```bash
+# Create a new spec
+sudocode spec create <title> [options]
+  -p, --priority <0-4>        Priority level (default: 2)
+  -d, --description <text>    Description
+  --design <text>             Design notes
+  --file-path <path>          Custom markdown file path
+  --parent <id>               Parent spec ID
+  --tags <tags>               Comma-separated tags
+
+# List specs
+sudocode spec list [options]
+  -p, --priority <priority>   Filter by priority
+  -g, --grep <query>          Search title or content
+  --limit <num>               Limit results (default: 50)
+
+# Show spec details
+sudocode spec show <id>
+
+# Delete specs
+sudocode spec delete <id...>
+```
+
+### Issue Management
+
+```bash
+# Create a new issue
+sudocode issue create <title> [options]
+  -p, --priority <0-4>        Priority level (default: 2)
+  -d, --description <text>    Description
+  -a, --assignee <name>       Assignee username
+  --parent <id>               Parent issue ID
+  --tags <tags>               Comma-separated tags
+
+# List issues
+sudocode issue list [options]
+  -s, --status <status>       Filter by status (open, in_progress, blocked, needs_review, closed)
+  -a, --assignee <assignee>   Filter by assignee
+  -p, --priority <priority>   Filter by priority
+  -g, --grep <query>          Search title, description, or content
+  --limit <num>               Limit results (default: 50)
+
+# Show issue details
+sudocode issue show <id>
+
+# Update issue
+sudocode issue update <id> [options]
+  -s, --status <status>       New status
+  -p, --priority <priority>   New priority
+  -a, --assignee <assignee>   New assignee
+  --title <title>             New title
+  --description <desc>        New description
+
+# Close issues
+sudocode issue close <id...> [options]
+  -r, --reason <text>         Reason for closing
+
+# Delete issues
+sudocode issue delete <id...> [options]
+  --hard                      Permanently delete (default: close)
+```
+
+### Relationships
+
+```bash
+# Link entities
+sudocode link <from> <to> [options]
+  -t, --type <type>           Relationship type (default: "references")
+```
+
+**Relationship types:**
+- `blocks` - From blocks To (e.g., ISSUE-1 blocks ISSUE-2)
+- `implements` - From implements To (e.g., ISSUE-1 implements SPEC-1)
+- `references` - From references To (general reference)
+- `depends-on` - From depends on To
+- `related` - General relation
+- `discovered-from` - Issue discovered from spec feedback
+
+### Cross-References
+
+Add inline references to specs or issues using Obsidian-style `[[ID]]` syntax.
+
+```bash
+# Add reference to a spec or issue
+sudocode spec add-ref <entity-id> <reference-id> [options]
+sudocode issue add-ref <entity-id> <reference-id> [options]
+  -l, --line <number>         Line number to insert reference
+  -t, --text <text>           Text to search for insertion point
+  --display <text>            Display text for reference (creates [[ID|text]])
+  --type <type>               Relationship type (creates [[ID]]{ type })
+  --format <format>           Format: inline or newline (default: inline)
+  --position <position>       Position: before or after (default: after)
+```
+
+**Notes:**
+- Either `--line` or `--text` is required (mutually exclusive)
+- References use Obsidian-style syntax: `[[ISSUE-001]]`
+- Display text: `[[ISSUE-001|OAuth Implementation]]`
+- With relationship: `[[SPEC-002]]{ implements }`
+- Combined: `[[SPEC-002|Auth Spec]]{ blocks }`
+- Inline format adds reference on same line with surrounding text
+- Newline format adds reference on its own line
+
+**Examples:**
+
+```bash
+# Add reference inline after line 45
+sudocode spec add-ref SPEC-001 ISSUE-003 --line 45
+
+# Add reference after specific text
+sudocode spec add-ref SPEC-001 ISSUE-003 --text "Requirements:"
+
+# Add with display text
+sudocode spec add-ref SPEC-001 ISSUE-003 --line 45 --display "OAuth implementation"
+
+# Add with relationship type
+sudocode issue add-ref ISSUE-001 SPEC-002 --text "Design" --type implements
+
+# Add on new line before text
+sudocode spec add-ref SPEC-001 ISSUE-004 --text "## Tasks" --format newline --position before
+```
+
+### Query Commands
+
+```bash
+# Show ready work (no blockers)
+sudocode ready
+
+# Show blocked issues
+sudocode blocked
+```
+
+### Status & Stats
+
+```bash
+# Quick project status
+sudocode status [options]
+  -v, --verbose               Show detailed status
+
+# Detailed statistics
+sudocode stats
+```
+
+### Feedback Management
+
+Feedback allows issues to reference specific locations in specs with anchored comments.
+
+```bash
+# Add feedback to a spec
+sudocode feedback add <issue-id> <spec-id> [options]
+  -l, --line <number>         Line number in spec
+  -t, --text <text>           Text to search for anchor
+  --type <type>               Feedback type (comment, suggestion, request)
+  -c, --content <text>        Feedback content (required)
+  -a, --agent <name>          Agent name
+
+# List feedback
+sudocode feedback list [options]
+  -i, --issue <id>            Filter by issue ID
+  -s, --spec <id>             Filter by spec ID
+  -t, --type <type>           Filter by type
+  --status <status>           Filter by status (open, acknowledged, resolved, wont_fix)
+  --limit <num>               Limit results (default: 50)
+
+# Show feedback details
+sudocode feedback show <id>
+
+# Dismiss feedback
+sudocode feedback dismiss <id> [options]
+  -c, --comment <text>        Optional comment
+
+# List stale feedback anchors
+sudocode feedback stale
+
+# Manually relocate stale anchor
+sudocode feedback relocate <id> --line <number>
+```
+
+### Sync & Export
+
+```bash
+# Sync between markdown, JSONL, and database
+sudocode sync [options]
+  --watch                     Watch for changes and auto-sync
+  --from-markdown             Sync from markdown to database
+  --to-markdown               Sync from database to markdown
+
+# Export database to JSONL
+sudocode export [options]
+  -o, --output <dir>          Output directory (default: ".sudocode")
+
+# Import JSONL to database
+sudocode import [options]
+  -i, --input <dir>           Input directory (default: ".sudocode")
+```
+
+## Global Options
+
+```bash
+--db <path>                   Custom database path (auto-discovers by default)
+--json                        Output in JSON format
+```
+
+## Example Workflows
+
+### Creating and Working on a Feature
+
+```bash
+# Create a spec for the feature
+sudocode spec create "Add OAuth authentication" -p 4 --tags auth,security
+
+# Create implementation issues
+sudocode issue create "Set up OAuth provider" -p 3 -a alice
+sudocode issue create "Create login flow" -p 3 -a bob
+
+# Link issues to spec
+sudocode link ISSUE-1 SPEC-1 --type implements
+sudocode link ISSUE-2 SPEC-1 --type implements
+
+# Mark an issue as blocking another
+sudocode link ISSUE-1 ISSUE-2 --type blocks
+
+# Check what's ready to work on
+sudocode ready
+
+# Start working
+sudocode issue update ISSUE-1 --status in_progress
+
+# Complete the work
+sudocode issue close ISSUE-1 -r "OAuth provider configured"
+```
+
+### Adding Feedback to Specs
+
+```bash
+# Add feedback at a specific line
+sudocode feedback add ISSUE-3 SPEC-1 \
+  --line 42 \
+  --content "Consider adding rate limiting" \
+  --type suggestion
+
+# Add feedback by searching for text
+sudocode feedback add ISSUE-4 SPEC-1 \
+  --text "password requirements" \
+  --content "Should we support passkeys?" \
+  --type comment
+
+# List all feedback for a spec
+sudocode feedback list --spec SPEC-1
+
+# Check for stale anchors
+sudocode feedback stale
+```

package/node_modules/@sudocode-ai/cli/dist/cli/feedback-commands.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CLI handlers for feedback commands
+ */
+import type Database from 'better-sqlite3';
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface FeedbackAddOptions {
+    line?: string;
+    text?: string;
+    type: string;
+    content: string;
+    agent?: string;
+}
+/**
+ * Add feedback to a spec from an issue
+ */
+export declare function handleFeedbackAdd(ctx: CommandContext, issueId: string, specId: string, options: FeedbackAddOptions): Promise<void>;
+export interface FeedbackListOptions {
+    issue?: string;
+    spec?: string;
+    type?: string;
+    dismissed?: string;
+    limit: string;
+}
+/**
+ * List feedback with optional filters
+ */
+export declare function handleFeedbackList(ctx: CommandContext, options: FeedbackListOptions): Promise<void>;
+/**
+ * Show detailed feedback information
+ */
+export declare function handleFeedbackShow(ctx: CommandContext, id: string): Promise<void>;
+export interface FeedbackDismissOptions {
+}
+/**
+ * Dismiss feedback
+ */
+export declare function handleFeedbackDismiss(ctx: CommandContext, id: string, options: FeedbackDismissOptions): Promise<void>;
+/**
+ * List stale feedback anchors
+ */
+export declare function handleFeedbackStale(ctx: CommandContext): Promise<void>;
+export interface FeedbackRelocateOptions {
+    line: string;
+}
+/**
+ * Manually relocate a stale anchor
+ */
+export declare function handleFeedbackRelocate(ctx: CommandContext, id: string, options: FeedbackRelocateOptions): Promise<void>;
+//# sourceMappingURL=feedback-commands.d.ts.map

package/node_modules/@sudocode-ai/cli/dist/cli/feedback-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-commands.d.ts","sourceRoot":"","sources":["../../src/cli/feedback-commands.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAc3C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA+Df;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoDf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,MAAM,WAAW,sBAAsB;CACtC;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAcf;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,cAAc,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA6Cf"}