@proletariat/cli 0.2.0 → 0.3.1

package/dist/lib/pmo/types.js

@@ -0,0 +1,108 @@
+/**
+ * PMO Interface Types
+ *
+ * Canonical interface for the Project Management Orchestration system.
+ * All storage backends must implement the PMOStorage interface.
+ *
+ * Hierarchy:
+ * - Initiative (optional) - OKR-level grouping
+ * - Project - Discrete effort with its own board + specs
+ * - Epic (optional) - Large body of work within a project
+ * - Ticket - Individual work item
+ * - Subtask - Smallest actionable piece
+ */
+/**
+ * Valid priority values as a const array for validation and CLI options.
+ */
+export const PRIORITIES = ['P0', 'P1', 'P2', 'P3'];
+/**
+ * Priority display names for UI presentation.
+ */
+export const PRIORITY_LABELS = {
+    P0: 'P0 - Critical',
+    P1: 'P1 - High',
+    P2: 'P2 - Medium',
+    P3: 'P3 - Low',
+};
+/**
+ * Mapping from legacy priority values to new P0-P3 format.
+ */
+export const LEGACY_PRIORITY_MAP = {
+    URGENT: 'P0',
+    HIGH: 'P1',
+    MEDIUM: 'P2',
+    LOW: 'P3',
+};
+/**
+ * Ticket categories for classification.
+ */
+export const TICKET_CATEGORIES = [
+    'feature',
+    'bug',
+    'refactor',
+    'docs',
+    'test',
+    'chore',
+    'performance',
+    'ci',
+    'build',
+    'security',
+    'database',
+    'release',
+];
+/**
+ * Check if a string is a valid Priority value.
+ */
+export function isValidPriority(value) {
+    if (!value)
+        return false;
+    return PRIORITIES.includes(value);
+}
+/**
+ * Check if a string is a legacy priority value.
+ */
+export function isLegacyPriority(value) {
+    if (!value)
+        return false;
+    return value in LEGACY_PRIORITY_MAP;
+}
+/**
+ * Normalize a priority value to the new P0-P3 format.
+ * Converts legacy values (URGENT/HIGH/MEDIUM/LOW) to P0-P3.
+ * Returns undefined for invalid values.
+ */
+export function normalizePriority(value) {
+    if (!value)
+        return undefined;
+    // Already in new format
+    if (isValidPriority(value)) {
+        return value;
+    }
+    // Convert from legacy format
+    if (isLegacyPriority(value)) {
+        return LEGACY_PRIORITY_MAP[value];
+    }
+    // Unknown value
+    return undefined;
+}
+/**
+ * State category order for sorting columns/statuses
+ */
+export const STATE_CATEGORY_ORDER = [
+    'triage',
+    'backlog',
+    'unstarted',
+    'started',
+    'completed',
+    'canceled',
+];
+export class PMOError extends Error {
+    code;
+    ticketId;
+    constructor(code, message, ticketId) {
+        super(message);
+        this.code = code;
+        this.ticketId = ticketId;
+        this.name = 'PMOError';
+    }
+}

package/dist/lib/pmo/utils.d.ts

