@sudocode-ai/cli 0.1.0

package/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/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/dist/cli/init-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI handlers for init command
+ */
+export interface InitOptions {
+    specPrefix?: string;
+    issuePrefix?: string;
+    dir?: string;
+    jsonOutput?: boolean;
+}
+/**
+ * Check if sudocode is initialized in a directory
+ */
+export declare function isInitialized(dir: string): boolean;
+/**
+ * Perform sudocode initialization
+ */
+export declare function performInitialization(options?: InitOptions): Promise<void>;
+/**
+ * Handle init command
+ */
+export declare function handleInit(options: InitOptions): Promise<void>;
+//# sourceMappingURL=init-commands.d.ts.map

package/dist/cli/issue-commands.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CLI handlers for issue commands
+ */
+import type Database from "better-sqlite3";
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface IssueCreateOptions {
+    priority: string;
+    description?: string;
+    assignee?: string;
+    parent?: string;
+    tags?: string;
+}
+export declare function handleIssueCreate(ctx: CommandContext, title: string, options: IssueCreateOptions): Promise<void>;
+export interface IssueListOptions {
+    status?: string;
+    assignee?: string;
+    priority?: string;
+    grep?: string;
+    archived?: string;
+    limit: string;
+}
+export declare function handleIssueList(ctx: CommandContext, options: IssueListOptions): Promise<void>;
+export declare function handleIssueShow(ctx: CommandContext, id: string): Promise<void>;
+export interface IssueUpdateOptions {
+    status?: string;
+    priority?: string;
+    assignee?: string;
+    title?: string;
+    description?: string;
+    archived?: string;
+}
+export declare function handleIssueUpdate(ctx: CommandContext, id: string, options: IssueUpdateOptions): Promise<void>;
+export interface IssueCloseOptions {
+    reason?: string;
+}
+export declare function handleIssueClose(ctx: CommandContext, ids: string[], options: IssueCloseOptions): Promise<void>;
+export interface IssueDeleteOptions {
+    hard?: boolean;
+}
+export declare function handleIssueDelete(ctx: CommandContext, ids: string[], options: IssueDeleteOptions): Promise<void>;
+//# sourceMappingURL=issue-commands.d.ts.map

package/dist/cli/query-commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI handlers for query commands (ready, blocked)
+ */
+import type Database from 'better-sqlite3';
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface ReadyOptions {
+    issues?: boolean;
+}
+export declare function handleReady(ctx: CommandContext, options: ReadyOptions): Promise<void>;
+export interface BlockedOptions {
+    issues?: boolean;
+}
+export declare function handleBlocked(ctx: CommandContext, options: BlockedOptions): Promise<void>;
+//# sourceMappingURL=query-commands.d.ts.map

package/dist/cli/reference-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI handlers for reference commands
+ */
+import type Database from 'better-sqlite3';
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface AddReferenceOptions {
+    line?: string;
+    text?: string;
+    display?: string;
+    type?: string;
+    format?: 'inline' | 'newline';
+    position?: 'before' | 'after';
+}
+/**
+ * Add a reference to a spec or issue markdown file
+ */
+export declare function handleAddReference(ctx: CommandContext, entityId: string, referenceId: string, options: AddReferenceOptions): Promise<void>;
+//# sourceMappingURL=reference-commands.d.ts.map

package/dist/cli/relationship-commands.d.ts

@@ -0,0 +1,14 @@
+/**
+ * CLI handlers for relationship commands
+ */
+import type Database from 'better-sqlite3';
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface LinkOptions {
+    type: string;
+}
+export declare function handleLink(ctx: CommandContext, from: string, to: string, options: LinkOptions): Promise<void>;
+//# sourceMappingURL=relationship-commands.d.ts.map

package/dist/cli/server-commands.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CLI handlers for server commands
+ */
+export interface CommandContext {
+    db: any;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface ServerStartOptions {
+    port?: string;
+    detach?: boolean;
+}
+/**
+ * Start the sudocode local server
+ */
+export declare function handleServerStart(ctx: CommandContext, options: ServerStartOptions): Promise<void>;
+//# sourceMappingURL=server-commands.d.ts.map

package/dist/cli/spec-commands.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI handlers for spec commands
+ */
+import type Database from "better-sqlite3";
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface SpecCreateOptions {
+    priority: string;
+    description?: string;
+    filePath?: string;
+    parent?: string;
+    tags?: string;
+}
+export declare function handleSpecCreate(ctx: CommandContext, title: string, options: SpecCreateOptions): Promise<void>;
+export interface SpecListOptions {
+    priority?: string;
+    grep?: string;
+    archived?: string;
+    limit: string;
+}
+export declare function handleSpecList(ctx: CommandContext, options: SpecListOptions): Promise<void>;
+export declare function handleSpecShow(ctx: CommandContext, id: string): Promise<void>;
+export interface SpecUpdateOptions {
+    title?: string;
+    priority?: string;
+    description?: string;
+    parent?: string;
+    tags?: string;
+    archived?: string;
+}
+export declare function handleSpecUpdate(ctx: CommandContext, id: string, options: SpecUpdateOptions): Promise<void>;
+export interface SpecDeleteOptions {
+}
+export declare function handleSpecDelete(ctx: CommandContext, ids: string[], options: SpecDeleteOptions): Promise<void>;
+//# sourceMappingURL=spec-commands.d.ts.map

package/dist/cli/status-commands.d.ts

@@ -0,0 +1,17 @@
+/**
+ * CLI handlers for status and stats commands
+ */
+import type Database from "better-sqlite3";
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface StatusOptions {
+    verbose?: boolean;
+}
+export declare function handleStatus(ctx: CommandContext, options: StatusOptions): Promise<void>;
+export interface StatsOptions {
+}
+export declare function handleStats(ctx: CommandContext, options: StatsOptions): Promise<void>;
+//# sourceMappingURL=status-commands.d.ts.map

package/dist/cli/sync-commands.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI handlers for sync commands
+ */
+import type Database from "better-sqlite3";
+export interface CommandContext {
+    db: Database.Database;
+    outputDir: string;
+    jsonOutput: boolean;
+}
+export interface SyncOptions {
+    watch?: boolean;
+    fromMarkdown?: boolean;
+    toMarkdown?: boolean;
+}
+export declare function handleSync(ctx: CommandContext, options: SyncOptions): Promise<void>;
+export interface ExportOptions {
+    output: string;
+}
+export declare function handleExport(ctx: CommandContext, options: ExportOptions): Promise<void>;
+export interface ImportOptions {
+    input: string;
+}
+export declare function handleImport(ctx: CommandContext, options: ImportOptions): Promise<void>;
+//# sourceMappingURL=sync-commands.d.ts.map

package/dist/cli/update-commands.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Update command handlers
+ */
+/**
+ * Handle update check command
+ */
+export declare function handleUpdateCheck(): Promise<void>;
+/**
+ * Handle update install command
+ */
+export declare function handleUpdate(): Promise<void>;
+//# sourceMappingURL=update-commands.d.ts.map

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * sudocode CLI - Git-native spec and issue management
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map