@proletariat/cli 0.3.35 → 0.3.36

package/dist/lib/mcp/tools/work.js

@@ -3,6 +3,8 @@
  */
 import { z } from 'zod';
 import { formatTicket, errorResponse, strictTool } from '../helpers.js';
+import { spawnAgentForTicket } from '../../execution/spawner.js';
+import { createEphemeralAgent } from '../../agents/commands.js';
 export function registerWorkTools(server, ctx) {
     strictTool(server, 'work_status', 'Get current work status (in-progress tickets)', {}, async () => {
         try {
@@ -31,7 +33,7 @@ export function registerWorkTools(server, ctx) {
             return errorResponse(error);
         }
     });
-    strictTool(server, 'work_start', 'Start working on a ticket (moves to In Progress)', {
+    strictTool(server, 'work_assign', 'Assign a ticket to someone for work preparation (does NOT move to In Progress — use the CLI "work start" command to actually start work with an agent/session)', {
         ticket_id: z.string().describe('Ticket ID'),
         assignee: z.string().optional().describe('Who is working'),
     }, async (params) => {
@@ -42,16 +44,14 @@ export function registerWorkTools(server, ctx) {
             if (params.assignee) {
                 await ctx.storage.updateTicket(params.ticket_id, { assignee: params.assignee });
             }
-            const columns = ctx.storage.getColumnNames(ticket.projectId);
-            const progressCol = columns.find((c) => c.toLowerCase().includes('progress') || c.toLowerCase().includes('doing')) || columns[Math.min(1, columns.length - 1)];
-            const moved = await ctx.storage.moveTicket(ticket.projectId, params.ticket_id, progressCol);
+            const updated = await ctx.storage.getTicket(params.ticket_id);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
                             success: true,
-                            ticket: formatTicket(moved),
-                            message: `Started ${moved.id}: ${moved.title}`,
+                            ticket: formatTicket(updated),
+                            message: `Assigned ${updated.id}: ${updated.title}${params.assignee ? ` to ${params.assignee}` : ''}`,
                         }, null, 2),
                     }],
             };
@@ -129,4 +129,94 @@ export function registerWorkTools(server, ctx) {
             return errorResponse(error);
         }
     });
