@proletariat/cli 0.3.36 → 0.3.41

package/README.md

@@ -24,7 +24,10 @@
 **prlt** is an agent orchestration platform for AI labor. Spin up workers on demand, coordinate multi-agent development from one CLI. Isolated workspaces, secure containers, persistent state.
 
 ```bash
-npm install -g @proletariat/cli
+brew install chrismcdermut/proletariat/prlt    # macOS (Homebrew)
+# or
+npm install -g @proletariat/cli        # any platform (npm)
+
 prlt init
 prlt ticket create --title "Add OAuth" --category feature
 prlt work spawn   # Interactive: select tickets, environment, action
@@ -48,7 +51,10 @@ Agent spawns in its own branch, writes code, opens PR. You review and merge.
 # Quick Start
 
 ```bash
-npm install -g @proletariat/cli    # Install
+npm install -g @proletariat/cli    # Install (npm)
+# or
+brew install chrismcdermut/proletariat/prlt  # Install (Homebrew, macOS)
+
 prlt init                          # Create HQ, add repos, choose theme
 prlt ticket create --title "Add OAuth" --category feature
 prlt work spawn                    # Interactive: select tickets, environment, action
@@ -117,6 +123,35 @@ Select tickets to spawn, grouped by priority:
 | Starting agents is heavyweight            | **Ephemeral** - Spawn on demand, they work, they PR, they're done                            |
 | Context lost between agent runs           | **Persistent** - Tickets accumulate context, hand off between agents                         |
 
