@dahrk/linear 0.1.0 → 0.2.0

package/src/oauth.ts

@@ -0,0 +1,255 @@
+/**
+ * Linear OAuth 2.0 helpers for the agent install + token rotation (build spec section 14).
+ *
+ * An agent becomes assignable/mentionable in a workspace only while the app is INSTALLED via
+ * the authorization-code flow with `actor=app` and the `app:assignable` / `app:mentionable`
+ * scopes (admin consent). That flow also yields the access + refresh tokens the hub posts with.
+ * Access tokens last ~24h, so the hub refreshes them with the refresh token (see the hub's
+ * `resolveClient`). Token grants use plain `fetch`; post-token reads use the typed LinearClient.
+ */
+import { LinearClient } from "@linear/sdk";
+
+const AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+const TOKEN_URL = "https://api.linear.app/oauth/token";
+const REVOKE_URL = "https://api.linear.app/oauth/revoke";
+
+/** The agent scopes: read/write plus the two that make the app assignable + mentionable. */
+export const DEFAULT_AGENT_SCOPES = ["read", "write", "app:assignable", "app:mentionable"] as const;
+
+export interface LinearTokens {
+  accessToken: string;
+  /** Present on every authorization-code and refresh response, absent on a client-credentials mint
+   *  (which issues no refresh token at all). It is NOT optional on a refresh: Linear rotates refresh
+   *  tokens single-use and always returns the replacement, so a refresh response without one is a
+   *  protocol violation rather than "keep the one you have" - see {@link refreshTokens}. */
+  refreshToken?: string;
+  /** When the access token expires (computed from `expires_in`). */
+  expiresAt: Date;
+  scope?: string;
+}
+
+/**
+ * Build the Linear consent URL. The admin opens this; approving installs the agent (with
+ * `actor=app`) and redirects to `redirectUri?code=...&state=...`. `state` is opaque here - the
+ * caller signs it (CSRF) and recovers the connection from it in the callback.
+ */
+export function authorizeUrl(params: {
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  scopes?: readonly string[];
+  actor?: "app" | "user";
+  /** `"consent"` (default) forces Linear's consent screen every time - right for the `actor=app`
+   *  install (re-grants and re-issues a refresh token, and lets an admin connect another workspace).
+   *  `"auto"` omits the `prompt` param so Linear only prompts when scopes are not already granted -
+   *  right for the `actor=user` sign-in, so a returning user is not made to re-authorise on every login. */
+  prompt?: "consent" | "auto";
+}): string {
+  const u = new URL(AUTHORIZE_URL);
+  u.searchParams.set("client_id", params.clientId);
+  u.searchParams.set("redirect_uri", params.redirectUri);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("scope", (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","));
+  u.searchParams.set("state", params.state);
+  u.searchParams.set("actor", params.actor ?? "app");
+  if ((params.prompt ?? "consent") === "consent") u.searchParams.set("prompt", "consent");
+  return u.toString();
+}
+
+interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+  error?: string;
+  error_description?: string;
+}
+
+async function postToken(body: Record<string, string>, now: () => Date): Promise<LinearTokens> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+  });
+  const json = (await res.json().catch(() => ({}))) as TokenResponse;
+  if (!res.ok || !json.access_token) {
+    const detail = json.error_description || json.error || `${res.status}`;
+    throw new Error(`linear token endpoint failed: ${detail}`);
+  }
+  const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 86_399;
+  return {
+    accessToken: json.access_token,
+    ...(json.refresh_token ? { refreshToken: json.refresh_token } : {}),
+    expiresAt: new Date(now().getTime() + expiresIn * 1000),
+    ...(json.scope ? { scope: json.scope } : {}),
+  };
+}
+
+/** Exchange the callback `code` for access + refresh tokens (one-time, at install). */
+export function exchangeCode(
+  params: { clientId: string; clientSecret: string; code: string; redirectUri: string },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "authorization_code",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      code: params.code,
+      redirect_uri: params.redirectUri,
+    },
+    now,
+  );
+}
+
+/**
+ * Personal API keys start with `lin_api_` and must be sent as `apiKey` (not Bearer accessToken).
+ * OAuth access tokens use `accessToken` so LinearClient adds the Bearer prefix automatically.
+ */
+function makeLinearClient(token: string): LinearClient {
+  return token.startsWith("lin_api_")
+    ? new LinearClient({ apiKey: token })
+    : new LinearClient({ accessToken: token });
+}
+
+/**
+ * Resolve the workspace (organization) id the access token belongs to. Used at install to backfill
+ * a connection's `workspaceIds` from the token, so an operator need not paste the org id by hand and
+ * intake can match the workspace on the very first webhook.
+ */
+export async function fetchOrganizationId(accessToken: string): Promise<string> {
+  const client = makeLinearClient(accessToken);
+  const org = await client.organization;
+  return org.id;
+}
+
+/** The agent identity + bound workspace a token resolves to, for the connection Probe. */
+export interface LinearProbe {
+  /** `email` (verified, owned by Linear) is the cross-provider account join key; `admin` is captured
+   *  now for later permission gating (unused at launch). Both are non-null on Linear's `User` type but
+   *  optional here so a partial/legacy probe response never throws. */
+  viewer?: { id: string; name?: string; email?: string; admin?: boolean };
+  organization?: { id: string; name?: string; urlKey?: string };
+}
+
+/**
+ * Probe a stored access token: query `viewer` (the app/agent user) and `organization` (the bound
+ * workspace) so the portal can confirm a connection's token is valid and show which workspace it
+ * binds to. Throws on an auth failure / GraphQL error, which the caller renders as "token invalid".
+ */
+export async function probeToken(accessToken: string): Promise<LinearProbe> {
+  const client = makeLinearClient(accessToken);
+  const [viewer, org] = await Promise.all([client.viewer, client.organization]);
+  const probe: LinearProbe = {};
+  if (viewer?.id) {
+    probe.viewer = {
+      id: viewer.id,
+      ...(viewer.name ? { name: viewer.name } : {}),
+      ...(viewer.email ? { email: viewer.email } : {}),
+      ...(typeof viewer.admin === "boolean" ? { admin: viewer.admin } : {}),
+    };
+  }
+  if (org?.id) {
+    probe.organization = {
+      id: org.id,
+      ...(org.name ? { name: org.name } : {}),
+      ...(org.urlKey ? { urlKey: org.urlKey } : {}),
+    };
+  }
+  return probe;
+}
+
+/**
+ * Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401).
+ *
+ * Linear rotates refresh tokens **single-use**: the request consumes the one presented and the response
+ * carries "a new valid access token and a new refresh token" (oauth-2-0-authentication.md, "Refresh an
+ * access token"). So the replacement is mandatory, and a response without one means the old token has
+ * been consumed while we learned nothing - the caller MUST NOT carry on with the previous value, which
+ * is now dead. Throwing here is what makes that loud instead of silently arming a connection to fail
+ * on its next refresh, forever (DHK-1306).
+ *
+ * Linear gives a 30-minute grace period for exactly this case: the original request can be replayed to
+ * retrieve the new refresh token. Recovery is the caller's to attempt; this function's job is to refuse
+ * to report success when the rotation is unaccounted for.
+ */
+export function refreshTokens(
+  params: { clientId: string; clientSecret: string; refreshToken: string },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "refresh_token",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      refresh_token: params.refreshToken,
+    },
+    now,
+  ).then((t) => {
+    if (!t.refreshToken) {
+      throw new Error(
+        "linear refresh returned no replacement refresh token: the presented token is now consumed. " +
+          "Replay the same request within 30 minutes to recover it.",
+      );
+    }
+    return t;
+  });
+}
+
+/**
+ * Revoke an access token at Linear, de-authorising the app for the workspace that token belongs to.
+ *
+ * This is the ONLY app-callable lever Linear gives us over an install: there is no uninstall mutation
+ * and nothing in the GraphQL schema that names or targets an install (`revokeOauthToken`,
+ * `userAuthorizedApplications`, `applicationWithAuthorization` are all absent). De-authorisation is
+ * per organisation - Linear signals it with an `OAuthApp revoked` webhook carrying `organizationId`.
+ *
+ * Why it matters beyond hygiene: while an install exists, Linear's authorize hop resolves against it
+ * and shows "Dahrk already installed - Continue" rather than a consent screen for the workspace the
+ * user is actually in. So a user who wanted to move the connection to another workspace got the old
+ * one back, every time, with no way out from inside the product. Forgetting a token locally is not
+ * enough; Linear has to be told.
+ *
+ * A `400` counts as revoked. The endpoint returns it for an already-revoked token, and the caller's
+ * question is "is this token dead", to which "Linear dropped it earlier" is a yes. A `401` does not:
+ * it means we could not authenticate the revocation at all, so the install may well still be live and
+ * the caller must say so rather than report a clean disconnect.
+ */
+export async function revokeToken(params: {
+  token: string;
+  tokenTypeHint?: "access_token" | "refresh_token";
+}): Promise<void> {
+  const body: Record<string, string> = { token: params.token };
+  // Documented as optional but helpful; must not be combined with the legacy access_token/refresh_token
+  // form fields, which we never send.
+  if (params.tokenTypeHint) body.token_type_hint = params.tokenTypeHint;
+  const res = await fetch(REVOKE_URL, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+  });
+  if (res.ok || res.status === 400) return;
+  throw new Error(`linear revoke endpoint failed: ${res.status}`);
+}
+
+/**
+ * Mint an `app` actor token via the `client_credentials` grant: headless (no user, no redirect, no
+ * callback, no refresh token), scoped to the app's workspace, valid ~30 days. Linear's documented
+ * renewal is simply to mint a fresh one on a 401/expiry. Requires the app's "Client credentials"
+ * toggle to be enabled. This is the durable token path for a headless agent, vs the interactive
+ * authorization-code flow (24h token + fragile refresh + "already installed" install UX).
+ */
+export function mintAppToken(
+  params: { clientId: string; clientSecret: string; scopes?: readonly string[] },
+  now: () => Date = () => new Date(),
+): Promise<LinearTokens> {
+  return postToken(
+    {
+      grant_type: "client_credentials",
+      client_id: params.clientId,
+      client_secret: params.clientSecret,
+      scope: (params.scopes ?? DEFAULT_AGENT_SCOPES).join(","),
+    },
+    now,
+  );
+}