+    strictTool(server, 'work_start', 'Start work on a ticket — spawns an agent with a running container/session, creates a git branch, and moves ticket to In Progress only after successful spawn', {
+        ticket_id: z.string().describe('Ticket ID to start work on'),
+        agent: z.string().optional().describe('Agent name to assign (defaults to creating an ephemeral agent)'),
+        environment: z.enum(['devcontainer', 'host']).optional().describe('Execution environment (default: devcontainer if available)'),
+        display_mode: z.enum(['background', 'terminal']).optional().describe('Display mode (default: background — MCP runs headless)'),
+        skip_permissions: z.boolean().optional().describe('Skip permission prompts (danger mode, default: false)'),
+        create_pr: z.boolean().optional().describe('Create PR when work is ready (default: false)'),
+    }, async (params) => {
+        try {
+            // Require workspace context for spawn operations
+            if (!ctx.getWorkspaceContext) {
+                throw new Error('Workspace not initialized. work_start requires a workspace with agents. Run "prlt init" first.');
+            }
+            const { workspaceInfo, executionStorage, db, pmoPath } = ctx.getWorkspaceContext();
+            // Validate ticket exists
+            const ticket = await ctx.storage.getTicket(params.ticket_id);
+            if (!ticket)
+                throw new Error(`Ticket not found: ${params.ticket_id}`);
+            // Check ticket is not blocked
+            if (ticket.blockedBy && ticket.blockedBy.length > 0) {
+                throw new Error(`Ticket ${ticket.id} is blocked by: ${ticket.blockedBy.join(', ')}. Resolve blockers first.`);
+            }
+            // Check for existing running execution
+            const runningExec = executionStorage.getRunningExecution(ticket.id);
+            if (runningExec) {
+                throw new Error(`Ticket ${ticket.id} already has a running execution: ${runningExec.id} (agent: ${runningExec.agentName})`);
+            }
+            // Select or create agent
+            let agentName;
+            if (params.agent) {
+                // Use specified agent — verify it exists
+                const agentExists = workspaceInfo.agents.some(a => a.name === params.agent);
+                if (!agentExists) {
+                    throw new Error(`Agent "${params.agent}" not found. Available agents: ${workspaceInfo.agents.map(a => a.name).join(', ') || 'none'}`);
+                }
+                agentName = params.agent;
+            }
+            else {
+                // Create an ephemeral agent (default for MCP)
+                const ephemeralResult = await createEphemeralAgent(workspaceInfo);
+                agentName = ephemeralResult.name;
+            }
+            // Spawn the agent with background mode (MCP is headless)
+            const displayMode = params.display_mode || 'background';
+            const environment = params.environment;
+            const result = await spawnAgentForTicket(ticket, agentName, ctx.storage, executionStorage, workspaceInfo, db, pmoPath, {
+                environment,
+                displayMode,
+                skipPermissions: params.skip_permissions ?? false,
+                createPR: params.create_pr ?? false,
+                skipRemoteCheck: false,
+            });
+            if (result.success) {
+                // Fetch updated ticket to return current state
+                const updatedTicket = await ctx.storage.getTicket(params.ticket_id);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                executionId: result.executionId,
+                                ticketId: result.ticketId,
+                                agent: result.agentName,
+                                status: 'running',
+                                ticket: updatedTicket ? formatTicket(updatedTicket) : undefined,
+                                message: `Started work on ${ticket.id}: ${ticket.title} (agent: ${agentName})`,
+                            }, null, 2),
+                        }],
+                };
+            }
+            else {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                ticketId: result.ticketId,
+                                agent: result.agentName,
+                                error: result.error || 'Spawn failed',
+                                message: `Failed to start work on ${ticket.id}: ${result.error}`,
+                            }, null, 2),
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
 }

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

