@proletariat/cli 0.3.46 → 0.3.48

package/dist/lib/external-issues/linear.js

@@ -0,0 +1,198 @@
+import { ExternalIssueAdapterError, toNormalizedEnvelope, } from './types.js';
+const DEFAULT_LINEAR_API_URL = 'https://api.linear.app/graphql';
+const LINEAR_ISSUES_QUERY = `
+  query IssuesForSpawn($teamKey: String!, $first: Int!) {
+    issues(
+      first: $first
+      filter: {
+        team: { key: { eq: $teamKey } }
+        state: { type: { nin: ["completed", "canceled"] } }
+      }
+      orderBy: updatedAt
+    ) {
+      nodes {
+        id
+        identifier
+        title
+        description
+        url
+        priority
+        labels {
+          nodes {
+            name
+          }
+        }
+        state {
+          name
+          type
+        }
+      }
+    }
+  }
+`;
+function priorityFromLinear(value) {
+    switch (value) {
+        case 1:
+            return 'P0';
+        case 2:
+            return 'P1';
+        case 3:
+            return 'P2';
+        case 4:
+            return 'P3';
+        default:
+            return null;
+    }
+}
+function ensureLinearConfig(config) {
+    const apiKey = config.apiKey || process.env.LINEAR_API_KEY || process.env.PRLT_LINEAR_API_KEY;
+    const team = config.team || process.env.PRLT_LINEAR_TEAM || process.env.LINEAR_TEAM_KEY;
+    const apiUrl = config.apiUrl || process.env.PRLT_LINEAR_API_URL || DEFAULT_LINEAR_API_URL;
+    if (!apiKey) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear API key. Set LINEAR_API_KEY or PRLT_LINEAR_API_KEY.');
+    }
+    if (!team) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear team key. Pass --team or set PRLT_LINEAR_TEAM.');
+    }
+    return { apiKey, team, apiUrl };
+}
+function ensureLinearIssueShape(issue) {
+    if (!issue.id || !issue.identifier || !issue.title || !issue.url) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear issue payload is missing required fields (id, identifier, title, url).', issue);
+    }
+}
+/**
+ * Normalize a raw Linear API issue node into a canonical IssueEnvelope.
+ */
+export function normalizeLinearIssue(rawIssue) {
+    if (!rawIssue || typeof rawIssue !== 'object') {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear issue payload is invalid.', rawIssue);
+    }
+    const issue = rawIssue;
+    ensureLinearIssueShape(issue);
+    const labels = (issue.labels?.nodes || [])
+        .map(label => label.name?.trim())
+        .filter((name) => Boolean(name));
+    const [projectKey] = issue.identifier.split('-');
+    return {
+        source: 'linear',
+        external_id: issue.id,
+        external_key: issue.identifier,
+        title: issue.title,
+        description: issue.description || '',
+        labels,
+        priority: priorityFromLinear(issue.priority),
+        status: issue.state?.name || 'Unknown',
+        url: issue.url,
+        project_key: projectKey || 'UNKNOWN',
+        assignee: null,
+        item_type: 'issue',
+        raw: rawIssue,
+    };
+}
+/**
+ * Normalize a raw Linear issue into a PMO-ready NormalizedIssueEnvelope.
+ */
+export function normalizeLinearIssueToEnvelope(rawIssue) {
+    const envelope = normalizeLinearIssue(rawIssue);
+    return toNormalizedEnvelope(envelope, 'feature');
+}
+/**
+ * Build a PMO ticket description from a NormalizedIssueEnvelope.
+ */
+export function buildLinearTicketDescription(envelope) {
+    const body = envelope.description.trim();
+    const metadataLines = [
+        `- Source: ${envelope.source.name}`,
+        `- External key: ${envelope.source.externalKey}`,
+        `- External id: ${envelope.source.externalId}`,
+        `- URL: ${envelope.source.url}`,
+        `- Status: ${envelope.status}`,
+        `- Priority: ${envelope.priority || 'Unset'}`,
+        `- Labels: ${envelope.labels.length > 0 ? envelope.labels.join(', ') : 'None'}`,
+    ];
+    const parts = [
+        body,
+        '## External Issue Context',
+        metadataLines.join('\n'),
+    ].filter(Boolean);
+    return parts.join('\n\n');
+}
+/**
+ * Build ticket metadata from a NormalizedIssueEnvelope for traceability.
+ */
+export function buildLinearMetadata(envelope) {
+    return {
+        external_source: envelope.source.name,
+        external_key: envelope.source.externalKey,
+        external_id: envelope.source.externalId,
+        external_url: envelope.source.url,
+        external_raw: JSON.stringify(envelope.source.raw),
+    };
+}
+/**
+ * Build a spawn context message from a NormalizedIssueEnvelope.
+ */
+export function buildLinearSpawnContextMessage(envelope, additionalMessage) {
+    const lines = [
+        `External issue source: ${envelope.source.name}`,
+        `External issue key: ${envelope.source.externalKey}`,
+        `External issue id: ${envelope.source.externalId}`,
+        `External issue URL: ${envelope.source.url}`,
+    ];
+    if (additionalMessage?.trim()) {
+        lines.push('', additionalMessage.trim());
+    }
+    return lines.join('\n');
+}
+/**
+ * Build a CLI command string for selecting a specific Linear issue.
+ */
+export function buildLinearIssueChoiceCommand(issueIdentifier, projectId) {
+    let command = `prlt work linear --issue ${issueIdentifier} --json`;
+    if (projectId) {
+        command += ` -P ${projectId}`;
+    }
+    return command;
+}
+/**
+ * Fetch and normalize Linear issues into NormalizedIssueEnvelopes.
+ */
+export async function listLinearIssues(configInput, options) {
+    const config = ensureLinearConfig(configInput);
+    const fetchImpl = options?.fetchImpl || fetch;
+    const limit = Math.max(1, Math.min(options?.limit ?? 20, 100));
+    const response = await fetchImpl(config.apiUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: config.apiKey,
+        },
+        body: JSON.stringify({
+            query: LINEAR_ISSUES_QUERY,
+            variables: {
+                teamKey: config.team,
+                first: limit,
+            },
+        }),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ExternalIssueAdapterError('AUTH_FAILED', 'Linear authentication failed. Verify your LINEAR_API_KEY token.');
+    }
+    if (!response.ok) {
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear request failed with status ${response.status}.`);
+    }
+    const payload = await response.json();
+    if (payload.errors && payload.errors.length > 0) {
+        const message = payload.errors[0]?.message || 'Unknown Linear API error.';
+        if (/auth|token|forbidden|unauthorized/i.test(message)) {
+            throw new ExternalIssueAdapterError('AUTH_FAILED', `Linear authentication failed: ${message}`);
+        }
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', `Linear API error: ${message}`);
+    }
+    const nodes = payload.data?.issues?.nodes;
+    if (!Array.isArray(nodes)) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Linear response payload was missing issues.nodes.', payload);
+    }
+    return nodes.map(normalizeLinearIssueToEnvelope);
+}

package/dist/lib/external-issues/types.d.ts

@@ -142,3 +142,70 @@ export declare class ExternalIssueError extends Error {
     validationErrors?: IssueValidationError[] | undefined;
     constructor(code: ExternalIssueErrorCode, message: string, source?: IssueSource | undefined, validationErrors?: IssueValidationError[] | undefined);
 }
+/**
+ * Error codes for adapter-level operations (config, auth, payload, request).
+ */
+export type ExternalIssueAdapterErrorCode = 'MISSING_CONFIG' | 'AUTH_FAILED' | 'BAD_PAYLOAD' | 'REQUEST_FAILED';
+/**
+ * Typed error for external issue adapter operations.
+ *
+ * Covers config, auth, payload, and request failures that occur
+ * when interacting with a specific external issue source.
+ */
+export declare class ExternalIssueAdapterError extends Error {
+    readonly code: ExternalIssueAdapterErrorCode;
+    readonly causeDetail?: unknown | undefined;
+    constructor(code: ExternalIssueAdapterErrorCode, message: string, causeDetail?: unknown | undefined);
+}
+/**
+ * Source metadata nested object for traceability.
+ */
+export interface IssueSourceMetadata {
+    /** Which external system the issue came from */
+    name: IssueSource;
+    /** Unique identifier in the external system (e.g., Linear UUID) */
+    externalId: string;
+    /** Human-readable key in the external system (e.g., "ENG-123") */
+    externalKey: string;
+    /** URL to view the issue in the external system */
+    url: string;
+    /** Original raw payload from the external system */
+    raw: Record<string, unknown>;
+}
+/**
+ * PMO-ready normalized issue envelope.
+ *
+ * Wraps a canonical IssueEnvelope with PMO-oriented fields (e.g., category)
+ * and a nested source metadata object for ergonomic access in commands.
+ *
+ * Produced by normalizing an IssueEnvelope into the shape expected by
+ * PMO ticket creation and the spawn context pipeline.
+ */
+export interface NormalizedIssueEnvelope {
+    /** Nested source metadata for traceability */
+    source: IssueSourceMetadata;
+    /** Issue title / summary */
+    title: string;
+    /** Issue description (markdown or plain text) */
+    description: string;
+    /** Labels / tags applied to the issue */
+    labels: string[];
+    /** Priority level (normalized to P0-P3 scale, or null) */
+    priority: string | null;
+    /** Current status name in the external system */
+    status: string;
+    /** Project key in the external system */
+    projectKey: string;
+    /** Assignee display name or identifier */
+    assignee: string | null;
+    /** PMO ticket category derived from source metadata (e.g., "feature") */
+    category: string | null;
+    /** Source-native work item kind when available */
+    itemType?: string | null;
+}
+/**
+ * Convert a canonical IssueEnvelope to a NormalizedIssueEnvelope.
+ *
+ * Deterministic: same input always produces same output.
+ */
+export declare function toNormalizedEnvelope(envelope: IssueEnvelope, category?: string | null): NormalizedIssueEnvelope;

package/dist/lib/external-issues/types.js

@@ -24,3 +24,44 @@ export class ExternalIssueError extends Error {
         this.name = 'ExternalIssueError';
     }
 }
+/**
+ * Typed error for external issue adapter operations.
+ *
+ * Covers config, auth, payload, and request failures that occur
+ * when interacting with a specific external issue source.
+ */
+export class ExternalIssueAdapterError extends Error {
+    code;
+    causeDetail;
+    constructor(code, message, causeDetail) {
+        super(message);
+        this.code = code;
+        this.causeDetail = causeDetail;
+        this.name = 'ExternalIssueAdapterError';
+    }
+}
+/**
+ * Convert a canonical IssueEnvelope to a NormalizedIssueEnvelope.
+ *
+ * Deterministic: same input always produces same output.
+ */
+export function toNormalizedEnvelope(envelope, category) {
+    return {
+        source: {
+            name: envelope.source,
+            externalId: envelope.external_id,
+            externalKey: envelope.external_key,
+            url: envelope.url,
+            raw: envelope.raw,
+        },
+        title: envelope.title,
+        description: envelope.description,
+        labels: envelope.labels,
+        priority: envelope.priority,
+        status: envelope.status,
+        projectKey: envelope.project_key,
+        assignee: envelope.assignee,
+        category: category ?? null,
+        itemType: envelope.item_type ?? null,
+    };
+}

package/dist/lib/init/index.d.ts

@@ -35,6 +35,10 @@ export declare function validateHQLocation(location: string): {
     valid: boolean;
     reason?: string;
 };
+/**
+ * Check if an HQ name is already in use by another headquarters on this machine.
+ */
+export declare function isHQNameTaken(name: string): boolean;
 /**
  * Prompt user for HQ name
  */

package/dist/lib/init/index.js

@@ -8,7 +8,7 @@ import { createAgentWorktrees } from '../agents/index.js';
 import { addRepositoriesToHQ, isInGitRepo } from '../repos/index.js';
 import { createPMO, } from '../pmo/index.js';
 import { createWorkspaceDatabase, addRepositoriesToDatabase, addAgentsToDatabase, createTheme, addThemeNames, setActiveTheme } from '../database/index.js';
-import { ensureMachineConfigDir, registerHeadquarters, getOrganizations, createOrganization, } from '../machine-config.js';
+import { ensureMachineConfigDir, registerHeadquarters, getOrganizations, createOrganization, findHeadquartersByName, } from '../machine-config.js';
 import { hasGitHubRemote } from '../repos/git.js';
 import { isGHInstalled, isGHAuthenticated } from '../pr/index.js';
 /**
@@ -55,6 +55,13 @@ export function validateHQLocation(location) {
     }
     return { valid: true };
 }
+/**
+ * Check if an HQ name is already in use by another headquarters on this machine.
+ */
+export function isHQNameTaken(name) {
+    const existing = findHeadquartersByName(name);
+    return existing.length > 0;
+}
 /**
  * Prompt user for HQ name
  */
@@ -74,6 +81,9 @@ export async function promptForHQName() {
                 if (!/^[a-zA-Z0-9-_]+$/.test(input)) {
                     return 'Name can only contain letters, numbers, hyphens, and underscores';
                 }
+                if (isHQNameTaken(input.trim())) {
+                    return `HQ name "${input.trim()}" is already in use on this machine. Pick another name.`;
+                }
                 return true;
             },
         }]);

package/dist/lib/machine-config.d.ts

@@ -40,6 +40,7 @@ export interface MachineConfig {
 }
 /**
  * Get the path to the machine-level config directory (~/.proletariat/).
+ * Uses process.env.HOME when set (for testability), falling back to os.homedir().
  */
 export declare function getMachineConfigDir(): string;
 /**

package/dist/lib/machine-config.js

@@ -5,9 +5,11 @@ import { isValidHQ } from './workspace.js';
 const CONFIG_VERSION = '1.0.0';
 /**
  * Get the path to the machine-level config directory (~/.proletariat/).
+ * Uses process.env.HOME when set (for testability), falling back to os.homedir().
  */
 export function getMachineConfigDir() {
-    return path.join(os.homedir(), '.proletariat');
+    const home = process.env.HOME || os.homedir();
+    return path.join(home, '.proletariat');
 }
 /**
  * Get the path to the machine-level config file (~/.proletariat/config.json).
@@ -32,9 +34,10 @@ export function ensureMachineConfigDir() {
  * - Removes trailing slashes
  */
 export function normalizePath(inputPath) {
-    // Expand ~ to home directory
+    // Expand ~ to home directory (respect process.env.HOME for testability)
+    const home = process.env.HOME || os.homedir();
     let resolved = inputPath.startsWith('~')
-        ? path.join(os.homedir(), inputPath.slice(1))
+        ? path.join(home, inputPath.slice(1))
         : inputPath;
     // Make absolute
     resolved = path.resolve(resolved);

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

@@ -219,6 +219,42 @@ export function registerWorkTools(server, ctx) {
             return errorResponse(error);
         }
     });
+    strictTool(server, 'work_review', 'Run automated review-fix pipeline on a ticket: spawns review agent, checks results, auto-spawns fix agent if issues found, re-reviews until clean or max cycles reached. Requires ticket to have a PR.', {
+        ticket_id: z.string().describe('Ticket ID to review'),
+        max_cycles: z.number().optional().describe('Maximum review-fix cycles (default: 3)'),
+        skip_permissions: z.boolean().optional().describe('Skip permission prompts (default: false)'),
+        environment: z.enum(['devcontainer', 'host']).optional().describe('Execution environment (default: devcontainer)'),
+    }, async (params) => {
+        try {
+            const args = [params.ticket_id, '--auto'];
+            if (params.max_cycles) {
+                args.push('--max-cycles', String(params.max_cycles));
+            }
+            if (params.skip_permissions) {
+                args.push('--skip-permissions');
+            }
+            if (params.environment === 'host') {
+                args.push('--run-on-host');
+            }
+            const cmd = `prlt work review ${args.join(' ')}`;
+            const output = ctx.runCommand(cmd);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            ticketId: params.ticket_id,
+                            command: cmd,
+                            output,
+                            message: `Review pipeline started for ${params.ticket_id}`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
     strictTool(server, 'work_spawn', 'Spawn work on a ticket using the full CLI pipeline (agent selection, Docker build, container creation, branch setup, tmux session). Shells out to "prlt work spawn" — works whenever prlt is installed, no workspace context needed in-process.', {
         ticket_id: z.string().describe('Ticket ID to spawn work for'),
         action: z.string().optional().describe('Action to perform (e.g., implement, groom, review, custom). Defaults to implement.'),

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

@@ -165,10 +165,10 @@ export class ActionStorage {
             description: row.description || undefined,
             prompt: row.prompt,
             endPrompt: row.end_prompt || undefined,
-            suggestedForCategories: row.default_category
-                ? JSON.parse(row.default_category)
+            suggestedForCategories: row.suggested_for_categories
+                ? JSON.parse(row.suggested_for_categories)
                 : undefined,
-            defaultMoveToCategory: row.default_category,
+            defaultMoveToCategory: row.default_move_to_category,
             modifiesCode: row.modifies_code === 1,
             isBuiltin: row.is_builtin === 1,
             createdAt: new Date(row.created_at),

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

@@ -817,7 +817,16 @@ After reviewing, determine your verdict:
 - **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. Do NOT attempt to fix any issues. This is a read-only review — report your findings only.
+## STRICT RULES - READ CAREFULLY
+
+- **DO NOT** merge the PR (\`gh pr merge\` is FORBIDDEN)
+- **DO NOT** push any code (\`git push\` is FORBIDDEN)
+- **DO NOT** run tests or test suites
+- **DO NOT** modify, edit, or write any code files
+- **DO NOT** create commits
+- Your ONLY output should be a \`gh pr review\` comment
+- This is a **read-only** review — read the diff, analyze it, post your review, and stop
+
 If you identify issues that need fixing, describe them in your review. A separate action (Review & Fix) will handle fixes.
 
 ${PRLT_COMMANDS_COMMON}
@@ -872,7 +881,7 @@ 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.
+**REMINDER:** Do NOT merge the PR. Do NOT run tests. Do NOT modify code. Only post the review comment above.
 
 **After posting your review**, if you found issues that need fixing, log them on the ticket so another action can address them:
 \`\`\`bash
@@ -884,6 +893,76 @@ prlt ticket edit <TICKET_ID> --add-subtask "Fix: <description of issue>"
             modifiesCode: false,
             position: 4,
         },
+        {
+            id: 'review-comment',
+            name: 'Review Comment',
+            description: 'Post review comments on a PR without merging, testing, or modifying code',
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Review Comment
+
+Read the PR diff, analyze the changes, and post a GitHub review comment. That is your ONLY job.
+
+## STRICT RULES - READ CAREFULLY
+
+You are a **read-only** reviewer. You MUST follow these rules:
+
+- **DO NOT** run \`gh pr merge\` — merging is FORBIDDEN
+- **DO NOT** run \`git push\` — pushing is FORBIDDEN
+- **DO NOT** run tests or test suites of any kind
+- **DO NOT** modify, edit, or write any code files
+- **DO NOT** create commits or branches
+- **DO NOT** run any commands that change repository state
+- Your **ONLY** permitted write operation is \`gh pr review\` to post your comment
+
+## What To Do
+
+1. Read the PR diff to understand the changes
+2. Analyze the code for bugs, issues, style, and correctness
+3. Post your review using \`gh pr review\` with the appropriate verdict
+4. **STOP** — do nothing else after posting the review
+
+${PRLT_COMMANDS_COMMON}
+${PRLT_COMMANDS_REVIEW}`,
+            endPrompt: `Post your review on the PR using \`gh pr review\`. This is the ONLY action you should take.
+
+**If approving:**
+\`\`\`bash
+gh pr review --approve --body "## Review
+
+### Summary
+- ...
+
+APPROVED - Looks good to merge."
+\`\`\`
+
+**If requesting changes:**
+\`\`\`bash
+gh pr review --request-changes --body "## Review
+
+### Issues
+- ...
+
+REQUEST CHANGES - Please address the above."
+\`\`\`
+
+**If commenting:**
+\`\`\`bash
+gh pr review --comment --body "## Review
+
+### Feedback
+- ...
+
+COMMENT - Some suggestions, no blockers."
+\`\`\`
+
+**CRITICAL REMINDER:** After posting your review, STOP. Do NOT merge the PR. Do NOT run tests. Do NOT modify code. Do NOT push anything. Your job is done after the \`gh pr review\` command.`,
+            suggestedForCategories: ['completed'],
+            modifiesCode: false,
+            position: 5,
+        },
         {
             id: 'review-fix',
             name: 'Review & Fix',
@@ -943,7 +1022,7 @@ ${PRLT_COMMANDS_REVIEW}`,
    \`\`\``,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: true,
-            position: 5,
+            position: 6,
         },
         {
             id: 'revise',
@@ -1007,7 +1086,7 @@ The PR will be updated automatically with your pushed changes.`,
             suggestedForCategories: ['completed'],
             defaultMoveToCategory: 'started',
             modifiesCode: true,
-            position: 6,
+            position: 7,
         },
         {
             id: 'explore-cli',
@@ -1168,7 +1247,7 @@ tmux_kill_session({ session: "qa-test" })
 \`\`\``,
             suggestedForCategories: [],
             modifiesCode: false,
-            position: 8,
+            position: 9,
         },
         {
             id: 'test',
@@ -1213,7 +1292,7 @@ ${PRLT_COMMANDS_CODE}`,
 **IMPORTANT:** Use the global \`prlt\` command.`,
             suggestedForCategories: ['started', 'completed'],
             modifiesCode: true,
-            position: 7,
+            position: 8,
         },
     ];
     // Use INSERT OR REPLACE to always update builtin actions with latest prompts

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

@@ -139,7 +139,7 @@ export class EpicStorage {
             updates.push('file_path = ?');
             params.push(changes.filePath);
         }
-        if (changes.specId !== undefined) {
+        if ('specId' in changes) {
             updates.push('spec_id = ?');
             params.push(changes.specId || null);
         }

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

@@ -301,8 +301,8 @@ export class TicketStorage {
             updates.assignee = changes.assignee;
         if (changes.branch !== undefined)
             updates.branch = changes.branch;
-        if (changes.specId !== undefined)
-            updates.specId = changes.specId;
+        if ('specId' in changes)
+            updates.specId = changes.specId ?? null;
         if (changes.lastSyncedFromSpec !== undefined) {
             updates.lastSyncedFromSpec = changes.lastSyncedFromSpec;
         }

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

@@ -168,7 +168,8 @@ export interface WorkActionRow {
     description: string | null;
     prompt: string;
     end_prompt: string | null;
-    default_category: string | null;
+    suggested_for_categories: string | null;
+    default_move_to_category: string | null;
     modifies_code: number;
     is_builtin: number;
     position: number;