@h-rig/linear-plugin 0.0.6-alpha.78 → 0.0.6-alpha.80

package/dist/src/fixture-transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Fixture-driven fake transport for testing the Linear adapter (and plugins
+ * built on the same pattern) without any live API calls.
+ *
+ * The adapter names every GraphQL operation (`RigListIssues`,
+ * `RigTeamStates`, …), so fixtures route on the operation name instead of
+ * fragile query-string matching. Each route returns either:
+ *   - a plain object        → wrapped as `{ data: <object> }` with HTTP 200
+ *   - `graphqlErrors([...])` → `{ errors: [...] }` with HTTP 200
+ *   - `httpFailure(status, body)` → a raw non-200 HTTP response
+ */
+import type { LinearTransport } from "./linear-issues-source";
+export interface RecordedLinearCall {
+    url: string;
+    /** Raw Authorization header the adapter sent. */
+    authorization: string | undefined;
+    /** GraphQL operation name parsed from the request body. */
+    operation: string;
+    query: string;
+    variables: Record<string, unknown>;
+}
+declare const HTTP_FAILURE: unique symbol;
+declare const GRAPHQL_ERRORS: unique symbol;
+interface HttpFailureFixture {
+    [HTTP_FAILURE]: true;
+    status: number;
+    body: string;
+}
+interface GraphQLErrorsFixture {
+    [GRAPHQL_ERRORS]: true;
+    errors: ReadonlyArray<{
+        message: string;
+        extensions?: {
+            code?: string;
+        };
+    }>;
+}
+/** Make a route fail at the HTTP layer (e.g. `httpFailure(401, "Unauthorized")`). */
+export declare function httpFailure(status: number, body: string): HttpFailureFixture;
+/** Make a route return a GraphQL-level errors payload with HTTP 200. */
+export declare function graphqlErrors(errors: ReadonlyArray<{
+    message: string;
+    extensions?: {
+        code?: string;
+    };
+}>): GraphQLErrorsFixture;
+export type FixtureRoute = (variables: Record<string, unknown>, call: RecordedLinearCall) => unknown;
+export interface FixtureTransport {
+    transport: LinearTransport;
+    /** Every request the adapter made, in order. Assert payloads against this. */
+    calls: RecordedLinearCall[];
+    /** Calls filtered to one operation name. */
+    callsFor(operation: string): RecordedLinearCall[];
+}
+/**
+ * Build a transport whose responses come from fixtures keyed by GraphQL
+ * operation name. Unrouted operations fail loudly so tests never silently
+ * exercise a request they didn't mean to allow.
+ */
+export declare function createFixtureTransport(routes: Record<string, FixtureRoute>): FixtureTransport;
+export {};

package/dist/src/fixtures.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared GraphQL fixtures for the test suite — shaped exactly like real
+ * Linear API responses (the `data` payload of each operation). No live API
+ * calls happen anywhere in this package's tests.
+ */
+export declare const TEAM_KEY = "ENG";
+export declare const STATE_IDS: {
+    readonly triage: "11111111-1111-4111-8111-111111111101";
+    readonly backlog: "11111111-1111-4111-8111-111111111102";
+    readonly todo: "11111111-1111-4111-8111-111111111103";
+    readonly inProgress: "11111111-1111-4111-8111-111111111104";
+    readonly inReview: "11111111-1111-4111-8111-111111111105";
+    readonly done: "11111111-1111-4111-8111-111111111106";
+    readonly canceled: "11111111-1111-4111-8111-111111111107";
+};
+/** Response payload for the RigTeamStates operation. */
+export declare const teamStatesFixture: {
+    teams: {
+        nodes: {
+            id: string;
+            key: string;
+            states: {
+                nodes: ({
+                    id: "11111111-1111-4111-8111-111111111101";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111102";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111103";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111105";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111104";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111106";
+                    name: string;
+                    type: string;
+                    position: number;
+                } | {
+                    id: "11111111-1111-4111-8111-111111111107";
+                    name: string;
+                    type: string;
+                    position: number;
+                })[];
+            };
+        }[];
+    };
+};
+export declare const ISSUE_UUIDS: {
+    readonly eng1: "33333333-3333-4333-8333-333333333301";
+    readonly eng2: "33333333-3333-4333-8333-333333333302";
+    readonly eng3: "33333333-3333-4333-8333-333333333303";
+    readonly eng4: "33333333-3333-4333-8333-333333333304";
+    readonly eng5: "33333333-3333-4333-8333-333333333305";
+    readonly eng6: "33333333-3333-4333-8333-333333333306";
+    readonly eng7: "33333333-3333-4333-8333-333333333307";
+};
+export interface FixtureIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description: string | null;
+    priority: number | null;
+    priorityLabel: string | null;
+    url: string;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    labels: {
+        nodes: Array<{
+            name: string;
+        }>;
+    };
+    assignee: {
+        name: string;
+        email: string;
+    } | null;
+}
+export declare const issueFixtures: FixtureIssue[];
+/** Single-page RigListIssues payload containing every fixture issue. */
+export declare function listIssuesPage(issues: readonly FixtureIssue[], pageInfo?: {
+    hasNextPage: boolean;
+    endCursor?: string | null;
+}): {
+    issues: {
+        pageInfo: {
+            hasNextPage: boolean;
+            endCursor?: string | null;
+        };
+        nodes: readonly FixtureIssue[];
+    };
+};
+export declare function issueByIdentifier(identifier: string): FixtureIssue;

