@proletariat/cli 0.1.4 → 0.3.0

package/dist/lib/pmo/base-command.js

@@ -0,0 +1,319 @@
+import { Command, Flags } from '@oclif/core';
+import inquirer from 'inquirer';
+import { getPMOContext } from './pmo-context.js';
+import { styles } from '../styles.js';
+import { shouldOutputJson, outputPromptAsJson, createMetadata, } from '../prompt-json.js';
+/**
+ * Base flags shared by all PMO commands
+ * Include these in your command's flags by spreading: ...PMOCommand.baseFlags
+ */
+export const pmoBaseFlags = {
+    project: Flags.string({
+        char: 'P',
+        description: 'Project ID (uses first project if only one exists)',
+    }),
+};
+/**
+ * Base command class for PMO commands
+ *
+ * Provides automatic PMO context initialization and cleanup:
+ * - Initializes storage before run() executes
+ * - Ensures storage.close() is called even if errors occur
+ * - Provides common PMO flags (--project)
+ *
+ * Storage is project-agnostic - projectId is passed explicitly to operations.
+ *
+ * Usage:
+ * ```typescript
+ * import { PMOCommand, pmoBaseFlags } from '../../lib/pmo/base-command.js';
+ *
+ * export default class MyCommand extends PMOCommand {
+ *   static flags = {
+ *     ...pmoBaseFlags,
+ *     // additional flags...
+ *   };
+ *
+ *   async execute(): Promise<void> {
+ *     // For project-agnostic operations (e.g., get ticket by ID):
+ *     const ticket = await this.storage.getTicketById('TKT-123');
+ *
+ *     // For project-scoped operations, get projectId first:
+ *     const projectId = await this.requireProject();
+ *     const board = await this.storage.getBoard(projectId);
+ *
+ *     // Or derive from an entity:
+ *     const projectId = ticket.projectId;
+ *     await this.storage.moveTicket(projectId, ticket.id, 'Done');
+ *   }
+ * }
+ * ```
+ */
+export class PMOCommand extends Command {
+    /**
+     * PMO context with storage, pmoPath, etc.
+     * Available after init() runs (before execute())
+     */
+    pmoContext;
+    /**
+     * Flag to track if context was successfully initialized
+     */
+    contextInitialized = false;
+    /**
+     * Cached project ID from -P flag
+     */
+    projectFlag;
+    /**
+     * Logger function for PMO context
+     * Can be overridden to customize logging behavior
+     */
+    pmoLogger(msg) {
+        this.log(styles.muted(msg));
+    }
+    /**
+     * oclif init hook - runs before the command executes
+     * Initializes PMO context with storage access
+     */
+    async init() {
+        await super.init();
+        // Parse flags to get project ID if provided
+        const { flags } = await this.parse(this.constructor);
+        this.projectFlag = flags.project;
+        try {
+            this.pmoContext = await getPMOContext({
+                logger: (msg) => this.pmoLogger(msg),
+            });
+            this.contextInitialized = true;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Require a project to be selected.
+     * Returns projectId that should be passed to storage operations.
+     *
+     * Priority:
+     * 1. If -P flag was provided, uses that
+     * 2. If only one project exists, uses that
+     * 3. If multiple projects exist, prompts user to select one (or outputs JSON if jsonMode)
+     *
+     * @param options.filterEmptyProjects - Only show projects with tickets
+     * @param options.jsonMode - JSON mode configuration for AI agents
+     * @returns The selected project ID - pass this to storage operations
+     */
+    async requireProject(options) {
+        // If -P flag was provided, use it
+        if (this.projectFlag) {
+            return this.projectFlag;
+        }
+        // Get all projects
+        const projects = await this.storage.listProjects();
+        if (projects.length === 0) {
+            throw new Error('No projects found. Run "prlt pmo init" first.');
+        }
+        // Filter to projects with tickets if requested
+        let filteredProjects = projects;
+        if (options?.filterEmptyProjects) {
+            const projectsWithTickets = [];
+            for (const p of projects) {
+                const tickets = await this.storage.listTickets(p.id);
+                if (tickets.length > 0) {
+                    projectsWithTickets.push(p);
+                }
+            }
+            filteredProjects = projectsWithTickets;
+            if (filteredProjects.length === 0) {
+                throw new Error('No projects with tickets found. Create a ticket first.');
+            }
+        }
+        // If only one project, use it
+        if (filteredProjects.length === 1) {
+            return filteredProjects[0].id;
+        }
+        // Multiple projects - check for JSON mode
+        // Sort projects by leading number in name (e.g., "1. MVP" before "10. Infra")
+        const sortedProjects = [...filteredProjects].sort((a, b) => {
+            const numA = parseInt(a.name.match(/^(\d+)/)?.[1] || '999', 10);
+            const numB = parseInt(b.name.match(/^(\d+)/)?.[1] || '999', 10);
+            return numA - numB;
+        });
+        // If JSON mode is active, output project choices as JSON
+        if (options?.jsonMode && shouldOutputJson(options.jsonMode.flags)) {
+            const choices = sortedProjects.map(p => ({
+                name: `${p.name} (${p.id})`,
+                value: p.id,
+                command: `${options.jsonMode.baseCommand} -P ${p.id} --json`,
+            }));
+            outputPromptAsJson({
+                type: 'list',
+                name: 'project',
+                message: 'Select project:',
+                choices,
+            }, createMetadata(options.jsonMode.commandName, options.jsonMode.flags));
+            // outputPromptAsJson calls process.exit, so this is unreachable
+            return '';
+        }
+        // Interactive mode - prompt for selection
+        const { selectedProjectId } = await inquirer.prompt([{
+                type: 'list',
+                name: 'selectedProjectId',
+                message: 'Select project:',
+                choices: sortedProjects.map(p => ({
+                    name: `${p.name} (${p.id})`,
+                    value: p.id,
+                })),
+            }]);
+        return selectedProjectId;
+    }
+    /**
+     * Get project name by ID
+     */
+    async getProjectName(projectId) {
+        const project = await this.storage.getProject(projectId);
+        return project?.name || projectId;
+    }
+    /**
+     * Select from a list of items with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs choices as JSON with command field and exits
+     * In interactive mode: shows prompt and returns selected value
+     *
+     * @param options Configuration for the selection
+     * @returns The selected value (only in interactive mode)
+     *
+     * @example
+     * ```typescript
+     * const ticketId = await this.selectFromList({
+     *   message: 'Select ticket:',
+     *   items: tickets,
+     *   getName: (t) => `${t.id}: ${t.title}`,
+     *   getValue: (t) => t.id,
+     *   getCommand: (t) => `prlt ticket view ${t.id} --json`,
+     *   jsonMode: { flags, commandName: 'ticket view' },
+     * });
+     * ```
+     */
+    async selectFromList(options) {
+        const { message, items, getName, getValue, getCommand, jsonMode, allowCancel = false, cancelValue, } = options;
+        // Build choices with command field
+        const choices = items.map(item => ({
+            name: getName(item),
+            value: getValue(item),
+            command: getCommand(item),
+        }));
+        // Check for JSON mode
+        if (jsonMode && shouldOutputJson(jsonMode.flags)) {
+            outputPromptAsJson({
+                type: 'list',
+                name: 'selection',
+                message,
+                choices,
+            }, createMetadata(jsonMode.commandName, jsonMode.flags));
+            // outputPromptAsJson exits, so this is unreachable
+            return null;
+        }
+        // Interactive mode
+        const interactiveChoices = choices.map(c => ({
+            name: c.name,
+            value: c.value,
+        }));
+        if (allowCancel) {
+            interactiveChoices.push({ name: '─'.repeat(20), value: '__separator__' }, { name: 'Cancel', value: cancelValue ?? '__cancel__' });
+        }
+        const { selection } = await inquirer.prompt([{
+                type: 'list',
+                name: 'selection',
+                message,
+                choices: interactiveChoices,
+            }]);
+        if (selection === '__cancel__' || selection === '__separator__') {
+            return null;
+        }
+        return selection;
+    }
+    /**
+     * Prompt for input with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs field info as JSON and exits
+     * In interactive mode: shows prompt and returns input value
+     *
+     * @param options Configuration for the input
+     * @returns The input value (only in interactive mode)
+     */
+    async promptForInput(options) {
+        const { message, fieldName, defaultValue, validate, jsonMode } = options;
+        // Check for JSON mode
+        if (jsonMode && shouldOutputJson(jsonMode.flags)) {
+            outputPromptAsJson({
+                type: 'input',
+                name: fieldName,
+                message,
+                default: defaultValue,
+                context: {
+                    hint: jsonMode.commandHint,
+                    example: jsonMode.example,
+                },
+            }, createMetadata(jsonMode.commandName, jsonMode.flags));
+            // outputPromptAsJson exits, so this is unreachable
+            return '';
+        }
+        // Interactive mode
+        const { value } = await inquirer.prompt([{
+                type: 'input',
+                name: 'value',
+                message,
+                default: defaultValue,
+                validate,
+            }]);
+        return value;
+    }
+    /**
+     * Override run() to delegate to execute() and ensure cleanup
+     * Subclasses should implement execute() instead of run()
+     */
+    async run() {
+        try {
+            await this.execute();
+        }
+        finally {
+            await this.cleanup();
+        }
+    }
+    /**
+     * Cleanup handler - ensures storage is closed
+     * Called automatically after execute() completes or throws
+     */
+    async cleanup() {
+        if (this.contextInitialized && this.pmoContext?.storage) {
+            try {
+                await this.pmoContext.storage.close();
+            }
+            catch {
+                // Ignore close errors - storage might already be closed
+            }
+        }
+    }
+    /**
+     * oclif catch hook - called when an error occurs
+     * Ensures cleanup even on errors
+     */
+    async catch(error) {
+        await this.cleanup();
+        throw error;
+    }
+    /**
+     * oclif finally hook - called after run() completes
+     */
+    async finally(_) {
+        await this.cleanup();
+    }
+    // Convenience getters for common context properties
+    /** Storage instance */
+    get storage() {
+        return this.pmoContext.storage;
+    }
+    /** PMO directory path */
+    get pmoPath() {
+        return this.pmoContext.pmoPath;
+    }
+}

package/dist/lib/pmo/create-spec-folders.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Create PMO folder structure
+ *
+ * Two distinct areas:
+ * 1. product/ - Living product definitions (specs, requirements, architecture)
+ *    These don't move - they get updated in place as the product evolves.
+ *
+ * 2. projects/{id}/ - Implementation work that flows through lifecycle
+ *    - epics/ with draft/active/complete stages
+ *    - board.md for tracking tickets
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to created project directory
+ */
+export declare function createSpecFolders(pmoPath: string, projectId: string): string;
+/**
+ * Get product folder path (for specs/requirements - PMO-wide)
+ *
+ * @param pmoPath - Path to PMO directory
+ * @returns Path to product directory
+ */
+export declare function getProductPath(pmoPath: string): string;
+/**
+ * Get epics folder path for a project
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to epics directory
+ */
+export declare function getEpicsPath(pmoPath: string, projectId: string): string;
+/**
+ * @deprecated Use getProductPath() for specs, getEpicsPath() for implementation work
+ */
+export declare function getSpecFolderPath(pmoPath: string, projectId: string): string;
+/**
+ * Get project folder path
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to project directory
+ */
+export declare function getProjectPath(pmoPath: string, projectId: string): string;

package/dist/lib/pmo/create-spec-folders.js

@@ -0,0 +1,64 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Create PMO folder structure
+ *
+ * Two distinct areas:
+ * 1. product/ - Living product definitions (specs, requirements, architecture)
+ *    These don't move - they get updated in place as the product evolves.
+ *
+ * 2. projects/{id}/ - Implementation work that flows through lifecycle
+ *    - epics/ with draft/active/complete stages
+ *    - board.md for tracking tickets
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to created project directory
+ */
+export function createSpecFolders(pmoPath, projectId) {
+    // Create product folder for specs/requirements (PMO-wide, not per-project)
+    const productPath = path.join(pmoPath, 'product');
+    fs.mkdirSync(productPath, { recursive: true });
+    // Create project folder with epics lifecycle
+    const projectPath = path.join(pmoPath, 'projects', projectId);
+    const epicsPath = path.join(projectPath, 'epics');
+    fs.mkdirSync(path.join(epicsPath, 'draft'), { recursive: true });
+    fs.mkdirSync(path.join(epicsPath, 'active'), { recursive: true });
+    fs.mkdirSync(path.join(epicsPath, 'complete'), { recursive: true });
+    return projectPath;
+}
+/**
+ * Get product folder path (for specs/requirements - PMO-wide)
+ *
+ * @param pmoPath - Path to PMO directory
+ * @returns Path to product directory
+ */
+export function getProductPath(pmoPath) {
+    return path.join(pmoPath, 'product');
+}
+/**
+ * Get epics folder path for a project
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to epics directory
+ */
+export function getEpicsPath(pmoPath, projectId) {
+    return path.join(pmoPath, 'projects', projectId, 'epics');
+}
+/**
+ * @deprecated Use getProductPath() for specs, getEpicsPath() for implementation work
+ */
+export function getSpecFolderPath(pmoPath, projectId) {
+    return path.join(pmoPath, 'projects', projectId, 'epics');
+}
+/**
+ * Get project folder path
+ *
+ * @param pmoPath - Path to PMO directory
+ * @param projectId - Project ID
+ * @returns Path to project directory
+ */
+export function getProjectPath(pmoPath, projectId) {
+    return path.join(pmoPath, 'projects', projectId);
+}

package/dist/lib/pmo/epic-files.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Epic File Operations
+ *
+ * Handles creating, moving, and managing epic markdown files
+ * in the PMO folder structure.
+ */
+import { Epic, EpicStatus } from './types.js';
+/**
+ * Get the epics directory for a project
+ */
+export declare function getEpicsDir(pmoPath: string, projectId?: string): string;
+/**
+ * Get the path to an epic's markdown file
+ */
+export declare function getEpicFilePath(pmoPath: string, epicId: string, status: EpicStatus, projectId?: string): string;
+/**
+ * Ensure epic status directories exist
+ */
+export declare function ensureEpicDirs(pmoPath: string, projectId?: string): void;
+/**
+ * Ticket info for markdown generation
+ */
+export interface TicketInfo {
+    id: string;
+    title: string;
+    status?: string;
+    priority?: string;
+}
+/**
+ * Generate markdown content for an epic
+ */
+export declare function generateEpicMarkdown(epic: Epic, tickets?: TicketInfo[]): string;
+/**
+ * Update the Tickets section of an existing epic markdown file
+ * This is a one-way sync: database → markdown
+ */
+export declare function updateEpicTicketsSection(pmoPath: string, epicId: string, status: EpicStatus, tickets: TicketInfo[], projectId?: string): boolean;
+/**
+ * Create an epic markdown file
+ */
+export declare function createEpicFile(pmoPath: string, epic: Epic, projectId?: string): string;
+/**
+ * Move an epic file to a new status directory
+ */
+export declare function moveEpicFile(pmoPath: string, epicId: string, fromStatus: EpicStatus, toStatus: EpicStatus, projectId?: string): {
+    oldPath: string;
+    newPath: string;
+} | null;
+/**
+ * Delete an epic file
+ */
+export declare function deleteEpicFile(pmoPath: string, epicId: string, status: EpicStatus, projectId?: string): boolean;
+/**
+ * Get relative path from PMO root for display
+ */
+export declare function getRelativeEpicPath(pmoPath: string, epicId: string, status: EpicStatus, projectId?: string): string;

package/dist/lib/pmo/epic-files.js

@@ -0,0 +1,195 @@
+/**
+ * Epic File Operations
+ *
+ * Handles creating, moving, and managing epic markdown files
+ * in the PMO folder structure.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Get the epics directory for a project
+ */
+export function getEpicsDir(pmoPath, projectId = 'default') {
+    // For default project, use pmo/epics directly
+    // For named projects, use pmo/projects/{projectId}/epics
+    if (projectId === 'default') {
+        return path.join(pmoPath, 'epics');
+    }
+    return path.join(pmoPath, 'projects', projectId, 'epics');
+}
+/**
+ * Get the path to an epic's markdown file
+ */
+export function getEpicFilePath(pmoPath, epicId, status, projectId = 'default') {
+    const epicsDir = getEpicsDir(pmoPath, projectId);
+    return path.join(epicsDir, status, `${epicId}.md`);
+}
+/**
+ * Ensure epic status directories exist
+ */
+export function ensureEpicDirs(pmoPath, projectId = 'default') {
+    const epicsDir = getEpicsDir(pmoPath, projectId);
+    const statuses = ['active', 'draft', 'complete', 'dropped', 'future'];
+    for (const status of statuses) {
+        const statusDir = path.join(epicsDir, status);
+        if (!fs.existsSync(statusDir)) {
+            fs.mkdirSync(statusDir, { recursive: true });
+        }
+    }
+}
+/**
+ * Generate markdown content for an epic
+ */
+export function generateEpicMarkdown(epic, tickets = []) {
+    const lines = [];
+    // YAML frontmatter
+    lines.push('---');
+    lines.push(`id: ${epic.id}`);
+    lines.push(`title: ${epic.title}`);
+    lines.push(`status: ${epic.status}`);
+    lines.push(`created: ${epic.createdAt.toISOString()}`);
+    if (epic.description) {
+        lines.push(`description: ${epic.description}`);
+    }
+    lines.push('---');
+    lines.push('');
+    // Title
+    lines.push(`# ${epic.title}`);
+    lines.push('');
+    // Overview section
+    lines.push('## Overview');
+    if (epic.description) {
+        lines.push(epic.description);
+    }
+    else {
+        lines.push('[Describe what this epic covers]');
+    }
+    lines.push('');
+    // Motivation section
+    lines.push('## Motivation');
+    lines.push('[Why this work matters - the problem being solved or opportunity being captured]');
+    lines.push('');
+    // Goals section
+    lines.push('## Goals');
+    lines.push('- [ ] Goal 1');
+    lines.push('- [ ] Goal 2');
+    lines.push('');
+    // Success Criteria section
+    lines.push('## Success Criteria');
+    lines.push('- [ ] Criterion 1');
+    lines.push('');
+    // Tickets section
+    lines.push('## Tickets');
+    lines.push('');
+    if (tickets.length === 0) {
+        lines.push('_No tickets linked yet. Create tickets with:_');
+        lines.push('```bash');
+        lines.push(`prlt ticket create --epic ${epic.id} "Task title"`);
+        lines.push('```');
+    }
+    else {
+        const doneCount = tickets.filter(t => t.status === 'done').length;
+        lines.push(`Progress: ${doneCount}/${tickets.length} complete`);
+        lines.push('');
+        for (const ticket of tickets) {
+            const emoji = ticket.status === 'done' ? '✅' : ticket.status === 'in_progress' ? '🚧' : '📋';
+            const priority = ticket.priority ? ` [${ticket.priority}]` : '';
+            lines.push(`- ${emoji} ${ticket.id}: ${ticket.title}${priority}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Update the Tickets section of an existing epic markdown file
+ * This is a one-way sync: database → markdown
+ */
+export function updateEpicTicketsSection(pmoPath, epicId, status, tickets, projectId = 'default') {
+    const filePath = getEpicFilePath(pmoPath, epicId, status, projectId);
+    if (!fs.existsSync(filePath)) {
+        return false;
+    }
+    let content = fs.readFileSync(filePath, 'utf-8');
+    // Find and replace the Tickets section
+    const ticketsSectionRegex = /## Tickets\n[\s\S]*?(?=\n## |\n---|\z|$)/;
+    // Generate new tickets section
+    const ticketsLines = ['## Tickets', ''];
+    if (tickets.length === 0) {
+        ticketsLines.push('_No tickets linked yet. Create tickets with:_');
+        ticketsLines.push('```bash');
+        ticketsLines.push(`prlt ticket create --epic ${epicId} "Task title"`);
+        ticketsLines.push('```');
+    }
+    else {
+        const doneCount = tickets.filter(t => t.status === 'done').length;
+        ticketsLines.push(`Progress: ${doneCount}/${tickets.length} complete`);
+        ticketsLines.push('');
+        for (const ticket of tickets) {
+            const emoji = ticket.status === 'done' ? '✅' : ticket.status === 'in_progress' ? '🚧' : '📋';
+            const priority = ticket.priority ? ` [${ticket.priority}]` : '';
+            ticketsLines.push(`- ${emoji} ${ticket.id}: ${ticket.title}${priority}`);
+        }
+    }
+    ticketsLines.push('');
+    const newTicketsSection = ticketsLines.join('\n');
+    if (ticketsSectionRegex.test(content)) {
+        // Replace existing section
+        content = content.replace(ticketsSectionRegex, newTicketsSection);
+    }
+    else {
+        // Append section at end
+        content = content.trimEnd() + '\n\n' + newTicketsSection;
+    }
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return true;
+}
+/**
+ * Create an epic markdown file
+ */
+export function createEpicFile(pmoPath, epic, projectId = 'default') {
+    ensureEpicDirs(pmoPath, projectId);
+    const filePath = getEpicFilePath(pmoPath, epic.id, epic.status, projectId);
+    const content = generateEpicMarkdown(epic);
+    fs.writeFileSync(filePath, content, 'utf-8');
+    return filePath;
+}
+/**
+ * Move an epic file to a new status directory
+ */
+export function moveEpicFile(pmoPath, epicId, fromStatus, toStatus, projectId = 'default') {
+    ensureEpicDirs(pmoPath, projectId);
+    const oldPath = getEpicFilePath(pmoPath, epicId, fromStatus, projectId);
+    const newPath = getEpicFilePath(pmoPath, epicId, toStatus, projectId);
+    if (!fs.existsSync(oldPath)) {
+        return null;
+    }
+    // Read the file content
+    let content = fs.readFileSync(oldPath, 'utf-8');
+    // Update the status in frontmatter
+    content = content.replace(/^status: .+$/m, `status: ${toStatus}`);
+    // Write to new location
+    fs.writeFileSync(newPath, content, 'utf-8');
+    // Delete old file
+    fs.unlinkSync(oldPath);
+    return { oldPath, newPath };
+}
+/**
+ * Delete an epic file
+ */
+export function deleteEpicFile(pmoPath, epicId, status, projectId = 'default') {
+    const filePath = getEpicFilePath(pmoPath, epicId, status, projectId);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        return true;
+    }
+    return false;
+}
+/**
+ * Get relative path from PMO root for display
+ */
+export function getRelativeEpicPath(pmoPath, epicId, status, projectId = 'default') {
+    const fullPath = getEpicFilePath(pmoPath, epicId, status, projectId);
+    // Get path relative to pmo directory's parent (the HQ root)
+    const hqRoot = path.dirname(pmoPath);
+    return path.relative(hqRoot, fullPath);
+}

package/dist/lib/pmo/find-pmo.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Find PMO directory by checking workspace.db for pmo_projects table
+ *
+ * Search priority:
+ * 1. PRLT_HQ_PATH env var (ONLY when DEVCONTAINER=true - for devcontainer mounts)
+ * 2. Current directory tree for HQ with PMO
+ * 3. Current directory tree for standalone PMO (.pmo/)
+ * 4. ~/.proletariat/config.json activeWorkspace (fallback when NOT in any workspace)
+ * 5. Global config for default PMO
+ *
+ * NOTE: PRLT_HQ_PATH is ignored on host machines to support multiple agents
+ * working in different workspaces simultaneously.
+ */
+export declare function findPMO(): string | null;