@dahrk/linear 0.1.0 → 0.2.0

package/src/issue-graph.ts

@@ -0,0 +1,169 @@
+/**
+ * Fetch the metadata of the issues one hop from a run's issue - parent, children, blockers, blocked,
+ * related - so the hub can snapshot a manifest into the run and tell the agent WHAT EXISTS around the
+ * ticket it is working.
+ *
+ * This is deliberately metadata only: identifier, title, relation, state. No descriptions, no comments,
+ * no documents. That keeps the manifest cheap enough to send on every run, and it is the piece that
+ * makes on-demand context work at all - an agent that cannot see there is a spike or an epic attached
+ * will never think to open one.
+ *
+ * Distinct from `fetchOpenBlockers` in `labels.ts`, which reads the same edges for the deterministic
+ * blocked guard: that one answers "may this run proceed" and feeds control flow, this one answers
+ * "what surrounds this ticket" and is context only. They are kept apart on purpose so a change to the
+ * manifest can never alter a guard.
+ *
+ * The `IssueGraphSource` seam keeps the assembly pure and unit-testable.
+ */
+import { LinearClient } from "@linear/sdk";
+import type { IssueRelation, RelatedIssue } from "@dahrk/contracts";
+
+/** An issue as returned by Linear before normalisation, with its state already resolved. */
+export interface RawRelatedIssue {
+  identifier?: string;
+  title?: string;
+  url?: string;
+  stateName?: string;
+  stateType?: string;
+}
+
+/** One edge: the neighbouring issue plus how it sits relative to the subject issue. */
+export interface RawEdge {
+  relation: IssueRelation;
+  issue: RawRelatedIssue | null;
+}
+
+/** The read seam the assembly depends on; the live impl wraps GraphQL, tests inject a fake. */
+export interface IssueGraphSource {
+  /** Every one-hop edge from the issue, in any order. */
+  issueEdges(issueId: string): Promise<RawEdge[]>;
+}
+
+/** How many neighbours ride the manifest. Beyond this the prompt stops being a summary. */
+export const MAX_RELATED_ISSUES = 50;
+
+/** Stable ordering for the manifest: the structurally important edges first, so a truncated list keeps
+ *  what matters. Parent and blockers change how the work should be done; `related` is a loose,
+ *  human-curated edge and is the first thing worth losing. */
+const RELATION_ORDER: Record<IssueRelation, number> = {
+  parent: 0,
+  blocker: 1,
+  child: 2,
+  blocked: 3,
+  related: 4,
+};
+
+/**
+ * Collect the issue's one-hop neighbourhood from a source: drop edges whose issue did not resolve or
+ * carries no identifier, de-dupe by identifier (an issue can be reachable by more than one edge -
+ * keep the structurally strongest, which is the lowest `RELATION_ORDER`), sort, and cap. Pure of any
+ * network.
+ */
+export async function collectRelatedIssues(
+  source: IssueGraphSource,
+  issueId: string,
+): Promise<RelatedIssue[]> {
+  const byKey = new Map<string, RelatedIssue>();
+  for (const edge of await source.issueEdges(issueId)) {
+    const issue = edge.issue;
+    const key = issue?.identifier?.trim();
+    if (!issue || !key) continue;
+    const candidate: RelatedIssue = {
+      key,
+      title: (issue.title ?? "").trim() || "Untitled issue",
+      relation: edge.relation,
+      stateName: (issue.stateName ?? "").trim() || "unknown",
+      stateType: (issue.stateType ?? "").trim() || "unknown",
+      url: issue.url ?? "",
+    };
+    const existing = byKey.get(key);
+    if (!existing || RELATION_ORDER[candidate.relation] < RELATION_ORDER[existing.relation]) {
+      byKey.set(key, candidate);
+    }
+  }
+  return [...byKey.values()]
+    .sort(
+      (a, b) => RELATION_ORDER[a.relation] - RELATION_ORDER[b.relation] || a.key.localeCompare(b.key),
+    )
+    .slice(0, MAX_RELATED_ISSUES);
+}
+
+/** The live `IssueGraphSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export function linearIssueGraphSource(token: string): IssueGraphSource {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async issueEdges(issueId) {
+      const issue = await client.issue(issueId);
+
+      // Resolve one neighbouring issue into the raw shape, including its state. Returns null when the
+      // issue or its state does not resolve, which the assembly then skips.
+      const shape = async (
+        node: {
+          identifier?: string;
+          title?: string;
+          url?: string;
+          state?: Promise<{ name?: string; type?: string } | undefined>;
+        } | null
+        | undefined,
+      ): Promise<RawRelatedIssue | null> => {
+        if (!node) return null;
+        const state = await node.state;
+        return {
+          ...(node.identifier ? { identifier: node.identifier } : {}),
+          ...(node.title ? { title: node.title } : {}),
+          ...(node.url ? { url: node.url } : {}),
+          ...(state?.name ? { stateName: state.name } : {}),
+          ...(state?.type ? { stateType: state.type } : {}),
+        };
+      };
+
+      // The four reads run concurrently; each is independently capped. `relations` is what this issue
+      // blocks/relates to, `inverseRelations` is what points AT this issue - the direction matters, and
+      // getting it backwards is the bug called out on `fetchOpenBlockers` (labels.ts).
+      const [parent, children, relations, inverseRelations] = await Promise.all([
+        issue.parent,
+        issue.children({ first: 25 }),
+        issue.relations({ first: 25 }),
+        issue.inverseRelations({ first: 25 }),
+      ]);
+
+      const edges: RawEdge[] = [];
+
+      const parentShape = await shape(parent as Parameters<typeof shape>[0]);
+      if (parentShape) edges.push({ relation: "parent", issue: parentShape });
+
+      for (const child of children.nodes) {
+        edges.push({ relation: "child", issue: await shape(child as Parameters<typeof shape>[0]) });
+      }
+
+      // Outbound: `A blocks B` stored on A means B is blocked BY us; anything else is a plain relation.
+      for (const rel of relations.nodes) {
+        const related = await rel.relatedIssue;
+        edges.push({
+          relation: rel.type === "blocks" ? "blocked" : "related",
+          issue: await shape(related as Parameters<typeof shape>[0]),
+        });
+      }
+
+      // Inbound: a `blocks` relation pointing at us means that issue is OUR blocker.
+      for (const rel of inverseRelations.nodes) {
+        const other = await rel.issue;
+        edges.push({
+          relation: rel.type === "blocks" ? "blocker" : "related",
+          issue: await shape(other as Parameters<typeof shape>[0]),
+        });
+      }
+
+      return edges;
+    },
+  };
+}
+
+/**
+ * Fetch the issue's one-hop neighbourhood as contract `RelatedIssue`s, ready to snapshot into a run.
+ * The single entry point the hub calls. A hard failure (auth, network) propagates so the caller can
+ * log and proceed with none.
+ */
+export async function fetchRelatedIssues(token: string, issueId: string): Promise<RelatedIssue[]> {
+  return collectRelatedIssues(linearIssueGraphSource(token), issueId);
+}

