@supaku/agentfactory-linear 0.7.9 → 0.7.11

package/dist/src/platform-adapter.d.ts

@@ -0,0 +1,119 @@
+/**
+ * LinearPlatformAdapter
+ *
+ * Extends LinearFrontendAdapter with Governor event integration methods.
+ * Structurally satisfies the PlatformAdapter interface from @supaku/agentfactory
+ * without an explicit `implements` clause, avoiding a circular package dependency
+ * (core depends on linear, so linear cannot import core).
+ *
+ * Responsibilities:
+ * - Normalize Linear webhook payloads into GovernorEvents
+ * - Scan Linear projects for non-terminal issues
+ * - Convert Linear SDK Issue objects to GovernorIssue
+ */
+import { LinearFrontendAdapter } from './frontend-adapter.js';
+import type { LinearAgentClient } from './agent-client.js';
+/**
+ * Minimal issue representation used by the Governor.
+ * Structurally identical to GovernorIssue in @supaku/agentfactory.
+ */
+export interface GovernorIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    status: string;
+    labels: string[];
+    createdAt: number;
+    parentId?: string;
+    project?: string;
+}
+/** Where an event originated. */
+type EventSource = 'webhook' | 'poll' | 'manual';
+/**
+ * Fired when an issue's workflow status changes.
+ * Structurally identical to IssueStatusChangedEvent in @supaku/agentfactory.
+ */
+interface IssueStatusChangedEvent {
+    type: 'issue-status-changed';
+    issueId: string;
+    issue: GovernorIssue;
+    previousStatus?: string;
+    newStatus: string;
+    timestamp: string;
+    source: EventSource;
+}
+/**
+ * Fired when a comment is added to an issue.
+ * Structurally identical to CommentAddedEvent in @supaku/agentfactory.
+ */
+interface CommentAddedEvent {
+    type: 'comment-added';
+    issueId: string;
+    issue: GovernorIssue;
+    commentId: string;
+    commentBody: string;
+    userId?: string;
+    userName?: string;
+    timestamp: string;
+    source: EventSource;
+}
+/** Union of events this adapter can produce. */
+type GovernorEvent = IssueStatusChangedEvent | CommentAddedEvent;
+/**
+ * Linear platform adapter for the EventDrivenGovernor.
+ *
+ * Extends LinearFrontendAdapter to inherit all frontend operations
+ * (status mapping, issue read/write, agent sessions) and adds
+ * Governor-specific methods for webhook normalization, project scanning,
+ * and issue conversion.
+ *
+ * Structurally satisfies PlatformAdapter from @supaku/agentfactory.
+ */
+export declare class LinearPlatformAdapter extends LinearFrontendAdapter {
+    /**
+     * The underlying Linear client, exposed to subclass methods.
+     * Re-declared here because the parent's `client` field is private.
+     */
+    private readonly linearAgentClient;
+    constructor(client: LinearAgentClient);
+    /**
+     * Normalize a raw Linear webhook payload into GovernorEvents.
+     *
+     * Handles two payload types:
+     * - Issue updates with state changes -> IssueStatusChangedEvent
+     * - Comment creations -> CommentAddedEvent
+     *
+     * Returns `null` for unrecognized payloads (e.g., label changes,
+     * AgentSession events, or other resource types).
+     *
+     * @param payload - Raw Linear webhook payload
+     * @returns Array of GovernorEvents, or null if not relevant
+     */
+    normalizeWebhookEvent(payload: unknown): GovernorEvent[] | null;
+    /**
+     * Scan a Linear project for all non-terminal issues.
+     *
+     * Queries the Linear API with a filter that excludes terminal statuses
+     * (Accepted, Canceled, Duplicate). Each issue is converted to a
+     * GovernorIssue for evaluation by the Governor.
+     *
+     * @param project - Linear project name to scan
+     * @returns Array of GovernorIssue for all active issues
+     */
+    scanProjectIssues(project: string): Promise<GovernorIssue[]>;
+    /**
+     * Convert a Linear SDK Issue object to a GovernorIssue.
+     *
+     * The `native` parameter is typed as `unknown` to satisfy the
+     * PlatformAdapter interface. Internally it is cast to the Linear SDK
+     * `Issue` type. Callers must ensure they pass a valid Linear Issue.
+     *
+     * @param native - Linear SDK Issue object
+     * @returns GovernorIssue representation
+     * @throws Error if the native object is not a valid Linear Issue
+     */
+    toGovernorIssue(native: unknown): Promise<GovernorIssue>;
+}
+export {};
+//# sourceMappingURL=platform-adapter.d.ts.map