package/src/recording-client.ts

@@ -0,0 +1,141 @@
+/**
+ * A credential-free AgentSessionClient that records every call instead of touching
+ * Linear. It is the offline-acceptance counterpart to the mock Runner: the hub harness
+ * and unit tests inject it and assert on the ordered call log, so the whole control
+ * surface (plan, activities, elicitation, auth, issue-start, PR attach, state,
+ * externalUrls) is verified with no Linear credentials. The real `@linear/sdk` client is
+ * the live path (./linear-client.ts).
+ */
+import type {
+  Activity,
+  AgentSessionClient,
+  AuthRequest,
+  DocumentInput,
+  ElicitOption,
+  ExternalUrl,
+  IssueEngagement,
+  PlanItem,
+  PrAttachment,
+  RepoCandidate,
+  SessionState,
+} from "./index.js";
+
+export type RecordedCall =
+  | { call: "postActivity"; sessionId: string; activity: Activity }
+  | { call: "setPlan"; sessionId: string; items: PlanItem[] }
+  | { call: "raiseElicitation"; sessionId: string; prompt: string; options?: ElicitOption[] }
+  | { call: "suggestRepositories"; issueId: string; candidates: RepoCandidate[] }
+  | { call: "addIssueLabel"; issueId: string; name: string }
+  | { call: "requestAuth"; sessionId: string; prompt: string; auth: AuthRequest }
+  | { call: "startIssue"; sessionId: string }
+  | { call: "moveIssueToReview"; sessionId: string }
+  | { call: "commentOnIssue"; sessionId: string; body: string }
+  | { call: "attachPr"; sessionId: string; pr: PrAttachment }
+  | { call: "createDocument"; sessionId: string; doc: DocumentInput }
+  | { call: "setExternalUrls"; sessionId: string; urls: ExternalUrl[] }
+  | { call: "setState"; sessionId: string; state: SessionState }
+  | { call: "readIssueEngagement"; issueIds: string[] }
+  | { call: "createSessionOnIssue"; issueId: string }
+  | { call: "createSessionOnComment"; commentId: string };
+
+export interface RecordingClient extends AgentSessionClient {
+  /** Every call made, in order. */
+  readonly calls: RecordedCall[];
+}
+
+/** Drive the read-only ground-truth methods so a test can simulate a disengaged issue. */
+export interface RecordingClientOptions {
+  /** The app user id `appUserId()` returns (default "app-user"). */
+  appUserId?: string;
+  /** Per-issue engagement `readIssueEngagement` returns. Any requested id NOT present here defaults
+   *  to a fully-engaged issue delegated + assigned to `appUserId` (so an unconfigured sweep never
+   *  false-cancels). Set an id to `null` to simulate a hard-deleted issue (omitted from the result). */
+  engagement?: Record<string, IssueEngagement | null>;
+}
+
+export function createRecordingClient(opts: RecordingClientOptions = {}): RecordingClient {
+  const calls: RecordedCall[] = [];
+  const appUserId = opts.appUserId ?? "app-user";
+  const engagement = opts.engagement ?? {};
+  return {
+    calls,
+    async postActivity(sessionId, activity) {
+      calls.push({ call: "postActivity", sessionId, activity });
+    },
+    async setPlan(sessionId, items) {
+      calls.push({ call: "setPlan", sessionId, items });
+    },
+    async raiseElicitation(sessionId, prompt, options) {
+      calls.push({ call: "raiseElicitation", sessionId, prompt, ...(options ? { options } : {}) });
+    },
+    async suggestRepositories(issueId, candidates) {
+      calls.push({ call: "suggestRepositories", issueId, candidates });
+      // No opinion offline: the caller then falls back to registry order (exercised by the unit tests
+      // of the pure ordering function, which take real suggestions).
+      return [];
+    },
+    async addIssueLabel(issueId, name) {
+      calls.push({ call: "addIssueLabel", issueId, name });
+    },
+    async requestAuth(sessionId, prompt, auth) {
+      calls.push({ call: "requestAuth", sessionId, prompt, auth });
+    },
+    async startIssue(sessionId) {
+      calls.push({ call: "startIssue", sessionId });
+      // Offline stub: report a successful move so the reporter's no-op surfacing stays quiet.
+      return { moved: true, stateName: "In Progress" };
+    },
+    async moveIssueToReview(sessionId) {
+      calls.push({ call: "moveIssueToReview", sessionId });
+      // Offline stub: report a successful move so the reporter's no-op surfacing stays quiet.
+      return { moved: true, stateName: "In Review" };
+    },
+    async commentOnIssue(sessionId, body) {
+      calls.push({ call: "commentOnIssue", sessionId, body });
+    },
+    async attachPr(sessionId, pr) {
+      calls.push({ call: "attachPr", sessionId, pr });
+    },
+    async createDocument(sessionId, doc) {
+      calls.push({ call: "createDocument", sessionId, doc });
+      // Deterministic fake id/url so offline runs and tests have a stable document reference.
+      const slug = doc.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+      return { id: `doc-${slug}`, url: `https://linear.app/doc/${slug}` };
+    },
+    async setExternalUrls(sessionId, urls) {
+      calls.push({ call: "setExternalUrls", sessionId, urls });
+    },
+    async setState(sessionId, state) {
+      calls.push({ call: "setState", sessionId, state });
+    },
+    async readIssueEngagement(issueIds) {
+      calls.push({ call: "readIssueEngagement", issueIds });
+      const out = new Map<string, IssueEngagement>();
+      for (const id of issueIds) {
+        if (!id) continue;
+        if (Object.prototype.hasOwnProperty.call(engagement, id)) {
+          const e = engagement[id];
+          // null => hard-deleted: leave it out of the result entirely.
+          if (e) out.set(id, e);
+        } else {
+          // Default: fully engaged (delegated + assigned to the app user), so a sweep against an
+          // unconfigured recording client reads every issue as still-engaged.
+          out.set(id, { present: true, archived: false, stateType: "started", delegateId: appUserId, assigneeId: appUserId });
+        }
+      }
+      return out;
+    },
+    async appUserId() {
+      return appUserId;
+    },
+    async createSessionOnIssue(issueId) {
+      calls.push({ call: "createSessionOnIssue", issueId });
+      // Deterministic synthetic session id so offline runs and tests have a stable reference.
+      return `sess-${issueId}`;
+    },
+    async createSessionOnComment(commentId) {
+      calls.push({ call: "createSessionOnComment", commentId });
+      return `sess-${commentId}`;
+    },
+  };
+}