@@ -3,9 +3,19 @@
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { SQLiteStorage } from '../pmo/storage/index.js';
+import type Database from 'better-sqlite3';
+import type { WorkspaceInfo } from '../agents/commands.js';
+import type { ExecutionStorage } from '../execution/storage.js';
 export interface McpToolContext {
     storage: SQLiteStorage;
     runCommand: (cmd: string) => string;
+    /** Workspace info — available when running in a workspace with agents */
+    getWorkspaceContext?: () => {
+        workspaceInfo: WorkspaceInfo;
+        executionStorage: ExecutionStorage;
+        db: Database.Database;
+        pmoPath: string;
+    };
 }
 export type McpToolResult = {
     content: Array<{

package/dist/lib/multiline-input.js

@@ -15,6 +15,7 @@
  */
 import * as readline from 'node:readline';
 import chalk from 'chalk';
+import { isNonTTY } from './prompt-json.js';
 // ANSI escape codes for terminal control
 const ESC = '\u001B';
 const CSI = `${ESC}[`;
@@ -83,7 +84,7 @@ function showCursor() {
 export async function multiLineInput(options) {
     const { message, default: defaultValue = '', hint = 'Ctrl+D to finish, Ctrl+C to cancel', required = false, validate, } = options;
     // If not a TTY, return the default value
-    if (!process.stdin.isTTY) {
+    if (isNonTTY()) {
         return { value: defaultValue, cancelled: false };
     }
     return new Promise((resolve) => {

package/dist/lib/pmo/base-command.js

@@ -3,7 +3,7 @@ import inquirer from 'inquirer';
 import { getPMOContext } from './pmo-context.js';
 import { styles } from '../styles.js';
 import { PromptCommand } from '../prompt-command.js';
-import { shouldOutputJson, outputPromptAsJson, outputErrorAsJson, createMetadata, } from '../prompt-json.js';
+import { shouldOutputJson, isNonTTY, outputPromptAsJson, outputErrorAsJson, createMetadata, } from '../prompt-json.js';
 /**
  * Base flags for JSON/agent mode support
  * Include these in your command's flags by spreading: ...jsonModeFlags
@@ -168,7 +168,7 @@ export class PMOCommand extends PromptCommand {
             return numA - numB;
         });
         // Auto-detect non-TTY: switch to JSON mode when no TTY present
-        const effectiveJsonMode = options?.jsonMode ?? (!process.stdin.isTTY
+        const effectiveJsonMode = options?.jsonMode ?? (isNonTTY()
             ? {
                 flags: { json: true },
                 commandName: this.id ?? 'unknown',
@@ -234,7 +234,7 @@ export class PMOCommand extends PromptCommand {
     async selectFromList(options) {
         const { message, items, getName, getValue, getCommand, jsonMode, allowCancel = false, cancelValue, } = options;
         // Auto-detect non-TTY: switch to JSON mode when no TTY present
-        const effectiveJsonMode = jsonMode ?? (!process.stdin.isTTY
+        const effectiveJsonMode = jsonMode ?? (isNonTTY()
             ? { flags: { json: true }, commandName: this.id ?? 'unknown' }
             : null);
         // Build choices with command field
@@ -285,7 +285,7 @@ export class PMOCommand extends PromptCommand {
     async promptForInput(options) {
         const { message, fieldName, defaultValue, validate, jsonMode } = options;
         // Auto-detect non-TTY: switch to JSON mode when no TTY present
-        const effectiveJsonMode = jsonMode ?? (!process.stdin.isTTY
+        const effectiveJsonMode = jsonMode ?? (isNonTTY()
             ? { flags: { json: true }, commandName: this.id ?? 'unknown', commandHint: '', example: undefined }
             : null);
         // Check for JSON mode

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

@@ -169,7 +169,7 @@ export class ActionStorage {
                 ? JSON.parse(row.default_category)
                 : undefined,
             defaultMoveToCategory: row.default_category,
-            modifiesCode: row.is_builtin === 1,
+            modifiesCode: row.modifies_code === 1,
             isBuiltin: row.is_builtin === 1,
             createdAt: new Date(row.created_at),
         };

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

@@ -693,6 +693,200 @@ git add -A && prlt commit "your change" && git push
             modifiesCode: true,
             position: 3,
         },
+        {
+            id: 'review',
+            name: 'Code Review',
+            description: 'Review the implementation and post feedback on the PR',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Code Review
+
+Review this ticket's implementation thoroughly:
+- Check for bugs, edge cases, and potential issues
+- Look for security vulnerabilities
+- Verify it meets all acceptance criteria
+- Check code quality and maintainability
+- Suggest improvements if appropriate
+
+After reviewing, determine your verdict:
+- **APPROVE**: Code is ready to merge, no significant issues
+- **REQUEST_CHANGES**: There are issues that must be fixed before merging
+- **COMMENT**: General feedback, no blocking issues but some suggestions
+
+Do NOT modify any code. This is a read-only review.`,
+            endPrompt: `When you have finished reviewing, post your review on the PR using \`gh pr review\`.
+
+Choose the appropriate command based on your verdict:
+
+**If approving:**
+\`\`\`bash
+gh pr review --approve --body "## Code Review
+
+### What looks good
+- ...
+
+### Verdict
+APPROVED - Code is ready to merge."
+\`\`\`
+
+**If requesting changes:**
+\`\`\`bash
+gh pr review --request-changes --body "## Code Review
+
+### What looks good
+- ...
+
+### Concerns
+- ...
+
+### Suggested improvements
+- ...
+
+### Verdict
+REQUEST CHANGES - Issues must be addressed before merging."
+\`\`\`
+
+**If commenting:**
+\`\`\`bash
+gh pr review --comment --body "## Code Review
+
+### What looks good
+- ...
+
+### Suggestions
+- ...
+
+### Verdict
+COMMENT - Some suggestions but no blocking issues."
+\`\`\`
+
+Format the body with: what looks good, concerns (if any), suggested improvements (if any), and your verdict.
+
+No commits are needed for code review.`,
+            suggestedForCategories: ['started', 'completed'],
+            modifiesCode: false,
+            position: 4,
+        },
+        {
+            id: 'review-fix',
+            name: 'Review & Fix',
+            description: 'Review the implementation, fix issues, and post feedback on the PR',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Review & Fix
+
+Review this ticket's implementation thoroughly and fix any issues found:
+- Check for bugs, edge cases, and potential issues
+- Look for security vulnerabilities
+- Verify it meets all acceptance criteria
+- Check code quality and maintainability
+- Fix any issues you find directly in the code
+
+**IMPORTANT: Commit and push frequently!**
+- Commit after each fix or logical group of changes
+- Push after every 1-2 commits to save your work
+
+\`\`\`bash
+git add -A && prlt commit "fix: address code review findings" && git push
+\`\`\``,
+            endPrompt: `When you have finished reviewing and fixing:
+
+1. **If issues were found and fixed**, post a review summary and push your fixes:
+   \`\`\`bash
+   gh pr review --comment --body "## Code Review & Fix Summary
+
+   ### Issues found and fixed
+   - ...
+
+   ### What looks good
+   - ...
+
+   ### Changes made
+   - ...
+   "
+   prlt commit "fix: address code review findings"
+   git push
+   \`\`\`
+
+2. **If no issues were found**, approve the PR:
+   \`\`\`bash
+   gh pr review --approve --body "## Code Review
+
+   ### What looks good
+   - ...
+
+   ### Verdict
+   APPROVED - Code looks great, no issues found."
+   \`\`\``,
+            suggestedForCategories: ['started', 'completed'],
+            modifiesCode: true,
+            position: 5,
+        },
+        {
+            id: 'revise',
+            name: 'Revise',
+            description: 'Pull the branch, read PR review feedback, implement fixes, and push',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Revise
+
+Address the feedback on this ticket's pull request:
+
+1. **Pull the latest branch** to ensure you have the most recent code:
+   \`\`\`bash
+   git pull
+   \`\`\`
+
+2. **Read all review comments and requested changes** from the PR:
+   \`\`\`bash
+   gh pr view
+   gh api repos/{owner}/{repo}/pulls/{number}/comments
+   \`\`\`
+
+3. **Understand each piece of feedback** before making changes — read carefully and understand the reviewer's intent
+
+4. **Implement the requested fixes** and address each review comment:
+   - Make the necessary code changes to address each point
+   - Respond to questions with explanations
+   - Ensure all requested changes are addressed
+
+**IMPORTANT: Commit and push frequently!**
+- Commit after each fix or logical group of changes
+- Push after every 1-2 commits to save your work
+
+\`\`\`bash
+git add -A && prlt commit "fix: address PR review feedback" && git push
+\`\`\``,
+            endPrompt: `After addressing all feedback:
+
+1. **Commit your changes**:
+   \`\`\`bash
+   git add -A
+   prlt commit "fix: address PR review feedback"
+   \`\`\`
+
+2. **Push your changes**:
+   \`\`\`bash
+   git push
+   \`\`\`
+
+3. **Optionally reply to resolved review threads** using the GitHub API:
+   \`\`\`bash
+   gh api repos/{owner}/{repo}/pulls/{number}/comments
+   \`\`\`
+
+The PR will be updated automatically with your pushed changes.`,
+            suggestedForCategories: ['completed'],
+            defaultMoveToCategory: 'started',
+            modifiesCode: true,
+            position: 6,
+        },
         {
             id: 'test',
             name: 'Write Tests',
@@ -733,56 +927,7 @@ git add -A && prlt commit "add tests for X" && git push
 **IMPORTANT:** Use the global \`prlt\` command.`,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: true,
-            position: 4,
-        },
-        {
-            id: 'review',
-            name: 'Code Review',
-            description: 'Review the implementation for issues',
-            prompt: `Review this ticket's implementation thoroughly:
-- Check for bugs, edge cases, and potential issues
-- Look for security vulnerabilities
-- Verify it meets all acceptance criteria
-- Check code quality and maintainability
-- Suggest improvements if appropriate
-
-Output a review summary with your findings and any concerns.`,
-            endPrompt: `When you have finished reviewing, output a detailed review summary with:
-- ✅ What looks good
-- ⚠️ Concerns or potential issues
-- 🔧 Suggested improvements
-- 📋 Verdict: Approve, Request Changes, or Needs Discussion
-
-No commits are needed for code review.`,
-            suggestedForCategories: ['started', 'completed'],
-            modifiesCode: false,
-            position: 5,
-        },
-        {
-            id: 'revise',
-            name: 'Revise',
-            description: 'Address PR feedback and review comments',
-            prompt: `${PRLT_USAGE_RULE}
-
----
-
-# Action: Revise
-
-Address the feedback on this ticket's pull request:
-- Review all comments and requested changes carefully
-- Make the necessary code changes to address each point
-- Respond to questions with explanations
-- Push updates to the PR branch
-- Mark resolved conversations as resolved`,
-            endPrompt: `After addressing the feedback:
-1. Commit your changes using \`prlt commit "your message"\`
-2. Push your changes: \`git push\`
-
-The PR will be updated automatically.`,
-            suggestedForCategories: ['completed'],
-            defaultMoveToCategory: 'started',
-            modifiesCode: true,
-            position: 6,
+            position: 7,
         },
     ];
     // Use INSERT OR REPLACE to always update builtin actions with latest prompts

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

@@ -169,6 +169,7 @@ export interface WorkActionRow {
     prompt: string;
     end_prompt: string | null;
     default_category: string | null;
+    modifies_code: number;
     is_builtin: number;
     position: number;
     created_at: string;

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

@@ -30,6 +30,26 @@ import { type JsonFlags } from './prompt-json.js';
  * ```
  */
 export declare abstract class PromptCommand extends Command {
+    /**
+     * TTY-aware log method - strips ANSI codes and emoji in non-TTY mode.
+     *
+     * Use this instead of this.log() when outputting styled text (chalk colors, emoji prefixes).
+     * In TTY mode, outputs styled text as-is. In non-TTY mode, strips ANSI and emoji.
+     *
+     * @param message - The styled message (may contain ANSI codes and emoji)
+     * @param args - Additional arguments passed to this.log()
+     */
+    protected logPlain(message?: string, ...args: string[]): void;
+    /**
+     * Check if plain output mode is active (non-TTY, PRLT_PLAIN, NO_COLOR).
+     * Convenience wrapper for use in commands.
+     */
+    protected get isPlain(): boolean;
+    /**
+     * Check if running in non-TTY environment.
+     * Convenience wrapper for use in commands.
+     */
+    protected get isNonTTY(): boolean;
     /**
      * Prompt wrapper - drop-in replacement for inquirer.prompt
      *

package/dist/lib/prompt-command.js

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import inquirer from 'inquirer';
-import { isAgentMode, outputPromptAsJson, createMetadata, normalizeChoices, } from './prompt-json.js';
+import { isAgentMode, isNonTTY, outputPromptAsJson, createMetadata, normalizeChoices, } from './prompt-json.js';
+import { isPlainOutput, plainText } from './styles.js';
 /**
  * Lightweight base command with prompt() method for JSON mode support.
  *
@@ -31,6 +32,41 @@ import { isAgentMode, outputPromptAsJson, createMetadata, normalizeChoices, } fr
  * ```
  */
 export class PromptCommand extends Command {
+    /**
+     * TTY-aware log method - strips ANSI codes and emoji in non-TTY mode.
+     *
+     * Use this instead of this.log() when outputting styled text (chalk colors, emoji prefixes).
+     * In TTY mode, outputs styled text as-is. In non-TTY mode, strips ANSI and emoji.
+     *
+     * @param message - The styled message (may contain ANSI codes and emoji)
+     * @param args - Additional arguments passed to this.log()
+     */
+    logPlain(message, ...args) {
+        if (message === undefined) {
+            this.log();
+            return;
+        }
+        if (isPlainOutput()) {
+            this.log(plainText(message), ...args);
+        }
+        else {
+            this.log(message, ...args);
+        }
+    }
+    /**
+     * Check if plain output mode is active (non-TTY, PRLT_PLAIN, NO_COLOR).
+     * Convenience wrapper for use in commands.
+     */
+    get isPlain() {
+        return isPlainOutput();
+    }
+    /**
+     * Check if running in non-TTY environment.
+     * Convenience wrapper for use in commands.
+     */
+    get isNonTTY() {
+        return isNonTTY();
+    }
     /**
      * Prompt wrapper - drop-in replacement for inquirer.prompt
      *
@@ -73,7 +109,7 @@ export class PromptCommand extends Command {
      */
     async prompt(questions, jsonModeConfig) {
         // Auto-detect non-TTY: switch to JSON mode when no TTY present
-        if (!jsonModeConfig && !process.stdin.isTTY) {
+        if (!jsonModeConfig && isNonTTY()) {
             jsonModeConfig = { flags: { json: true }, commandName: this.id ?? 'unknown' };
         }
         // Check for JSON/agent mode

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

@@ -193,6 +193,27 @@ export interface ExecutionResultJsonOutput {
  * Union type for all JSON output types
  */
 export type JsonOutput = PromptJsonOutput | SuccessJsonOutput | ErrorJsonOutput | DryRunJsonOutput | ConfirmationNeededJsonOutput | ExecutionResultJsonOutput;
+/**
+ * All valid JSON envelope type discriminators.
+ * Used for contract tests and schema validation.
+ */
+export declare const JSON_ENVELOPE_TYPES: readonly ["prompt", "success", "error", "dry-run", "confirmation_needed", "execution_result"];
+export type JsonEnvelopeType = typeof JSON_ENVELOPE_TYPES[number];
+/**
+ * Required fields per envelope type for contract validation.
+ * Tests use this to verify no fields are accidentally removed.
+ */
+export declare const JSON_ENVELOPE_REQUIRED_FIELDS: Record<JsonEnvelopeType, string[]>;
+/**
+ * Validate that a parsed JSON object conforms to the machine-mode envelope schema.
+ *
+ * Returns an array of validation errors (empty = valid).
+ * Useful for contract tests and runtime validation of JSON output.
+ *
+ * @param obj - Parsed JSON object to validate
+ * @returns Array of validation error strings (empty if valid)
+ */
+export declare function validateJsonEnvelope(obj: unknown): string[];
 /**
  * Flags interface for JSON mode detection
  */
@@ -211,9 +232,18 @@ export interface MachineOutputFlags {
     machine?: boolean;
 }
 /**
- * Check if the current environment is non-TTY (piped output)
+ * Check if the current environment is non-TTY (piped input or output)
+ *
+ * Uses the "either" strategy: returns true if EITHER stdin OR stdout is non-TTY.
+ * This covers the primary use case of scripts/agents calling prlt as a subprocess,
+ * where both stdin and stdout are typically non-TTY.
+ *
+ * Returns true if:
+ * - stdin is not a TTY (e.g., piped input)
+ * - stdout is not a TTY (e.g., piped output)
+ * - PRLT_JSON=1 environment variable is set (overrides TTY detection)
  *
- * @returns true if stdout is not a TTY (e.g., piped to another process)
+ * @returns true if either stdin or stdout is not a TTY, or PRLT_JSON=1 is set
  */
 export declare function isNonTTY(): boolean;
 /**
@@ -221,7 +251,8 @@ export declare function isNonTTY(): boolean;
  *
  * Returns true if:
  * - The --json flag is set (or -m/--machine aliases)
- * - The environment is non-TTY (piped output)
+ * - The PRLT_JSON=1 environment variable is set
+ * - Either stdin or stdout is non-TTY (piped input/output)
  *
  * @param flags - Command flags object
  * @returns true if JSON mode should be used
@@ -236,7 +267,8 @@ export declare const isAgentMode: typeof shouldOutputJson;
  *
  * Returns true if:
  * - The --json flag is set (or -m/--machine aliases)
- * - The environment is non-TTY (piped output)
+ * - The PRLT_JSON=1 environment variable is set
+ * - Either stdin or stdout is non-TTY (piped input/output)
  *
  * @param flags - Command flags object
  * @returns true if machine-readable output mode should be used