@proletariat/cli 0.3.110 → 0.3.112

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

@@ -0,0 +1,133 @@
+/**
+ * Tier 2 State Reconciler — Types (PRLT-1280)
+ *
+ * The reconciler is the safety net that fixes board drift when Tier 1
+ * (event-driven hooks) misses an event. It polls the provider (GitHub for
+ * PR state) and fires normal ticket transitions when it detects drift.
+ *
+ * Design constraints:
+ * - Provider-agnostic: the reconciler core does not branch on provider type.
+ *   It routes every transition through the existing provider adapter layer.
+ * - Idempotent: running twice back-to-back must be safe. Every check asks
+ *   "is current == expected?" and no-ops when they match.
+ * - No LLM, no supervision tree, no daemon rewrite. One function on a timer.
+ */
+import type { PRInfo } from '../pr/index.js';
+import type { Ticket } from '../pmo/types.js';
+/**
+ * Source of a linked PR. Used for logging and to decide which PMO mapping
+ * to touch when the reconciler sees a transition is needed.
+ */
+export type LinkedPRSource = 'ticket_branch' | 'external_map';
+/**
+ * A PR linked to a ticket, along with its provenance.
+ */
+export interface LinkedPR {
+    /** Live PR info as reported by GitHub at the time of the reconcile cycle */
+    pr: PRInfo;
+    /** How this PR was discovered for the ticket */
+    source: LinkedPRSource;
+}
+/**
+ * A single transition the reconciler is about to apply (or would apply in dry-run).
+ */
+export interface ReconcileTransition {
+    /** Ticket being moved */
+    ticketId: string;
+    /** Ticket display title (for logging) */
+    ticketTitle: string;
+    /** The project the ticket belongs to */
+    projectId: string;
+    /** Provider name that owns this ticket (from resolver) */
+    provider: string;
+    /** Ticket's state before the transition */
+    fromState: string | null;
+    /** Ticket's state after the transition (target column name) */
+    toState: string;
+    /** PR number that drove this transition, when available */
+    prNumber?: number;
+    /** PR state that drove this transition (MERGED, CLOSED, OPEN) */
+    prState?: PRInfo['state'];
+    /** Human-readable reason for the transition */
+    reason: string;
+    /** ISO timestamp the reconciler decided on this transition */
+    decidedAt: string;
+}
+/**
+ * Options for running a reconcile cycle.
+ */
+export interface ReconcileOptions {
+    /** If true, compute transitions but do not apply them */
+    dryRun?: boolean;
+    /** Working directory for GitHub CLI calls (git remote, gh pr view) */
+    cwd?: string;
+    /** Optional callback for human-readable logs */
+    log?: (msg: string) => void;
+    /**
+     * Restrict reconciliation to a specific project. When omitted the
+     * reconciler runs workspace-wide across every project.
+     */
+    projectId?: string;
+    /**
+     * Injectable PR lookup. Tests use this to avoid the real gh CLI.
+     * Implementations must query live — the reconciler is not allowed to
+     * depend on a local PR cache.
+     */
+    prLookup?: PRLookupFn;
+}
+/**
+ * Function signature for live PR lookup.
+ *
+ * The reconciler calls this once per PR reference. Implementations must
+ * hit the remote GitHub API (gh CLI or the REST client) — a stale local
+ * cache defeats the whole point of a Tier 2 reconciler.
+ */
+export type PRLookupFn = (ref: PRLookupRef, cwd?: string) => PRInfo | null;
+/**
+ * A PR reference that can be resolved to a PRInfo.
+ *
+ * Tickets link to PRs via either their ticket branch (common for
+ * prlt-managed work) or via a stored URL in the external execution
+ * mapping table (common when the PR was opened outside prlt).
+ */
+export type PRLookupRef = {
+    kind: 'branch';
+    branch: string;
+} | {
+    kind: 'number';
+    number: number;
+} | {
+    kind: 'url';
+    url: string;
+};
+/**
+ * Report returned after a reconcile cycle completes.
+ */
+export interface ReconcileReport {
+    /** Total number of tickets considered (across all scanned projects) */
+    checked: number;
+    /** Transitions that were applied (or would be applied in dry-run) */
+    applied: ReconcileTransition[];
+    /** Transitions that the reconciler decided on but did not execute because of --dry-run */
+    skipped: ReconcileTransition[];
+    /** Transitions that failed to apply */
+    failed: Array<{
+        transition: ReconcileTransition;
+        error: string;
+    }>;
+    /** Non-fatal errors encountered while gathering state */
+    errors: Array<{
+        ticketId: string;
+        error: string;
+    }>;
+    /** ISO timestamp when the cycle started */
+    startedAt: string;
+    /** ISO timestamp when the cycle finished */
+    finishedAt: string;
+}
+/**
+ * Minimal view of a ticket the reconciler actually reads. Narrow surface
+ * makes the reconciler easy to unit-test without fabricating full Ticket
+ * objects.
+ */
+export type ReconcileTicket = Pick<Ticket, 'id' | 'title' | 'projectId' | 'statusName' | 'statusCategory' | 'branch' | 'metadata'>;

package/dist/lib/reconcile/types.js

