@proletariat/cli 0.3.111 → 0.3.112

package/dist/lib/reconcile/index.js

@@ -0,0 +1,377 @@
+/**
+ * Tier 2 State Reconciler — Runner (PRLT-1280)
+ *
+ * This module owns the IO: it talks to the database, the GitHub CLI, and
+ * the provider adapter layer. The pure rule logic lives in ./core.ts so
+ * it can be unit-tested without these dependencies.
+ *
+ * Scope (narrow — the ticket is very explicit about what this is NOT):
+ *   - Single idempotent reconciliation function on a schedule
+ *   - Provider-agnostic — the reconciler does not branch on provider type
+ *   - Fires normal state-transition code path so hooks & cleanup fire too
+ *
+ * Everything outside that — webhook listeners, LLM escalation, human
+ * inbox, supervision tree — is explicitly out of scope per PRLT-1280.
+ */
+import { PMO_TABLES } from '../pmo/schema.js';
+import { resolveTicketProvider } from '../providers/resolver.js';
+import { getPRForBranch, getPRByNumber } from '../pr/index.js';
+import { getWorkflowConfig } from '../work-lifecycle/settings.js';
+import { buildTransition, deriveExpectedState, formatTransitionLogLine } from './core.js';
+export { deriveExpectedState, buildTransition, formatTransitionLogLine } from './core.js';
+/**
+ * Non-terminal state categories that the reconciler scans.
+ *
+ * The ticket spec says:
+ *   "Query all tickets in non-terminal states across all connected
+ *    providers (Linear, PMO, Notion, Asana, Jira, Shortcut)"
+ *
+ * Terminal states (`completed`, `canceled`) are deliberately excluded —
+ * the reconciler never resurrects a closed ticket.
+ */
+const NON_TERMINAL_CATEGORIES = [
+    'triage',
+    'backlog',
+    'unstarted',
+    'started',
+];
+/**
+ * Default live PR lookup. Always goes to the remote — the Tier 2
+ * reconciler must not depend on any local PR cache.
+ */
+export const defaultPRLookup = (ref, cwd) => {
+    switch (ref.kind) {
+        case 'branch':
+            return getPRForBranch(ref.branch, cwd);
+        case 'number':
+            return getPRByNumber(ref.number, cwd);
+        case 'url': {
+            // `gh pr view <url>` works with either a number or URL; reuse it.
+            const num = parsePRNumberFromUrl(ref.url);
+            if (num !== null)
+                return getPRByNumber(num, cwd);
+            return null;
+        }
+    }
+};
+/**
+ * Run one reconciliation cycle.
+ *
+ * Strictly idempotent: if a ticket is already in its expected state the
+ * runner computes no transition and touches nothing. Running twice
+ * back-to-back produces no redundant side effects.
+ */
+export async function runReconcile(db, storage, options = {}) {
+    const startedAt = new Date();
+    const { dryRun = false, cwd, log, projectId } = options;
+    const prLookup = options.prLookup ?? defaultPRLookup;
+    // Workflow config is used to resolve "Done" / "In Progress" / "Review"
+    // column names for the ticket's board. Fall back gracefully if the
+    // settings table is missing (older databases, unit tests).
+    let workflowConfig;
+    try {
+        workflowConfig = getWorkflowConfig(db);
+    }
+    catch {
+        workflowConfig = undefined;
+    }
+    // Gather every non-terminal ticket in scope. Either one project if
+    // -P was passed, or every project in the workspace.
+    const projectIds = projectId ? [projectId] : await listAllProjectIds(storage);
+    const tickets = [];
+    for (const pid of projectIds) {
+        for (const category of NON_TERMINAL_CATEGORIES) {
+            try {
+                // eslint-disable-next-line no-await-in-loop -- sequential is fine; small N
+                const batch = await storage.listTickets(pid, { statusCategory: category });
+                tickets.push(...batch);
+            }
+            catch {
+                // Tolerate transient read errors on a single category; keep going.
+            }
+        }
+    }
+    log?.(`Scanning ${tickets.length} non-terminal ticket(s) across ${projectIds.length} project(s)...`);
+    const transitions = [];
+    const errors = [];
+    for (const ticket of tickets) {
+        try {
+            const linkedPRs = gatherLinkedPRs(db, ticket, prLookup, cwd);
+            if (linkedPRs.length === 0) {
+                continue;
+            }
+            // Resolve the provider for this ticket so we can log which backend
+            // owns it. The actual move happens through the same resolver later
+            // in applyTransition() — this is just for the transition record.
+            const providerName = providerNameFor(db, storage, ticket);
+            const decision = deriveExpectedState(toReconcileTicket(ticket), linkedPRs, workflowConfig);
+            if (!decision)
+                continue;
+            transitions.push(buildTransition({
+                ticket: toReconcileTicket(ticket),
+                provider: providerName,
+                targetState: decision.targetState,
+                reason: decision.reason,
+                driver: decision.driver,
+            }));
+        }
+        catch (err) {
+            errors.push({ ticketId: ticket.id, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // Apply (or dry-run) every transition. Failures on one ticket do not
+    // stop the others — the reconciler is a best-effort safety net.
+    const applied = [];
+    const skipped = [];
+    const failed = [];
+    for (const transition of transitions) {
+        log?.(formatTransitionLogLine(transition));
+        if (dryRun) {
+            skipped.push(transition);
+            continue;
+        }
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            await applyTransition(db, storage, transition);
+            applied.push(transition);
+            // Dual-identity tickets: if the primary provider is NOT local PMO,
+            // the local PMO board may still hold a stale mirror row. Nudge it
+            // to the same column so the local kanban view does not drift.
+            if (transition.provider !== 'pmo') {
+                // eslint-disable-next-line no-await-in-loop
+                await reconcilePmoMirror(db, storage, transition, log);
+            }
+        }
+        catch (err) {
+            failed.push({
+                transition,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const finishedAt = new Date();
+    return {
+        checked: tickets.length,
+        applied,
+        skipped,
+        failed,
+        errors,
+        startedAt: startedAt.toISOString(),
+        finishedAt: finishedAt.toISOString(),
+    };
+}
+// -----------------------------------------------------------------------------
+// PR lookup
+// -----------------------------------------------------------------------------
+/**
+ * Gather every PR linked to a ticket by:
+ *   1. the ticket's branch (if set), and
+ *   2. PR URLs stored in `pmo_external_execution_prs` under any of the
+ *      ticket's external-source identities.
+ *
+ * Every lookup goes through the live PR lookup function — no cache.
+ */
+function gatherLinkedPRs(db, ticket, prLookup, cwd) {
+    const results = [];
+    const seen = new Set(); // de-dupe by PR number
+    const push = (pr, source) => {
+        if (!pr)
+            return;
+        if (seen.has(pr.number))
+            return;
+        seen.add(pr.number);
+        results.push({ pr, source });
+    };
+    // 1. Ticket branch
+    if (ticket.branch) {
+        push(prLookup({ kind: 'branch', branch: ticket.branch }, cwd), 'ticket_branch');
+    }
+    // 2. PR URLs stored in the external execution map for this ticket.
+    //    A ticket can carry multiple external identities (metadata.external_id,
+    //    external_key) and can have been linked to multiple PRs over time.
+    const prUrls = listLinkedPrUrls(db, ticket);
+    for (const url of prUrls) {
+        push(prLookup({ kind: 'url', url }, cwd), 'external_map');
+    }
+    return results;
+}
+/**
+ * Read every PR URL stored for this ticket in `pmo_external_execution_prs`.
+ * Keyed by (provider, external_id) — the reconciler doesn't care which
+ * provider it came from, so we union across all of them.
+ */
+function listLinkedPrUrls(db, ticket) {
+    const urls = new Set();
+    const md = ticket.metadata ?? {};
+    // Collect every identifier that might key the external mapping table.
+    const externalIds = new Set();
+    if (md.external_id)
+        externalIds.add(md.external_id);
+    if (md.external_key)
+        externalIds.add(md.external_key);
+    // A PMO-native ticket's id can also appear in the map under provider='pmo'.
+    externalIds.add(ticket.id);
+    if (externalIds.size === 0)
+        return [];
+    let stmt;
+    try {
+        stmt = db.prepare(`
+      SELECT pr_url FROM ${PMO_TABLES.external_execution_prs}
+      WHERE external_id = ?
+    `);
+    }
+    catch {
+        // Table may not exist yet (fresh DB or older schema).
+        return [];
+    }
+    for (const extId of externalIds) {
+        try {
+            const rows = stmt.all(extId);
+            for (const row of rows)
+                urls.add(row.pr_url);
+        }
+        catch {
+            // Non-fatal: skip this id.
+        }
+    }
+    return [...urls];
+}
+/**
+ * Parse a PR number out of a github.com URL.
+ * Accepts both `/pull/123` and `/pull/123/...` shapes.
+ */
+function parsePRNumberFromUrl(url) {
+    const m = url.match(/\/pull\/(\d+)(?:\b|\/)/);
+    if (!m)
+        return null;
+    const n = Number.parseInt(m[1], 10);
+    return Number.isFinite(n) ? n : null;
+}
+// -----------------------------------------------------------------------------
+// Apply (goes through normal state-transition code path)
+// -----------------------------------------------------------------------------
+/**
+ * Apply a transition through the same provider adapter layer that
+ * `prlt ticket move` uses. This is load-bearing: it ensures hooks,
+ * provider sync, and worktree cleanup all fire.
+ */
+async function applyTransition(db, storage, transition) {
+    const ticket = await storage.getTicket(transition.ticketId);
+    if (!ticket) {
+        throw new Error(`Ticket ${transition.ticketId} vanished between scan and apply`);
+    }
+    const provider = resolveTicketProvider(ticket.id, ticket.projectId ?? transition.projectId, db, storage, ticket.metadata);
+    const result = await provider.moveTicket(ticket.id, transition.toState);
+    if (!result.success) {
+        throw new Error(result.error ?? 'moveTicket failed without an error message');
+    }
+}
+/**
+ * For tickets whose source of truth is an external provider (Linear,
+ * Jira, etc.), the local PMO board can still hold a mirror row. After
+ * successfully moving the external ticket, reconcile the local PMO side
+ * too so `prlt board` does not drift.
+ *
+ * Best effort — failures here never block the primary transition.
+ */
+async function reconcilePmoMirror(db, storage, transition, log) {
+    try {
+        const mirror = await storage.getTicket(transition.ticketId);
+        if (!mirror)
+            return;
+        // Only move if the mirror truly holds a different status — that way
+        // we stay idempotent and do not fire redundant hooks.
+        if (mirror.statusName && mirror.statusName.toLowerCase() === transition.toState.toLowerCase()) {
+            return;
+        }
+        // Use the pmo provider directly (bypass resolver so we definitely
+        // hit the local mirror, not bounce back to Linear).
+        const pmoProvider = resolveTicketProvider(mirror.id, mirror.projectId ?? transition.projectId, db, storage, 
+        // Strip external_source so the resolver picks PMO.
+        null);
+        if (pmoProvider.name !== 'pmo')
+            return;
+        const result = await pmoProvider.moveTicket(mirror.id, transition.toState);
+        if (!result.success && log) {
+            log(`[reconcile] pmo mirror update for ${mirror.id} failed: ${result.error}`);
+        }
+    }
+    catch (err) {
+        log?.(`[reconcile] pmo mirror update for ${transition.ticketId} errored: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+// -----------------------------------------------------------------------------
+// Project / provider resolution helpers
+// -----------------------------------------------------------------------------
+async function listAllProjectIds(storage) {
+    try {
+        const projects = await storage.listProjects();
+        return projects.map(p => p.id);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve the provider name for a ticket without triggering any state
+ * resolution or event emission. Used purely so the transition record
+ * can log which backend owns the ticket.
+ */
+function providerNameFor(db, storage, ticket) {
+    try {
+        const provider = resolveTicketProvider(ticket.id, ticket.projectId ?? '', db, storage, ticket.metadata);
+        return provider.name;
+    }
+    catch {
+        return 'pmo';
+    }
+}
+function toReconcileTicket(ticket) {
+    return {
+        id: ticket.id,
+        title: ticket.title,
+        projectId: ticket.projectId,
+        statusName: ticket.statusName,
+        statusCategory: ticket.statusCategory,
+        branch: ticket.branch,
+        metadata: ticket.metadata,
+    };
+}
+// -----------------------------------------------------------------------------
+// Watch loop
+// -----------------------------------------------------------------------------
+/**
+ * Run the reconciler on a timer until the caller-supplied `shouldStop`
+ * callback returns true.
+ *
+ * Each iteration runs one full {@link runReconcile} cycle and then sleeps
+ * for `intervalMs` before the next one. Errors inside a cycle are caught
+ * and surfaced via `log` — a single bad cycle never kills the watcher.
+ */
+export async function watchReconcile(db, storage, options = {}) {
+    const { intervalMs = 5 * 60 * 1000, shouldStop = () => false, onCycle, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), log, } = options;
+    // Cycle counter for tests that want to bound the loop.
+    let cycle = 0;
+    while (!shouldStop()) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const report = await runReconcile(db, storage, options);
+            cycle += 1;
+            log?.(`[reconcile] cycle ${cycle} complete — checked=${report.checked} ` +
+                `applied=${report.applied.length} skipped=${report.skipped.length} ` +
+                `failed=${report.failed.length}`);
+            onCycle?.(report);
+        }
+        catch (err) {
+            log?.(`[reconcile] cycle failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (shouldStop())
+            return;
+        // eslint-disable-next-line no-await-in-loop
+        await sleep(intervalMs);
+    }
+}
+// Exported for tests that want to call the PR URL parser directly.
+export { parsePRNumberFromUrl as _parsePRNumberFromUrl };
+//# sourceMappingURL=index.js.map

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

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

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"}