@proletariat/cli 0.3.45 → 0.3.46

package/dist/lib/linear/config.js

@@ -0,0 +1,100 @@
+/**
+ * Linear Configuration Storage
+ *
+ * Stores Linear credentials and preferences in the workspace_settings table.
+ */
+const SETTINGS_TABLE = 'workspace_settings';
+// Config keys stored in workspace_settings table
+const LINEAR_CONFIG_KEYS = {
+    apiKey: 'linear.api_key',
+    defaultTeamId: 'linear.default_team_id',
+    defaultTeamKey: 'linear.default_team_key',
+    organizationName: 'linear.organization_name',
+};
+/**
+ * Get a setting value from the database.
+ */
+function getSetting(db, key) {
+    const row = db
+        .prepare(`SELECT value FROM ${SETTINGS_TABLE} WHERE key = ?`)
+        .get(key);
+    return row?.value ?? null;
+}
+/**
+ * Set a setting value in the database.
+ */
+function setSetting(db, key, value) {
+    db.prepare(`
+    INSERT INTO ${SETTINGS_TABLE} (key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(key, value);
+}
+/**
+ * Delete a setting from the database.
+ */
+function deleteSetting(db, key) {
+    db.prepare(`DELETE FROM ${SETTINGS_TABLE} WHERE key = ?`).run(key);
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Check if Linear is configured (API key is stored).
+ */
+export function isLinearConfigured(db) {
+    return getSetting(db, LINEAR_CONFIG_KEYS.apiKey) !== null;
+}
+/**
+ * Load Linear configuration from the database.
+ * Returns null if not configured.
+ */
+export function loadLinearConfig(db) {
+    const apiKey = getSetting(db, LINEAR_CONFIG_KEYS.apiKey);
+    if (!apiKey)
+        return null;
+    return {
+        apiKey,
+        defaultTeamId: getSetting(db, LINEAR_CONFIG_KEYS.defaultTeamId) ?? undefined,
+        defaultTeamKey: getSetting(db, LINEAR_CONFIG_KEYS.defaultTeamKey) ?? undefined,
+        organizationName: getSetting(db, LINEAR_CONFIG_KEYS.organizationName) ?? undefined,
+    };
+}
+/**
+ * Save Linear API key to the database.
+ */
+export function saveLinearApiKey(db, apiKey) {
+    setSetting(db, LINEAR_CONFIG_KEYS.apiKey, apiKey);
+}
+/**
+ * Save the default team for Linear operations.
+ */
+export function saveLinearDefaultTeam(db, teamId, teamKey) {
+    setSetting(db, LINEAR_CONFIG_KEYS.defaultTeamId, teamId);
+    setSetting(db, LINEAR_CONFIG_KEYS.defaultTeamKey, teamKey);
+}
+/**
+ * Save the organization name.
+ */
+export function saveLinearOrganization(db, name) {
+    setSetting(db, LINEAR_CONFIG_KEYS.organizationName, name);
+}
+/**
+ * Clear all Linear configuration from the database.
+ */
+export function clearLinearConfig(db) {
+    for (const key of Object.values(LINEAR_CONFIG_KEYS)) {
+        deleteSetting(db, key);
+    }
+}
+/**
+ * Get the stored Linear API key.
+ * Also checks PRLT_LINEAR_API_KEY and LINEAR_API_KEY environment variables.
+ */
+export function getLinearApiKey(db) {
+    // Environment variables take precedence
+    const envKey = process.env.PRLT_LINEAR_API_KEY || process.env.LINEAR_API_KEY;
+    if (envKey)
+        return envKey;
+    return getSetting(db, LINEAR_CONFIG_KEYS.apiKey);
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Linear Integration Module
+ *
+ * Provides Linear API access, PMO mapping, and sync capabilities.
+ */
+export { LinearClient } from './client.js';
+export { isLinearConfigured, loadLinearConfig, saveLinearApiKey, saveLinearDefaultTeam, saveLinearOrganization, clearLinearConfig, getLinearApiKey, } from './config.js';
+export { LinearMapper } from './mapper.js';
+export { LinearSync } from './sync.js';
+export type { LinearIssue, LinearTeam, LinearWorkflowState, LinearCycle, LinearConfig, LinearIssueFilter, LinearIssueMap, LinearSyncResult, } from './types.js';
+export { LINEAR_STATE_TO_PMO_CATEGORY, LINEAR_PRIORITY_TO_PMO, PMO_PRIORITY_TO_LINEAR, } from './types.js';

package/dist/lib/linear/index.js

@@ -0,0 +1,10 @@
+/**
+ * Linear Integration Module
+ *
+ * Provides Linear API access, PMO mapping, and sync capabilities.
+ */
+export { LinearClient } from './client.js';
+export { isLinearConfigured, loadLinearConfig, saveLinearApiKey, saveLinearDefaultTeam, saveLinearOrganization, clearLinearConfig, getLinearApiKey, } from './config.js';
+export { LinearMapper } from './mapper.js';
+export { LinearSync } from './sync.js';
+export { LINEAR_STATE_TO_PMO_CATEGORY, LINEAR_PRIORITY_TO_PMO, PMO_PRIORITY_TO_LINEAR, } from './types.js';

package/dist/lib/linear/mapper.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Linear Issue ↔ PMO Ticket Mapper
+ *
+ * Converts Linear issues to PMO tickets and manages the mapping table.
+ * Handles import (Linear → PMO) and reverse lookup for sync operations.
+ */
+import Database from 'better-sqlite3';
+import type { CreateTicketInput, PMOStorage, WorkflowStatus } from '../pmo/types.js';
+import type { LinearIssue, LinearIssueMap, LinearSyncResult } from './types.js';
+export declare class LinearMapper {
+    private db;
+    constructor(db: Database.Database);
+    /**
+     * Ensure the linear_issue_map table exists.
+     * Uses CREATE TABLE IF NOT EXISTS to match the schema defined in schema.ts.
+     */
+    private ensureTable;
+    /**
+     * Convert a Linear issue to a PMO ticket creation input.
+     * Finds the matching workflow status in the project's workflow.
+     */
+    issueToTicketInput(issue: LinearIssue, statuses: WorkflowStatus[]): CreateTicketInput;
+    /**
+     * Import a single Linear issue into PMO as a ticket.
+     * Returns the PMO ticket ID if created, null if already mapped.
+     */
+    importIssue(issue: LinearIssue, projectId: string, storage: PMOStorage, statuses: WorkflowStatus[]): Promise<{
+        ticketId: string;
+        created: boolean;
+    }>;
+    /**
+     * Batch import multiple Linear issues into PMO.
+     */
+    importIssues(issues: LinearIssue[], projectId: string, storage: PMOStorage, statuses: WorkflowStatus[]): Promise<LinearSyncResult>;
+    /**
+     * Create a mapping record.
+     */
+    createMapping(map: Omit<LinearIssueMap, 'lastSyncedAt'>): void;
+    /**
+     * Get a mapping by PMO ticket ID.
+     */
+    getByTicketId(ticketId: string): LinearIssueMap | null;
+    /**
+     * Get a mapping by Linear issue ID.
+     */
+    getByLinearId(linearIssueId: string): LinearIssueMap | null;
+    /**
+     * Get a mapping by Linear identifier (e.g., "ENG-123").
+     */
+    getByIdentifier(identifier: string): LinearIssueMap | null;
+    /**
+     * List all mappings.
+     */
+    listMappings(): LinearIssueMap[];
+    /**
+     * Update the last synced timestamp for a mapping.
+     */
+    updateSyncTimestamp(pmoTicketId: string): void;
+    /**
+     * Delete a mapping by PMO ticket ID.
+     */
+    deleteMapping(pmoTicketId: string): void;
+    /**
+     * Convert a database row to a LinearIssueMap.
+     */
+    private rowToMap;
+}

package/dist/lib/linear/mapper.js

@@ -0,0 +1,219 @@
+/**
+ * Linear Issue ↔ PMO Ticket Mapper
+ *
+ * Converts Linear issues to PMO tickets and manages the mapping table.
+ * Handles import (Linear → PMO) and reverse lookup for sync operations.
+ */
+import { PMO_TABLES } from '../pmo/schema.js';
+import { LINEAR_STATE_TO_PMO_CATEGORY, LINEAR_PRIORITY_TO_PMO, } from './types.js';
+export class LinearMapper {
+    db;
+    constructor(db) {
+        this.db = db;
+        this.ensureTable();
+    }
+    /**
+     * Ensure the linear_issue_map table exists.
+     * Uses CREATE TABLE IF NOT EXISTS to match the schema defined in schema.ts.
+     */
+    ensureTable() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${PMO_TABLES.linear_issue_map} (
+        pmo_ticket_id TEXT NOT NULL REFERENCES ${PMO_TABLES.tickets}(id) ON DELETE CASCADE,
+        linear_issue_id TEXT NOT NULL,
+        linear_identifier TEXT NOT NULL,
+        linear_team_key TEXT NOT NULL,
+        linear_url TEXT NOT NULL,
+        sync_direction TEXT NOT NULL DEFAULT 'inbound',
+        last_synced_at TIMESTAMP,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (pmo_ticket_id),
+        UNIQUE (linear_issue_id)
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_pmo_linear_issue_map_linear_id
+        ON ${PMO_TABLES.linear_issue_map}(linear_issue_id)
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_pmo_linear_issue_map_identifier
+        ON ${PMO_TABLES.linear_issue_map}(linear_identifier)
+    `);
+    }
+    /**
+     * Convert a Linear issue to a PMO ticket creation input.
+     * Finds the matching workflow status in the project's workflow.
+     */
+    issueToTicketInput(issue, statuses) {
+        // Map Linear state type to PMO state category
+        const pmoCategory = LINEAR_STATE_TO_PMO_CATEGORY[issue.state.type] ?? 'backlog';
+        // Find matching status by category
+        const matchingStatus = statuses.find((s) => s.category === pmoCategory);
+        const fallbackStatus = statuses.find((s) => s.isDefault) ?? statuses[0];
+        const targetStatus = matchingStatus ?? fallbackStatus;
+        // Map priority
+        const pmoPriority = LINEAR_PRIORITY_TO_PMO[issue.priority] ?? 'P2';
+        // Build description with Linear reference
+        const descriptionParts = [];
+        if (issue.description) {
+            descriptionParts.push(issue.description);
+        }
+        descriptionParts.push('');
+        descriptionParts.push(`---`);
+        descriptionParts.push(`_Imported from Linear: [${issue.identifier}](${issue.url})_`);
+        // Map labels
+        const labels = issue.labels.map((l) => l.name);
+        return {
+            title: issue.title,
+            description: descriptionParts.join('\n'),
+            priority: pmoPriority,
+            statusId: targetStatus?.id,
+            labels,
+            metadata: {
+                'linear.issue_id': issue.id,
+                'linear.identifier': issue.identifier,
+                'linear.url': issue.url,
+                'linear.team': issue.team.key,
+                'linear.state': issue.state.name,
+            },
+        };
+    }
+    /**
+     * Import a single Linear issue into PMO as a ticket.
+     * Returns the PMO ticket ID if created, null if already mapped.
+     */
+    async importIssue(issue, projectId, storage, statuses) {
+        // Check if already mapped
+        const existing = this.getByLinearId(issue.id);
+        if (existing) {
+            return { ticketId: existing.pmoTicketId, created: false };
+        }
+        // Convert to ticket input
+        const ticketInput = this.issueToTicketInput(issue, statuses);
+        // Create the PMO ticket
+        const ticket = await storage.createTicket(projectId, ticketInput);
+        // Record the mapping
+        this.createMapping({
+            pmoTicketId: ticket.id,
+            linearIssueId: issue.id,
+            linearIdentifier: issue.identifier,
+            linearTeamKey: issue.team.key,
+            linearUrl: issue.url,
+            syncDirection: 'inbound',
+            createdAt: new Date(),
+        });
+        return { ticketId: ticket.id, created: true };
+    }
+    /**
+     * Batch import multiple Linear issues into PMO.
+     */
+    async importIssues(issues, projectId, storage, statuses) {
+        const result = {
+            imported: 0,
+            updated: 0,
+            skipped: 0,
+            errors: [],
+        };
+        for (const issue of issues) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                const { created } = await this.importIssue(issue, projectId, storage, statuses);
+                if (created) {
+                    result.imported++;
+                }
+                else {
+                    result.skipped++;
+                }
+            }
+            catch (error) {
+                result.errors.push({
+                    identifier: issue.identifier,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return result;
+    }
+    // ===========================================================================
+    // Mapping CRUD
+    // ===========================================================================
+    /**
+     * Create a mapping record.
+     */
+    createMapping(map) {
+        this.db.prepare(`
+      INSERT INTO ${PMO_TABLES.linear_issue_map}
+        (pmo_ticket_id, linear_issue_id, linear_identifier, linear_team_key, linear_url, sync_direction, last_synced_at, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+    `).run(map.pmoTicketId, map.linearIssueId, map.linearIdentifier, map.linearTeamKey, map.linearUrl, map.syncDirection);
+    }
+    /**
+     * Get a mapping by PMO ticket ID.
+     */
+    getByTicketId(ticketId) {
+        const row = this.db.prepare(`
+      SELECT * FROM ${PMO_TABLES.linear_issue_map} WHERE pmo_ticket_id = ?
+    `).get(ticketId);
+        return row ? this.rowToMap(row) : null;
+    }
+    /**
+     * Get a mapping by Linear issue ID.
+     */
+    getByLinearId(linearIssueId) {
+        const row = this.db.prepare(`
+      SELECT * FROM ${PMO_TABLES.linear_issue_map} WHERE linear_issue_id = ?
+    `).get(linearIssueId);
+        return row ? this.rowToMap(row) : null;
+    }
+    /**
+     * Get a mapping by Linear identifier (e.g., "ENG-123").
+     */
+    getByIdentifier(identifier) {
+        const row = this.db.prepare(`
+      SELECT * FROM ${PMO_TABLES.linear_issue_map} WHERE linear_identifier = ?
+    `).get(identifier);
+        return row ? this.rowToMap(row) : null;
+    }
+    /**
+     * List all mappings.
+     */
+    listMappings() {
+        const rows = this.db.prepare(`
+      SELECT * FROM ${PMO_TABLES.linear_issue_map} ORDER BY created_at DESC
+    `).all();
+        return rows.map((row) => this.rowToMap(row));
+    }
+    /**
+     * Update the last synced timestamp for a mapping.
+     */
+    updateSyncTimestamp(pmoTicketId) {
+        this.db.prepare(`
+      UPDATE ${PMO_TABLES.linear_issue_map}
+      SET last_synced_at = CURRENT_TIMESTAMP
+      WHERE pmo_ticket_id = ?
+    `).run(pmoTicketId);
+    }
+    /**
+     * Delete a mapping by PMO ticket ID.
+     */
+    deleteMapping(pmoTicketId) {
+        this.db.prepare(`
+      DELETE FROM ${PMO_TABLES.linear_issue_map} WHERE pmo_ticket_id = ?
+    `).run(pmoTicketId);
+    }
+    /**
+     * Convert a database row to a LinearIssueMap.
+     */
+    rowToMap(row) {
+        return {
+            pmoTicketId: row.pmo_ticket_id,
+            linearIssueId: row.linear_issue_id,
+            linearIdentifier: row.linear_identifier,
+            linearTeamKey: row.linear_team_key,
+            linearUrl: row.linear_url,
+            syncDirection: row.sync_direction,
+            lastSyncedAt: row.last_synced_at ? new Date(row.last_synced_at) : undefined,
+            createdAt: new Date(row.created_at),
+        };
+    }
+}

package/dist/lib/linear/sync.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Linear Outbound Sync
+ *
+ * Handles syncing PMO ticket status changes back to Linear,
+ * attaching PR links, and posting status comments.
+ */
+import type { PMOStorage, Ticket } from '../pmo/types.js';
+import { LinearClient } from './client.js';
+import { LinearMapper } from './mapper.js';
+import type { LinearWorkflowState } from './types.js';
+export declare class LinearSync {
+    private client;
+    private mapper;
+    constructor(client: LinearClient, mapper: LinearMapper);
+    /**
+     * Sync a PMO ticket's status back to Linear.
+     * Finds the best matching Linear state based on category.
+     */
+    syncTicketStatus(ticket: Ticket, linearStates: LinearWorkflowState[]): Promise<boolean>;
+    /**
+     * Attach a PR link to the corresponding Linear issue.
+     */
+    syncPRLink(ticketId: string, prUrl: string, prTitle: string): Promise<boolean>;
+    /**
+     * Post a status update comment to the Linear issue.
+     */
+    syncStatusComment(ticketId: string, statusName: string, message?: string): Promise<boolean>;
+    /**
+     * Batch sync all mapped tickets that have changed since last sync.
+     * Returns counts of synced/skipped/errored items.
+     */
+    syncAllStatuses(storage: PMOStorage, mappings: ReturnType<LinearMapper['listMappings']>, linearStates: LinearWorkflowState[]): Promise<{
+        synced: number;
+        skipped: number;
+        errors: number;
+    }>;
+}

package/dist/lib/linear/sync.js

@@ -0,0 +1,89 @@
+/**
+ * Linear Outbound Sync
+ *
+ * Handles syncing PMO ticket status changes back to Linear,
+ * attaching PR links, and posting status comments.
+ */
+export class LinearSync {
+    client;
+    mapper;
+    constructor(client, mapper) {
+        this.client = client;
+        this.mapper = mapper;
+    }
+    /**
+     * Sync a PMO ticket's status back to Linear.
+     * Finds the best matching Linear state based on category.
+     */
+    async syncTicketStatus(ticket, linearStates) {
+        const mapping = this.mapper.getByTicketId(ticket.id);
+        if (!mapping)
+            return false;
+        const pmoCategory = ticket.statusCategory;
+        if (!pmoCategory)
+            return false;
+        // Find the best matching Linear state
+        const matchingState = linearStates.find((s) => s.type === pmoCategory);
+        if (!matchingState)
+            return false;
+        await this.client.updateIssueState(mapping.linearIssueId, matchingState.id);
+        this.mapper.updateSyncTimestamp(ticket.id);
+        return true;
+    }
+    /**
+     * Attach a PR link to the corresponding Linear issue.
+     */
+    async syncPRLink(ticketId, prUrl, prTitle) {
+        const mapping = this.mapper.getByTicketId(ticketId);
+        if (!mapping)
+            return false;
+        await this.client.attachUrl(mapping.linearIssueId, prUrl, `PR: ${prTitle}`);
+        // Also add a comment for visibility
+        await this.client.addComment(mapping.linearIssueId, `Pull request created: [${prTitle}](${prUrl})`);
+        this.mapper.updateSyncTimestamp(ticketId);
+        return true;
+    }
+    /**
+     * Post a status update comment to the Linear issue.
+     */
+    async syncStatusComment(ticketId, statusName, message) {
+        const mapping = this.mapper.getByTicketId(ticketId);
+        if (!mapping)
+            return false;
+        const body = message
+            ? `Status updated to **${statusName}**: ${message}`
+            : `Status updated to **${statusName}**`;
+        await this.client.addComment(mapping.linearIssueId, body);
+        this.mapper.updateSyncTimestamp(ticketId);
+        return true;
+    }
+    /**
+     * Batch sync all mapped tickets that have changed since last sync.
+     * Returns counts of synced/skipped/errored items.
+     */
+    async syncAllStatuses(storage, mappings, linearStates) {
+        const result = { synced: 0, skipped: 0, errors: 0 };
+        for (const mapping of mappings) {
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                const ticket = await storage.getTicket(mapping.pmoTicketId);
+                if (!ticket) {
+                    result.skipped++;
+                    continue;
+                }
+                // eslint-disable-next-line no-await-in-loop
+                const synced = await this.syncTicketStatus(ticket, linearStates);
+                if (synced) {
+                    result.synced++;
+                }
+                else {
+                    result.skipped++;
+                }
+            }
+            catch {
+                result.errors++;
+            }
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Linear Integration Types
+ *
+ * Type definitions for the Linear ↔ PMO integration layer.
+ */
+/**
+ * Represents a Linear issue as fetched from the API.
+ */
+export interface LinearIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    priority: number;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    team: {
+        id: string;
+        key: string;
+        name: string;
+    };
+    assignee?: {
+        id: string;
+        name: string;
+        email: string;
+    };
+    labels: Array<{
+        id: string;
+        name: string;
+        color: string;
+    }>;
+    cycle?: {
+        id: string;
+        name: string;
+        number: number;
+    };
+    project?: {
+        id: string;
+        name: string;
+    };
+    estimate?: number;
+    url: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Represents a Linear team (workspace organizational unit).
+ */
+export interface LinearTeam {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+}
+/**
+ * Represents a Linear workflow state.
+ */
+export interface LinearWorkflowState {
+    id: string;
+    name: string;
+    type: string;
+    color: string;
+    position: number;
+}
+/**
+ * Represents a Linear cycle (sprint).
+ */
+export interface LinearCycle {
+    id: string;
+    name: string;
+    number: number;
+    startsAt: string;
+    endsAt: string;
+}
+/**
+ * Linear connection configuration stored in workspace_settings.
+ */
+export interface LinearConfig {
+    apiKey: string;
+    defaultTeamId?: string;
+    defaultTeamKey?: string;
+    organizationName?: string;
+}
+/**
+ * Filters for querying Linear issues.
+ */
+export interface LinearIssueFilter {
+    teamId?: string;
+    teamKey?: string;
+    stateType?: string;
+    stateName?: string;
+    assigneeId?: string;
+    assigneeMe?: boolean;
+    labelName?: string;
+    cycleId?: string;
+    projectId?: string;
+    search?: string;
+    limit?: number;
+}
+/**
+ * Mapping record between a Linear issue and a PMO ticket.
+ * Stored in pmo_linear_issue_map table.
+ */
+export interface LinearIssueMap {
+    pmoTicketId: string;
+    linearIssueId: string;
+    linearIdentifier: string;
+    linearTeamKey: string;
+    linearUrl: string;
+    syncDirection: 'inbound' | 'outbound' | 'bidirectional';
+    lastSyncedAt?: Date;
+    createdAt: Date;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface LinearSyncResult {
+    imported: number;
+    updated: number;
+    skipped: number;
+    errors: Array<{
+        identifier: string;
+        error: string;
+    }>;
+}
+/**
+ * Status mapping between Linear state types and PMO state categories.
+ */
+export declare const LINEAR_STATE_TO_PMO_CATEGORY: Record<string, string>;
+/**
+ * Priority mapping between Linear (1-4) and PMO (P0-P3).
+ * Linear: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low
+ * PMO: P0=Critical, P1=High, P2=Medium, P3=Low
+ */
+export declare const LINEAR_PRIORITY_TO_PMO: Record<number, string>;
+export declare const PMO_PRIORITY_TO_LINEAR: Record<string, number>;