@proletariat/cli 0.2.0 → 0.3.0

package/dist/lib/pmo/spec-parser.js

@@ -0,0 +1,205 @@
+/**
+ * Spec Parser
+ *
+ * Parses markdown spec files into structured data.
+ * Uses the new simplified spec format with frontmatter.
+ */
+import * as fs from 'node:fs';
+import matter from 'gray-matter';
+// =============================================================================
+// Main Parser
+// =============================================================================
+/**
+ * Parse a spec markdown file into structured data
+ */
+export function parseSpecFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseSpecContent(content, filePath);
+}
+/**
+ * Parse spec content string into structured data
+ */
+export function parseSpecContent(content, filePath = '') {
+    const { data: rawFrontmatter, content: body } = matter(content);
+    const frontmatter = {
+        id: rawFrontmatter.id,
+        status: rawFrontmatter.status,
+        type: rawFrontmatter.type,
+        tags: rawFrontmatter.tags,
+        depends_on: rawFrontmatter.depends_on,
+    };
+    return {
+        frontmatter,
+        title: parseTitle(body),
+        problem: parseSection(body, 'Problem'),
+        solution: parseSection(body, 'Solution'),
+        decisions: parseSection(body, 'Decisions'),
+        notNow: parseSection(body, 'Not Now'),
+        uiUx: parseSection(body, 'UI/UX'),
+        acceptanceCriteria: parseSection(body, 'Acceptance Criteria'),
+        openQuestions: parseSection(body, 'Open Questions'),
+        requirementsFunctional: parseNestedSection(body, 'Requirements', 'Functional'),
+        requirementsTechnical: parseNestedSection(body, 'Requirements', 'Technical'),
+        context: parseSection(body, 'Context'),
+        rawContent: content,
+        filePath,
+    };
+}
+// =============================================================================
+// Section Parsers
+// =============================================================================
+/**
+ * Parse title from the first H1 heading
+ */
+function parseTitle(body) {
+    const match = body.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : 'Untitled';
+}
+/**
+ * Parse a section by heading name
+ */
+function parseSection(body, sectionName) {
+    // Match ## Section Name followed by content until next ## or end
+    const regex = new RegExp(`## ${sectionName}\\s*\\n+([\\s\\S]*?)(?=\\n## [^#]|$)`, 'i');
+    const match = body.match(regex);
+    if (!match)
+        return undefined;
+    const content = match[1].trim();
+    return content || undefined;
+}
+/**
+ * Parse a nested section (e.g., ## Requirements -> ### Functional)
+ */
+function parseNestedSection(body, parentSection, childSection) {
+    // First find the parent section
+    const parentRegex = new RegExp(`## ${parentSection}\\s*\\n+([\\s\\S]*?)(?=\\n## [^#]|$)`, 'i');
+    const parentMatch = body.match(parentRegex);
+    if (!parentMatch)
+        return undefined;
+    const parentContent = parentMatch[1];
+    // Then find the child section within it
+    const childRegex = new RegExp(`### ${childSection}\\s*\\n+([\\s\\S]*?)(?=\\n### |$)`, 'i');
+    const childMatch = parentContent.match(childRegex);
+    if (!childMatch)
+        return undefined;
+    const content = childMatch[1].trim();
+    return content || undefined;
+}
+// =============================================================================
+// Validation
+// =============================================================================
+/**
+ * Validate a parsed spec for completeness
+ */
+export function validateSpec(spec) {
+    const errors = [];
+    if (!spec.frontmatter.id) {
+        errors.push('Missing id in frontmatter');
+    }
+    if (!spec.title || spec.title === 'Untitled') {
+        errors.push('Missing title (H1 heading)');
+    }
+    if (!spec.problem) {
+        errors.push('Missing Problem section');
+    }
+    if (!spec.solution) {
+        errors.push('Missing Solution section');
+    }
+    return errors;
+}
+// =============================================================================
+// Export Format
+// =============================================================================
+/**
+ * Convert a parsed spec back to markdown format
+ */
+export function specToMarkdown(spec, options) {
+    const lines = [];
+    // Frontmatter
+    if (options?.includeFrontmatter !== false) {
+        lines.push('---');
+        if (spec.frontmatter.id)
+            lines.push(`id: ${spec.frontmatter.id}`);
+        if (spec.frontmatter.status)
+            lines.push(`status: ${spec.frontmatter.status}`);
+        if (spec.frontmatter.type)
+            lines.push(`type: ${spec.frontmatter.type}`);
+        if (spec.frontmatter.tags && spec.frontmatter.tags.length > 0) {
+            lines.push(`tags: [${spec.frontmatter.tags.join(', ')}]`);
+        }
+        if (spec.frontmatter.depends_on && spec.frontmatter.depends_on.length > 0) {
+            lines.push(`depends_on: [${spec.frontmatter.depends_on.join(', ')}]`);
+        }
+        lines.push('---');
+        lines.push('');
+    }
+    // Title
+    lines.push(`# ${spec.title}`);
+    lines.push('');
+    // Sections
+    if (spec.problem) {
+        lines.push('## Problem');
+        lines.push('');
+        lines.push(spec.problem);
+        lines.push('');
+    }
+    if (spec.solution) {
+        lines.push('## Solution');
+        lines.push('');
+        lines.push(spec.solution);
+        lines.push('');
+    }
+    if (spec.decisions) {
+        lines.push('## Decisions');
+        lines.push('');
+        lines.push(spec.decisions);
+        lines.push('');
+    }
+    if (spec.notNow) {
+        lines.push('## Not Now');
+        lines.push('');
+        lines.push(spec.notNow);
+        lines.push('');
+    }
+    if (spec.uiUx) {
+        lines.push('## UI/UX');
+        lines.push('');
+        lines.push(spec.uiUx);
+        lines.push('');
+    }
+    if (spec.acceptanceCriteria) {
+        lines.push('## Acceptance Criteria');
+        lines.push('');
+        lines.push(spec.acceptanceCriteria);
+        lines.push('');
+    }
+    if (spec.openQuestions) {
+        lines.push('## Open Questions');
+        lines.push('');
+        lines.push(spec.openQuestions);
+        lines.push('');
+    }
+    if (spec.requirementsFunctional || spec.requirementsTechnical) {
+        lines.push('## Requirements');
+        lines.push('');
+        if (spec.requirementsFunctional) {
+            lines.push('### Functional');
+            lines.push('');
+            lines.push(spec.requirementsFunctional);
+            lines.push('');
+        }
+        if (spec.requirementsTechnical) {
+            lines.push('### Technical');
+            lines.push('');
+            lines.push(spec.requirementsTechnical);
+            lines.push('');
+        }
+    }
+    if (spec.context) {
+        lines.push('## Context');
+        lines.push('');
+        lines.push(spec.context);
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/lib/pmo/spec-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Spec Format Type Definitions
+ *
+ * Types for parsing spec documents with frontmatter.
+ * DB types are in types.ts (Spec, SpecDependency)
+ */
+export { SpecType, SpecStatus, Spec, SpecDependency, } from './types.js';
+/**
+ * Spec frontmatter - parsed from YAML at top of markdown file
+ */
+export interface SpecFrontmatter {
+    id?: string;
+    status?: 'draft' | 'active' | 'implemented';
+    type?: 'product' | 'platform' | 'infra' | 'integration';
+    tags?: string[];
+    depends_on?: string[];
+}
+/**
+ * A spec parsed from a markdown file
+ */
+export interface ParsedSpec {
+    frontmatter: SpecFrontmatter;
+    title: string;
+    problem?: string;
+    solution?: string;
+    decisions?: string;
+    notNow?: string;
+    uiUx?: string;
+    acceptanceCriteria?: string;
+    openQuestions?: string;
+    requirementsFunctional?: string;
+    requirementsTechnical?: string;
+    context?: string;
+    rawContent: string;
+    filePath: string;
+}
+/**
+ * Format for exporting spec to markdown
+ */
+export interface SpecExportOptions {
+    includeFrontmatter?: boolean;
+    includeEmptySections?: boolean;
+}

package/dist/lib/pmo/spec-types.js

@@ -0,0 +1,7 @@
+/**
+ * Spec Format Type Definitions
+ *
+ * Types for parsing spec documents with frontmatter.
+ * DB types are in types.ts (Spec, SpecDependency)
+ */
+export {};

package/dist/lib/pmo/storage/actions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Work action operations.
+ */
+import { StateCategory, WorkAction, WorkActionFilter } from '../types.js';
+import { StorageContext } from './types.js';
+export declare class ActionStorage {
+    private ctx;
+    constructor(ctx: StorageContext);
+    /**
+     * List work actions.
+     */
+    listActions(filter?: WorkActionFilter): Promise<WorkAction[]>;
+    /**
+     * Get a work action by ID.
+     */
+    getAction(id: string): Promise<WorkAction | null>;
+    /**
+     * Create a new work action.
+     */
+    createAction(action: Partial<WorkAction>): Promise<WorkAction>;
+    /**
+     * Update a work action.
+     */
+    updateAction(id: string, changes: Partial<WorkAction>): Promise<WorkAction>;
+    /**
+     * Delete a work action.
+     */
+    deleteAction(id: string): Promise<void>;
+    /**
+     * Get suggested action for a state category.
+     */
+    getSuggestedAction(category: StateCategory): Promise<WorkAction | null>;
+    private rowToAction;
+}

package/dist/lib/pmo/storage/actions.js

@@ -0,0 +1,177 @@
+/**
+ * Work action operations.
+ */
+import { PMO_TABLES } from '../schema.js';
+import { PMOError } from '../types.js';
+import { slugify } from '../utils.js';
+const T = PMO_TABLES;
+export class ActionStorage {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * List work actions.
+     */
+    async listActions(filter) {
+        let sql = `SELECT * FROM ${T.actions}`;
+        const conditions = [];
+        const params = [];
+        if (filter?.isBuiltin !== undefined) {
+            conditions.push('is_builtin = ?');
+            params.push(filter.isBuiltin ? 1 : 0);
+        }
+        if (filter?.suggestedFor) {
+            conditions.push('suggested_for_categories LIKE ?');
+            params.push(`%"${filter.suggestedFor}"%`);
+        }
+        if (filter?.search) {
+            conditions.push('(name LIKE ? OR description LIKE ?)');
+            params.push(`%${filter.search}%`, `%${filter.search}%`);
+        }
+        if (conditions.length > 0) {
+            sql += ` WHERE ${conditions.join(' AND ')}`;
+        }
+        sql += ' ORDER BY is_builtin DESC, position ASC, name ASC';
+        const rows = this.ctx.db.prepare(sql).all(...params);
+        return rows.map((row) => this.rowToAction(row));
+    }
+    /**
+     * Get a work action by ID.
+     */
+    async getAction(id) {
+        const row = this.ctx.db.prepare(`SELECT * FROM ${T.actions} WHERE id = ?`).get(id);
+        if (!row)
+            return null;
+        return this.rowToAction(row);
+    }
+    /**
+     * Create a new work action.
+     */
+    async createAction(action) {
+        if (!action.name) {
+            throw new PMOError('INVALID', 'Action name is required');
+        }
+        if (!action.prompt) {
+            throw new PMOError('INVALID', 'Action prompt is required');
+        }
+        const id = action.id || slugify(action.name);
+        // Check for duplicate name
+        const existing = this.ctx.db.prepare(`
+      SELECT id FROM ${T.actions} WHERE LOWER(name) = LOWER(?)
+    `).get(action.name);
+        if (existing) {
+            throw new PMOError('CONFLICT', `Action with name "${action.name}" already exists`);
+        }
+        const now = new Date().toISOString();
+        const modifiesCode = action.modifiesCode !== false;
+        this.ctx.db.prepare(`
+      INSERT INTO ${T.actions} (id, name, description, prompt, end_prompt, suggested_for_categories, default_move_to_category, modifies_code, is_builtin, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, action.name, action.description || null, action.prompt, action.endPrompt || null, action.suggestedForCategories ? JSON.stringify(action.suggestedForCategories) : null, action.defaultMoveToCategory || null, modifiesCode ? 1 : 0, action.isBuiltin ? 1 : 0, now);
+        return {
+            id,
+            name: action.name,
+            description: action.description,
+            prompt: action.prompt,
+            endPrompt: action.endPrompt,
+            suggestedForCategories: action.suggestedForCategories,
+            defaultMoveToCategory: action.defaultMoveToCategory,
+            modifiesCode,
+            isBuiltin: action.isBuiltin || false,
+            createdAt: new Date(now),
+        };
+    }
+    /**
+     * Update a work action.
+     */
+    async updateAction(id, changes) {
+        const existing = await this.getAction(id);
+        if (!existing) {
+            throw new PMOError('NOT_FOUND', `Action not found: ${id}`);
+        }
+        if (existing.isBuiltin) {
+            throw new PMOError('INVALID', 'Cannot modify built-in actions');
+        }
+        // Check for duplicate name if name is changing
+        if (changes.name && changes.name.toLowerCase() !== existing.name.toLowerCase()) {
+            const dup = this.ctx.db.prepare(`
+        SELECT id FROM ${T.actions} WHERE LOWER(name) = LOWER(?) AND id != ?
+      `).get(changes.name, id);
+            if (dup) {
+                throw new PMOError('CONFLICT', `Action "${changes.name}" already exists`);
+            }
+        }
+        const updates = [];
+        const params = [];
+        if (changes.name !== undefined) {
+            updates.push('name = ?');
+            params.push(changes.name);
+        }
+        if (changes.description !== undefined) {
+            updates.push('description = ?');
+            params.push(changes.description || null);
+        }
+        if (changes.prompt !== undefined) {
+            updates.push('prompt = ?');
+            params.push(changes.prompt);
+        }
+        if (changes.endPrompt !== undefined) {
+            updates.push('end_prompt = ?');
+            params.push(changes.endPrompt || null);
+        }
+        if (changes.suggestedForCategories !== undefined) {
+            updates.push('suggested_for_categories = ?');
+            params.push(changes.suggestedForCategories ? JSON.stringify(changes.suggestedForCategories) : null);
+        }
+        if (changes.defaultMoveToCategory !== undefined) {
+            updates.push('default_move_to_category = ?');
+            params.push(changes.defaultMoveToCategory || null);
+        }
+        if (changes.modifiesCode !== undefined) {
+            updates.push('modifies_code = ?');
+            params.push(changes.modifiesCode ? 1 : 0);
+        }
+        if (updates.length > 0) {
+            params.push(id);
+            this.ctx.db.prepare(`UPDATE ${T.actions} SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        }
+        return (await this.getAction(id));
+    }
+    /**
+     * Delete a work action.
+     */
+    async deleteAction(id) {
+        const existing = await this.getAction(id);
+        if (!existing) {
+            throw new PMOError('NOT_FOUND', `Action not found: ${id}`);
+        }
+        if (existing.isBuiltin) {
+            throw new PMOError('INVALID', 'Cannot delete built-in actions');
+        }
+        this.ctx.db.prepare(`DELETE FROM ${T.actions} WHERE id = ?`).run(id);
+    }
+    /**
+     * Get suggested action for a state category.
+     */
+    async getSuggestedAction(category) {
+        const actions = await this.listActions({ suggestedFor: category });
+        return actions.length > 0 ? actions[0] : null;
+    }
+    rowToAction(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            description: row.description || undefined,
+            prompt: row.prompt,
+            endPrompt: row.end_prompt || undefined,
+            suggestedForCategories: row.default_category
+                ? JSON.parse(row.default_category)
+                : undefined,
+            defaultMoveToCategory: row.default_category,
+            modifiesCode: row.is_builtin === 1,
+            isBuiltin: row.is_builtin === 1,
+            createdAt: new Date(row.created_at),
+        };
+    }
+}

package/dist/lib/pmo/storage/base.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Base storage module with database initialization, migrations, and seeding.
+ * This module handles database setup and provides shared utilities.
+ */
+import Database from 'better-sqlite3';
+/**
+ * Initialize PMO tables in the database.
+ * Runs migrations, creates tables, seeds built-in data, and validates schema.
+ */
+export declare function initializePMOTables(db: Database.Database): void;
+/**
+ * Run schema migrations for existing databases.
+ */
+export declare function runMigrations(db: Database.Database): void;
+/**
+ * Seed built-in workflows (shared workflow definitions).
+ * Creates workflows from existing templates for reuse across projects.
+ */
+export declare function seedBuiltinWorkflows(db: Database.Database): void;
+/**
+ * Seed default project phases.
+ */
+export declare function seedBuiltinPhases(db: Database.Database): void;
+/**
+ * Seed built-in phase templates.
+ */
+export declare function seedBuiltinPhaseTemplates(db: Database.Database): void;
+/**
+ * Seed built-in work actions.
+ */
+export declare function seedBuiltinActions(db: Database.Database): void;
+/**
+ * Seed built-in ticket templates.
+ */
+export declare function seedBuiltinTicketTemplates(db: Database.Database): void;
+/**
+ * Update board timestamp for a project.
+ */
+export declare function updateBoardTimestamp(db: Database.Database, projectId: string): void;
+/**
+ * Get max position for columns in a project.
+ */
+export declare function getMaxColumnPosition(db: Database.Database, projectId: string): number;
+/**
+ * Get max position for tickets in a column.
+ */
+export declare function getMaxTicketPosition(db: Database.Database, projectId: string, columnId: string): number;