package/src/responding-client.ts

@@ -0,0 +1,106 @@
+/**
+ * An actively-responding, credential-free AgentSessionClient for the `pnpm dev` offline
+ * environment. It is a superset of the recording client (./recording-client.ts): it keeps
+ * the ordered `calls` log so it is a drop-in wherever the recording client is injected, but
+ * it additionally
+ *
+ *   1. maintains a small, queryable per-session projection of what the hub last pushed
+ *      (latest state, latest plan, appended activities, set external URLs), so a dev can
+ *      observe a run without touching Linear, and
+ *   2. exposes a pure, pre-declared gate-decision policy (`decide`) a dev CLI reads to know
+ *      which answer to fire for a stage.
+ *
+ * The gate policy is a value the dev supplies up front; it NEVER chooses the next stage
+ * (that would cross the determinism boundary). Gate answers remain human-drive: the CLI
+ * uses `decide` only to pick which `prompted` webhook to send.
+ */
+import type {
+  Activity,
+  ElicitOption,
+  ExternalUrl,
+  PlanItem,
+  SessionState,
+} from "./index.js";
+import {
+  createRecordingClient,
+  type RecordingClient,
+  type RecordingClientOptions,
+} from "./recording-client.js";
+
+/** A pre-declared gate answer for a stage. Never a control-flow decision (see file header). */
+export type GateDecision = "allow" | "deny";
+
+/** What the hub last pushed for one session, observable offline without touching Linear. */
+export interface SessionProjection {
+  /** The latest session state the hub mirrored, or undefined if none was set yet. */
+  state?: SessionState;
+  /** The latest plan (agent-plan checklist); replaced wholesale on each `setPlan`. */
+  plan: PlanItem[];
+  /** Every activity posted to the session, in order. */
+  activities: Activity[];
+  /** The latest external-URL set; replaced wholesale on each `setExternalUrls`. */
+  externalUrls: ExternalUrl[];
+  /** The latest elicitation raised on the session, if any. */
+  elicitation?: { prompt: string; options?: ElicitOption[] };
+}
+
+export interface RespondingClientOptions extends RecordingClientOptions {
+  /** Per-stage gate answers the dev pre-declares. A stage absent here defaults to "allow". */
+  gateDecisions?: Record<string, GateDecision>;
+}
+
+export interface RespondingClient extends RecordingClient {
+  /** The queryable projection of what the hub last pushed for a session, or undefined if the
+   *  hub has not touched that session. */
+  session(sessionId: string): SessionProjection | undefined;
+  /** The dev's pre-declared gate answer for a stage (default "allow"). Pure. */
+  decide(stageId: string): GateDecision;
+}
+
+export function createRespondingLinearClient(opts: RespondingClientOptions = {}): RespondingClient {
+  // Reuse the recording client wholesale for the ordered call log and the seeded read-side
+  // methods (engagement, appUserId, createDocument), then wrap the mutating methods to also
+  // update a per-session projection.
+  const base = createRecordingClient(opts);
+  const gateDecisions = opts.gateDecisions ?? {};
+  const projections = new Map<string, SessionProjection>();
+
+  const projectionFor = (sessionId: string): SessionProjection => {
+    let p = projections.get(sessionId);
+    if (!p) {
+      p = { plan: [], activities: [], externalUrls: [] };
+      projections.set(sessionId, p);
+    }
+    return p;
+  };
+
+  return {
+    ...base,
+    async setPlan(sessionId, items) {
+      await base.setPlan(sessionId, items);
+      projectionFor(sessionId).plan = items;
+    },
+    async postActivity(sessionId, activity) {
+      await base.postActivity(sessionId, activity);
+      projectionFor(sessionId).activities.push(activity);
+    },
+    async raiseElicitation(sessionId, prompt, options) {
+      await base.raiseElicitation(sessionId, prompt, options);
+      projectionFor(sessionId).elicitation = { prompt, ...(options ? { options } : {}) };
+    },
+    async setExternalUrls(sessionId, urls) {
+      await base.setExternalUrls(sessionId, urls);
+      projectionFor(sessionId).externalUrls = urls;
+    },
+    async setState(sessionId, state) {
+      await base.setState(sessionId, state);
+      projectionFor(sessionId).state = state;
+    },
+    session(sessionId) {
+      return projections.get(sessionId);
+    },
+    decide(stageId) {
+      return gateDecisions[stageId] ?? "allow";
+    },
+  };
+}

