@proletariat/cli 0.2.0 → 0.3.1

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

@@ -0,0 +1,145 @@
+/**
+ * Execution Types
+ *
+ * Types for agent execution and runtime management.
+ */
+/**
+ * ExecutionEnvironment - Where the agent code runs.
+ */
+export type ExecutionEnvironment = 'devcontainer' | 'host' | 'docker' | 'vm';
+/**
+ * SessionManager - How agent sessions are managed inside the execution environment.
+ * - tmux: Run inside tmux session (can attach/detach, persistent)
+ * - direct: Run process directly (simple, no session management)
+ *
+ * Currently always 'tmux' for consistent session persistence across all environments.
+ */
+export type SessionManager = 'tmux' | 'direct';
+/**
+ * DisplayMode - How output is presented to the user.
+ * - terminal: Opens a new terminal tab attached to the tmux session
+ * - background: Runs detached, reattach later with `prlt session attach`
+ */
+export type DisplayMode = 'terminal' | 'background';
+/**
+ * OutputMode - How Claude Code displays its output.
+ * - interactive: Shows streaming UI with real-time tool calls, file reads, etc.
+ * - print: Outputs final result only (uses -p flag), better for logs/automation
+ */
+export type OutputMode = 'interactive' | 'print';
+export type ExecutorType = 'claude-code' | 'codex' | 'aider' | 'custom';
+export type TerminalApp = 'Terminal' | 'iTerm' | 'Alacritty' | 'Ghostty' | 'Kitty' | 'tmux' | 'Warp' | 'WezTerm';
+export type Shell = 'bash' | 'zsh' | 'fish';
+export type ExecutionStatus = 'starting' | 'running' | 'completed' | 'failed' | 'stopped';
+export interface AgentWork {
+    id: string;
+    ticketId: string;
+    agentName: string;
+    executor: ExecutorType;
+    environment: ExecutionEnvironment;
+    displayMode: DisplayMode;
+    sessionManager?: SessionManager;
+    sandboxed: boolean;
+    status: ExecutionStatus;
+    branch?: string;
+    pid?: string;
+    containerId?: string;
+    sessionId?: string;
+    host?: string;
+    logPath?: string;
+    startedAt: Date;
+    completedAt?: Date;
+    exitCode?: number;
+}
+export interface ExecutionContext {
+    ticketId: string;
+    ticketTitle: string;
+    ticketDescription?: string;
+    ticketSubtasks?: Array<{
+        title: string;
+        done: boolean;
+    }>;
+    ticketPriority?: string;
+    ticketCategory?: string;
+    epicTitle?: string;
+    specId?: string;
+    specTitle?: string;
+    specProblem?: string;
+    specSolution?: string;
+    agentName: string;
+    agentDir: string;
+    worktreePath: string;
+    branch: string;
+    hqPath?: string;
+    pmoPath?: string;
+    createPR?: boolean;
+    actionId?: string;
+    actionName?: string;
+    actionPrompt?: string;
+    actionEndPrompt?: string;
+    modifiesCode?: boolean;
+    prFeedback?: string;
+    isRevision?: boolean;
+}
+/**
+ * Map ticket category to branch type.
+ * Used when creating branches for agent work.
+ */
+export declare const CATEGORY_TO_BRANCH_TYPE: Record<string, string>;
+/**
+ * Get branch type from ticket category.
+ * Defaults to 'feat' if no mapping found.
+ */
+export declare function getBranchType(category?: string): string;
+/**
+ * Generate branch name for agent work.
+ * Format: {ticketId}/{type}/{owner}/{agent}/{slug}
+ *
+ * Example: TKT-054/feat/chris/altman/update-branch-naming
+ *
+ * - ticketId first for easy filtering: git branch | grep TKT-054
+ * - owner: the human who owns the HQ/spawned the agent
+ * - agent: the AI agent doing the work
+ */
+export declare function generateBranchName(ticketId: string, ticketTitle: string, ownerName: string, agentName: string, category?: string): string;
+export interface ExecutionConfig {
+    defaultEnvironment: ExecutionEnvironment;
+    defaultExecutor: ExecutorType;
+    autoExecute: boolean;
+    shell: Shell;
+    outputMode: OutputMode;
+    sandboxed: boolean;
+    tmux: {
+        session: string;
+        layout: 'split' | 'window';
+        controlMode: boolean;
+    };
+    terminal: {
+        app: TerminalApp;
+    };
+    devcontainer: {
+        defaultImage: string;
+        memory: string;
+        cpus: number;
+        autoStart: boolean;
+    };
+    docker: {
+        image: string;
+        network: string;
+        memory?: string;
+        cpus?: number;
+    };
+    vm: {
+        defaultHost?: string;
+        user: string;
+        keyPath?: string;
+        syncMethod: 'rsync' | 'git';
+    };
+}
+/**
+ * Extract ticket ID from a tmux session name.
+ * Session names like: prlt-TKT-347-implement or TKT-347-implement
+ * Returns the ticket ID (e.g., "TKT-347") or undefined if not found.
+ */
+export declare function extractTicketFromSession(sessionName: string | null | undefined): string | undefined;
+export declare const DEFAULT_EXECUTION_CONFIG: ExecutionConfig;

