@proletariat/cli 0.3.93 → 0.3.95

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

@@ -0,0 +1,219 @@
+/**
+ * RuntimeCommand - Base class for commands that need workspace.db access.
+ *
+ * Hierarchy: PromptCommand → RuntimeCommand → PMOCommand
+ *
+ * Provides:
+ * - HQ workspace resolution (this.hqPath)
+ * - workspace.db lifecycle (this.db, auto-close on cleanup)
+ * - SettingsStore for workspace_settings (this.settings)
+ * - execute()/cleanup() lifecycle pattern
+ * - Generic prompt utilities (selectFromList, promptForInput, handleError)
+ *
+ * Use this base class for commands that need workspace database access
+ * but do NOT require a ticket provider (PMO, Linear, etc.). For commands
+ * that need ticket/project operations, use PMOCommand which extends this.
+ *
+ * Commands that don't need workspace.db should extend PromptCommand directly.
+ *
+ * @example
+ * ```typescript
+ * import { RuntimeCommand, runtimeBaseFlags } from '../../lib/runtime-command.js';
+ *
+ * export default class MyCommand extends RuntimeCommand {
+ *   static flags = { ...runtimeBaseFlags };
+ *
+ *   async execute(): Promise<void> {
+ *     // HQ path and workspace.db are available
+ *     const hqPath = this.requireHQ();
+ *     const db = this.requireDB();
+ *     const apiKey = this.settings?.get('linear.api_key');
+ *   }
+ * }
+ * ```
+ */
+import type Database from 'better-sqlite3';
+import { PromptCommand } from './prompt-command.js';
+import { type WorkspaceConfig } from './database/index.js';
+import { SettingsStore } from './database/settings-store.js';
+import { type JsonFlags } from './prompt-json.js';
+/**
+ * Base flags for machine-readable output mode.
+ * Include these in your command's flags by spreading: ...machineOutputFlags
+ */
+export declare const machineOutputFlags: {
+    json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    machine: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * Base flags for RuntimeCommand subclasses.
+ * Includes machine output flags. Add command-specific flags alongside.
+ */
+export declare const runtimeBaseFlags: {
+    json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    machine: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+export declare abstract class RuntimeCommand extends PromptCommand {
+    /**
+     * Workspace database connection.
+     * Available after init() runs. May be null if no HQ found or DB failed to open.
+     */
+    private _db;
+    /**
+     * Settings store for workspace_settings table.
+     * Available after init() runs. May be null if no DB available.
+     */
+    private _settings;
+    /**
+     * HQ workspace root path.
+     * Available after init() runs. May be null if not in an HQ workspace.
+     */
+    private _hqPath;
+    /**
+     * Workspace configuration from workspace.db.
+     * Available after init() runs. May be null if no DB available.
+     */
+    private _workspaceConfig;
+    /**
+     * Flag to track if runtime context was successfully initialized
+     */
+    private _runtimeInitialized;
+    /**
+     * oclif init hook - runs before the command executes.
+     * Resolves HQ workspace and opens workspace.db.
+     */
+    init(): Promise<void>;
+    /**
+     * Override run() to delegate to execute() and ensure cleanup.
+     * Subclasses should implement execute() instead of run().
+     */
+    run(): Promise<void>;
+    /**
+     * Main command logic — implement this instead of run().
+     * Runtime context (hqPath, db, settings) is available via getters.
+     */
+    protected abstract execute(): Promise<void>;
+    /**
+     * Cleanup handler — ensures database connections are closed.
+     * Called automatically after execute() completes or throws.
+     * Override in subclasses to add additional cleanup (call super.cleanup()).
+     */
+    protected cleanup(): Promise<void>;
+    /**
+     * oclif catch hook — called when an error occurs.
+     * Ensures cleanup even on errors.
+     */
+    catch(error: Error & {
+        exitCode?: number;
+    }): Promise<void>;
+    /**
+     * oclif finally hook — called after run() completes.
+     */
+    finally(_: Error | undefined): Promise<void>;
+    /** HQ workspace root path, or null if not in an HQ workspace. */
+    protected get hqPath(): string | null;
+    /** Workspace database connection, or null if not available. */
+    protected get db(): Database.Database | null;
+    /** Settings store for workspace_settings, or null if not available. */
+    protected get settings(): SettingsStore | null;
+    /** Workspace configuration, or null if not available. */
+    protected get workspaceConfig(): WorkspaceConfig | null;
+    /** Whether the runtime context was successfully initialized. */
+    protected get runtimeInitialized(): boolean;
+    /**
+     * Require HQ workspace to be available. Throws with a helpful
+     * error message if no HQ was found.
+     */
+    protected requireHQ(): string;
+    /**
+     * Require workspace database to be available. Throws with a helpful
+     * error message if the DB could not be opened.
+     */
+    protected requireDB(): Database.Database;
+    /**
+     * Require settings store to be available.
+     */
+    protected requireSettings(): SettingsStore;
+    /**
+     * Select from a list of items with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs choices as JSON with command field and exits
+     * In interactive mode: shows prompt and returns selected value
+     *
+     * @param options Configuration for the selection
+     * @returns The selected value (only in interactive mode)
+     *
+     * @example
+     * ```typescript
+     * const ticketId = await this.selectFromList({
+     *   message: 'Select ticket:',
+     *   items: tickets,
+     *   getName: (t) => `${t.id}: ${t.title}`,
+     *   getValue: (t) => t.id,
+     *   getCommand: (t) => `prlt ticket view ${t.id} --json`,
+     *   jsonMode: { flags, commandName: 'ticket view' },
+     * });
+     * ```
+     */
+    protected selectFromList<T>(options: {
+        /** Prompt message shown to user */
+        message: string;
+        /** Items to select from */
+        items: T[];
+        /** Extract display name from item */
+        getName: (item: T) => string;
+        /** Extract value from item */
+        getValue: (item: T) => string;
+        /** Build command string for item (should include --json) */
+        getCommand: (item: T) => string;
+        /** JSON mode config — if provided and flags indicate JSON mode, outputs JSON */
+        jsonMode?: {
+            flags: JsonFlags & Record<string, unknown>;
+            commandName: string;
+        } | null;
+        /** Optional: include a Cancel option */
+        allowCancel?: boolean;
+        /** Optional: custom cancel value (default: null returned) */
+        cancelValue?: string;
+    }): Promise<string | null>;
+    /**
+     * Prompt for input with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs field info as JSON and exits
+     * In interactive mode: shows prompt and returns input value
+     *
+     * @param options Configuration for the input
+     * @returns The input value (only in interactive mode)
+     */
+    protected promptForInput(options: {
+        /** Prompt message shown to user */
+        message: string;
+        /** Field name for the prompt */
+        fieldName: string;
+        /** Default value */
+        defaultValue?: string;
+        /** Validation function */
+        validate?: (input: string) => boolean | string;
+        /** JSON mode config */
+        jsonMode?: {
+            flags: JsonFlags & Record<string, unknown>;
+            commandName: string;
+            /** Hint for how to provide this value */
+            commandHint: string;
+            /** Example command */
+            example?: string;
+        } | null;
+    }): Promise<string>;
+    /**
+     * Unified error handler for JSON/interactive modes.
+     *
+     * Consolidates error handling to avoid message drift between JSON and interactive modes.
+     * In JSON mode: outputs structured error JSON and exits
+     * In interactive mode: calls this.error() with the message
+     */
+    protected handleError(code: string, message: string, options: {
+        jsonMode: boolean;
+        commandName: string;
+        flags: Record<string, unknown>;
+    }): void;
+}

package/dist/lib/runtime-command.js

@@ -0,0 +1,320 @@
+/**
+ * RuntimeCommand - Base class for commands that need workspace.db access.
+ *
+ * Hierarchy: PromptCommand → RuntimeCommand → PMOCommand
+ *
+ * Provides:
+ * - HQ workspace resolution (this.hqPath)
+ * - workspace.db lifecycle (this.db, auto-close on cleanup)
+ * - SettingsStore for workspace_settings (this.settings)
+ * - execute()/cleanup() lifecycle pattern
+ * - Generic prompt utilities (selectFromList, promptForInput, handleError)
+ *
+ * Use this base class for commands that need workspace database access
+ * but do NOT require a ticket provider (PMO, Linear, etc.). For commands
+ * that need ticket/project operations, use PMOCommand which extends this.
+ *
+ * Commands that don't need workspace.db should extend PromptCommand directly.
+ *
+ * @example
+ * ```typescript
+ * import { RuntimeCommand, runtimeBaseFlags } from '../../lib/runtime-command.js';
+ *
+ * export default class MyCommand extends RuntimeCommand {
+ *   static flags = { ...runtimeBaseFlags };
+ *
+ *   async execute(): Promise<void> {
+ *     // HQ path and workspace.db are available
+ *     const hqPath = this.requireHQ();
+ *     const db = this.requireDB();
+ *     const apiKey = this.settings?.get('linear.api_key');
+ *   }
+ * }
+ * ```
+ */
+import { Flags } from '@oclif/core';
+import inquirer from 'inquirer';
+import { PromptCommand } from './prompt-command.js';
+import { findHQRoot } from './workspace.js';
+import { openWorkspaceDatabase, getWorkspaceConfig } from './database/index.js';
+import { SettingsStore } from './database/settings-store.js';
+import { shouldOutputJson, isNonTTY, outputPromptAsJson, outputErrorAsJson, createMetadata, } from './prompt-json.js';
+import { withSignalSafePrompt } from './signal-handler.js';
+/**
+ * Base flags for machine-readable output mode.
+ * Include these in your command's flags by spreading: ...machineOutputFlags
+ */
+export const machineOutputFlags = {
+    json: Flags.boolean({
+        description: 'Output as JSON for AI agents/scripts',
+        default: false,
+    }),
+    machine: Flags.boolean({
+        char: 'm',
+        description: 'Output as JSON for AI agents/scripts',
+        default: false,
+    }),
+};
+/**
+ * Base flags for RuntimeCommand subclasses.
+ * Includes machine output flags. Add command-specific flags alongside.
+ */
+export const runtimeBaseFlags = {
+    ...machineOutputFlags,
+};
+export class RuntimeCommand extends PromptCommand {
+    /**
+     * Workspace database connection.
+     * Available after init() runs. May be null if no HQ found or DB failed to open.
+     */
+    _db = null;
+    /**
+     * Settings store for workspace_settings table.
+     * Available after init() runs. May be null if no DB available.
+     */
+    _settings = null;
+    /**
+     * HQ workspace root path.
+     * Available after init() runs. May be null if not in an HQ workspace.
+     */
+    _hqPath = null;
+    /**
+     * Workspace configuration from workspace.db.
+     * Available after init() runs. May be null if no DB available.
+     */
+    _workspaceConfig = null;
+    /**
+     * Flag to track if runtime context was successfully initialized
+     */
+    _runtimeInitialized = false;
+    /**
+     * oclif init hook - runs before the command executes.
+     * Resolves HQ workspace and opens workspace.db.
+     */
+    async init() {
+        await super.init();
+        this._hqPath = findHQRoot(process.cwd());
+        if (!this._hqPath) {
+            return; // No HQ found — subclass decides whether to error
+        }
+        try {
+            this._db = openWorkspaceDatabase(this._hqPath);
+            this._settings = new SettingsStore(this._db);
+            this._workspaceConfig = getWorkspaceConfig(this._hqPath);
+            this._runtimeInitialized = true;
+        }
+        catch {
+            // Database open failed — subclass decides how to handle
+        }
+    }
+    /**
+     * Override run() to delegate to execute() and ensure cleanup.
+     * Subclasses should implement execute() instead of run().
+     */
+    async run() {
+        try {
+            await this.execute();
+        }
+        finally {
+            await this.cleanup();
+        }
+    }
+    /**
+     * Cleanup handler — ensures database connections are closed.
+     * Called automatically after execute() completes or throws.
+     * Override in subclasses to add additional cleanup (call super.cleanup()).
+     */
+    async cleanup() {
+        if (this._runtimeInitialized && this._db) {
+            try {
+                this._db.close();
+            }
+            catch {
+                // Ignore close errors — database might already be closed
+            }
+            this._db = null;
+        }
+    }
+    /**
+     * oclif catch hook — called when an error occurs.
+     * Ensures cleanup even on errors.
+     */
+    async catch(error) {
+        await this.cleanup();
+        throw error;
+    }
+    /**
+     * oclif finally hook — called after run() completes.
+     */
+    async finally(_) {
+        await this.cleanup();
+    }
+    // ─── Getters ────────────────────────────────────────────────
+    /** HQ workspace root path, or null if not in an HQ workspace. */
+    get hqPath() {
+        return this._hqPath;
+    }
+    /** Workspace database connection, or null if not available. */
+    get db() {
+        return this._db;
+    }
+    /** Settings store for workspace_settings, or null if not available. */
+    get settings() {
+        return this._settings;
+    }
+    /** Workspace configuration, or null if not available. */
+    get workspaceConfig() {
+        return this._workspaceConfig;
+    }
+    /** Whether the runtime context was successfully initialized. */
+    get runtimeInitialized() {
+        return this._runtimeInitialized;
+    }
+    // ─── Require helpers (throw if missing) ─────────────────────
+    /**
+     * Require HQ workspace to be available. Throws with a helpful
+     * error message if no HQ was found.
+     */
+    requireHQ() {
+        if (!this._hqPath) {
+            throw new Error('Not in an HQ workspace. Run "prlt new" first.');
+        }
+        return this._hqPath;
+    }
+    /**
+     * Require workspace database to be available. Throws with a helpful
+     * error message if the DB could not be opened.
+     */
+    requireDB() {
+        if (!this._db) {
+            throw new Error('Workspace database not available. Run "prlt new" first.');
+        }
+        return this._db;
+    }
+    /**
+     * Require settings store to be available.
+     */
+    requireSettings() {
+        if (!this._settings) {
+            throw new Error('Workspace settings not available. Run "prlt new" first.');
+        }
+        return this._settings;
+    }
+    // ─── Prompt utilities ───────────────────────────────────────
+    /**
+     * Select from a list of items with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs choices as JSON with command field and exits
+     * In interactive mode: shows prompt and returns selected value
+     *
+     * @param options Configuration for the selection
+     * @returns The selected value (only in interactive mode)
+     *
+     * @example
+     * ```typescript
+     * const ticketId = await this.selectFromList({
+     *   message: 'Select ticket:',
+     *   items: tickets,
+     *   getName: (t) => `${t.id}: ${t.title}`,
+     *   getValue: (t) => t.id,
+     *   getCommand: (t) => `prlt ticket view ${t.id} --json`,
+     *   jsonMode: { flags, commandName: 'ticket view' },
+     * });
+     * ```
+     */
+    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 ?? (isNonTTY()
+            ? { flags: { json: true }, commandName: this.id ?? 'unknown' }
+            : null);
+        // Build choices with command field
+        const choices = items.map(item => ({
+            name: getName(item),
+            value: getValue(item),
+            command: getCommand(item),
+        }));
+        // Check for JSON mode
+        if (effectiveJsonMode && shouldOutputJson(effectiveJsonMode.flags)) {
+            outputPromptAsJson({
+                type: 'list',
+                name: 'selection',
+                message,
+                choices,
+            }, createMetadata(effectiveJsonMode.commandName, effectiveJsonMode.flags));
+            return null;
+        }
+        // Interactive mode
+        const interactiveChoices = choices.map(c => ({
+            name: c.name,
+            value: c.value,
+        }));
+        if (allowCancel) {
+            interactiveChoices.push({ name: '─'.repeat(20), value: '__separator__' }, { name: 'Cancel', value: cancelValue ?? '__cancel__' });
+        }
+        const { selection } = await withSignalSafePrompt(() => inquirer.prompt([{
+                type: 'list',
+                name: 'selection',
+                message,
+                choices: interactiveChoices,
+            }]));
+        if (selection === '__cancel__' || selection === '__separator__') {
+            return null;
+        }
+        return selection;
+    }
+    /**
+     * Prompt for input with JSON mode support for AI agents.
+     *
+     * In JSON mode: outputs field info as JSON and exits
+     * In interactive mode: shows prompt and returns input value
+     *
+     * @param options Configuration for the input
+     * @returns The input value (only in interactive mode)
+     */
+    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 ?? (isNonTTY()
+            ? { flags: { json: true }, commandName: this.id ?? 'unknown', commandHint: '', example: undefined }
+            : null);
+        // Check for JSON mode
+        if (effectiveJsonMode && shouldOutputJson(effectiveJsonMode.flags)) {
+            outputPromptAsJson({
+                type: 'input',
+                name: fieldName,
+                message,
+                default: defaultValue,
+                context: {
+                    hint: effectiveJsonMode.commandHint,
+                    example: effectiveJsonMode.example,
+                },
+            }, createMetadata(effectiveJsonMode.commandName, effectiveJsonMode.flags));
+            return '';
+        }
+        // Interactive mode
+        const { value } = await withSignalSafePrompt(() => inquirer.prompt([{
+                type: 'input',
+                name: 'value',
+                message,
+                default: defaultValue,
+                validate,
+            }]));
+        return value;
+    }
+    /**
+     * Unified error handler for JSON/interactive modes.
+     *
+     * Consolidates error handling to avoid message drift between JSON and interactive modes.
+     * In JSON mode: outputs structured error JSON and exits
+     * In interactive mode: calls this.error() with the message
+     */
+    handleError(code, message, options) {
+        if (options.jsonMode) {
+            outputErrorAsJson(code, message, createMetadata(options.commandName, options.flags));
+            return;
+        }
+        this.error(message);
+    }
+}
+//# sourceMappingURL=runtime-command.js.map

