@proletariat/cli 0.3.45 → 0.3.47

package/dist/lib/external-issues/types.js

@@ -0,0 +1,26 @@
+/**
+ * External Issue Adapter Types
+ *
+ * Canonical types for normalizing issues from external sources
+ * (Linear and Jira) into a shared IssueEnvelope format
+ * that can be mapped to spawn context.
+ */
+/**
+ * All valid issue sources as a const array.
+ */
+export const ISSUE_SOURCES = ['linear', 'jira'];
+/**
+ * Typed error for external issue operations.
+ */
+export class ExternalIssueError extends Error {
+    code;
+    source;
+    validationErrors;
+    constructor(code, message, source, validationErrors) {
+        super(message);
+        this.code = code;
+        this.source = source;
+        this.validationErrors = validationErrors;
+        this.name = 'ExternalIssueError';
+    }
+}

package/dist/lib/external-issues/validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * IssueEnvelope Validation
+ *
+ * Validates raw data into a canonical IssueEnvelope.
+ * Provides typed validation errors for missing or invalid fields.
+ */
+import { type IssueEnvelope, type IssueValidationResult } from './types.js';
+/**
+ * Validate and construct an IssueEnvelope from untyped input.
+ *
+ * Checks:
+ * - `source` is a valid IssueSource
+ * - Required string fields are present and non-empty
+ * - `description` is present (may be empty string)
+ * - `labels` is an array of strings
+ * - `priority` is a string or null
+ * - `assignee` is a string or null
+ * - `item_type` is optional, but if present must be a non-empty string or null
+ * - `raw` is a plain object
+ *
+ * @param input - Untyped input to validate
+ * @returns Validation result with either the valid envelope or an array of errors
+ */
+export declare function validateIssueEnvelope(input: unknown): IssueValidationResult;
+/**
+ * Validate an IssueEnvelope or throw an ExternalIssueError.
+ *
+ * Convenience wrapper around validateIssueEnvelope that throws on failure.
+ *
+ * @param input - Untyped input to validate
+ * @returns Valid IssueEnvelope
+ * @throws ExternalIssueError with code 'VALIDATION_FAILED' if invalid
+ */
+export declare function validateOrThrow(input: unknown): IssueEnvelope;

package/dist/lib/external-issues/validation.js