package/src/teams.ts

@@ -0,0 +1,44 @@
+/**
+ * Workspace-team listing (DHK-777). A repository routes issues to itself partly by team key
+ * (`Repository.routing.teamKeys`); the portal offers the real keys instead of free text by reading
+ * the linked workspace's teams. The `TeamsApi` seam keeps this pure and unit-testable: the live
+ * adapter (`linearTeamsApi`) wraps `@linear/sdk`, while tests inject a fake - mirroring `LabelApi`.
+ */
+import { LinearClient } from "@linear/sdk";
+
+/** A workspace team, reduced to just what the picker needs. */
+export interface Team {
+  id: string;
+  key: string;
+  name: string;
+}
+
+/** The injectable seam: list the workspace's teams. */
+export interface TeamsApi {
+  listTeams(): Promise<Team[]>;
+}
+
+/**
+ * List the workspace's teams via the `TeamsApi` seam, normalised to `{id,key,name}` and sorted by
+ * key so the picker renders in a stable, deterministic order. A thin deterministic transform - no
+ * control flow, no network - so it feeds the portal picker directly.
+ */
+export async function listWorkspaceTeams(api: TeamsApi): Promise<Team[]> {
+  const teams = await api.listTeams();
+  return teams
+    .map((t) => ({ id: t.id, key: t.key, name: t.name }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+}
+
+/** The live `TeamsApi` backed by a Linear bearer token (workspace-scoped teams). Paginates
+ *  `client.teams()` exactly as `linearLabelApi` paginates `issueLabels()`. */
+export function linearTeamsApi(token: string): TeamsApi {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async listTeams() {
+      const conn = await client.teams();
+      while (conn.pageInfo.hasNextPage) await conn.fetchNext();
+      return conn.nodes.map((t) => ({ id: t.id, key: t.key, name: t.name }));
+    },
+  };
+}