package/dist/lib/runtime-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-command.js","sourceRoot":"","sources":["../../src/lib/runtime-command.ts"],"names":[],"mappings":"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"}

package/dist/lib/session/heartbeat.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Agent Heartbeat
+ *
+ * Heartbeat recording and checking for agent executions.
+ * The heartbeat system has two sides:
+ *
+ * 1. Agent-side (push): Agents update their heartbeat when alive/active.
+ *    This is done by checking tmux pane liveness and JSONL file activity.
+ *
+ * 2. Host-side (pull): The watcher checks heartbeat timestamps and marks
+ *    stale executions as failed. This catches the case where the agent is
+ *    so dead it can't self-report (OOM, zombie processes).
+ */
+import { ExecutionStorage } from '../execution/storage.js';
+import type { AgentWork } from '../execution/types.js';
+/**
+ * Record a heartbeat for an execution by checking if its tmux session is alive.
+ * Uses tmux pane inspection to determine if the agent is still active.
+ *
+ * Returns the detected health state, or null if the session couldn't be found.
+ */
+export declare function recordHeartbeatFromSession(storage: ExecutionStorage, execution: AgentWork): string | null;
+/**
+ * Record heartbeats for all running executions.
+ * Returns a map of execution ID to detected state.
+ */
+export declare function recordAllHeartbeats(storage: ExecutionStorage): Map<string, string>;
+/**
+ * Information about a stale execution detected by heartbeat timeout.
+ */
+export interface StaleExecution {
+    execution: AgentWork;
+    lastHeartbeat: Date | null;
+    staleDurationMinutes: number;
+    reason: string;
+}
+/**
+ * Check for stale executions that have exceeded the heartbeat timeout.
+ */
+export declare function detectStaleExecutions(storage: ExecutionStorage, timeoutMinutes: number): StaleExecution[];
+/**
+ * Kill a Docker container by ID.
+ * Returns true if the container was killed or already stopped.
+ */
+export declare function killContainer(containerId: string): boolean;