@proletariat/cli 0.3.21 → 0.3.23

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

@@ -3,6 +3,7 @@
  * This module handles database setup and provides shared utilities.
  */
 import { PMO_TABLES, PMO_SCHEMA_SQL, validateTicketSchema } from '../schema.js';
+import { TICKET_CATEGORIES, STATE_CATEGORY_ORDER } from '../types.js';
 import { BUILTIN_TEMPLATES } from '../templates-builtin.js';
 const T = PMO_TABLES;
 /**
@@ -802,6 +803,36 @@ Why is this refactor needed?
         insertTemplate.run(template.id, template.name, template.description || null, template.titlePattern || null, template.descriptionTemplate || null, template.defaultPriority || null, template.defaultCategory || null, null, null, null, '[]', JSON.stringify(template.suggestedSubtasks || []), now);
     }
 }
+/**
+ * Seed built-in categories from TICKET_CATEGORIES and STATE_CATEGORY_ORDER.
+ */
+export function seedBuiltinCategories(db) {
+    const insertCategory = db.prepare(`
+    INSERT OR IGNORE INTO ${T.categories} (id, name, type, description, position, is_builtin, created_at)
+    VALUES (?, ?, ?, ?, ?, 1, ?)
+  `);
+    const now = new Date().toISOString();
+    // Seed ticket categories from TICKET_CATEGORIES
+    for (let i = 0; i < TICKET_CATEGORIES.length; i++) {
+        const category = TICKET_CATEGORIES[i];
+        const id = `ticket-${category}`;
+        insertCategory.run(id, category, 'ticket', null, i, now);
+    }
+    // Seed status categories from STATE_CATEGORY_ORDER
+    const statusCategoryDescriptions = {
+        triage: 'Inbox - needs review before entering workflow',
+        backlog: 'Not yet scheduled for work',
+        unstarted: 'Scheduled but work has not begun',
+        started: 'Work is actively in progress',
+        completed: 'Work finished successfully',
+        canceled: 'Work will not be done',
+    };
+    for (let i = 0; i < STATE_CATEGORY_ORDER.length; i++) {
+        const category = STATE_CATEGORY_ORDER[i];
+        const id = `status-${category}`;
+        insertCategory.run(id, category, 'status', statusCategoryDescriptions[category] || null, i, now);
+    }
+}
 /**
  * Update board timestamp for a project.
  */

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

@@ -0,0 +1,50 @@
+/**
+ * Category operations.
+ * Manages ticket and status categories.
+ */
+import { Category, CategoryFilter, CategoryType } from '../types.js';
+import { StorageContext } from './types.js';
+export declare class CategoryStorage {
+    private ctx;
+    constructor(ctx: StorageContext);
+    /**
+     * List categories.
+     */
+    listCategories(filter?: CategoryFilter): Promise<Category[]>;
+    /**
+     * Get a category by ID.
+     */
+    getCategory(id: string): Promise<Category | null>;
+    /**
+     * Get a category by name and type.
+     */
+    getCategoryByName(name: string, type: CategoryType): Promise<Category | null>;
+    /**
+     * Create a new category.
+     */
+    createCategory(category: Partial<Category> & {
+        name: string;
+        type: CategoryType;
+    }): Promise<Category>;
+    /**
+     * Update a category.
+     */
+    updateCategory(id: string, changes: Partial<Category>): Promise<Category>;
+    /**
+     * Rename a category.
+     */
+    renameCategory(id: string, newName: string): Promise<Category>;
+    /**
+     * Delete a category.
+     */
+    deleteCategory(id: string): Promise<void>;
+    /**
+     * Get category names for a type (for validation and autocomplete).
+     */
+    getCategoryNames(type: CategoryType): Promise<string[]>;
+    /**
+     * Check if a category name is valid for a type.
+     */
+    isValidCategory(name: string, type: CategoryType): Promise<boolean>;
+    private rowToCategory;
+}

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

