planfs-cli 1.2.0

package/README.md

@@ -0,0 +1,167 @@
+# planfs-cli
+
+Command-line interface for PlanFS.
+
+## Overview
+
+`planfs-cli` provides command-line tools for managing PlanFS repositories:
+
+- **Validate** - Check repository integrity
+- **Init** - Create repository structure
+- **List** - Query entities with filtering
+- **Backlog** - Capture, refine, order, and review backlog items
+- **Next** - List ranked next-work candidates with explanations
+- **Show** - Display entity details
+- **Create** - Create new entities
+- **PR** - Generate pull request planning context
+
+## Installation
+
+```bash
+npm install -g planfs-cli
+```
+
+Or use locally:
+
+```bash
+npm install planfs-cli
+npx planfs --help
+```
+
+## Commands
+
+### Init
+
+Initialize the repository structure:
+
+```bash
+planfs init
+planfs init --format json
+```
+
+### Validate
+
+Validate the repository for errors:
+
+```bash
+planfs validate
+planfs validate --verbose
+```
+
+### List
+
+List entities:
+
+```bash
+# List all tasks
+planfs list tasks
+
+# List tasks by status
+planfs list tasks --status todo
+
+# List tasks by assignee
+planfs list tasks --assignee user@example.com
+
+# List by epic
+planfs list tasks --epic EPIC-auth-system
+
+# Output as JSON
+planfs list tasks --format json
+
+# List other entity types
+planfs list epics
+planfs list milestones
+planfs list decisions
+```
+
+### Next
+
+List the most actionable work:
+
+```bash
+planfs next
+planfs next --assignee justin
+planfs next --epic EPIC-auth-system --explain
+planfs next --include-blocked
+planfs next --format json
+```
+
+`planfs next` filters out completed work by default, ranks ready and active tasks, and explains blockers when `--include-blocked` is used.
+
+### Backlog
+
+Capture and refine work before it becomes actionable:
+
+```bash
+planfs backlog capture --title "Investigate import workflow"
+planfs backlog list
+planfs backlog list --state needs-refinement --assignee justin
+planfs backlog set-state --id TASK-060 --state ready
+planfs backlog review
+planfs backlog list --format json
+```
+
+Backlog refinement states are `captured`, `needs-refinement`, `ready`, `deferred`, and `discarded`. Explicit non-ready backlog items are separate from next-work recommendations.
+
+### Show
+
+Display entity details:
+
+```bash
+planfs show TASK-001
+planfs show TASK-001 --format json
+```
+
+### Create
+
+Create new entities:
+
+```bash
+# Create task
+planfs create task --title "Implement feature X" --priority high
+
+# With assignee
+planfs create task --title "Fix bug" --status todo --assignee user@example.com
+
+# Create epic
+planfs create epic --title "Phase 6 - Polish" --owner justin
+
+# Create milestone
+planfs create milestone --title "v0.2" --target-date 2026-09-01 --owner justin
+```
+
+### Pull Requests
+
+Generate pull request planning context from the current branch:
+
+```bash
+planfs pr summary
+planfs pr summary --format json
+planfs pr providers --format json
+```
+
+## Usage
+
+### As a Module
+
+```typescript
+import { validateCommand, listCommand } from 'planfs-cli';
+
+// Validate repository
+const exitCode = await validateCommand('/path/to/repo', { verbose: true });
+
+// List tasks
+const code = await listCommand('/path/to/repo', {
+  type: 'tasks',
+  status: 'todo',
+  format: 'json'
+});
+```
+
+## Architecture
+
+See [Architecture Documentation](../../docs/ARCHITECTURE.md) for system design.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Main CLI entry point
+ */
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,540 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Main CLI entry point
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const validate_1 = require("./commands/validate");
+const ai_1 = require("./commands/ai");
+const init_1 = require("./commands/init");
+const list_1 = require("./commands/list");
+const next_1 = require("./commands/next");
+const show_1 = require("./commands/show");
+const create_1 = require("./commands/create");
+const backlog_1 = require("./commands/backlog");
+const archive_1 = require("./commands/archive");
+const branch_1 = require("./commands/branch");
+const git_1 = require("./commands/git");
+const pr_1 = require("./commands/pr");
+const package_json_1 = __importDefault(require("../package.json"));
+async function main() {
+    await (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+        .version(package_json_1.default.version)
+        .command('ai <action>', 'AI-oriented planning summary and update helpers', (y) => y
+        .positional('action', {
+        describe: 'AI helper to run',
+        choices: ['summary', 'update-task', 'bulk-update-tasks', 'initialize']
+    })
+        .option('id', {
+        type: 'string',
+        description: 'Task ID to update'
+    })
+        .option('ids', {
+        type: 'array',
+        string: true,
+        description: 'Task IDs to bulk update, comma-separated or repeated'
+    })
+        .option('assignee', {
+        type: 'string',
+        description: 'Scope summary or set task assignee'
+    })
+        .option('epic', {
+        type: 'string',
+        description: 'Scope summary or set task epic'
+    })
+        .option('milestone', {
+        type: 'string',
+        description: 'Scope summary or set task milestone'
+    })
+        .option('estimate', {
+        type: 'string',
+        description: 'Set task estimate'
+    })
+        .option('status', {
+        type: 'array',
+        string: true,
+        choices: ['todo', 'in-progress', 'review', 'done'],
+        description: 'Scope summary by status or set task status'
+    })
+        .option('priority', {
+        type: 'string',
+        choices: ['low', 'medium', 'high', 'critical'],
+        description: 'Set task priority'
+    })
+        .option('refinement-state', {
+        type: 'array',
+        string: true,
+        choices: ['captured', 'needs-refinement', 'ready', 'deferred', 'discarded'],
+        description: 'Scope summary by refinement state or set task refinement state'
+    })
+        .option('due-date', {
+        type: 'string',
+        description: 'Set task due date'
+    })
+        .option('tags', {
+        type: 'string',
+        description: 'Set task tags as a comma-separated list'
+    })
+        .option('limit', {
+        type: 'number',
+        description: 'Maximum number of summary items per list'
+    })
+        .option('only', {
+        type: 'string',
+        choices: ['open', 'ready', 'blocked', 'review', 'stale', 'recent'],
+        description: 'Return only one planning summary section'
+    })
+        .option('compact', {
+        type: 'boolean',
+        default: false,
+        description: 'Emit minified JSON for lower-overhead agent context'
+    })
+        .option('expected-updated-at', {
+        type: 'string',
+        description: 'Refuse a task update if updatedAt changed since preview (use none for an unset timestamp)'
+    })
+        .option('command', {
+        type: 'string',
+        description: 'CLI command written by ai initialize (default: planfs)'
+    })
+        .option('dry-run', {
+        type: 'boolean',
+        default: false,
+        description: 'Preview task updates or awareness initialization without writing files'
+    })
+        .option('file', {
+        type: 'string',
+        default: 'AGENTS.md',
+        description: 'Agent instruction file to create or update'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['json', 'text'],
+        default: 'json',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, ai_1.aiCommand)(process.cwd(), args.action, {
+            id: args.id,
+            ids: args.ids,
+            assignee: args.assignee,
+            epic: args.epic,
+            milestone: args.milestone,
+            estimate: args.estimate,
+            status: args.status,
+            priority: args.priority,
+            refinementState: args.refinementState,
+            dueDate: args.dueDate,
+            tags: args.tags,
+            limit: args.limit,
+            dryRun: args.dryRun,
+            file: args.file,
+            format: args.format,
+            only: args.only,
+            compact: args.compact,
+            expectedUpdatedAt: args.expectedUpdatedAt,
+            command: args.command
+        });
+        process.exit(exitCode);
+    })
+        .command('init', 'Initialize PlanFS repository structure', (y) => y.option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, init_1.initCommand)(process.cwd(), {
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('validate', 'Validate the PlanFS repository', (y) => y
+        .option('verbose', {
+        alias: 'v',
+        type: 'boolean',
+        description: 'Show detailed output',
+        default: false
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, validate_1.validateCommand)(process.cwd(), {
+            verbose: args.verbose,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('branch', 'Show PlanFS changes on the current Git branch', (y) => y
+        .option('base', {
+        type: 'string',
+        description: 'Base branch or ref to compare against'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, branch_1.branchCommand)(process.cwd(), {
+            base: args.base,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('git <action> [message..]', 'Use Git-aware PlanFS helpers', (y) => y
+        .positional('action', {
+        describe: 'Git helper to run',
+        choices: ['commit-message', 'validate-message']
+    })
+        .positional('message', {
+        describe: 'Commit message to validate',
+        type: 'string'
+    })
+        .option('base', {
+        type: 'string',
+        description: 'Base branch or ref for commit message suggestions'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const message = Array.isArray(args.message)
+            ? args.message.join(' ')
+            : args.message;
+        const exitCode = await (0, git_1.gitCommand)(process.cwd(), args.action, message, {
+            base: args.base,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('pr <action>', 'Generate pull request planning context', (y) => y
+        .positional('action', {
+        describe: 'Pull request helper to run',
+        choices: ['summary', 'providers']
+    })
+        .option('base', {
+        type: 'string',
+        description: 'Base branch or ref to compare against'
+    })
+        .option('provider', {
+        type: 'string',
+        choices: ['github', 'gitlab', 'azure-devops'],
+        default: 'github',
+        description: 'Pull request provider'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['markdown', 'json'],
+        default: 'markdown',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, pr_1.pullRequestCommand)(process.cwd(), args.action, {
+            base: args.base,
+            provider: args.provider,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('archive <action>', 'Archive, restore, and browse hidden PlanFS tasks and epics', (y) => y
+        .positional('action', {
+        describe: 'Archive workflow to run',
+        choices: ['list', 'archive', 'restore', 'delete']
+    })
+        .option('id', {
+        type: 'string',
+        description: 'Task or epic ID'
+    })
+        .option('include-children', {
+        type: 'boolean',
+        default: false,
+        description: 'When archiving an epic, also archive child tasks'
+    })
+        .option('dry-run', {
+        type: 'boolean',
+        default: false,
+        description: 'Preview archive changes without writing files'
+    })
+        .option('expected-updated-at', {
+        type: 'string',
+        description: 'Refuse archive if the target updatedAt has changed'
+    })
+        .option('yes', {
+        type: 'boolean',
+        default: false,
+        description: 'Confirm permanent archive deletion'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, archive_1.archiveCommand)(process.cwd(), args.action, {
+            id: args.id,
+            includeChildren: args.includeChildren,
+            dryRun: args.dryRun,
+            expectedUpdatedAt: args.expectedUpdatedAt,
+            yes: args.yes,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('backlog <action>', 'Manage backlog intake, refinement, and hygiene', (y) => y
+        .positional('action', {
+        describe: 'Backlog workflow to run',
+        choices: ['list', 'capture', 'set-state', 'review']
+    })
+        .option('title', {
+        alias: 't',
+        type: 'string',
+        description: 'Title for captured backlog items'
+    })
+        .option('id', {
+        type: 'string',
+        description: 'Task ID to update'
+    })
+        .option('state', {
+        type: 'string',
+        choices: ['captured', 'needs-refinement', 'ready', 'deferred', 'discarded'],
+        description: 'Backlog refinement state'
+    })
+        .option('assignee', {
+        type: 'string',
+        description: 'Filter or set assignee'
+    })
+        .option('epic', {
+        type: 'string',
+        description: 'Filter or set epic'
+    })
+        .option('milestone', {
+        type: 'string',
+        description: 'Filter or set milestone'
+    })
+        .option('priority', {
+        type: 'string',
+        choices: ['low', 'medium', 'high', 'critical'],
+        description: 'Filter or set priority'
+    })
+        .option('tag', {
+        type: 'array',
+        string: true,
+        description: 'Filter by tag'
+    })
+        .option('query', {
+        type: 'string',
+        description: 'Filter by text query'
+    })
+        .option('body', {
+        type: 'string',
+        description: 'Markdown body for captured backlog items'
+    })
+        .option('limit', {
+        type: 'number',
+        description: 'Maximum number of items to show'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, backlog_1.backlogCommand)(process.cwd(), args.action, {
+            title: args.title,
+            id: args.id,
+            state: args.state,
+            assignee: args.assignee,
+            epic: args.epic,
+            milestone: args.milestone,
+            priority: args.priority,
+            tag: args.tag,
+            query: args.query,
+            body: args.body,
+            limit: args.limit,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('next', 'List ranked next-work candidates', (y) => y
+        .option('assignee', {
+        type: 'string',
+        description: 'Filter by assignee'
+    })
+        .option('epic', {
+        type: 'string',
+        description: 'Filter by epic'
+    })
+        .option('milestone', {
+        type: 'string',
+        description: 'Filter by milestone'
+    })
+        .option('tag', {
+        type: 'array',
+        string: true,
+        description: 'Filter by tag'
+    })
+        .option('status', {
+        type: 'array',
+        string: true,
+        choices: ['todo', 'in-progress', 'review', 'done'],
+        description: 'Filter by status'
+    })
+        .option('include-blocked', {
+        type: 'boolean',
+        default: false,
+        description: 'Include blocked and missing-dependency tasks'
+    })
+        .option('explain', {
+        type: 'boolean',
+        default: false,
+        description: 'Show all ranking reasons'
+    })
+        .option('limit', {
+        type: 'number',
+        description: 'Maximum number of candidates to show'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, next_1.nextCommand)(process.cwd(), {
+            assignee: args.assignee,
+            epic: args.epic,
+            milestone: args.milestone,
+            tag: args.tag,
+            status: args.status,
+            includeBlocked: args.includeBlocked,
+            explain: args.explain,
+            limit: args.limit,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('list [type]', 'List entities', (y) => y
+        .positional('type', {
+        describe: 'Entity type to list',
+        choices: ['tasks', 'epics', 'milestones', 'decisions'],
+        default: 'tasks'
+    })
+        .option('status', {
+        type: 'string',
+        description: 'Filter by status'
+    })
+        .option('assignee', {
+        type: 'string',
+        description: 'Filter by assignee'
+    })
+        .option('epic', {
+        type: 'string',
+        description: 'Filter by epic'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['table', 'json'],
+        default: 'table',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, list_1.listCommand)(process.cwd(), {
+            type: args.type,
+            status: args.status,
+            assignee: args.assignee,
+            epic: args.epic,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('show <id>', 'Show entity details', (y) => y
+        .positional('id', {
+        describe: 'Entity ID to show'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['pretty', 'json'],
+        default: 'pretty'
+    }), async (args) => {
+        const exitCode = await (0, show_1.showCommand)(process.cwd(), args.id, {
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .command('create <type>', 'Create new entity', (y) => y
+        .positional('type', {
+        describe: 'Entity type to create',
+        choices: ['task', 'epic', 'milestone']
+    })
+        .option('title', {
+        alias: 't',
+        type: 'string',
+        description: 'Entity title'
+    })
+        .option('status', {
+        type: 'string',
+        description: 'Initial status'
+    })
+        .option('priority', {
+        type: 'string',
+        description: 'Priority (for tasks)'
+    })
+        .option('assignee', {
+        type: 'string',
+        description: 'Assignee'
+    })
+        .option('owner', {
+        type: 'string',
+        description: 'Owner for epics and milestones'
+    })
+        .option('description', {
+        type: 'string',
+        description: 'Description/body for epics and milestones'
+    })
+        .option('target-date', {
+        type: 'string',
+        description: 'Target date for milestones'
+    })
+        .option('dry-run', {
+        type: 'boolean',
+        default: false,
+        description: 'Preview created Markdown without writing files'
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['text', 'json'],
+        default: 'text',
+        description: 'Output format'
+    }), async (args) => {
+        const exitCode = await (0, create_1.createCommand)(process.cwd(), args.type, {
+            title: args.title,
+            status: args.status,
+            priority: args.priority,
+            assignee: args.assignee,
+            owner: args.owner,
+            description: args.description,
+            targetDate: args.targetDate,
+            dryRun: args.dryRun,
+            format: args.format
+        });
+        process.exit(exitCode);
+    })
+        .demandCommand(1, 'You must provide a command')
+        .help()
+        .strict()
+        .parseAsync();
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map