package/dist/src/platform-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapter.d.ts","sourceRoot":"","sources":["../../src/platform-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAY1D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,iCAAiC;AACjC,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEhD;;;GAGG;AACH,UAAU,uBAAuB;IAC/B,IAAI,EAAE,sBAAsB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED;;;GAGG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,eAAe,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,aAAa,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,WAAW,CAAA;CACpB;AAED,gDAAgD;AAChD,KAAK,aAAa,GAAG,uBAAuB,GAAG,iBAAiB,CAAA;AAmJhE;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,qBAAqB;IAC9D;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;gBAEzC,MAAM,EAAE,iBAAiB;IAOrC;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,GAAG,IAAI;IA0D/D;;;;;;;;;OASG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAkBlE;;;;;;;;;;OAUG;IACG,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;CAS/D"}

package/dist/src/platform-adapter.js

@@ -0,0 +1,229 @@
+/**
+ * LinearPlatformAdapter
+ *
+ * Extends LinearFrontendAdapter with Governor event integration methods.
+ * Structurally satisfies the PlatformAdapter interface from @supaku/agentfactory
+ * without an explicit `implements` clause, avoiding a circular package dependency
+ * (core depends on linear, so linear cannot import core).
+ *
+ * Responsibilities:
+ * - Normalize Linear webhook payloads into GovernorEvents
+ * - Scan Linear projects for non-terminal issues
+ * - Convert Linear SDK Issue objects to GovernorIssue
+ */
+import { LinearFrontendAdapter } from './frontend-adapter.js';
+// ---------------------------------------------------------------------------
+// Terminal statuses
+// ---------------------------------------------------------------------------
+/**
+ * Statuses that represent terminal states in Linear.
+ * Issues in these states are excluded from project scans.
+ */
+const TERMINAL_STATUSES = ['Accepted', 'Canceled', 'Duplicate'];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Generate an ISO-8601 timestamp for the current moment.
+ * Equivalent to `eventTimestamp()` from @supaku/agentfactory.
+ */
+function eventTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Build a GovernorIssue from Linear webhook issue data.
+ * Does not make API calls -- uses only the data present in the webhook payload.
+ */
+function webhookIssueToGovernorIssue(issueData) {
+    return {
+        id: issueData.id,
+        identifier: issueData.identifier,
+        title: issueData.title,
+        description: issueData.description ?? undefined,
+        status: issueData.state?.name ?? 'Backlog',
+        labels: issueData.labels?.map((l) => l.name) ?? [],
+        createdAt: issueData.createdAt
+            ? new Date(issueData.createdAt).getTime()
+            : Date.now(),
+        parentId: issueData.parent?.id,
+        project: issueData.project?.name,
+    };
+}
+/**
+ * Convert a Linear SDK Issue object to a GovernorIssue.
+ * Resolves lazy-loaded relations (state, labels, parent, project).
+ */
+async function sdkIssueToGovernorIssue(issue) {
+    const state = await issue.state;
+    const labels = await issue.labels();
+    const parent = await issue.parent;
+    const project = await issue.project;
+    return {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description ?? undefined,
+        status: state?.name ?? 'Backlog',
+        labels: labels.nodes.map((l) => l.name),
+        createdAt: issue.createdAt.getTime(),
+        parentId: parent?.id,
+        project: project?.name,
+    };
+}
+// ---------------------------------------------------------------------------
+// Type guards for webhook payloads
+// ---------------------------------------------------------------------------
+/**
+ * Check if a payload looks like a Linear issue webhook.
+ */
+function isIssuePayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const p = payload;
+    return (p.type === 'Issue' &&
+        typeof p.action === 'string' &&
+        typeof p.data === 'object' &&
+        p.data !== null);
+}
+/**
+ * Check if a payload looks like a Linear comment webhook.
+ */
+function isCommentPayload(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const p = payload;
+    return (p.type === 'Comment' &&
+        typeof p.action === 'string' &&
+        typeof p.data === 'object' &&
+        p.data !== null);
+}
+// ---------------------------------------------------------------------------
+// LinearPlatformAdapter
+// ---------------------------------------------------------------------------
+/**
+ * Linear platform adapter for the EventDrivenGovernor.
+ *
+ * Extends LinearFrontendAdapter to inherit all frontend operations
+ * (status mapping, issue read/write, agent sessions) and adds
+ * Governor-specific methods for webhook normalization, project scanning,
+ * and issue conversion.
+ *
+ * Structurally satisfies PlatformAdapter from @supaku/agentfactory.
+ */
+export class LinearPlatformAdapter extends LinearFrontendAdapter {
+    /**
+     * The underlying Linear client, exposed to subclass methods.
+     * Re-declared here because the parent's `client` field is private.
+     */
+    linearAgentClient;
+    constructor(client) {
+        super(client);
+        this.linearAgentClient = client;
+    }
+    // ---- PlatformAdapter methods ----
+    /**
+     * Normalize a raw Linear webhook payload into GovernorEvents.
+     *
+     * Handles two payload types:
+     * - Issue updates with state changes -> IssueStatusChangedEvent
+     * - Comment creations -> CommentAddedEvent
+     *
+     * Returns `null` for unrecognized payloads (e.g., label changes,
+     * AgentSession events, or other resource types).
+     *
+     * @param payload - Raw Linear webhook payload
+     * @returns Array of GovernorEvents, or null if not relevant
+     */
+    normalizeWebhookEvent(payload) {
+        // Handle Issue update with state change
+        if (isIssuePayload(payload)) {
+            // Only handle updates (not creates/removes)
+            if (payload.action !== 'update')
+                return null;
+            // Only produce an event if the state actually changed
+            const hasStateChange = payload.updatedFrom?.stateId !== undefined;
+            if (!hasStateChange)
+                return null;
+            const issue = webhookIssueToGovernorIssue(payload.data);
+            const event = {
+                type: 'issue-status-changed',
+                issueId: payload.data.id,
+                issue,
+                newStatus: issue.status,
+                // Previous status name is not directly available from stateId alone;
+                // we only know the stateId changed. The previous status name would
+                // require an API call, so we leave it undefined.
+                previousStatus: undefined,
+                timestamp: eventTimestamp(),
+                source: 'webhook',
+            };
+            return [event];
+        }
+        // Handle Comment creation
+        if (isCommentPayload(payload)) {
+            if (payload.action !== 'create')
+                return null;
+            const commentData = payload.data;
+            const issueData = commentData.issue;
+            if (!issueData)
+                return null;
+            const issue = webhookIssueToGovernorIssue(issueData);
+            const event = {
+                type: 'comment-added',
+                issueId: issueData.id,
+                issue,
+                commentId: commentData.id,
+                commentBody: commentData.body,
+                userId: commentData.user?.id,
+                userName: commentData.user?.name,
+                timestamp: eventTimestamp(),
+                source: 'webhook',
+            };
+            return [event];
+        }
+        // Unrecognized payload type
+        return null;
+    }
+    /**
+     * Scan a Linear project for all non-terminal issues.
+     *
+     * Queries the Linear API with a filter that excludes terminal statuses
+     * (Accepted, Canceled, Duplicate). Each issue is converted to a
+     * GovernorIssue for evaluation by the Governor.
+     *
+     * @param project - Linear project name to scan
+     * @returns Array of GovernorIssue for all active issues
+     */
+    async scanProjectIssues(project) {
+        const linearClient = this.linearAgentClient.linearClient;
+        const issueConnection = await linearClient.issues({
+            filter: {
+                project: { name: { eq: project } },
+                state: { name: { nin: [...TERMINAL_STATUSES] } },
+            },
+        });
+        const results = [];
+        for (const issue of issueConnection.nodes) {
+            results.push(await sdkIssueToGovernorIssue(issue));
+        }
+        return results;
+    }
+    /**
+     * Convert a Linear SDK Issue object to a GovernorIssue.
+     *
+     * The `native` parameter is typed as `unknown` to satisfy the
+     * PlatformAdapter interface. Internally it is cast to the Linear SDK
+     * `Issue` type. Callers must ensure they pass a valid Linear Issue.
+     *
+     * @param native - Linear SDK Issue object
+     * @returns GovernorIssue representation
+     * @throws Error if the native object is not a valid Linear Issue
+     */
+    async toGovernorIssue(native) {
+        const issue = native;
+        if (!issue || typeof issue.id !== 'string') {
+            throw new Error('LinearPlatformAdapter.toGovernorIssue: expected a Linear SDK Issue object');
+        }
+        return sdkIssueToGovernorIssue(issue);
+    }
+}

package/dist/src/platform-adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=platform-adapter.test.d.ts.map

package/dist/src/platform-adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-adapter.test.d.ts","sourceRoot":"","sources":["../../src/platform-adapter.test.ts"],"names":[],"mappings":""}