@@ -0,0 +1,16 @@
+/**
+ * Tier 2 State Reconciler — Types (PRLT-1280)
+ *
+ * The reconciler is the safety net that fixes board drift when Tier 1
+ * (event-driven hooks) misses an event. It polls the provider (GitHub for
+ * PR state) and fires normal ticket transitions when it detects drift.
+ *
+ * Design constraints:
+ * - Provider-agnostic: the reconciler core does not branch on provider type.
+ *   It routes every transition through the existing provider adapter layer.
+ * - Idempotent: running twice back-to-back must be safe. Every check asks
+ *   "is current == expected?" and no-ops when they match.
+ * - No LLM, no supervision tree, no daemon rewrite. One function on a timer.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/reconcile/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/reconcile/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

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

@@ -0,0 +1,121 @@
+/**
+ * Session Renderer (PRLT-1272)
+ *
+ * Unified machine-wide session collection and grouped rendering.
+ *
+ * The principle: `prlt session list`, `prlt orchestrator status`, and related
+ * commands should ALWAYS query machine-wide for all sessions, regardless of
+ * whether the user is inside an HQ. Sessions are then visually grouped by
+ * their originating HQ — the current HQ bubbles to the top, other locations
+ * are still visible but de-emphasized.
+ *
+ * Sources collected:
+ *   1. machine.db `executions` table — cross-repo ticketless and ticketed work
+ *   2. Each registered HQ's workspace.db `agent_work` table — per-HQ workers
+ *   3. Discovered tmux/Docker orchestrator sessions — detected by name prefix
+ *
+ * Each entry is annotated with its hqPath/hqName/role so the renderer can
+ * group them.
+ */
+export type SessionRole = 'orchestrator' | 'worker' | 'headless';
+export type SessionStatus = 'starting' | 'running' | 'idle' | 'died' | 'stale' | 'stopped' | 'completed' | 'failed';
+/**
+ * Where a session record came from.
+ *   - `db`: tracked in workspace.db or machine.db
+ *   - `discovered`: found via tmux/Docker prefix scan (orphan)
+ */
+export type SessionSource = 'db' | 'discovered';
+/**
+ * A unified session record representing one running agent on the machine.
+ *
+ * Sessions originate from three sources:
+ *   - workspace.db (per-HQ agent_work table) → workers, ticketed
+ *   - machine.db (cross-repo executions table) → ticketless
+ *   - tmux/Docker discovery → orchestrators (named prlt-orchestrator-*)
+ */
+export interface UnifiedSession {
+    /** Stable identifier — sessionId where present, else execution id */
+    id: string;
+    /** tmux session name (or container synthetic id) */
+    sessionId: string;
+    /** Ticket id (e.g., 'PRLT-123', 'orchestrator', 'headless') */
+    ticketId: string;
+    /** Agent name (display) */
+    agentName: string;
+    /** Status — running/idle/stale/etc. */
+    status: SessionStatus;
+    /** Role — orchestrator vs worker vs headless */
+    role: SessionRole;
+    /** Execution environment */
+    environment: 'host' | 'container';
+    /** Container id (for container envs) */
+    containerId?: string;
+    /** Whether the runtime is verified alive */
+    exists: boolean;
+    /** Where the record was sourced from (backward compat field) */
+    source: SessionSource;
+    /** When this session started (best effort) */
+    startedAt?: Date;
+    /** Last heartbeat (workers only) */
+    lastHeartbeat?: Date;
+    /** Lifecycle state from DB (workers only) */
+    lifecycleState?: string;
+    /** HQ path this session originated from, if known */
+    hqPath?: string;
+    /** HQ name (display) */
+    hqName?: string;
+    /** Repo path the agent ran in (machine.db only, may differ from HQ) */
+    repoPath?: string;
+}
+export interface CollectOptions {
+    /** Include only sessions in this HQ path */
+    hqPathFilter?: string;
+    /** Filter to specific role */
+    roleFilter?: SessionRole;
+    /** Include stopped/completed sessions (default: only active runtimes) */
+    includeAll?: boolean;
+}
+export interface GroupedSessions {
+    /** Path of the HQ the user is currently in (resolved from cwd), if any */
+    currentHq?: string;
+    currentHqName?: string;
+    /** Sessions belonging to the current HQ */
+    here: UnifiedSession[];
+    /** Sessions in other HQs or headless */
+    elsewhere: UnifiedSession[];
+}
+/**
+ * Replace the user's home directory in a path with `~` for display.
+ */
+export declare function tildifyPath(p: string): string;
+/**
+ * Collect all sessions on the machine, regardless of cwd.
+ *
+ * Queries:
+ *   1. machine.db (cross-repo executions, source of truth for ticketless work)
+ *   2. Every registered HQ's workspace.db (workers per HQ)
+ *   3. tmux/Docker (orchestrators by name prefix)
+ *
+ * Filters are applied at the end so the underlying machine query path is
+ * the same in every command.
+ */
+export declare function collectAllSessions(options?: CollectOptions): UnifiedSession[];
+/**
+ * Group sessions into "current HQ" vs "other locations" buckets.
+ *
+ * The current HQ is resolved from `process.cwd()` (or an explicit override).
+ * Sessions whose hqPath matches the current HQ go into `here`; everything
+ * else goes into `elsewhere`.
+ */
+export declare function groupSessionsByHQ(sessions: UnifiedSession[], currentHqOverride?: string | null): GroupedSessions;
+/** Format a Date into a compact relative duration like "~15m", "~3h", "~2d". */
+export declare function formatRelativeAge(start?: Date, now?: Date): string;
+/**
+ * Group elsewhere sessions by hqPath/hqName for nicer rendering.
+ * Sessions without an hqPath are bucketed under "(no HQ)".
+ */
+export declare function bucketElsewhereByHq(elsewhere: UnifiedSession[]): Array<{
+    hqPath: string | null;
+    hqName: string;
+    sessions: UnifiedSession[];
+}>;