@@ -0,0 +1,122 @@
+/**
+ * PMO Utility Functions
+ */
+/**
+ * Convert a string to a URL-safe slug
+ */
+export declare function slugify(text: string): string;
+/**
+ * Format a date as ISO string (date only)
+ */
+export declare function formatDate(date: Date): string;
+/**
+ * Format a date as ISO timestamp
+ */
+export declare function formatTimestamp(date: Date): string;
+/**
+ * Parse an ISO date string
+ */
+export declare function parseDate(str: string): Date;
+/**
+ * Entity type prefixes for ID generation
+ */
+export declare const ENTITY_PREFIXES: {
+    readonly ticket: "TKT";
+    readonly epic: "EPIC";
+    readonly spec: "SPEC";
+    readonly project: "PROJ";
+};
+export type EntityType = keyof typeof ENTITY_PREFIXES;
+/**
+ * Database interface for ID generation (compatible with better-sqlite3)
+ */
+interface DatabaseLike {
+    prepare(sql: string): {
+        get(...params: unknown[]): unknown;
+        run(...params: unknown[]): unknown;
+    };
+}
+/**
+ * Generate a sequential ID for an entity.
+ *
+ * Format: TKT-001, EPIC-001, SPEC-001, PROJ-001
+ *
+ * Uses pmo_settings table to track the next ID for each entity type.
+ * IDs are zero-padded to 3 digits (001-999), then expand (1000+).
+ *
+ * @param db - Database instance with prepare method
+ * @param entityType - Type of entity (ticket, epic, spec, project)
+ * @returns Generated ID like "TKT-001"
+ */
+export declare function generateEntityId(db: DatabaseLike, entityType: EntityType): string;
+/**
+ * Parsed entity ID components
+ */
+export interface ParsedEntityId {
+    entityType: string;
+    number: number;
+    raw: string;
+}
+/**
+ * Parse an entity ID into its components.
+ *
+ * Format: TKT-001 → { entityType: 'TKT', number: 1 }
+ *
+ * @param id - Entity ID to parse
+ * @returns Parsed components, or null if invalid format
+ */
+export declare function parseEntityId(id: string): ParsedEntityId | null;
+/**
+ * Deep clone an object
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Default column names for work commands (Linear-style workflow)
+ *
+ * Linear-style: Backlog → Planned → In Progress → Done
+ * - planned: Move tickets here when scheduled/assigned
+ * - in_progress: Move tickets here when work starts
+ * - done: Move tickets here when work is complete (includes review/merged)
+ */
+export declare const DEFAULT_WORK_COLUMNS: {
+    readonly planned: "Planned";
+    readonly in_progress: "In Progress";
+    readonly done: "Done";
+};
+export type WorkColumnType = keyof typeof DEFAULT_WORK_COLUMNS;
+/**
+ * Get a work column setting from pmo_settings with fallback to default.
+ * Column matching is case-insensitive.
+ *
+ * Settings keys:
+ * - column_in_progress: Column to move tickets to when work starts
+ * - column_review: Column to move tickets to when work is ready for review
+ * - column_done: Column to move tickets to when work is complete
+ *
+ * @param db - Database instance
+ * @param columnType - Type of column (in_progress, review, done)
+ * @returns The configured column name, or the default if not set
+ */
+export declare function getWorkColumnSetting(db: DatabaseLike, columnType: WorkColumnType): string;
+/**
+ * Set a work column setting in pmo_settings.
+ *
+ * @param db - Database instance
+ * @param columnType - Type of column (in_progress, review, done)
+ * @param columnName - Name of the column to use
+ */
+export declare function setWorkColumnSetting(db: DatabaseLike, columnType: WorkColumnType, columnName: string): void;
+/**
+ * Find a column by configured name (case-insensitive match).
+ * Returns the actual column name from the board if found, null otherwise.
+ *
+ * @param columnNames - Array of column names from the board
+ * @param targetColumn - The column name to find (from settings or default)
+ * @returns The matching column name, or null if not found
+ */
+export declare function findColumnByName(columnNames: string[], targetColumn: string): string | null;
+/**
+ * Check if two arrays have the same elements (order-independent)
+ */
+export declare function arraysEqual<T>(a: T[], b: T[]): boolean;
+export {};

package/dist/lib/pmo/utils.js