package/dist/lib/execution/types.js

@@ -0,0 +1,157 @@
+/**
+ * Execution Types
+ *
+ * Types for agent execution and runtime management.
+ */
+// =============================================================================
+// Branch Type Mapping
+// =============================================================================
+/**
+ * Map ticket category to branch type.
+ * Used when creating branches for agent work.
+ */
+export const CATEGORY_TO_BRANCH_TYPE = {
+    // ===========================================================================
+    // Conventional Commits (standard types)
+    // ===========================================================================
+    // feat - New features and additions
+    'feature': 'feat',
+    'feat': 'feat',
+    'new': 'feat',
+    // fix - Bug fixes
+    'bug': 'fix',
+    'fix': 'fix',
+    'bugfix': 'fix',
+    // docs - Documentation
+    'docs': 'docs',
+    'documentation': 'docs',
+    // test - Testing
+    'test': 'test',
+    'testing': 'test',
+    // chore - Maintenance tasks
+    'chore': 'chore',
+    'maintenance': 'chore',
+    // perf - Performance improvements
+    'performance': 'perf',
+    'perf': 'perf',
+    // ci - CI/CD pipeline
+    'ci': 'ci',
+    'pipeline': 'ci',
+    // build - Build system (mapped to 'ship' to avoid conflict with commit type)
+    'build': 'build',
+    'deps': 'build',
+    'dependencies': 'build',
+    // refactor - Code refactoring
+    'refactor': 'rfct',
+    'cleanup': 'rfct',
+    'rfct': 'rfct',
+    // ===========================================================================
+    // Extended Types (proletariat extras)
+    // ===========================================================================
+    // sec - Security fixes
+    'security': 'sec',
+    'sec': 'sec',
+    // db - Database changes
+    'database': 'db',
+    'migration': 'db',
+    'schema': 'db',
+    'db': 'db',
+    // rel - Releases
+    'release': 'rel',
+    'rel': 'rel',
+    // ===========================================================================
+    // 5Tool Founder Types (business/ops categories)
+    // ===========================================================================
+    // ship - Shipping and deployment
+    'ship': 'ship',
+    'deploy': 'ship',
+    'launch': 'ship',
+    // grow - Growth and marketing
+    'growth': 'grow',
+    'marketing': 'grow',
+    'grow': 'grow',
+    // cx - Customer experience/support
+    'support': 'cx',
+    'customer': 'cx',
+    'cx': 'cx',
+    // strat - Strategy and planning
+    'strategy': 'strat',
+    'planning': 'strat',
+    'strat': 'strat',
+    // ops - Operations
+    'ops': 'ops',
+    'operations': 'ops',
+    'bizops': 'ops',
+};
+/**
+ * Get branch type from ticket category.
+ * Defaults to 'feat' if no mapping found.
+ */
+export function getBranchType(category) {
+    if (!category)
+        return 'feat';
+    const normalized = category.toLowerCase().trim();
+    return CATEGORY_TO_BRANCH_TYPE[normalized] || 'feat';
+}
+/**
+ * Generate branch name for agent work.
+ * Format: {ticketId}/{type}/{owner}/{agent}/{slug}
+ *
+ * Example: TKT-054/feat/chris/altman/update-branch-naming
+ *
+ * - ticketId first for easy filtering: git branch | grep TKT-054
+ * - owner: the human who owns the HQ/spawned the agent
+ * - agent: the AI agent doing the work
+ */
+export function generateBranchName(ticketId, ticketTitle, ownerName, agentName, category) {
+    const type = getBranchType(category);
+    const slug = ticketTitle
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .substring(0, 20)
+        .replace(/-+$/, '');
+    return `${ticketId}/${type}/${ownerName}/${agentName}/${slug}`;
+}
+/**
+ * Extract ticket ID from a tmux session name.
+ * Session names like: prlt-TKT-347-implement or TKT-347-implement
+ * Returns the ticket ID (e.g., "TKT-347") or undefined if not found.
+ */
+export function extractTicketFromSession(sessionName) {
+    if (!sessionName)
+        return undefined;
+    const name = sessionName.replace(/^prlt-/, '');
+    const match = name.match(/^(TKT-\d+)/);
+    return match ? match[1] : undefined;
+}
+export const DEFAULT_EXECUTION_CONFIG = {
+    defaultEnvironment: 'host',
+    defaultExecutor: 'claude-code',
+    autoExecute: false,
+    shell: 'zsh', // macOS default
+    outputMode: 'interactive', // Show streaming UI by default
+    sandboxed: true, // Require approval for dangerous operations by default
+    tmux: {
+        session: 'proletariat',
+        layout: 'window',
+        controlMode: true, // Enable -CC for iTerm native integration by default
+    },
+    terminal: {
+        app: 'Terminal',
+    },
+    devcontainer: {
+        defaultImage: 'mcr.microsoft.com/devcontainers/base:ubuntu',
+        memory: '8g',
+        cpus: 4,
+        autoStart: true,
+    },
+    docker: {
+        image: 'claude-code:latest',
+        network: 'host',
+    },
+    vm: {
+        user: 'agent',
+        syncMethod: 'git',
+    },
+};

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

