@proletariat/cli 0.3.44 → 0.3.46

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

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ */
+/**
+ * Supported external issue sources.
+ *
+ */
+export type IssueSource = 'linear' | 'jira';
+/**
+ * All valid issue sources as a const array.
+ */
+export declare const ISSUE_SOURCES: readonly ["linear", "jira"];
+/**
+ * Canonical envelope for external issues/work items.
+ *
+ * Normalizes issues from different sources into a shared structure that can be
+ * deterministically mapped to spawn context.
+ *
+ * Source-specific fields are preserved in the `raw` payload.
+ */
+export interface IssueEnvelope {
+    /** Which external system this issue came from */
+    source: IssueSource;
+    /** Unique identifier in the external system (e.g., Linear UUID, Jira issue ID) */
+    external_id: string;
+    /** Human-readable key in the external system (e.g., "ENG-123", "PROJ-456") */
+    external_key: string;
+    /** Issue title / summary */
+    title: string;
+    /** Issue description (markdown or plain text) */
+    description: string;
+    /** Labels / tags applied to the issue */
+    labels: string[];
+    /** Priority level (normalized to P0-P3 scale) */
+    priority: string | null;
+    /** Current status name in the external system */
+    status: string;
+    /** URL to view the issue in the external system */
+    url: string;
+    /** Project key or identifier in the external system */
+    project_key: string;
+    /** Assignee display name or identifier */
+    assignee: string | null;
+    /**
+     * Source-native work item kind when available (e.g., issue, ticket, task).
+     * Optional to preserve compatibility with adapters that do not expose a
+     * stable item kind.
+     */
+    item_type?: string | null;
+    /** Original source-specific payload (preserved for source-specific logic) */
+    raw: Record<string, unknown>;
+}
+/**
+ * Metadata derived from an IssueEnvelope for spawn context.
+ * Used to populate ExecutionContext fields when spawning agent work
+ * from an external issue.
+ */
+export interface IssueSpawnContext {
+    /** Prompt text generated from the issue for the agent */
+    prompt: string;
+    /** Metadata key-value pairs to attach to the ticket */
+    metadata: Record<string, string>;
+}
+/**
+ * Error codes for issue envelope validation failures.
+ */
+export type IssueValidationErrorCode = 'MISSING_FIELD' | 'INVALID_SOURCE' | 'INVALID_FIELD_TYPE' | 'EMPTY_FIELD';
+/**
+ * Structured validation error for issue envelope fields.
+ */
+export interface IssueValidationError {
+    /** Machine-readable error code */
+    code: IssueValidationErrorCode;
+    /** The field that failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Result of validating an issue envelope.
+ */
+export type IssueValidationResult = {
+    valid: true;
+    envelope: IssueEnvelope;
+} | {
+    valid: false;
+    errors: IssueValidationError[];
+};
+/**
+ * Contract for external issue source adapters.
+ *
+ * Both Linear and Jira adapters must implement this interface to normalize
+ * their issues into the shared IssueEnvelope format.
+ *
+ * Adapters are responsible for:
+ * 1. Fetching issues from their source API
+ * 2. Normalizing source-specific data into IssueEnvelope format
+ * 3. Preserving source-specific fields in the `raw` payload
+ */
+export interface ExternalIssueAdapter {
+    /** Which source this adapter handles */
+    readonly source: IssueSource;
+    /**
+     * Normalize a raw API response into an IssueEnvelope.
+     *
+     * @param raw - Raw issue data from the source API
+     * @returns Validated IssueEnvelope
+     * @throws ExternalIssueError if the raw data cannot be normalized
+     */
+    normalize(raw: unknown): IssueEnvelope;
+    /**
+     * Fetch and normalize a single issue by its external key.
+     *
+     * @param key - External issue key (e.g., "ENG-123" for Linear, "PROJ-456" for Jira)
+     * @returns Normalized IssueEnvelope
+     * @throws ExternalIssueError if the issue cannot be fetched or normalized
+     */
+    fetchByKey(key: string): Promise<IssueEnvelope>;
+    /**
+     * Fetch and normalize multiple issues matching a query.
+     *
+     * @param query - Source-specific query parameters
+     * @returns Array of normalized IssueEnvelopes
+     * @throws ExternalIssueError if the query fails
+     */
+    fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+}
+/**
+ * Error codes for external issue operations.
+ */
+export type ExternalIssueErrorCode = 'VALIDATION_FAILED' | 'FETCH_FAILED' | 'NORMALIZE_FAILED' | 'SOURCE_NOT_SUPPORTED';
+/**
+ * Typed error for external issue operations.
+ */
+export declare class ExternalIssueError extends Error {
+    code: ExternalIssueErrorCode;
+    source?: IssueSource | undefined;
+    validationErrors?: IssueValidationError[] | undefined;
+    constructor(code: ExternalIssueErrorCode, message: string, source?: IssueSource | undefined, validationErrors?: IssueValidationError[] | undefined);
+}

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>;
+}