@dahrk/linear 0.1.0 → 0.1.1

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