@@ -0,0 +1,75 @@
+import { PMOSetupResult } from '../pmo/index.js';
+export interface HQConfig {
+    type: 'hq';
+    created: string;
+    hqName: string;
+    hasPMO: boolean;
+    agents: string[];
+    repos: string[];
+}
+export interface InitOptions {
+    workspaceType: 'hq';
+    hqName: string;
+    hqPath: string;
+    selectedAgents: string[];
+    /** Suppress console output (for JSON/agent mode) */
+    quiet?: boolean;
+    repos?: Array<{
+        path: string;
+        action: 'move' | 'clone';
+    }>;
+    pmoSetup?: PMOSetupResult;
+    themeId?: string;
+    customTheme?: {
+        name: string;
+        displayName: string;
+        names: string[];
+    };
+    orgName?: string;
+}
+/**
+ * Validate that HQ path is not inside a git repository or another HQ
+ * Returns: { valid: true } or { valid: false, reason: string }
+ */
+export declare function validateHQLocation(location: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Prompt user for HQ name
+ */
+export declare function promptForHQName(): Promise<string>;
+/**
+ * Prompt user for HQ location
+ */
+export declare function promptForHQLocation(hqName: string): Promise<string>;
+/**
+ * Prompt user for organization selection or creation
+ */
+export declare function promptForOrganization(): Promise<string>;
+/**
+ * Create the basic HQ directory structure
+ *
+ * Structure:
+ * my-hq/
+ *   .proletariat/           # HQ config and database
+ *   repos/                  # Repositories
+ *   agents/
+ *     staff/                # Persistent agents
+ *     temp/                 # Ephemeral agents
+ */
+export declare function createHQStructure(hqPath: string, hqName: string, themeId?: string, quiet?: boolean): void;
+/**
+ * Create HQ database and config
+ */
+export declare function initializeHQDatabase(hqPath: string, options: InitOptions): void;
+/** @deprecated Use initializeHQDatabase instead */
+export declare const initializeWorkspaceDatabase: typeof initializeHQDatabase;
+/**
+ * Complete HQ initialization workflow
+ */
+export declare function initializeHQ(options: InitOptions): Promise<void>;
+/**
+ * Show next steps to user
+ */
+export declare function showNextSteps(options: InitOptions): Promise<void>;