package/src/issues.ts

@@ -0,0 +1,142 @@
+/**
+ * Auto-create a Linear triage issue when a run fails (failure-notification path). Mirrors the
+ * `LabelApi` seam in ./labels.ts: a small `TriageApi` interface so the hub stays pure and testable,
+ * plus a live adapter (`linearTriageApi`) that wraps `@linear/sdk`. It uses the hub's OWN triage
+ * token (an internal ops workspace), never a customer connection's token.
+ */
+import { IssueRelationType, LinearClient } from "@linear/sdk";
+
+export interface TriageApi {
+  /** Create an issue in `teamKey` (optionally under `projectName`); returns its identifier + url.
+   *  Created with NO `stateId`, so the issue lands in the team's Triage view when triage is enabled
+   *  (the intake/review surface), rather than a workflow's default backlog state. */
+  createIssue(input: {
+    teamKey: string;
+    projectName?: string;
+    title: string;
+    description: string;
+  }): Promise<{ identifier: string; url: string }>;
+  /** Associate a Customer Request (CustomerNeed) with an issue (SL-359), linking customer feedback to
+   *  the logged issue. Off-by-default: only called when the source carries customer identity (a
+   *  `customerId` or external id). Returns the created need's id. */
+  createCustomerNeed(input: {
+    issueId: string;
+    customerId?: string;
+    customerExternalId?: string;
+    body?: string;
+  }): Promise<{ id: string }>;
+  /** Relate one issue to another (SL-379), so a triage-filed fix issue links back to the originating
+   *  bug. Off-by-default: only called when the target run carries an originating Linear issue. `type`
+   *  defaults to `related` (a non-directional link); `blocks` records the fix-blocks-bug direction.
+   *  `issueId`/`relatedIssueId` accept a UUID or an identifier (e.g. `TEST-49`). */
+  relateIssues(input: {
+    issueId: string;
+    relatedIssueId: string;
+    type?: "related" | "blocks";
+  }): Promise<void>;
+}
+
+/** Pick the right `@linear/sdk` auth field for a triage token. A personal API key (`lin_api_…`) must
+ *  go in the raw `Authorization` header (the SDK's `apiKey`); an OAuth access token uses `Bearer` (the
+ *  SDK's `accessToken`). Sending an API key as a Bearer token fails with "Remove the Bearer prefix…"
+ *  (SL-399), which is exactly what silently broke triage logging. Exported for testing. */
+export function linearClientAuth(token: string): { apiKey: string } | { accessToken: string } {
+  return token.startsWith("lin_api_") ? { apiKey: token } : { accessToken: token };
+}
+
+/** The live `TriageApi` backed by a Linear token (personal API key or OAuth access token). Resolves
+ *  team by key and optional project by name via server-side `filter` (verified on @linear/sdk 86.0.0,
+ *  DHK-579: `TeamFilter.key`/`ProjectFilter.name` return exactly the expected node - the earlier
+ *  paginate-then-match workaround is no longer needed). */
+export function linearTriageApi(token: string): TriageApi {
+  const client = new LinearClient(linearClientAuth(token));
+  return {
+    async createIssue(input) {
+      const team = (await client.teams({ filter: { key: { eq: input.teamKey } } })).nodes[0];
+      if (!team) throw new Error(`triage team not found: ${input.teamKey}`);
+
+      let projectId: string | undefined;
+      if (input.projectName) {
+        projectId = (await client.projects({ filter: { name: { eq: input.projectName } } })).nodes[0]?.id;
+      }
+
+      const payload = await client.createIssue({
+        teamId: team.id,
+        title: input.title,
+        description: input.description,
+        ...(projectId ? { projectId } : {}),
+      });
+      const issue = await payload.issue;
+      return { identifier: issue?.identifier ?? "", url: issue?.url ?? "" };
+    },
+
+    async createCustomerNeed(input) {
+      // `issueId` accepts a UUID or an issue identifier (e.g. `TEST-49`); exactly one of
+      // `customerId`/`customerExternalId` identifies the customer (the SDK forbids both at once).
+      const payload = await client.createCustomerNeed({
+        issueId: input.issueId,
+        ...(input.customerId ? { customerId: input.customerId } : {}),
+        ...(input.customerExternalId ? { customerExternalId: input.customerExternalId } : {}),
+        ...(input.body ? { body: input.body } : {}),
+      });
+      return { id: payload.needId ?? "" };
+    },
+
+    async relateIssues(input) {
+      await client.createIssueRelation({
+        issueId: input.issueId,
+        relatedIssueId: input.relatedIssueId,
+        type: input.type === "blocks" ? IssueRelationType.Blocks : IssueRelationType.Related,
+      });
+    },
+  };
+}
+
+/** The result of a Capture create/update: the issue's internal id plus its human identifier and url. */
+export interface CaptureIssueResult {
+  issueId: string;
+  identifier: string;
+  url: string;
+}
+
+/** The Capture Linear seam (DHK-1187): create an issue in a team (or under a project), or update an
+ *  existing one. Unlike {@link TriageApi}, it returns the issue's internal `issueId` too (a Capture
+ *  receipt needs it) and can update. Backed by a CUSTOMER connection token, never the hub triage token. */
+export interface CaptureLinearApi {
+  createIssue(input: {
+    teamKey: string;
+    projectName?: string;
+    title: string;
+    description: string;
+  }): Promise<CaptureIssueResult>;
+  updateIssue(input: { issueId: string; title: string; description: string }): Promise<CaptureIssueResult>;
+}
+
+/** The live {@link CaptureLinearApi} backed by a tenant connection token (API key or OAuth token). */
+export function linearCaptureApi(token: string): CaptureLinearApi {
+  const client = new LinearClient(linearClientAuth(token));
+  return {
+    async createIssue(input) {
+      const team = (await client.teams({ filter: { key: { eq: input.teamKey } } })).nodes[0];
+      if (!team) throw new Error(`capture team not found: ${input.teamKey}`);
+      let projectId: string | undefined;
+      if (input.projectName) {
+        projectId = (await client.projects({ filter: { name: { eq: input.projectName } } })).nodes[0]?.id;
+      }
+      const payload = await client.createIssue({
+        teamId: team.id,
+        title: input.title,
+        description: input.description,
+        ...(projectId ? { projectId } : {}),
+      });
+      const issue = await payload.issue;
+      return { issueId: issue?.id ?? "", identifier: issue?.identifier ?? "", url: issue?.url ?? "" };
+    },
+
+    async updateIssue(input) {
+      const payload = await client.updateIssue(input.issueId, { title: input.title, description: input.description });
+      const issue = await payload.issue;
+      return { issueId: issue?.id ?? input.issueId, identifier: issue?.identifier ?? "", url: issue?.url ?? "" };
+    },
+  };
+}