@@ -0,0 +1,205 @@
+/**
+ * Category operations.
+ * Manages ticket and status categories.
+ */
+import { PMO_TABLES } from '../schema.js';
+import { PMOError } from '../types.js';
+import { slugify } from '../utils.js';
+const T = PMO_TABLES;
+export class CategoryStorage {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * List categories.
+     */
+    async listCategories(filter) {
+        let sql = `SELECT * FROM ${T.categories}`;
+        const conditions = [];
+        const params = [];
+        if (filter?.type) {
+            conditions.push('type = ?');
+            params.push(filter.type);
+        }
+        if (filter?.isBuiltin !== undefined) {
+            conditions.push('is_builtin = ?');
+            params.push(filter.isBuiltin ? 1 : 0);
+        }
+        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 type, position ASC, name ASC';
+        const rows = this.ctx.db.prepare(sql).all(...params);
+        return rows.map((row) => this.rowToCategory(row));
+    }
+    /**
+     * Get a category by ID.
+     */
+    async getCategory(id) {
+        const row = this.ctx.db.prepare(`SELECT * FROM ${T.categories} WHERE id = ?`).get(id);
+        if (!row)
+            return null;
+        return this.rowToCategory(row);
+    }
+    /**
+     * Get a category by name and type.
+     */
+    async getCategoryByName(name, type) {
+        const row = this.ctx.db.prepare(`
+      SELECT * FROM ${T.categories} WHERE LOWER(name) = LOWER(?) AND type = ?
+    `).get(name, type);
+        if (!row)
+            return null;
+        return this.rowToCategory(row);
+    }
+    /**
+     * Create a new category.
+     */
+    async createCategory(category) {
+        if (!category.name) {
+            throw new PMOError('INVALID', 'Category name is required');
+        }
+        if (!category.type) {
+            throw new PMOError('INVALID', 'Category type is required');
+        }
+        const id = category.id || slugify(category.name);
+        // Check for duplicate name within the same type
+        const existing = this.ctx.db.prepare(`
+      SELECT id FROM ${T.categories} WHERE LOWER(name) = LOWER(?) AND type = ?
+    `).get(category.name, category.type);
+        if (existing) {
+            throw new PMOError('CONFLICT', `Category "${category.name}" already exists for type "${category.type}"`);
+        }
+        // Get the next position
+        const maxPos = this.ctx.db.prepare(`
+      SELECT MAX(position) as max FROM ${T.categories} WHERE type = ?
+    `).get(category.type);
+        const position = category.position ?? (maxPos.max ?? -1) + 1;
+        const now = new Date().toISOString();
+        this.ctx.db.prepare(`
+      INSERT INTO ${T.categories} (id, name, type, description, color, position, is_builtin, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, category.name, category.type, category.description || null, category.color || null, position, category.isBuiltin ? 1 : 0, now);
+        return {
+            id,
+            name: category.name,
+            type: category.type,
+            description: category.description,
+            color: category.color,
+            position,
+            isBuiltin: category.isBuiltin || false,
+            createdAt: new Date(now),
+        };
+    }
+    /**
+     * Update a category.
+     */
+    async updateCategory(id, changes) {
+        const existing = await this.getCategory(id);
+        if (!existing) {
+            throw new PMOError('NOT_FOUND', `Category not found: ${id}`);
+        }
+        if (existing.isBuiltin) {
+            throw new PMOError('INVALID', 'Cannot modify built-in categories');
+        }
+        // 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.categories} WHERE LOWER(name) = LOWER(?) AND type = ? AND id != ?
+      `).get(changes.name, existing.type, id);
+            if (dup) {
+                throw new PMOError('CONFLICT', `Category "${changes.name}" already exists for type "${existing.type}"`);
+            }
+        }
+        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.color !== undefined) {
+            updates.push('color = ?');
+            params.push(changes.color || null);
+        }
+        if (changes.position !== undefined) {
+            updates.push('position = ?');
+            params.push(changes.position);
+        }
+        if (updates.length > 0) {
+            params.push(id);
+            this.ctx.db.prepare(`UPDATE ${T.categories} SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        }
+        return (await this.getCategory(id));
+    }
+    /**
+     * Rename a category.
+     */
+    async renameCategory(id, newName) {
+        return this.updateCategory(id, { name: newName });
+    }
+    /**
+     * Delete a category.
+     */
+    async deleteCategory(id) {
+        const existing = await this.getCategory(id);
+        if (!existing) {
+            throw new PMOError('NOT_FOUND', `Category not found: ${id}`);
+        }
+        if (existing.isBuiltin) {
+            throw new PMOError('INVALID', 'Cannot delete built-in categories');
+        }
+        // Check if the category is in use
+        if (existing.type === 'ticket') {
+            const ticketsUsing = this.ctx.db.prepare(`
+        SELECT COUNT(*) as count FROM ${T.tickets} WHERE category = ?
+      `).get(existing.name);
+            if (ticketsUsing.count > 0) {
+                throw new PMOError('INVALID', `Cannot delete category "${existing.name}": ${ticketsUsing.count} ticket(s) are using it. Reassign tickets first.`);
+            }
+        }
+        else if (existing.type === 'status') {
+            const statusesUsing = this.ctx.db.prepare(`
+        SELECT COUNT(*) as count FROM ${T.workflow_statuses} WHERE category = ?
+      `).get(existing.name);
+            if (statusesUsing.count > 0) {
+                throw new PMOError('INVALID', `Cannot delete category "${existing.name}": ${statusesUsing.count} status(es) are using it. Reassign statuses first.`);
+            }
+        }
+        this.ctx.db.prepare(`DELETE FROM ${T.categories} WHERE id = ?`).run(id);
+    }
+    /**
+     * Get category names for a type (for validation and autocomplete).
+     */
+    async getCategoryNames(type) {
+        const categories = await this.listCategories({ type });
+        return categories.map(c => c.name);
+    }
+    /**
+     * Check if a category name is valid for a type.
+     */
+    async isValidCategory(name, type) {
+        const category = await this.getCategoryByName(name, type);
+        return category !== null;
+    }
+    rowToCategory(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            type: row.type,
+            description: row.description || undefined,
+            color: row.color || undefined,
+            position: row.position,
+            isBuiltin: row.is_builtin === 1,
+            createdAt: new Date(row.created_at),
+        };
+    }
+}

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