@proletariat/cli 0.3.21 → 0.3.22

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

@@ -9,7 +9,7 @@
  */
 import Database from 'better-sqlite3';
 import { DrizzleDB } from '../../database/drizzle.js';
-import { AcceptanceCriterion, Board, BoardConfig, BoardView, BoardViewFilter, BoardViewFilters, Column, CreateTicketInput, Epic, EpicDependency, EpicDependencyType, EpicFilter, PhaseFilter, PhaseTemplate, PhaseTemplateFilter, PMOStorage, Project, ProjectFilter, ProjectPhase, Roadmap, RoadmapFilter, RoadmapProject, Spec, SpecDependency, SpecDependencyType, SpecFilter, StateCategory, Subtask, SyncResult, SyncStatus, Ticket, TicketDependency, TicketDependencyType, TicketFilter, TicketTemplate, TicketTemplateFilter, WorkAction, WorkActionFilter, Workflow, WorkflowFilter, WorkflowStatus } from '../types.js';
+import { AcceptanceCriterion, Board, BoardConfig, BoardView, BoardViewFilter, BoardViewFilters, Category, CategoryFilter, CategoryType, Column, CreateTicketInput, Epic, EpicDependency, EpicDependencyType, EpicFilter, PhaseFilter, PhaseTemplate, PhaseTemplateFilter, PMOStorage, Project, ProjectFilter, ProjectPhase, Roadmap, RoadmapFilter, RoadmapProject, Spec, SpecDependency, SpecDependencyType, SpecFilter, StateCategory, Subtask, SyncResult, SyncStatus, Ticket, TicketDependency, TicketDependencyType, TicketFilter, TicketTemplate, TicketTemplateFilter, WorkAction, WorkActionFilter, Workflow, WorkflowFilter, WorkflowStatus } from '../types.js';
 export declare class SQLiteStorage implements PMOStorage {
     readonly type: "sqlite";
     private db;
@@ -28,6 +28,7 @@ export declare class SQLiteStorage implements PMOStorage {
     private actionStorage;
     private viewStorage;
     private roadmapStorage;
+    private categoryStorage;
     constructor(dbPath: string);
     /**
      * Get the underlying database connection.
@@ -186,6 +187,18 @@ export declare class SQLiteStorage implements PMOStorage {
     removeProjectFromRoadmap(roadmapId: string, projectId: string): Promise<void>;
     reorderRoadmapProject(roadmapId: string, projectId: string, newPosition: number): Promise<RoadmapProject>;
     getRoadmapsForProject(projectId: string): Promise<Roadmap[]>;
+    listCategories(filter?: CategoryFilter): Promise<Category[]>;
+    getCategory(id: string): Promise<Category | null>;
+    getCategoryByName(name: string, type: CategoryType): Promise<Category | null>;
+    createCategory(category: Partial<Category> & {
+        name: string;
+        type: CategoryType;
+    }): Promise<Category>;
+    updateCategory(id: string, changes: Partial<Category>): Promise<Category>;
+    renameCategory(id: string, newName: string): Promise<Category>;
+    deleteCategory(id: string): Promise<void>;
+    getCategoryNames(type: CategoryType): Promise<string[]>;
+    isValidCategory(name: string, type: CategoryType): Promise<boolean>;
     pull(): Promise<SyncResult>;
     push(): Promise<SyncResult>;
     status(): Promise<SyncStatus>;

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

@@ -10,7 +10,7 @@
 import Database from 'better-sqlite3';
 import { createDrizzleConnection } from '../../database/drizzle.js';
 import { PMO_TABLES, PMO_SCHEMA_SQL, validateTicketSchema } from '../schema.js';
-import { runMigrations, seedBuiltinWorkflows, seedBuiltinPhases, seedBuiltinPhaseTemplates, seedBuiltinActions, seedBuiltinTicketTemplates, updateBoardTimestamp, } from './base.js';
+import { runMigrations, seedBuiltinWorkflows, seedBuiltinPhases, seedBuiltinPhaseTemplates, seedBuiltinActions, seedBuiltinTicketTemplates, seedBuiltinCategories, updateBoardTimestamp, } from './base.js';
 import { ProjectStorage } from './projects.js';
 import { TicketStorage } from './tickets.js';
 import { SubtaskStorage, AcceptanceCriteriaStorage } from './subtasks.js';
@@ -23,6 +23,7 @@ import { PhaseStorage } from './phases.js';
 import { ActionStorage } from './actions.js';
 import { ViewStorage } from './views.js';
 import { RoadmapStorage } from './roadmaps.js';
+import { CategoryStorage } from './categories.js';
 const T = PMO_TABLES;
 export class SQLiteStorage {
     type = 'sqlite';
@@ -43,6 +44,7 @@ export class SQLiteStorage {
     actionStorage;
     viewStorage;
     roadmapStorage;
+    categoryStorage;
     constructor(dbPath) {
         this.dbPath = dbPath;
         // Open database (creates if doesn't exist)
@@ -71,6 +73,7 @@ export class SQLiteStorage {
         this.actionStorage = new ActionStorage(ctx);
         this.viewStorage = new ViewStorage(ctx);
         this.roadmapStorage = new RoadmapStorage(ctx);
+        this.categoryStorage = new CategoryStorage(ctx);
         // Ensure PMO tables exist
         this.ensurePMOTables();
     }
@@ -100,6 +103,7 @@ export class SQLiteStorage {
         seedBuiltinPhaseTemplates(this.db);
         seedBuiltinActions(this.db);
         seedBuiltinTicketTemplates(this.db);
+        seedBuiltinCategories(this.db);
         // Validate schema
         validateTicketSchema(this.db);
     }
@@ -579,6 +583,36 @@ export class SQLiteStorage {
         return this.roadmapStorage.getRoadmapsForProject(projectId);
     }
     // ===========================================================================
+    // Category Operations
+    // ===========================================================================
+    async listCategories(filter) {
+        return this.categoryStorage.listCategories(filter);
+    }
+    async getCategory(id) {
+        return this.categoryStorage.getCategory(id);
+    }
+    async getCategoryByName(name, type) {
+        return this.categoryStorage.getCategoryByName(name, type);
+    }
+    async createCategory(category) {
+        return this.categoryStorage.createCategory(category);
+    }
+    async updateCategory(id, changes) {
+        return this.categoryStorage.updateCategory(id, changes);
+    }
+    async renameCategory(id, newName) {
+        return this.categoryStorage.renameCategory(id, newName);
+    }
+    async deleteCategory(id) {
+        return this.categoryStorage.deleteCategory(id);
+    }
+    async getCategoryNames(type) {
+        return this.categoryStorage.getCategoryNames(type);
+    }
+    async isValidCategory(name, type) {
+        return this.categoryStorage.isValidCategory(name, type);
+    }
+    // ===========================================================================
     // Sync Operations (no-op for pure SQLite)
     // ===========================================================================
     async pull() {

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

@@ -8,6 +8,11 @@ import { StorageContext } from './types.js';
 export declare class TicketStorage {
     private ctx;
     constructor(ctx: StorageContext);
+    /**
+     * Validate a category against the DB.
+     * Returns the valid category name if found, throws error if invalid.
+     */
+    private validateCategory;
     /**
      * Resolve a project identifier to its actual ID.
      * Tries multiple strategies:

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

@@ -13,6 +13,27 @@ export class TicketStorage {
     constructor(ctx) {
         this.ctx = ctx;
     }
+    /**
+     * Validate a category against the DB.
+     * Returns the valid category name if found, throws error if invalid.
+     */
+    async validateCategory(category) {
+        if (!category)
+            return null;
+        // Check if category exists in DB for ticket type
+        const row = this.ctx.db.prepare(`
+      SELECT name FROM ${T.categories} WHERE LOWER(name) = LOWER(?) AND type = 'ticket'
+    `).get(category);
+        if (!row) {
+            // Get valid categories for error message
+            const validCategories = this.ctx.db.prepare(`
+        SELECT name FROM ${T.categories} WHERE type = 'ticket' ORDER BY position
+      `).all();
+            const validNames = validCategories.map(c => c.name).join(', ');
+            throw new PMOError('INVALID', `Invalid category "${category}". Valid categories: ${validNames}`);
+        }
+        return row.name;
+    }
     /**
      * Resolve a project identifier to its actual ID.
      * Tries multiple strategies:
@@ -71,6 +92,8 @@ export class TicketStorage {
         const title = ticket.title || 'Untitled';
         const now = Date.now();
         const specId = ticket.specId || null;
+        // Validate category against DB
+        const validatedCategory = await this.validateCategory(ticket.category);
         // Get status_id from project's workflow
         let statusId = ticket.statusId;
         // Get the project's workflow
@@ -134,7 +157,7 @@ export class TicketStorage {
           created_at, updated_at, last_synced_from_spec, last_synced_from_board
         )
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(id, projectId, title, ticket.description || null, ticket.priority || null, ticket.category || null, statusId, ticket.owner || null, ticket.assignee || null, specId, ticket.epicId || null, JSON.stringify(labels), now, now, ticket.lastSyncedFromSpec || null, ticket.lastSyncedFromBoard || null);
+      `).run(id, projectId, title, ticket.description || null, ticket.priority || null, validatedCategory, statusId, ticket.owner || null, ticket.assignee || null, specId, ticket.epicId || null, JSON.stringify(labels), now, now, ticket.lastSyncedFromSpec || null, ticket.lastSyncedFromBoard || null);
         }
         catch (err) {
             wrapSqliteError('Ticket', 'create', err);
@@ -196,6 +219,11 @@ export class TicketStorage {
         if (!existing) {
             throw new PMOError('NOT_FOUND', `Ticket not found: ${id}`, id);
         }
+        // Validate category if being updated
+        let validatedCategory;
+        if (changes.category !== undefined) {
+            validatedCategory = await this.validateCategory(changes.category);
+        }
         const updates = [];
         const params = [];
         if (changes.title !== undefined) {
@@ -210,9 +238,9 @@ export class TicketStorage {
             updates.push('priority = ?');
             params.push(changes.priority);
         }
-        if (changes.category !== undefined) {
+        if (validatedCategory !== undefined) {
             updates.push('category = ?');
-            params.push(changes.category);
+            params.push(validatedCategory);
         }
         if (changes.statusId !== undefined) {
             updates.push('status_id = ?');

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

@@ -216,3 +216,13 @@ export interface RoadmapProjectRow {
     position: number;
     created_at: string;
 }
+export interface CategoryRow {
+    id: string;
+    name: string;
+    type: string;
+    description: string | null;
+    color: string | null;
+    position: number;
+    is_builtin: number;
+    created_at: string;
+}

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

@@ -83,6 +83,31 @@ export declare const LEGACY_PRIORITY_MAP: Record<LegacyPriority, Priority>;
  */
 export declare const TICKET_CATEGORIES: readonly ["feature", "bug", "refactor", "docs", "test", "chore", "performance", "ci", "build", "security", "database", "release"];
 export type TicketCategory = typeof TICKET_CATEGORIES[number];
+/**
+ * Category types (ticket vs status).
+ */
+export type CategoryType = 'ticket' | 'status';
+/**
+ * Category record for ticket or status classification.
+ */
+export interface Category {
+    id: string;
+    name: string;
+    type: CategoryType;
+    description?: string;
+    color?: string;
+    position: number;
+    isBuiltin: boolean;
+    createdAt: Date;
+}
+/**
+ * Filter options for listing categories.
+ */
+export interface CategoryFilter {
+    type?: CategoryType;
+    isBuiltin?: boolean;
+    search?: string;
+}
 /**
  * Check if a string is a valid Priority value.
  */

package/dist/lib/prompt-json.d.ts

@@ -128,20 +128,17 @@ export interface ErrorJsonOutput {
  */
 export type JsonOutput = PromptJsonOutput | SuccessJsonOutput | ErrorJsonOutput;
 /**
- * Flags interface for JSON mode detection (legacy)
- * @deprecated Use MachineOutputFlags instead
+ * Flags interface for JSON mode detection
  */
 export interface JsonFlags {
     json?: boolean;
 }
 /**
  * Flags interface for machine-readable output mode detection
- * Supports both new --machine format and legacy --json boolean
+ * --json is the primary flag, -m/--machine are aliases that set json=true
  */
 export interface MachineOutputFlags {
-    /** New format: --machine (enables machine-readable JSON output for AI agents) */
-    machine?: boolean;
-    /** Legacy format: --json (deprecated, use --machine instead) */
+    /** Primary JSON output flag. -m and --machine are aliases to this flag */
     json?: boolean;
 }
 /**
@@ -154,16 +151,13 @@ export declare function isNonTTY(): boolean;
  * Determine if JSON output mode is active (for AI agents)
  *
  * Returns true if:
- * - The --machine flag is explicitly set
- * - The --json flag is explicitly set
+ * - The --json flag is set (or -m/--machine aliases)
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
  * @returns true if JSON mode should be used
  */
-export declare function shouldOutputJson(flags: JsonFlags & {
-    machine?: boolean;
-}): boolean;
+export declare function shouldOutputJson(flags: JsonFlags): boolean;
 /**
  * Alias for shouldOutputJson - clearer name for agent-focused code
  */
@@ -172,8 +166,7 @@ export declare const isAgentMode: typeof shouldOutputJson;
  * Determine if machine-readable output mode is active (for AI agents/scripts)
  *
  * Returns true if:
- * - The --machine flag is set
- * - The --json flag is explicitly set (legacy support)
+ * - The --json flag is set (or -m/--machine aliases)
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
@@ -200,15 +193,16 @@ export declare function createMetadata(command: string, flags: Record<string, un
  */
 export declare function outputPromptAsJson(config: PromptConfig, metadata: OutputMetadata): never;
 /**
- * Output success result as JSON
+ * Output success result as JSON and exit
  *
  * Use this when all required data was provided via flags
- * and no prompt is needed.
+ * and no prompt is needed. Exits with EXIT_SUCCESS (0) to signal
+ * successful command completion.
  *
  * @param result - Command-specific result data
  * @param metadata - Command metadata
  */
-export declare function outputSuccessAsJson(result: Record<string, unknown>, metadata: OutputMetadata): void;
+export declare function outputSuccessAsJson(result: Record<string, unknown>, metadata: OutputMetadata): never;
 /**
  * Output error as JSON and exit
  *

package/dist/lib/prompt-json.js

@@ -41,19 +41,14 @@ export function isNonTTY() {
  * Determine if JSON output mode is active (for AI agents)
  *
  * Returns true if:
- * - The --machine flag is explicitly set
- * - The --json flag is explicitly set
+ * - The --json flag is set (or -m/--machine aliases)
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
  * @returns true if JSON mode should be used
  */
 export function shouldOutputJson(flags) {
-    // New --machine flag
-    if (flags.machine === true) {
-        return true;
-    }
-    // Legacy --json flag
+    // --json flag (includes -m and --machine aliases)
     if (flags.json === true) {
         return true;
     }
@@ -68,19 +63,14 @@ export const isAgentMode = shouldOutputJson;
  * Determine if machine-readable output mode is active (for AI agents/scripts)
  *
  * Returns true if:
- * - The --machine flag is set
- * - The --json flag is explicitly set (legacy support)
+ * - The --json flag is set (or -m/--machine aliases)
  * - The environment is non-TTY (piped output)
  *
  * @param flags - Command flags object
  * @returns true if machine-readable output mode should be used
  */
 export function isMachineOutput(flags) {
-    // New --machine flag takes precedence
-    if (flags.machine === true) {
-        return true;
-    }
-    // Legacy --json flag support
+    // --json flag (includes -m and --machine aliases)
     if (flags.json === true) {
         return true;
     }
@@ -128,10 +118,11 @@ export function outputPromptAsJson(config, metadata) {
     process.exit(EXIT_NEEDS_INPUT);
 }
 /**
- * Output success result as JSON
+ * Output success result as JSON and exit
  *
  * Use this when all required data was provided via flags
- * and no prompt is needed.
+ * and no prompt is needed. Exits with EXIT_SUCCESS (0) to signal
+ * successful command completion.
  *
  * @param result - Command-specific result data
  * @param metadata - Command metadata
@@ -144,6 +135,7 @@ export function outputSuccessAsJson(result, metadata) {
         metadata,
     };
     console.log(JSON.stringify(output, null, 2));
+    process.exit(EXIT_SUCCESS);
 }
 /**
  * Output error as JSON and exit