@valescoagency/runway 0.4.0 → 0.5.0

package/dist/linear.js

@@ -1,29 +1,177 @@
 import { LinearClient } from "@linear/sdk";
+import { Data, Effect, ParseResult, Redacted, Schedule, Schema, } from "effect";
+// VA-360: schemas covering only the fields runway actually reads
+// off the Linear SDK. Validation runs at the gateway boundary so an
+// upstream API drift (renamed field, removed field, type change)
+// surfaces as a typed `LinearSchemaError` rather than a `Cannot read
+// property 'nodes' of undefined` deep in the call stack.
+const IssueNodeSchema = Schema.Struct({
+    id: Schema.String,
+    identifier: Schema.String,
+    title: Schema.String,
+    description: Schema.NullOr(Schema.String),
+});
+const WorkflowStateNodeSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+});
+const TeamNodeSchema = Schema.Struct({
+    id: Schema.String,
+    key: Schema.String,
+});
+const IssueLabelNodeSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+});
+const ProjectNodeSchema = Schema.Struct({
+    id: Schema.String,
+});
+const decodeIssueNode = Schema.decodeUnknownSync(IssueNodeSchema);
+const decodeWorkflowStateNode = Schema.decodeUnknownSync(WorkflowStateNodeSchema);
+const decodeTeamNode = Schema.decodeUnknownSync(TeamNodeSchema);
+const decodeIssueLabelNode = Schema.decodeUnknownSync(IssueLabelNodeSchema);
+const decodeProjectNode = Schema.decodeUnknownSync(ProjectNodeSchema);
+export class LinearNotFound extends Data.TaggedError("LinearNotFound") {
+}
+export class LinearUnauthorized extends Data.TaggedError("LinearUnauthorized") {
+}
+export class LinearRateLimited extends Data.TaggedError("LinearRateLimited") {
+}
+export class LinearNetworkError extends Data.TaggedError("LinearNetworkError") {
+}
+// VA-357: a stalled HTTP request becomes a typed timeout (rather than
+// a stuck process). Retryable just like NetworkError — the next attempt
+// may succeed.
+export class LinearTimeout extends Data.TaggedError("LinearTimeout") {
+}
+// VA-360: SDK response failed schema validation — Linear's GraphQL
+// schema drifted, an expected field went missing, or a type changed.
+// NOT retryable: re-running the same call will produce the same
+// drift. The operator needs to update runway's schemas (or pin the
+// SDK version) before this gets better.
+export class LinearSchemaError extends Data.TaggedError("LinearSchemaError") {
+}
+// VA-357: which typed errors a retry policy will re-attempt. Hard
+// failures (NotFound, Unauthorized) bypass the retry loop and surface
+// immediately — they are operator-fix problems, not transient blips.
+const RETRYABLE_LINEAR_TAGS = new Set([
+    "LinearNetworkError",
+    "LinearRateLimited",
+    "LinearTimeout",
+]);
+const isRetryableLinearError = (err) => RETRYABLE_LINEAR_TAGS.has(err._tag);
+/**
+ * VA-357: timeout + jittered-exponential retry policy for one Linear
+ * call. 5 retries from a 1s base ⇒ delays jittered around 1/2/4/8/16s
+ * ⇒ ~31s worst-case wall time before bubbling out. `while` gates the
+ * retry on the typed error tag so an `Unauthorized` or `NotFound` is
+ * not retried (no point: it's an operator/config problem).
+ *
+ * Exported so unit tests can apply it to a hand-built Effect and
+ * verify retry behavior under `TestClock`.
+ */
+export const linearRetrySchedule = Schedule.exponential("1 second").pipe(Schedule.compose(Schedule.recurs(5)), Schedule.jittered);
+export const applyLinearPolicy = (effect, opts) => {
+    const timeoutMs = opts.timeoutMs ?? 30_000;
+    return effect.pipe(Effect.timeoutFail({
+        duration: `${timeoutMs} millis`,
+        onTimeout: () => new LinearTimeout({
+            call: opts.call,
+            afterMs: timeoutMs,
+            message: `Linear ${opts.call} timed out after ${timeoutMs}ms`,
+        }),
+    }), Effect.retry({
+        schedule: linearRetrySchedule,
+        while: isRetryableLinearError,
+    }));
+};
+/**
+ * Best-effort classification of an unknown thrown value into the
+ * gateway's typed error ADT. `LinearNotFound`s we threw ourselves
+ * (from the find* helpers) pass through unchanged; SDK / network
+ * exceptions are bucketed by message-shape. Step 2 (VA-357) is where
+ * the retry policy actually leans on these tags — for now, the value
+ * is mostly that the orchestrator's `catch (err: unknown)` becomes
+ * `catch (err: LinearError)`.
+ */
+function classifyLinearError(err, context) {
+    if (err instanceof LinearNotFound ||
+        err instanceof LinearUnauthorized ||
+        err instanceof LinearRateLimited ||
+        err instanceof LinearNetworkError ||
+        err instanceof LinearTimeout ||
+        err instanceof LinearSchemaError) {
+        return err;
+    }
+    // VA-360: a schema validation throw (Linear API drift) should
+    // surface as `LinearSchemaError`, not get bucketed as a transient
+    // NetworkError — retrying won't fix a drifted field.
+    if (ParseResult.isParseError(err)) {
+        return new LinearSchemaError({
+            call: context,
+            message: `${context}: SDK response failed schema validation — ${err.message}`,
+        });
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/\b(401|403)\b|unauthorized|invalid api key|forbidden/i.test(msg)) {
+        return new LinearUnauthorized({ message: msg });
+    }
+    if (/\b429\b|rate.?limit/i.test(msg)) {
+        return new LinearRateLimited({ message: msg });
+    }
+    return new LinearNetworkError({
+        cause: err,
+        message: `${context}: ${msg}`,
+    });
+}
 /**
  * Concrete @linear/sdk-backed implementation. Tests inject their own
  * gateway; never reach for the SDK directly outside this file.
+ *
+ * The internal `find*` helpers stay plain `async` and throw typed
+ * `LinearNotFound` directly. Only the public `LinearGateway` methods
+ * wrap into `Effect.tryPromise` — that's the boundary the orchestrator
+ * sees.
+ *
+ * VA-358: optional `limiter` wraps every method's Effect so the queue
+ * drain respects Linear's API rate limit (~1500 req/hr). When `null`
+ * (the default — tests don't need it), calls go through unrestricted.
+ * Production: `commands/run.ts` builds a limiter inside `Effect.scoped`
+ * and passes it here.
  */