package/src/labels.ts

@@ -0,0 +1,254 @@
+/**
+ * Trigger-label auto-provisioning (build spec section 14; plan item 7). A repository declares its
+ * workflows as `.dahrk/workflows/*.yaml`, each with a `select.label`; for those labels to be
+ * assignable in Linear they must exist in the workspace. Rather than make operators create them by
+ * hand, the onboarding path reads the workflow label set and creates any that are missing - once,
+ * idempotently - optionally grouped under a single "Dahrk workflow" label group.
+ *
+ * The `LabelApi` seam keeps this pure and unit-testable: the live adapter (`linearLabelApi`) wraps
+ * `@linear/sdk`, while tests inject a fake. Provisioning is read-decoupled from execution - it uses
+ * the hub's own credential, not a node's.
+ */
+import { LinearClient } from "@linear/sdk";
+
+export interface LabelApi {
+  /** Existing workspace labels as a name -> id map. */
+  listLabels(): Promise<Map<string, string>>;
+  /** Create a label (or label group) and return its id. */
+  createLabel(input: {
+    name: string;
+    color?: string;
+    description?: string;
+    parentId?: string;
+    isGroup?: boolean;
+  }): Promise<string>;
+}
+
+export interface ProvisionOptions {
+  /** Colour applied to created labels (hex, e.g. "#5e6ad2"). */
+  color?: string;
+  /** When set, missing labels are created under a group label of this name (created if absent). */
+  groupName?: string;
+  /** Description set on the group label when it is created. */
+  groupDescription?: string;
+  /** Build the description for each created child label. */
+  describe?: (name: string) => string;
+}
+
+/**
+ * Idempotently create any missing labels via the `LabelApi` seam. Pre-existing labels (by name) are
+ * left untouched; the group, if named, is created once and reused. Returns the names actually created,
+ * so callers can log what changed. The seam is namespace-agnostic - pass `linearLabelApi` to provision
+ * issue labels or `projectLabelApi` to provision project labels.
+ */
+export async function provisionLabels(
+  api: LabelApi,
+  names: Iterable<string>,
+  opts: ProvisionOptions = {},
+): Promise<string[]> {
+  const existing = await api.listLabels();
+
+  let parentId: string | undefined;
+  if (opts.groupName) {
+    parentId =
+      existing.get(opts.groupName) ??
+      (await api.createLabel({
+        name: opts.groupName,
+        isGroup: true,
+        ...(opts.groupDescription ? { description: opts.groupDescription } : {}),
+      }));
+  }
+
+  const created: string[] = [];
+  for (const name of new Set(names)) {
+    if (existing.has(name)) continue;
+    await api.createLabel({
+      name,
+      ...(opts.color ? { color: opts.color } : {}),
+      ...(opts.describe ? { description: opts.describe(name) } : {}),
+      ...(parentId ? { parentId } : {}),
+    });
+    created.push(name);
+  }
+  return created;
+}
+
+/**
+ * Idempotently create any missing workflow trigger labels (build spec section 14). Thin wrapper over
+ * `provisionLabels` with the workflow-trigger wording, preserving the onboarding behaviour.
+ */
+export async function provisionWorkflowLabels(
+  api: LabelApi,
+  names: Iterable<string>,
+  opts: ProvisionOptions = {},
+): Promise<string[]> {
+  return provisionLabels(api, names, {
+    ...opts,
+    ...(opts.groupName ? { groupDescription: "Dahrk workflow trigger labels" } : {}),
+    describe: (name) => `Dahrk workflow trigger: ${name}`,
+  });
+}
+
+/** The canonical repo-selector label group: a parent group named `repo` whose children name each
+ *  repository, rendered `repo › <name>` in Linear. This is the form the routing tier recognises (issue
+ *  labels override, project labels default); the colon/slash string forms are back-compat only. */
+export const REPO_LABEL_GROUP = "repo";
+
+/**
+ * Idempotently create the `repo` label group and a child per repository name, so a `repo › <name>`
+ * label is assignable in Linear. Works for either namespace: pass `linearLabelApi(token)` to create the
+ * issue-label override group, or `projectLabelApi(token)` to create the project-label default group.
+ */
+export async function provisionRepoLabels(
+  api: LabelApi,
+  repoNames: Iterable<string>,
+  opts: { color?: string } = {},
+): Promise<string[]> {
+  return provisionLabels(api, repoNames, {
+    ...(opts.color ? { color: opts.color } : {}),
+    groupName: REPO_LABEL_GROUP,
+    groupDescription: "Dahrk repository selector labels",
+    describe: (name) => `Dahrk repository selector: ${name}`,
+  });
+}
+
+/**
+ * Fetch the child names of the issue's **project** `repo` label group (project labels are a separate
+ * Linear namespace from issue labels, `Project.labels`). Returns the names of project labels whose
+ * parent group is `repo` - e.g. `["dahrk-web"]` - so the hub can bind every issue in that project to
+ * a repo via the project-label routing tier. Empty when the issue has no project, no project labels, or
+ * no `repo` group. A read against the connection token; data assembly, not control flow, so the result
+ * feeds deterministic routing and is snapshotted into the run.
+ */
+export async function fetchIssueProjectRepoLabels(token: string, issueId: string): Promise<string[]> {
+  const client = new LinearClient({ accessToken: token });
+  const issue = await client.issue(issueId);
+  const project = await issue.project;
+  if (!project) return [];
+  const conn = await project.labels({ first: 100, filter: { parent: { name: { eqIgnoreCase: REPO_LABEL_GROUP } } } });
+  return conn.nodes.map((n) => n.name.trim());
+}
+
+/**
+ * Count an issue's child issues (DHK-412), so the hub's epic guard can decline a parent-of-children.
+ * The webhook payload carries an issue's `<parent-issue>` but never a listing of its children, so
+ * "has children" must be resolved with a read against the connection token. Returns 0 when the issue
+ * has none (or the field is empty). Capped at `first:1` - the guard only needs "any", not an exact
+ * total - so it stays a cheap intake read. Data assembly, not control flow: the count feeds the
+ * deterministic, no-LLM epic guard.
+ */
+export async function fetchIssueChildCount(token: string, issueId: string): Promise<number> {
+  const client = new LinearClient({ accessToken: token });
+  const issue = await client.issue(issueId);
+  const conn = await issue.children({ first: 1 });
+  return conn.nodes.length;
+}
+
+/** One issue that blocks another and has not settled yet. `identifier` is the human key (e.g.
+ *  `DHK-777`) the decline note names; `stateName` is the team's own label for the state it sits in,
+ *  carried for the note only - never matched on (see `fetchOpenBlockers`). */
+export interface OpenBlocker {
+  identifier: string;
+  stateName: string;
+}
+
+/**
+ * Has a blocker finished, so it no longer blocks?
+ *
+ * Decided on the workflow state's `type` - Linear's own fixed vocabulary (`backlog`, `unstarted`,
+ * `started`, `completed`, `canceled`) - and NEVER on its name. Teams rename states freely: "Done"
+ * becomes "Shipped", "Released", "Merged". A name match would stop guarding for every one of those
+ * teams with nothing to notice, because the guard would simply never fire again.
+ *
+ * An absent/unknown type is treated as NOT settled: a blocker we cannot prove is finished is one we
+ * must assume is not. Pure, so the rule is pinned by a test rather than by a live Linear read.
+ */
+export function isBlockerSettled(stateType: string | undefined): boolean {
+  return stateType === "completed" || stateType === "canceled";
+}
+
+/**
+ * The issues blocking `issueId` that are not finished yet, so the hub's blocked guard can decline a
+ * run that cannot possibly succeed. The webhook payload carries no relation data at all, so this must
+ * be resolved with a read against the connection token, exactly as `fetchIssueChildCount` resolves the
+ * epic signal. Returns an empty list when nothing blocks the issue, or when every blocker has settled.
+ *
+ * The direction matters: `A blocks B` is stored on A, so B reads it through `inverseRelations`. Reading
+ * `relations` instead would return what this issue blocks - the opposite question, and one that would
+ * silently never guard anything.
+ *
+ * "Settled" is decided on the state's `type` (`completed` / `canceled`), NEVER on its name. Teams rename
+ * workflow states freely - "Done" becomes "Shipped", "Released", "Merged" - and a name match would stop
+ * guarding for those teams without any error to notice. The type is Linear's own fixed vocabulary.
+ *
+ * Capped, like the child-count read: a ticket with more open blockers than the cap is still blocked, and
+ * the note naming the first few is enough to act on. Data assembly, not control flow: the list feeds the
+ * deterministic, no-LLM blocked guard.
+ */
+export async function fetchOpenBlockers(token: string, issueId: string): Promise<OpenBlocker[]> {
+  const client = new LinearClient({ accessToken: token });
+  const issue = await client.issue(issueId);
+  const conn = await issue.inverseRelations({ first: 25 });
+  const open: OpenBlocker[] = [];
+  for (const relation of conn.nodes) {
+    if (relation.type !== "blocks") continue;
+    const blocker = await relation.issue;
+    if (!blocker) continue;
+    const state = await blocker.state;
+    if (isBlockerSettled(state?.type)) continue;
+    open.push({ identifier: blocker.identifier, stateName: state?.name ?? "unknown" });
+  }
+  return open;
+}
+
+/** The live `LabelApi` backed by a Linear bearer token (workspace-scoped labels). */
+export function linearLabelApi(token: string): LabelApi {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async listLabels() {
+      const conn = await client.issueLabels();
+      while (conn.pageInfo.hasNextPage) await conn.fetchNext();
+      const map = new Map<string, string>();
+      for (const label of conn.nodes) map.set(label.name, label.id);
+      return map;
+    },
+    async createLabel(input) {
+      const payload = await client.createIssueLabel({
+        name: input.name,
+        ...(input.color ? { color: input.color } : {}),
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.parentId ? { parentId: input.parentId } : {}),
+        ...(input.isGroup ? { isGroup: true } : {}),
+      });
+      const label = await payload.issueLabel;
+      return label?.id ?? "";
+    },
+  };
+}
+
+/** The live `LabelApi` backed by a Linear bearer token, for **project** labels (a separate namespace
+ *  from issue labels). Lets `provisionLabels`/`provisionRepoLabels` create the project-label `repo`
+ *  group that drives the default routing layer. */
+export function projectLabelApi(token: string): LabelApi {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async listLabels() {
+      const conn = await client.projectLabels();
+      while (conn.pageInfo.hasNextPage) await conn.fetchNext();
+      const map = new Map<string, string>();
+      for (const label of conn.nodes) map.set(label.name, label.id);
+      return map;
+    },
+    async createLabel(input) {
+      const payload = await client.createProjectLabel({
+        name: input.name,
+        ...(input.color ? { color: input.color } : {}),
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.parentId ? { parentId: input.parentId } : {}),
+        ...(input.isGroup ? { isGroup: true } : {}),
+      });
+      const label = await payload.projectLabel;
+      return label?.id ?? "";
+    },
+  };
+}