@@ -0,0 +1,219 @@
+/**
+ * IssueEnvelope Validation
+ *
+ * Validates raw data into a canonical IssueEnvelope.
+ * Provides typed validation errors for missing or invalid fields.
+ */
+import { ISSUE_SOURCES, ExternalIssueError, } from './types.js';
+/**
+ * Required string fields on IssueEnvelope (must be present and non-empty).
+ */
+const REQUIRED_STRING_FIELDS = [
+    'external_id',
+    'external_key',
+    'title',
+    'status',
+    'url',
+    'project_key',
+];
+/**
+ * Validate and construct an IssueEnvelope from untyped input.
+ *
+ * Checks:
+ * - `source` is a valid IssueSource
+ * - Required string fields are present and non-empty
+ * - `description` is present (may be empty string)
+ * - `labels` is an array of strings
+ * - `priority` is a string or null
+ * - `assignee` is a string or null
+ * - `item_type` is optional, but if present must be a non-empty string or null
+ * - `raw` is a plain object
+ *
+ * @param input - Untyped input to validate
+ * @returns Validation result with either the valid envelope or an array of errors
+ */
+export function validateIssueEnvelope(input) {
+    const errors = [];
+    if (typeof input !== 'object' || input === null) {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: '(root)',
+            message: 'Input must be a non-null object',
+        });
+        return { valid: false, errors };
+    }
+    const data = input;
+    // Validate source
+    if (!('source' in data) || data.source === undefined || data.source === null) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'source',
+            message: 'source is required',
+        });
+    }
+    else if (typeof data.source !== 'string') {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'source',
+            message: 'source must be a string',
+        });
+    }
+    else if (!ISSUE_SOURCES.includes(data.source)) {
+        errors.push({
+            code: 'INVALID_SOURCE',
+            field: 'source',
+            message: `source must be one of: ${ISSUE_SOURCES.join(', ')}. Got: "${data.source}"`,
+        });
+    }
+    // Validate required string fields
+    for (const field of REQUIRED_STRING_FIELDS) {
+        if (!(field in data) || data[field] === undefined || data[field] === null) {
+            errors.push({
+                code: 'MISSING_FIELD',
+                field,
+                message: `${field} is required`,
+            });
+        }
+        else if (typeof data[field] !== 'string') {
+            errors.push({
+                code: 'INVALID_FIELD_TYPE',
+                field,
+                message: `${field} must be a string`,
+            });
+        }
+        else if (data[field].trim() === '') {
+            errors.push({
+                code: 'EMPTY_FIELD',
+                field,
+                message: `${field} must not be empty`,
+            });
+        }
+    }
+    // Validate description (required, but may be empty string)
+    if (!('description' in data) || data.description === undefined || data.description === null) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'description',
+            message: 'description is required',
+        });
+    }
+    else if (typeof data.description !== 'string') {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'description',
+            message: 'description must be a string',
+        });
+    }
+    // Validate labels
+    if (!('labels' in data) || data.labels === undefined || data.labels === null) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'labels',
+            message: 'labels is required',
+        });
+    }
+    else if (!Array.isArray(data.labels)) {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'labels',
+            message: 'labels must be an array',
+        });
+    }
+    else {
+        for (let i = 0; i < data.labels.length; i++) {
+            if (typeof data.labels[i] !== 'string') {
+                errors.push({
+                    code: 'INVALID_FIELD_TYPE',
+                    field: `labels[${i}]`,
+                    message: `labels[${i}] must be a string`,
+                });
+            }
+        }
+    }
+    // Validate priority (string or null)
+    if (!('priority' in data) || data.priority === undefined) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'priority',
+            message: 'priority is required (use null if not set)',
+        });
+    }
+    else if (data.priority !== null && typeof data.priority !== 'string') {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'priority',
+            message: 'priority must be a string or null',
+        });
+    }
+    // Validate assignee (string or null)
+    if (!('assignee' in data) || data.assignee === undefined) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'assignee',
+            message: 'assignee is required (use null if not assigned)',
+        });
+    }
+    else if (data.assignee !== null && typeof data.assignee !== 'string') {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'assignee',
+            message: 'assignee must be a string or null',
+        });
+    }
+    // Validate item_type (optional: string or null)
+    if ('item_type' in data && data.item_type !== undefined) {
+        if (data.item_type !== null && typeof data.item_type !== 'string') {
+            errors.push({
+                code: 'INVALID_FIELD_TYPE',
+                field: 'item_type',
+                message: 'item_type must be a string or null',
+            });
+        }
+        else if (typeof data.item_type === 'string' && data.item_type.trim() === '') {
+            errors.push({
+                code: 'EMPTY_FIELD',
+                field: 'item_type',
+                message: 'item_type must not be empty when provided',
+            });
+        }
+    }
+    // Validate raw
+    if (!('raw' in data) || data.raw === undefined || data.raw === null) {
+        errors.push({
+            code: 'MISSING_FIELD',
+            field: 'raw',
+            message: 'raw is required',
+        });
+    }
+    else if (typeof data.raw !== 'object' || Array.isArray(data.raw)) {
+        errors.push({
+            code: 'INVALID_FIELD_TYPE',
+            field: 'raw',
+            message: 'raw must be a plain object',
+        });
+    }
+    if (errors.length > 0) {
+        return { valid: false, errors };
+    }
+    return {
+        valid: true,
+        envelope: data,
+    };
+}
+/**
+ * Validate an IssueEnvelope or throw an ExternalIssueError.
+ *
+ * Convenience wrapper around validateIssueEnvelope that throws on failure.
+ *
+ * @param input - Untyped input to validate
+ * @returns Valid IssueEnvelope
+ * @throws ExternalIssueError with code 'VALIDATION_FAILED' if invalid
+ */
+export function validateOrThrow(input) {
+    const result = validateIssueEnvelope(input);
+    if (!result.valid) {
+        const fieldList = result.errors.map((e) => e.field).join(', ');
+        throw new ExternalIssueError('VALIDATION_FAILED', `Issue envelope validation failed: invalid fields [${fieldList}]`, undefined, result.errors);
+    }
+    return result.envelope;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Linear API Client
+ *
+ * Thin wrapper around @linear/sdk providing typed access to
+ * Linear issues, teams, states, and cycles for the PMO integration.
+ */
+import type { LinearIssue, LinearTeam, LinearWorkflowState, LinearCycle, LinearIssueFilter } from './types.js';
+export declare class LinearClient {
+    private sdk;
+    constructor(apiKey: string);
+    /**
+     * Verify the API key is valid and return the authenticated user's organization.
+     */
+    verify(): Promise<{
+        organizationName: string;
+        userName: string;
+        email: string;
+    }>;
+    /**
+     * List all teams in the workspace.
+     */
+    listTeams(): Promise<LinearTeam[]>;
+    /**
+     * Get a team by its key (e.g., "ENG").
+     */
+    getTeamByKey(key: string): Promise<LinearTeam | null>;
+    /**
+     * List workflow states for a team.
+     */
+    listStates(teamId: string): Promise<LinearWorkflowState[]>;
+    /**
+     * List cycles for a team.
+     */
+    listCycles(teamId: string): Promise<LinearCycle[]>;
+    /**
+     * Fetch issues from Linear with optional filters.
+     */
+    listIssues(filter?: LinearIssueFilter): Promise<LinearIssue[]>;
+    /**
+     * Fetch a single issue by its identifier (e.g., "ENG-123").
+     */
+    getIssueByIdentifier(identifier: string): Promise<LinearIssue | null>;
+    /**
+     * Update the state of an issue.
+     */
+    updateIssueState(issueId: string, stateId: string): Promise<void>;
+    /**
+     * Add a comment to an issue.
+     */
+    addComment(issueId: string, body: string): Promise<void>;
+    /**
+     * Attach a URL to an issue (e.g., a PR link).
+     */
+    attachUrl(issueId: string, url: string, title: string): Promise<void>;
+}

package/dist/lib/linear/client.js

@@ -0,0 +1,254 @@
+/**
+ * Linear API Client
+ *
+ * Thin wrapper around @linear/sdk providing typed access to
+ * Linear issues, teams, states, and cycles for the PMO integration.
+ */
+import { LinearClient as SDKClient } from '@linear/sdk';
+export class LinearClient {
+    sdk;
+    constructor(apiKey) {
+        this.sdk = new SDKClient({ apiKey });
+    }
+    /**
+     * Verify the API key is valid and return the authenticated user's organization.
+     */
+    async verify() {
+        const viewer = await this.sdk.viewer;
+        const org = await this.sdk.organization;
+        return {
+            organizationName: org.name,
+            userName: viewer.name,
+            email: viewer.email,
+        };
+    }
+    /**
+     * List all teams in the workspace.
+     */
+    async listTeams() {
+        const teams = await this.sdk.teams();
+        return teams.nodes.map((t) => ({
+            id: t.id,
+            key: t.key,
+            name: t.name,
+            description: t.description ?? undefined,
+        }));
+    }
+    /**
+     * Get a team by its key (e.g., "ENG").
+     */
+    async getTeamByKey(key) {
+        const teams = await this.listTeams();
+        return teams.find((t) => t.key.toLowerCase() === key.toLowerCase()) ?? null;
+    }
+    /**
+     * List workflow states for a team.
+     */
+    async listStates(teamId) {
+        const team = await this.sdk.team(teamId);
+        const states = await team.states();
+        return states.nodes.map((s) => ({
+            id: s.id,
+            name: s.name,
+            type: s.type,
+            color: s.color,
+            position: s.position,
+        }));
+    }
+    /**
+     * List cycles for a team.
+     */
+    async listCycles(teamId) {
+        const team = await this.sdk.team(teamId);
+        const cycles = await team.cycles();
+        return cycles.nodes.map((c) => ({
+            id: c.id,
+            name: c.name ?? `Cycle ${c.number}`,
+            number: c.number,
+            startsAt: c.startsAt?.toISOString() ?? '',
+            endsAt: c.endsAt?.toISOString() ?? '',
+        }));
+    }
+    /**
+     * Fetch issues from Linear with optional filters.
+     */
+    async listIssues(filter = {}) {
+        const queryFilter = {};
+        if (filter.teamId) {
+            queryFilter.team = { id: { eq: filter.teamId } };
+        }
+        else if (filter.teamKey) {
+            queryFilter.team = { key: { eq: filter.teamKey } };
+        }
+        if (filter.stateType) {
+            queryFilter.state = { type: { eq: filter.stateType } };
+        }
+        else if (filter.stateName) {
+            queryFilter.state = { name: { eqIgnoreCase: filter.stateName } };
+        }
+        if (filter.assigneeMe) {
+            const viewer = await this.sdk.viewer;
+            queryFilter.assignee = { id: { eq: viewer.id } };
+        }
+        else if (filter.assigneeId) {
+            queryFilter.assignee = { id: { eq: filter.assigneeId } };
+        }
+        if (filter.labelName) {
+            queryFilter.labels = { name: { eqIgnoreCase: filter.labelName } };
+        }
+        if (filter.cycleId) {
+            queryFilter.cycle = { id: { eq: filter.cycleId } };
+        }
+        if (filter.projectId) {
+            queryFilter.project = { id: { eq: filter.projectId } };
+        }
+        const issues = await this.sdk.issues({
+            filter: queryFilter,
+            first: filter.limit ?? 50,
+        });
+        const results = [];
+        for (const issue of issues.nodes) {
+            // eslint-disable-next-line no-await-in-loop
+            const state = await issue.state;
+            // eslint-disable-next-line no-await-in-loop
+            const team = await issue.team;
+            // eslint-disable-next-line no-await-in-loop
+            const assignee = await issue.assignee;
+            // eslint-disable-next-line no-await-in-loop
+            const labelsConn = await issue.labels();
+            // eslint-disable-next-line no-await-in-loop
+            const cycle = await issue.cycle;
+            // eslint-disable-next-line no-await-in-loop
+            const project = await issue.project;
+            results.push({
+                id: issue.id,
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description ?? undefined,
+                priority: issue.priority,
+                state: state ? {
+                    id: state.id,
+                    name: state.name,
+                    type: state.type,
+                } : { id: '', name: 'Unknown', type: 'backlog' },
+                team: team ? {
+                    id: team.id,
+                    key: team.key,
+                    name: team.name,
+                } : { id: '', key: '', name: 'Unknown' },
+                assignee: assignee ? {
+                    id: assignee.id,
+                    name: assignee.name,
+                    email: assignee.email,
+                } : undefined,
+                labels: labelsConn.nodes.map((l) => ({
+                    id: l.id,
+                    name: l.name,
+                    color: l.color,
+                })),
+                cycle: cycle ? {
+                    id: cycle.id,
+                    name: cycle.name ?? `Cycle ${cycle.number}`,
+                    number: cycle.number,
+                } : undefined,
+                project: project ? {
+                    id: project.id,
+                    name: project.name,
+                } : undefined,
+                estimate: issue.estimate ?? undefined,
+                url: issue.url,
+                createdAt: issue.createdAt.toISOString(),
+                updatedAt: issue.updatedAt.toISOString(),
+            });
+        }
+        return results;
+    }
+    /**
+     * Fetch a single issue by its identifier (e.g., "ENG-123").
+     */
+    async getIssueByIdentifier(identifier) {
+        // Parse team key from identifier
+        const match = identifier.match(/^([A-Z]+)-(\d+)$/i);
+        if (!match)
+            return null;
+        const [, teamKey, numberStr] = match;
+        const issues = await this.sdk.issues({
+            filter: {
+                team: { key: { eq: teamKey.toUpperCase() } },
+                number: { eq: parseInt(numberStr, 10) },
+            },
+            first: 1,
+        });
+        if (issues.nodes.length === 0)
+            return null;
+        const issue = issues.nodes[0];
+        const state = await issue.state;
+        const team = await issue.team;
+        const assignee = await issue.assignee;
+        const labelsConn = await issue.labels();
+        const cycle = await issue.cycle;
+        const project = await issue.project;
+        return {
+            id: issue.id,
+            identifier: issue.identifier,
+            title: issue.title,
+            description: issue.description ?? undefined,
+            priority: issue.priority,
+            state: state ? {
+                id: state.id,
+                name: state.name,
+                type: state.type,
+            } : { id: '', name: 'Unknown', type: 'backlog' },
+            team: team ? {
+                id: team.id,
+                key: team.key,
+                name: team.name,
+            } : { id: '', key: '', name: 'Unknown' },
+            assignee: assignee ? {
+                id: assignee.id,
+                name: assignee.name,
+                email: assignee.email,
+            } : undefined,
+            labels: labelsConn.nodes.map((l) => ({
+                id: l.id,
+                name: l.name,
+                color: l.color,
+            })),
+            cycle: cycle ? {
+                id: cycle.id,
+                name: cycle.name ?? `Cycle ${cycle.number}`,
+                number: cycle.number,
+            } : undefined,
+            project: project ? {
+                id: project.id,
+                name: project.name,
+            } : undefined,
+            estimate: issue.estimate ?? undefined,
+            url: issue.url,
+            createdAt: issue.createdAt.toISOString(),
+            updatedAt: issue.updatedAt.toISOString(),
+        };
+    }
+    /**
+     * Update the state of an issue.
+     */
+    async updateIssueState(issueId, stateId) {
+        await this.sdk.updateIssue(issueId, { stateId });
+    }
+    /**
+     * Add a comment to an issue.
+     */
+    async addComment(issueId, body) {
+        await this.sdk.createComment({ issueId, body });
+    }
+    /**
+     * Attach a URL to an issue (e.g., a PR link).
+     */
+    async attachUrl(issueId, url, title) {
+        await this.sdk.createAttachment({
+            issueId,
+            url,
+            title,
+        });
+    }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Linear Configuration Storage
+ *
+ * Stores Linear credentials and preferences in the workspace_settings table.
+ */
+import Database from 'better-sqlite3';
+import type { LinearConfig } from './types.js';
+/**
+ * Check if Linear is configured (API key is stored).
+ */
+export declare function isLinearConfigured(db: Database.Database): boolean;
+/**
+ * Load Linear configuration from the database.
+ * Returns null if not configured.
+ */
+export declare function loadLinearConfig(db: Database.Database): LinearConfig | null;
+/**
+ * Save Linear API key to the database.
+ */
+export declare function saveLinearApiKey(db: Database.Database, apiKey: string): void;
+/**
+ * Save the default team for Linear operations.
+ */
+export declare function saveLinearDefaultTeam(db: Database.Database, teamId: string, teamKey: string): void;
+/**
+ * Save the organization name.
+ */
+export declare function saveLinearOrganization(db: Database.Database, name: string): void;
+/**
+ * Clear all Linear configuration from the database.
+ */
+export declare function clearLinearConfig(db: Database.Database): void;
+/**
+ * Get the stored Linear API key.
+ * Also checks PRLT_LINEAR_API_KEY and LINEAR_API_KEY environment variables.
+ */
+export declare function getLinearApiKey(db: Database.Database): string | null;