+### Installation
+
+#### Homebrew (macOS)
+
+```bash
+brew install chrismcdermut/proletariat/prlt
+```
+
+Works on both Apple Silicon (arm64) and Intel (x86_64) Macs.
+
+**Upgrade:**
+
+```bash
+brew update
+brew upgrade prlt
+```
+
+**Verify:**
+
+```bash
+prlt --version
+```
+
+#### npm (all platforms)
+
+```bash
+npm install -g @proletariat/cli
+```
+
 ### Data Model
 
 ```

package/dist/commands/branch/where.js

@@ -5,7 +5,7 @@ import { PMOCommand, pmoBaseFlags } from '../../lib/pmo/index.js';
 import { shouldOutputJson } from '../../lib/prompt-json.js';
 import { styles } from '../../lib/styles.js';
 import { isGitRepo, isTicketId } from '../../lib/branch/index.js';
-import { openWorkspaceDatabase } from '../../lib/database/index.js';
+import { findWorktreesByBranch as findDbWorktreesByBranch } from '../../lib/database/index.js';
 export default class BranchWhere extends PMOCommand {
     static description = 'Find which directory a branch is checked out in';
     static examples = [
@@ -148,24 +148,13 @@ export default class BranchWhere extends PMOCommand {
             const workspacePath = this.getWorkspacePath();
             if (!workspacePath)
                 return [];
-            const db = openWorkspaceDatabase(workspacePath);
             const searchLower = search.toLowerCase();
             const isTicket = isTicketId(search);
-            // Query for matching branches
-            let query;
-            let params;
-            if (isTicket) {
-                // Match branches starting with ticket ID
-                query = 'SELECT * FROM agent_worktrees WHERE LOWER(branch) LIKE ?';
-                params = [`${searchLower}/%`];
-            }
-            else {
-                // Match branches containing the search term
-                query = 'SELECT * FROM agent_worktrees WHERE LOWER(branch) LIKE ?';
-                params = [`%${searchLower}%`];
-            }
-            const rows = db.prepare(query).all(...params);
-            db.close();
+            // Build LIKE pattern based on search type
+            const branchPattern = isTicket
+                ? `${searchLower}/%` // Match branches starting with ticket ID
+                : `%${searchLower}%`; // Match branches containing the search term
+            const rows = findDbWorktreesByBranch(workspacePath, branchPattern);
             return rows.map(row => ({
                 path: path.join(workspacePath, row.worktree_path),
                 branch: row.branch,

package/dist/commands/epic/ticket.js

@@ -81,11 +81,10 @@ export default class EpicTicket extends PMOCommand {
             this.log(styles.muted('\nNo tickets found.'));
             return;
         }
-        // Get epic_id for each ticket via direct DB query
-        const db = this.storage.db;
+        // Helper to get ticket's epic ID from the loaded ticket list
         const getTicketEpicId = (ticketId) => {
-            const row = db.prepare(`SELECT epic_id FROM pmo_tickets WHERE id = ?`).get(ticketId);
-            return row?.epic_id || null;
+            const ticket = allTickets.find((t) => t.id === ticketId);
+            return ticket?.epicId ?? null;
         };
         let epicId = args.id;
         // If no epic ID provided, prompt for selection
@@ -201,11 +200,7 @@ export default class EpicTicket extends PMOCommand {
                     this.log(styles.muted(`  ${ticketId} is not linked to ${epicId}, skipping`));
                     continue;
                 }
-                db.prepare(`
-          UPDATE pmo_tickets
-          SET epic_id = NULL, updated_at = ?
-          WHERE id = ?
-        `).run(Date.now(), ticketId);
+                await this.storage.unlinkTicketFromEpic(ticketId);
             }
             else {
                 // Link: check if already linked to same epic
@@ -253,11 +248,7 @@ export default class EpicTicket extends PMOCommand {
                     }
                     if (action === 'use_epic') {
                         // Update ticket to use epic's spec
-                        db.prepare(`
-              UPDATE pmo_tickets
-              SET spec_id = ?, updated_at = ?
-              WHERE id = ?
-            `).run(epicSpecId, Date.now(), ticketId);
+                        await this.storage.updateTicket(ticketId, { specId: epicSpecId });
                         this.log(styles.muted(`  Updated ${ticketId} to use spec "${epicSpecId}"`));
                     }
                 }
@@ -284,19 +275,11 @@ export default class EpicTicket extends PMOCommand {
                         inherit = result.inherit;
                     }
                     if (inherit) {
-                        db.prepare(`
-              UPDATE pmo_tickets
-              SET spec_id = ?, updated_at = ?
-              WHERE id = ?
-            `).run(epicSpecId, Date.now(), ticketId);
+                        await this.storage.updateTicket(ticketId, { specId: epicSpecId });
                         this.log(styles.muted(`  Assigned spec "${epicSpecId}" to ${ticketId}`));
                     }
                 }
-                db.prepare(`
-          UPDATE pmo_tickets
-          SET epic_id = ?, updated_at = ?
-          WHERE id = ?
-        `).run(epicId, Date.now(), ticketId);
+                await this.storage.linkTicketToEpic(ticketId, epicId);
             }
             linkedTickets.push(`${ticketId}: ${ticket.title}`);
             successCount++;

package/dist/commands/execution/config.js

@@ -1,10 +1,9 @@
 import { Flags } from '@oclif/core';
-import * as path from 'node:path';
-import Database from 'better-sqlite3';
 import inquirer from 'inquirer';
 import { PMOCommand, pmoBaseFlags } from '../../lib/pmo/index.js';
 import { styles } from '../../lib/styles.js';
 import { getWorkspaceInfo } from '../../lib/agents/commands.js';
+import { openWorkspaceDatabase } from '../../lib/database/index.js';
 import { loadExecutionConfig, saveTerminalApp, saveTerminalOpenInBackground, saveTmuxControlMode, saveShell, saveExecutionSetting, } from '../../lib/execution/config.js';
 import { shouldOutputJson, outputSuccessAsJson, outputErrorAsJson, createMetadata, } from '../../lib/prompt-json.js';
 export default class ExecutionConfig extends PMOCommand {
@@ -54,8 +53,7 @@ export default class ExecutionConfig extends PMOCommand {
             this.error('Not in a workspace. Run "prlt init" first.');
         }
         // Open database
-        const dbPath = path.join(workspaceInfo.path, '.proletariat', 'workspace.db');
-        const db = new Database(dbPath);
+        const db = openWorkspaceDatabase(workspaceInfo.path);
         try {
             // Load current config
             const config = loadExecutionConfig(db);
@@ -388,20 +386,12 @@ export default class ExecutionConfig extends PMOCommand {
      * Save output mode to workspace settings
      */
     setOutputMode(db, mode) {
-        db.prepare(`
-      INSERT INTO workspace_settings (key, value)
-      VALUES (?, ?)
-      ON CONFLICT(key) DO UPDATE SET value = excluded.value
-    `).run('execution.output_mode', mode);
+        saveExecutionSetting(db, 'outputMode', mode);
     }
     /**
      * Save sandboxed preference to workspace settings
      */
     setSandboxed(db, sandboxed) {
-        db.prepare(`
-      INSERT INTO workspace_settings (key, value)
-      VALUES (?, ?)
-      ON CONFLICT(key) DO UPDATE SET value = excluded.value
-    `).run('execution.sandboxed', sandboxed.toString());
+        saveExecutionSetting(db, 'sandboxed', sandboxed.toString());
     }
 }

package/dist/commands/execution/logs.js

@@ -90,6 +90,12 @@ export default class ExecutionLogs extends PMOCommand {
             if (!execution.logPath) {
                 this.log(styles.muted(`\nNo log file for execution ${execId}`));
                 this.log(styles.muted(`Environment: ${execution.environment}`));
+                // Show error message if available (TKT-1082)
+                if (execution.errorMessage) {
+                    this.log('');
+                    this.log(styles.error('Error:'));
+                    this.log(styles.error(`  ${execution.errorMessage}`));
+                }
                 if (execution.sessionId) {
                     this.log('');
                     this.log(styles.muted('View in tmux:'));

package/dist/commands/execution/view.js

@@ -104,6 +104,7 @@ export default class ExecutionView extends PMOCommand {
                     startedAt: execution.startedAt.toISOString(),
                     completedAt: execution.completedAt?.toISOString() || null,
                     exitCode: execution.exitCode ?? null,
+                    errorMessage: execution.errorMessage || null,
                 }, createMetadata('execution view', flags));
             }
             // Display execution details
@@ -160,6 +161,13 @@ export default class ExecutionView extends PMOCommand {
                 this.log(`${styles.muted('Exit Code:')}    ${exitStyle(execution.exitCode.toString())}`);
             }
             this.log('');
+            // Error details (TKT-1082)
+            if (execution.errorMessage) {
+                this.log(styles.header('Error'));
+                this.log('─'.repeat(40));
+                this.log(styles.error(execution.errorMessage));
+                this.log('');
+            }
             // Logs summary
             if (execution.logPath) {
                 this.log(styles.header('Logs'));

package/dist/commands/init.js

@@ -6,7 +6,7 @@ import { promptForHQName, promptForHQLocation, initializeHQ, showNextSteps, vali
 import { promptForAgentsWithTheme } from '../lib/agents/index.js';
 import { promptForRepositories } from '../lib/repos/index.js';
 import { promptForPMOSetup, machineOutputFlags } from '../lib/pmo/index.js';
-import { shouldOutputJson } from '../lib/prompt-json.js';
+import { shouldOutputJson, outputPromptAsJson, buildPromptConfig, createMetadata, } from '../lib/prompt-json.js';
 export default class Init extends Command {
     static description = 'Initialize an HQ (headquarters) for managing repositories, agents, and projects';
     static examples = [
@@ -19,7 +19,7 @@ export default class Init extends Command {
     static flags = {
         ...machineOutputFlags,
         name: Flags.string({
-            description: 'HQ name (required in --json mode)',
+            description: 'HQ name',
             char: 'n',
         }),
         path: Flags.string({
@@ -85,13 +85,9 @@ export default class Init extends Command {
      * Agent mode: use flags, output JSON
      */
     async runAgentMode(flags) {
-        // Validate required fields
+        // If --name not provided, output a prompt so agents can supply it
         if (!flags.name) {
-            this.outputJson({
-                success: false,
-                error: 'Missing required flag: --name',
-            });
-            this.exit(1);
+            outputPromptAsJson(buildPromptConfig('input', 'name', 'Enter a name for your headquarters:', undefined, undefined), createMetadata('init', flags));
         }
         const hqName = flags.name;
         const hqPath = flags.path || path.resolve(`./${hqName}-hq`);

package/dist/commands/mcp-server.js

@@ -22,7 +22,7 @@ import Database from 'better-sqlite3';
 import { getPMOContext } from '../lib/pmo/pmo-context.js';
 import { getWorkspaceInfo } from '../lib/agents/commands.js';
 import { ExecutionStorage } from '../lib/execution/storage.js';
-import { registerTicketTools, registerProjectTools, registerBoardTools, registerSpecTools, registerEpicTools, registerWorkTools, registerWorkflowTools, registerStatusTools, registerPhaseTools, registerActionTools, registerRoadmapTools, registerCategoryTools, registerTemplateTools, registerViewTools, registerDietTools, registerLabelTools, registerAgentTools, registerDockerTools, registerRepoTools, registerBranchTools, registerGitHubTools, registerInitTools, registerUtilityTools, } from '../lib/mcp/index.js';
+import { registerTicketTools, registerProjectTools, registerBoardTools, registerSpecTools, registerEpicTools, registerWorkTools, registerWorkflowTools, registerStatusTools, registerPhaseTools, registerActionTools, registerRoadmapTools, registerCategoryTools, registerTemplateTools, registerViewTools, registerDietTools, registerLabelTools, registerTmuxTools, registerAgentTools, registerDockerTools, registerRepoTools, registerBranchTools, registerGitHubTools, registerInitTools, registerUtilityTools, } from '../lib/mcp/index.js';
 export default class McpServerCommand extends Command {
     static description = 'Start MCP server for AI agent integration (exposes all prlt commands as tools)';
     static hidden = true;
@@ -111,6 +111,7 @@ export default class McpServerCommand extends Command {
         registerViewTools(server, ctx);
         registerDietTools(server, ctx);
         registerLabelTools(server, ctx);
+        registerTmuxTools(server, ctx);
         registerAgentTools(server, ctx);
         registerDockerTools(server, ctx);
         registerRepoTools(server, ctx);

package/dist/commands/pmo/init.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import { execSync } from 'node:child_process';
 import chalk from 'chalk';
 import { PromptCommand } from '../../lib/prompt-command.js';
-import Database from 'better-sqlite3';
+import { checkPMOExists, getPMOSetting, dropPMOTables } from '../../lib/database/index.js';
 import { SQLiteStorage, getColumnsForTemplate, createPMO, promptForPMOLocation, promptForBoardTemplate, promptForBoardName, promptForCustomColumns, determinePMOPath, getPickerTemplates, machineOutputFlags, } from '../../lib/pmo/index.js';
 import { styles } from '../../lib/styles.js';
 import { isGHInstalled, isGHAuthenticated, getGHUsername, isGHTokenInEnv } from '../../lib/pr/index.js';
@@ -56,17 +56,10 @@ export default class PMOInit extends PromptCommand {
             const dbPath = path.join(hqRoot, '.proletariat', 'workspace.db');
             if (fs.existsSync(dbPath)) {
                 try {
-                    const db = new Database(dbPath);
-                    const result = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='pmo_projects'").get();
-                    if (result !== undefined) {
-                        existingPMO = true;
-                        // Get counts
-                        const projectCountResult = db.prepare('SELECT COUNT(*) as count FROM pmo_projects').get();
-                        const ticketCountResult = db.prepare('SELECT COUNT(*) as count FROM pmo_tickets').get();
-                        projectCount = projectCountResult.count;
-                        ticketCount = ticketCountResult.count;
-                    }
-                    db.close();
+                    const pmoStatus = checkPMOExists(dbPath);
+                    existingPMO = pmoStatus.exists;
+                    projectCount = pmoStatus.projectCount;
+                    ticketCount = pmoStatus.ticketCount;
                 }
                 catch (error) {
                     // Log error for debugging
@@ -243,16 +236,9 @@ export default class PMOInit extends PromptCommand {
         // Find PMO location from database
         const dbPath = path.join(hqRoot, '.proletariat', 'workspace.db');
         let pmoPath = path.join(hqRoot, 'pmo'); // Default fallback
-        try {
-            const db = new Database(dbPath);
-            const result = db.prepare('SELECT value FROM pmo_settings WHERE key = ?').get('pmo_path');
-            if (result) {
-                pmoPath = result.value;
-            }
-            db.close();
-        }
-        catch {
-            // Use default if table doesn't exist
+        const savedPmoPath = getPMOSetting(dbPath, 'pmo_path');
+        if (savedPmoPath) {
+            pmoPath = savedPmoPath;
         }
         // Define choices once, use for both JSON and interactive modes
         const actionChoices = [
@@ -336,30 +322,16 @@ export default class PMOInit extends PromptCommand {
         const dbPath = path.join(hqRoot, '.proletariat', 'workspace.db');
         let pmoPath = path.join(hqRoot, 'pmo'); // Default fallback
         if (fs.existsSync(dbPath)) {
-            const db = new Database(dbPath);
             // Get PMO path from database before deleting
-            try {
-                const result = db.prepare('SELECT value FROM pmo_settings WHERE key = ?').get('pmo_path');
-                if (result) {
-                    pmoPath = result.value;
-                }
-            }
-            catch {
-                // Ignore - table might not exist, use default
+            const savedPmoPath = getPMOSetting(dbPath, 'pmo_path');
+            if (savedPmoPath) {
+                pmoPath = savedPmoPath;
             }
             // Drop all pmo_* tables
             const tables = ['pmo_ticket_specs', 'pmo_ticket_metadata', 'pmo_subtasks', 'pmo_tickets',
                 'pmo_columns', 'pmo_specs', 'pmo_epics', 'pmo_projects',
                 'pmo_initiatives', 'pmo_ticket_assignments', 'pmo_cache_metadata', 'pmo_settings'];
-            for (const table of tables) {
-                try {
-                    db.prepare(`DROP TABLE IF EXISTS ${table}`).run();
-                }
-                catch {
-                    // Ignore errors - table might not exist
-                }
-            }
-            db.close();
+            dropPMOTables(dbPath, tables);
             this.log(chalk.green('  ✓ Dropped database tables'));
         }
         // Delete pmo/ directory (using path from database or default)

package/dist/commands/qa/index.d.ts

@@ -0,0 +1,54 @@
+import { PromptCommand } from '../../lib/prompt-command.js';
+export default class QA extends PromptCommand {
+    static description: string;
+    static aliases: string[];
+    static examples: string[];
+    static flags: {
+        seed: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        watch: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        environment: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'display-mode': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'permission-mode': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        prompt: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        machine: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * Load the explore-cli action prompt from PMO storage.
+     */
+    private getExploreCLIPrompt;
+    /**
+     * Run seed-explore-data.mjs to pre-populate test data.
+     */
+    private runSeedData;
+    /**
+     * Run in tracked mode - inside an HQ
+     * Creates an ephemeral QA agent with full tracking
+     */
+    private runTracked;
+    /**
+     * Run in yolo mode - outside any HQ
+     */
+    private runYolo;
+    /**
+     * Resolve execution environment (devcontainer vs host).
+     */
+    private resolveEnvironment;
+    /**
+     * Resolve display mode.
+     */
+    private resolveDisplayMode;
+    /**
+     * Resolve permission mode. Defaults to danger for QA (container provides isolation).
+     */
+    private resolvePermissionMode;
+    /**
+     * Set up catch-all devcontainer for directories without one.
+     */
+    private setupCatchallDevcontainer;
+    /**
+     * Check if catch-all container image is available.
+     */
+    private checkCatchallImage;
+}