-export function createLinearGateway(config) {
-    const client = new LinearClient({ apiKey: config.linearApiKey });
+export function createLinearGateway(config, limiter = null) {
+    const client = new LinearClient({ apiKey: Redacted.value(config.linearApiKey) });
+    const gate = (eff) => (limiter ? limiter(eff) : eff);
     async function findStateId(teamId, name) {
         const states = await client.workflowStates({
             filter: { team: { id: { eq: teamId } }, name: { eq: name } },
         });
-        const state = states.nodes[0];
-        if (!state) {
-            throw new Error(`Linear workflow state "${name}" not found on team ${teamId}`);
+        const rawState = states.nodes[0];
+        if (!rawState) {
+            throw new LinearNotFound({
+                resource: "state",
+                identifier: name,
+                message: `Linear workflow state "${name}" not found on team ${teamId}`,
+            });
         }
-        return state.id;
+        // VA-360: validate the SDK shape. `decodeWorkflowStateNode` throws
+        // `ParseError` on drift, which `classifyLinearError` maps to
+        // `LinearSchemaError` (non-retryable).
+        return decodeWorkflowStateNode(rawState).id;
     }
     async function findTeamId() {
         const teams = await client.teams({
             filter: { key: { eq: config.linearTeam } },
         });
-        const team = teams.nodes[0];
-        if (!team) {
-            throw new Error(`Linear team "${config.linearTeam}" not found`);
+        const rawTeam = teams.nodes[0];
+        if (!rawTeam) {
+            throw new LinearNotFound({
+                resource: "team",
+                identifier: config.linearTeam,
+                message: `Linear team "${config.linearTeam}" not found`,
+            });
         }
-        return team.id;
+        return decodeTeamNode(rawTeam).id;
     }
     /**
      * Resolve a project identifier (UUID, slug, or name) to its Linear
@@ -40,72 +188,115 @@ export function createLinearGateway(config) {
                 ],
             },
         });
-        const project = projects.nodes[0];
-        if (!project) {
-            throw new Error(`Linear project "${identifier}" not found`);
+        const rawProject = projects.nodes[0];
+        if (!rawProject) {
+            throw new LinearNotFound({
+                resource: "project",
+                identifier,
+                message: `Linear project "${identifier}" not found`,
+            });
         }
-        return project.id;
+        return decodeProjectNode(rawProject).id;
     }
     return {
-        async fetchReady() {
-            const teamId = await findTeamId();
-            const readyStateId = await findStateId(teamId, config.readyStatus);
-            const projectId = config.linearProject
-                ? await findProjectId(config.linearProject)
-                : null;
-            const issues = await client.issues({
-                filter: {
-                    team: { id: { eq: teamId } },
-                    state: { id: { eq: readyStateId } },
-                    ...(projectId ? { project: { id: { eq: projectId } } } : {}),
+        fetchReady() {
+            return gate(applyLinearPolicy(Effect.tryPromise({
+                try: async () => {
+                    const teamId = await findTeamId();
+                    const readyStateId = await findStateId(teamId, config.readyStatus);
+                    const projectId = config.linearProject
+                        ? await findProjectId(config.linearProject)
+                        : null;
+                    const issues = await client.issues({
+                        filter: {
+                            team: { id: { eq: teamId } },
+                            state: { id: { eq: readyStateId } },
+                            ...(projectId ? { project: { id: { eq: projectId } } } : {}),
+                        },
+                        // Stable order: oldest first so the queue drains FIFO.
+                        orderBy: "createdAt",
+                    });
+                    // VA-360: validate every issue node through the schema —
+                    // a single drifted issue surfaces as `LinearSchemaError`
+                    // instead of a downstream `cannot read property X`.
+                    return issues.nodes.map((raw) => {
+                        const i = decodeIssueNode(raw);
+                        return {
+                            id: i.id,
+                            identifier: i.identifier,
+                            title: i.title,
+                            description: i.description ?? "",
+                        };
+                    });
                 },
-                // Stable order: oldest first so the queue drains FIFO.
-                orderBy: "createdAt",
-            });
-            return issues.nodes.map((i) => ({
-                id: i.id,
-                identifier: i.identifier,
-                title: i.title,
-                description: i.description ?? "",
-            }));
+                catch: (err) => classifyLinearError(err, "fetchReady"),
+            }), { call: "fetchReady" }));
         },
-        async transition(issueId, statusName) {
-            const issue = await client.issue(issueId);
-            const team = await issue.team;
-            if (!team)
-                throw new Error(`Issue ${issueId} has no team`);
-            const stateId = await findStateId(team.id, statusName);
-            await client.updateIssue(issueId, { stateId });
+        transition(issueId, statusName) {
+            return gate(applyLinearPolicy(Effect.tryPromise({
+                try: async () => {
+                    const issue = await client.issue(issueId);
+                    const team = await issue.team;
+                    if (!team) {
+                        throw new LinearNotFound({
+                            resource: "issue",
+                            identifier: issueId,
+                            message: `Issue ${issueId} has no team`,
+                        });
+                    }
+                    const stateId = await findStateId(team.id, statusName);
+                    await client.updateIssue(issueId, { stateId });
+                },
+                catch: (err) => classifyLinearError(err, `transition(${statusName})`),
+            }), { call: `transition(${statusName})` }));
         },
-        async applyLabel(issueId, labelName) {
-            const issue = await client.issue(issueId);
-            const team = await issue.team;
-            if (!team)
-                throw new Error(`Issue ${issueId} has no team`);
-            const labels = await client.issueLabels({
-                filter: {
-                    team: { id: { eq: team.id } },
-                    name: { eq: labelName },
+        applyLabel(issueId, labelName) {
+            return gate(applyLinearPolicy(Effect.tryPromise({
+                try: async () => {
+                    const issue = await client.issue(issueId);
+                    const team = await issue.team;
+                    if (!team) {
+                        throw new LinearNotFound({
+                            resource: "issue",
+                            identifier: issueId,
+                            message: `Issue ${issueId} has no team`,
+                        });
+                    }
+                    const labels = await client.issueLabels({
+                        filter: {
+                            team: { id: { eq: team.id } },
+                            name: { eq: labelName },
+                        },
+                    });
+                    const rawLabel = labels.nodes[0];
+                    if (!rawLabel) {
+                        throw new LinearNotFound({
+                            resource: "label",
+                            identifier: labelName,
+                            message: `Linear label "${labelName}" not found on team ${team.id}`,
+                        });
+                    }
+                    const label = decodeIssueLabelNode(rawLabel);
+                    const existing = await issue.labels();
+                    const existingIds = existing.nodes.map((l) => decodeIssueLabelNode(l).id);
+                    const labelIds = [...existingIds, label.id];
+                    await client.updateIssue(issueId, { labelIds });
                 },
-            });
-            const label = labels.nodes[0];
-            if (!label) {
-                throw new Error(`Linear label "${labelName}" not found on team ${team.id}`);
-            }
-            const existing = await issue.labels();
-            const labelIds = [
-                ...existing.nodes.map((l) => l.id),
-                label.id,
-            ];
-            await client.updateIssue(issueId, { labelIds });
+                catch: (err) => classifyLinearError(err, `applyLabel(${labelName})`),
+            }), { call: `applyLabel(${labelName})` }));
         },
-        async comment(issueId, body) {
-            await client.createComment({ issueId, body });
+        comment(issueId, body) {
+            return gate(applyLinearPolicy(Effect.tryPromise({
+                try: async () => {
+                    await client.createComment({ issueId, body });
+                },
+                catch: (err) => classifyLinearError(err, "comment"),
+            }), { call: "comment" }));
         },
     };
 }
 export async function validateLinearConfig(config) {
-    const client = new LinearClient({ apiKey: config.linearApiKey });
+    const client = new LinearClient({ apiKey: Redacted.value(config.linearApiKey) });
     const teams = await client.teams({
         filter: { key: { eq: config.linearTeam } },
     });