@@ -0,0 +1,174 @@
+/**
+ * PMO Utility Functions
+ */
+/**
+ * Convert a string to a URL-safe slug
+ */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, '') // Remove non-word chars (except spaces and hyphens)
+        .replace(/[\s_]+/g, '-') // Replace spaces and underscores with hyphens
+        .replace(/-+/g, '-') // Replace multiple hyphens with single hyphen
+        .replace(/^-+|-+$/g, '') // Remove leading/trailing hyphens
+        .substring(0, 100); // Limit length
+}
+/**
+ * Format a date as ISO string (date only)
+ */
+export function formatDate(date) {
+    return date.toISOString().split('T')[0];
+}
+/**
+ * Format a date as ISO timestamp
+ */
+export function formatTimestamp(date) {
+    return date.toISOString();
+}
+/**
+ * Parse an ISO date string
+ */
+export function parseDate(str) {
+    return new Date(str);
+}
+/**
+ * Entity type prefixes for ID generation
+ */
+export const ENTITY_PREFIXES = {
+    ticket: 'TKT',
+    epic: 'EPIC',
+    spec: 'SPEC',
+    project: 'PROJ',
+};
+/**
+ * Generate a sequential ID for an entity.
+ *
+ * Format: TKT-001, EPIC-001, SPEC-001, PROJ-001
+ *
+ * Uses pmo_settings table to track the next ID for each entity type.
+ * IDs are zero-padded to 3 digits (001-999), then expand (1000+).
+ *
+ * @param db - Database instance with prepare method
+ * @param entityType - Type of entity (ticket, epic, spec, project)
+ * @returns Generated ID like "TKT-001"
+ */
+export function generateEntityId(db, entityType) {
+    const typePrefix = ENTITY_PREFIXES[entityType];
+    const settingKey = `next_${entityType}_id`;
+    // Get current counter
+    const row = db.prepare(`SELECT value FROM pmo_settings WHERE key = ?`).get(settingKey);
+    const nextNum = row ? parseInt(row.value, 10) : 1;
+    // Update counter
+    db.prepare(`
+    INSERT INTO pmo_settings (key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = ?
+  `).run(settingKey, String(nextNum + 1), String(nextNum + 1));
+    // Format ID with zero-padding (3 digits minimum)
+    const numStr = nextNum.toString().padStart(3, '0');
+    return `${typePrefix}-${numStr}`;
+}
+/**
+ * Parse an entity ID into its components.
+ *
+ * Format: TKT-001 → { entityType: 'TKT', number: 1 }
+ *
+ * @param id - Entity ID to parse
+ * @returns Parsed components, or null if invalid format
+ */
+export function parseEntityId(id) {
+    if (!id)
+        return null;
+    const match = id.match(/^([A-Z]+)-(\d+)$/);
+    if (match) {
+        return {
+            entityType: match[1],
+            number: parseInt(match[2], 10),
+            raw: id,
+        };
+    }
+    return null;
+}
+/**
+ * Deep clone an object
+ */
+export function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+// =============================================================================
+// Work Column Settings
+// =============================================================================
+/**
+ * Default column names for work commands (Linear-style workflow)
+ *
+ * Linear-style: Backlog → Planned → In Progress → Done
+ * - planned: Move tickets here when scheduled/assigned
+ * - in_progress: Move tickets here when work starts
+ * - done: Move tickets here when work is complete (includes review/merged)
+ */
+export const DEFAULT_WORK_COLUMNS = {
+    planned: 'Planned',
+    in_progress: 'In Progress',
+    done: 'Done',
+};
+/**
+ * Get a work column setting from pmo_settings with fallback to default.
+ * Column matching is case-insensitive.
+ *
+ * Settings keys:
+ * - column_in_progress: Column to move tickets to when work starts
+ * - column_review: Column to move tickets to when work is ready for review
+ * - column_done: Column to move tickets to when work is complete
+ *
+ * @param db - Database instance
+ * @param columnType - Type of column (in_progress, review, done)
+ * @returns The configured column name, or the default if not set
+ */
+export function getWorkColumnSetting(db, columnType) {
+    const settingKey = `column_${columnType}`;
+    const row = db.prepare(`SELECT value FROM pmo_settings WHERE key = ?`).get(settingKey);
+    return row?.value || DEFAULT_WORK_COLUMNS[columnType];
+}
+/**
+ * Set a work column setting in pmo_settings.
+ *
+ * @param db - Database instance
+ * @param columnType - Type of column (in_progress, review, done)
+ * @param columnName - Name of the column to use
+ */
+export function setWorkColumnSetting(db, columnType, columnName) {
+    const settingKey = `column_${columnType}`;
+    db.prepare(`
+    INSERT INTO pmo_settings (key, value) VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = ?
+  `).run(settingKey, columnName, columnName);
+}
+/**
+ * Find a column by configured name (case-insensitive match).
+ * Returns the actual column name from the board if found, null otherwise.
+ *
+ * @param columnNames - Array of column names from the board
+ * @param targetColumn - The column name to find (from settings or default)
+ * @returns The matching column name, or null if not found
+ */
+export function findColumnByName(columnNames, targetColumn) {
+    const targetLower = targetColumn.toLowerCase();
+    // First try exact match (case-insensitive)
+    const exactMatch = columnNames.find(col => col.toLowerCase() === targetLower);
+    if (exactMatch)
+        return exactMatch;
+    // Then try partial match (contains)
+    const partialMatch = columnNames.find(col => col.toLowerCase().includes(targetLower) ||
+        targetLower.includes(col.toLowerCase()));
+    return partialMatch || null;
+}
+/**
+ * Check if two arrays have the same elements (order-independent)
+ */
+export function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, idx) => val === sortedB[idx]);
+}