package/dist/src/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `@rig/linear-plugin` — Linear as a Rig task source.
+ *
+ * This package is the canonical example of a plugin that adapts an external
+ * HTTP API into Rig's task-source contract. The README walks through the
+ * anatomy; `linear-issues-source.ts` holds the adapter, this file holds the
+ * `definePlugin` wiring (metadata channel + executable runtime channel).
+ *
+ * Usage in rig.config.ts:
+ *
+ *   import { defineConfig } from "@rig/core";
+ *   import linear from "@rig/linear-plugin";
+ *
+ *   export default defineConfig({
+ *     plugins: [linear()],
+ *     taskSource: {
+ *       kind: "linear",
+ *       options: { teamKey: "ENG", states: ["Todo"], labels: ["rig"] },
+ *     },
+ *     // ...
+ *   });
+ *
+ * The API key comes from LINEAR_API_KEY (or `linear({ apiKey })`) — never
+ * from rig.config.ts, which is committed.
+ */
+import { type RigPluginWithRuntime } from "@rig/core";
+import { type LinearIssuesOptions, type LinearTransport } from "./linear-issues-source";
+export { createLinearIssuesTaskSource, linearStateTypeForRigStatus, rigStatusForLinearStateType, updateRigOwnedMetadataBlock, RIG_METADATA_START, RIG_METADATA_END, } from "./linear-issues-source";
+export type { LinearIssuesOptions, LinearIssuesTaskSource, LinearTransport, LinearTransportRequest, LinearTransportResponse, } from "./linear-issues-source";
+export { createFixtureTransport, graphqlErrors, httpFailure, } from "./fixture-transport";
+export type { FixtureTransport, FixtureRoute, RecordedLinearCall } from "./fixture-transport";
+/**
+ * Process-level options passed where the plugin is instantiated (rig.config.ts).
+ * Per-project source configuration (team key, filters) lives in
+ * `taskSource.options` instead — see the factory below.
+ */
+export interface LinearPluginOptions {
+    /** Linear API key. Defaults to process.env.LINEAR_API_KEY at request time. */
+    apiKey?: string;
+    /** GraphQL endpoint override (self-hosted proxies, test servers). */
+    endpoint?: string;
+    /** fetch-shaped transport override — tests inject a fixture transport here. */
+    transport?: LinearTransport;
+    /** Notify the host that issue-backed task state changed. */
+    onTaskChanged?: LinearIssuesOptions["onTaskChanged"];
+}
+export default function linearPlugin(opts?: LinearPluginOptions): RigPluginWithRuntime;

package/dist/src/linear-issues-source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Linear issues task source — the canonical external-HTTP-API adapter.
+ *
+ * Everything goes through one GraphQL endpoint (`https://api.linear.app/graphql`)
+ * via an injectable fetch-shaped transport, so the entire adapter is testable
+ * from fixtures with zero live API calls. See the package README for the
+ * walk-through; this file is deliberately self-contained (no SDK dependency).
+ */
+import type { RegisteredTaskSource, TaskRecord, TaskSourceUpdate } from "@rig/contracts";
+/** The exact request shape the adapter sends. */
+export interface LinearTransportRequest {
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+}
+/** The minimal response surface the adapter reads. `Response` satisfies it. */
+export interface LinearTransportResponse {
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}
+/**
+ * A fetch-shaped function. Global `fetch` is assignable as-is; tests inject a
+ * fixture-driven fake (see `createFixtureTransport` in `fixture-transport.ts`).
+ */
+export type LinearTransport = (url: string, init: LinearTransportRequest) => Promise<LinearTransportResponse>;
+export interface LinearIssuesOptions {
+    /** Linear team key (the "ENG" in ENG-123). Issues are listed for this team. */
+    teamKey: string;
+    /**
+     * Linear API key. Defaults to `process.env.LINEAR_API_KEY`, resolved at
+     * request time. Personal API keys (`lin_api_…`) are sent raw in the
+     * `Authorization` header; OAuth tokens (`lin_oauth_…`) get a `Bearer` prefix.
+     */
+    apiKey?: string;
+    /** Filter: workflow state names (e.g. `["Todo", "In Progress"]`). */
+    states?: readonly string[];
+    /** Filter: assignee email (anything containing "@") or display name. */
+    assignee?: string;
+    /** Filter: label names. An issue must carry every listed label (AND). */
+    labels?: readonly string[];
+    /** GraphQL endpoint override. Defaults to the public Linear API. */
+    endpoint?: string;
+    /** fetch-shaped transport. Defaults to global `fetch`; tests inject a fake. */
+    transport?: LinearTransport;
+    /** Issues per GraphQL page (Linear caps pages at 250). Defaults to 50. */
+    pageSize?: number;
+    /** Maximum issue-list rows before Rig fails loudly instead of silently truncating. Defaults to 1,000. */
+    listLimit?: number;
+    /** Notify the host that issue-backed task state changed and snapshots should refresh. */
+    onTaskChanged?: (event: {
+        teamKey: string;
+        id: string;
+        status?: TaskRecord["status"];
+        reason: "linear-issue-updated";
+    }) => void;
+}
+/**
+ * Linear workflow-state *type* → Rig task status.
+ *   triage / backlog / unstarted → ready
+ *   started                      → in_progress
+ *   completed                    → completed
+ *   canceled                     → cancelled
+ * Unknown types fall back to "open" rather than failing the whole list.
+ */
+export declare function rigStatusForLinearStateType(stateType: string | undefined): TaskRecord["status"];
+/**
+ * Rig task status → Linear workflow-state type for lifecycle writeback.
+ * Returns null when Linear has no workflow equivalent (e.g. "blocked") — the
+ * adapter then leaves the workflow state untouched and relies on comments.
+ */
+export declare function linearStateTypeForRigStatus(status: TaskRecord["status"]): "unstarted" | "started" | "completed" | "canceled" | null;
+export declare const RIG_METADATA_START = "<!-- rig:metadata:start -->";
+export declare const RIG_METADATA_END = "<!-- rig:metadata:end -->";
+/** Insert or replace the Rig-owned metadata block in an issue description. */
+export declare function updateRigOwnedMetadataBlock(body: string, metadata: Record<string, unknown>): string;
+export interface LinearIssuesTaskSource extends RegisteredTaskSource {
+    get(id: string): Promise<TaskRecord | undefined>;
+    updateStatus(id: string, status: TaskRecord["status"]): Promise<void>;
+    updateTask(id: string, update: TaskSourceUpdate): Promise<void>;
+}
+export declare function createLinearIssuesTaskSource(opts: LinearIssuesOptions): LinearIssuesTaskSource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-rig/linear-plugin",
-  "version": "0.0.6-alpha.78",
+  "version": "0.0.6-alpha.80",
   "type": "module",
   "description": "Rig package",
   "license": "UNLICENSED",
@@ -10,6 +10,7 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     }
   },
@@ -18,9 +19,10 @@
   },
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "dependencies": {
-    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.78",
-    "@rig/core": "npm:@h-rig/core@0.0.6-alpha.78",
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.80",
+    "@rig/core": "npm:@h-rig/core@0.0.6-alpha.80",
     "effect": "4.0.0-beta.78"
   }
 }