package/dist/lib/pmo/watcher.d.ts

@@ -0,0 +1,43 @@
+/**
+ * PMO Board Watcher
+ *
+ * Watches board.md for changes and automatically syncs to SQLite database.
+ * Uses chokidar for efficient cross-platform file watching.
+ *
+ * Features:
+ * - Debounced sync (waits for file to stabilize before syncing)
+ * - Hybrid mtime + content detection (avoids unnecessary syncs)
+ * - Graceful shutdown handling
+ */
+export interface WatcherOptions {
+    /** Debounce delay in milliseconds (default: 500) */
+    debounceMs?: number;
+    /** Logger function for status messages */
+    logger?: (msg: string) => void;
+    /** Callback when sync occurs */
+    onSync?: (stats: SyncStats) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+export interface SyncStats {
+    syncedAt: Date;
+    ticketCount: number;
+    durationMs: number;
+}
+export interface WatcherInstance {
+    /** Stop watching */
+    stop: () => Promise<void>;
+    /** Force a sync now */
+    syncNow: () => Promise<SyncStats>;
+    /** Check if watcher is running */
+    isRunning: () => boolean;
+}
+/**
+ * Start watching kanban.md for changes
+ */
+export declare function startWatcher(pmoPath: string, storageType: 'sqlite' | 'git', options?: WatcherOptions, projectId?: string): WatcherInstance;
+/**
+ * Run watcher as a foreground process (for CLI command)
+ * Handles SIGINT/SIGTERM for graceful shutdown
+ */
+export declare function runWatcherForeground(pmoPath: string, storageType: 'sqlite' | 'git', options?: WatcherOptions): Promise<void>;

package/dist/lib/pmo/watcher.js

@@ -0,0 +1,208 @@
+/**
+ * PMO Board Watcher
+ *
+ * Watches board.md for changes and automatically syncs to SQLite database.
+ * Uses chokidar for efficient cross-platform file watching.
+ *
+ * Features:
+ * - Debounced sync (waits for file to stabilize before syncing)
+ * - Hybrid mtime + content detection (avoids unnecessary syncs)
+ * - Graceful shutdown handling
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { watch } from 'chokidar';
+import { SQLiteStorage } from './storage-sqlite.js';
+import { parseBoard } from './markdown.js';
+/**
+ * Compute SHA-256 hash of content
+ */
+function computeHash(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Get the workspace.db path from a PMO path
+ */
+function getWorkspaceDbPath(pmoPath) {
+    const workspacePath = path.dirname(pmoPath);
+    return path.join(workspacePath, '.proletariat', 'workspace.db');
+}
+/**
+ * Start watching kanban.md for changes
+ */
+export function startWatcher(pmoPath, storageType, options = {}, projectId) {
+    const { debounceMs = 500, logger = () => { }, onSync, onError, } = options;
+    // Get board path - either from projectId or find first project
+    let boardPath;
+    if (projectId) {
+        boardPath = path.join(pmoPath, 'projects', projectId, 'kanban.md');
+        // Fall back to legacy board.md
+        if (!fs.existsSync(boardPath)) {
+            boardPath = path.join(pmoPath, 'projects', projectId, 'board.md');
+        }
+    }
+    else {
+        // Legacy: look for board.md in pmo root
+        boardPath = path.join(pmoPath, 'board.md');
+        if (!fs.existsSync(boardPath)) {
+            // Try to find first project
+            const projectsDir = path.join(pmoPath, 'projects');
+            if (fs.existsSync(projectsDir)) {
+                const projects = fs.readdirSync(projectsDir).filter(f => fs.statSync(path.join(projectsDir, f)).isDirectory());
+                if (projects.length > 0) {
+                    const firstProject = projects[0];
+                    boardPath = path.join(projectsDir, firstProject, 'kanban.md');
+                    if (!fs.existsSync(boardPath)) {
+                        boardPath = path.join(projectsDir, firstProject, 'board.md');
+                    }
+                }
+            }
+        }
+    }
+    // All storage types now use unified workspace.db
+    const dbPath = getWorkspaceDbPath(pmoPath);
+    // Validate paths exist
+    if (!fs.existsSync(boardPath)) {
+        throw new Error(`kanban.md not found at ${boardPath}`);
+    }
+    if (!fs.existsSync(dbPath)) {
+        throw new Error(`Database not found at ${dbPath}. Run 'prlt init' first.`);
+    }
+    let watcher = null;
+    let debounceTimer = null;
+    let lastHash = null;
+    let isRunning = true;
+    // Initialize last hash from current file
+    try {
+        const content = fs.readFileSync(boardPath, 'utf-8');
+        lastHash = computeHash(content);
+    }
+    catch {
+        // Ignore - will sync on first change
+    }
+    /**
+     * Perform sync from board.md to SQLite
+     */
+    async function doSync() {
+        const startTime = Date.now();
+        // Read and hash content
+        const content = fs.readFileSync(boardPath, 'utf-8');
+        const currentHash = computeHash(content);
+        // Check if content actually changed
+        if (currentHash === lastHash) {
+            logger('📋 board.md unchanged (hash match), skipping sync');
+            return {
+                syncedAt: new Date(),
+                ticketCount: 0,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        // Parse and sync
+        const board = parseBoard(content);
+        const storage = new SQLiteStorage(dbPath);
+        try {
+            storage.rebuildFromBoard(board);
+            // Update cache metadata
+            const stats = fs.statSync(boardPath);
+            storage.setCacheMetadata({
+                boardMtime: stats.mtimeMs,
+                cacheBuiltAt: Date.now(),
+                contentHash: currentHash,
+            });
+            // Count tickets
+            const ticketCount = board.columns.reduce((sum, col) => sum + col.tickets.length, 0);
+            lastHash = currentHash;
+            const syncStats = {
+                syncedAt: new Date(),
+                ticketCount,
+                durationMs: Date.now() - startTime,
+            };
+            logger(`📥 Synced board.md → SQLite (${ticketCount} tickets, ${syncStats.durationMs}ms)`);
+            if (onSync) {
+                onSync(syncStats);
+            }
+            return syncStats;
+        }
+        finally {
+            await storage.close();
+        }
+    }
+    /**
+     * Handle file change with debouncing
+     */
+    function handleChange(_eventPath) {
+        if (!isRunning)
+            return;
+        // Clear existing timer
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        // Set new timer
+        debounceTimer = setTimeout(async () => {
+            try {
+                await doSync();
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                logger(`❌ Sync error: ${err.message}`);
+                if (onError) {
+                    onError(err);
+                }
+            }
+        }, debounceMs);
+    }
+    // Start watching
+    watcher = watch(boardPath, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: 100,
+            pollInterval: 50,
+        },
+    });
+    watcher.on('change', handleChange);
+    watcher.on('error', (err) => {
+        const error = err instanceof Error ? err : new Error(String(err));
+        logger(`❌ Watcher error: ${error.message}`);
+        if (onError) {
+            onError(error);
+        }
+    });
+    logger(`👀 Watching ${boardPath} for changes...`);
+    return {
+        stop: async () => {
+            isRunning = false;
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+            }
+            if (watcher) {
+                await watcher.close();
+                watcher = null;
+            }
+            logger('🛑 Watcher stopped');
+        },
+        syncNow: async () => {
+            return doSync();
+        },
+        isRunning: () => isRunning,
+    };
+}
+/**
+ * Run watcher as a foreground process (for CLI command)
+ * Handles SIGINT/SIGTERM for graceful shutdown
+ */
+export async function runWatcherForeground(pmoPath, storageType, options = {}) {
+    const watcher = startWatcher(pmoPath, storageType, options);
+    // Handle graceful shutdown
+    const shutdown = async () => {
+        await watcher.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Keep process alive
+    await new Promise(() => {
+        // Never resolves - runs until signal
+    });
+}