@dahrk/linear 0.1.0 → 0.2.0

package/src/batch-source.ts

@@ -0,0 +1,208 @@
+/**
+ * Snapshot a parent control issue as a deterministic child-sourced Batch (DHK-1154; ADRs 0016-0017).
+ *
+ * Assigning or @mentioning Dahrk on a PARENT issue launches its direct child work as one immutable
+ * Batch. This module takes ONE credential-resolved read of the parent's direct, nonterminal children
+ * (the control issue itself is never included - children only) and normalises it into a
+ * {@link ParentBatchSnapshot}: an ordered list of {@link BatchMember}s keyed by stable issue UUID, the
+ * explicit `blocks` edges BETWEEN members ({@link BatchBlockEdge}), and any unsettled blocker OUTSIDE
+ * the member set that must block creation (`externalBlockers`).
+ *
+ * Two rules pin the dependency model:
+ *  - Containment is not a dependency. A parent/child relation NEVER produces an edge; only an explicit
+ *    Linear `blocks` relation does. Children carry only their own `blocks` blockers, so containment is
+ *    structurally incapable of creating one here.
+ *  - "External" is relative to the SELECTED source. A blocker that is itself another selected child is
+ *    an internal edge, not an external blocker, even when unsettled - that is a dependency to sequence,
+ *    not a refusal. The membership test runs before the external-blocker test.
+ *
+ * The `ParentBatchSource` seam keeps the assembly pure and unit-testable (the `collectRelatedIssues`
+ * pattern from `issue-graph.ts`): the live impl wraps the SDK, tests inject a fake.
+ */
+import { LinearClient } from "@linear/sdk";
+import type { BatchMember, BatchBlockEdge } from "@dahrk/contracts";
+import { isBlockerSettled } from "./labels.js";
+
+/** An issue that `blocks` a child, as read from the child's `inverseRelations`. `stateType` decides
+ *  whether it has settled (terminal); `stateName` is carried for the decline note only, never matched. */
+export interface RawBlocker {
+  id?: string;
+  identifier?: string;
+  stateType?: string;
+  stateName?: string;
+}
+
+/** A child issue as returned by Linear before normalisation, with its state and blockers resolved. */
+export interface RawChild {
+  id?: string;
+  identifier?: string;
+  /** The child's workflow-state category (`state.type`); terminal children are dropped. */
+  stateType?: string;
+  /** Linear priority (`0` = none, `1` = urgent … `4` = low). */
+  priority?: number;
+  /** The child's rank within the parent (`subIssueSortOrder`, falling back to `sortOrder`). */
+  containerRank?: number;
+  /** The issues that `blocks` this child (its `inverseRelations` of type `blocks`). */
+  blockers: RawBlocker[];
+}
+
+/** The read seam the assembly depends on; the live impl wraps the SDK, tests inject a fake. */
+export interface ParentBatchSource {
+  /** The parent's direct children, each with its state and its `blocks` blockers, in any order. */
+  children(parentIssueId: string): Promise<RawChild[]>;
+}
+
+/** One unsettled blocker outside the selected source that prevents Batch creation. Shaped like the
+ *  hub's `OpenBlocker` so the decline note names it (`identifier` is the key; `stateName` is display). */
+export interface ExternalBlocker {
+  identifier: string;
+  stateName: string;
+}
+
+/** The normalised parent-Batch snapshot: the ordered members, the internal `blocks` edges between them,
+ *  and any external blocker that must block creation. */
+export interface ParentBatchSnapshot {
+  members: BatchMember[];
+  blocks: BatchBlockEdge[];
+  externalBlockers: ExternalBlocker[];
+}
+
+/** How many children ride one snapshot. A parent with more direct children than this is unusual; the
+ *  cap keeps the intake read bounded, mirroring the neighbours read in `issue-graph.ts`. */
+export const MAX_BATCH_CHILDREN = 200;
+
+/** Sort key for priority: urgent (1) first, none (0) last. Linear priority is `0=none,1=urgent..4=low`,
+ *  so "order by priority" must map `0` to the end rather than the front. Pure, pinned by a test. */
+function priorityRank(priority: number): number {
+  return priority === 0 ? Number.POSITIVE_INFINITY : priority;
+}
+
+/**
+ * Collect the parent's direct nonterminal children as a {@link ParentBatchSnapshot} from a source: drop
+ * children with no id/identifier; drop terminal (`completed`/`canceled`) children; classify each
+ * member's `blocks` blockers into internal edges (blocker is another member) or external blockers
+ * (blocker is outside the set and unsettled); order members by priority, then container rank, then
+ * identifier. Pure of any network.
+ */
+export async function collectParentBatchSource(
+  source: ParentBatchSource,
+  parentIssueId: string,
+): Promise<ParentBatchSnapshot> {
+  const raw = await source.children(parentIssueId);
+
+  // Keep only real, nonterminal children. A child needs a stable id AND a human identifier; a terminal
+  // child (settled state) is finished work, not something to launch.
+  const kept: RawChild[] = [];
+  for (const c of raw) {
+    const id = c.id?.trim();
+    const identifier = c.identifier?.trim();
+    if (!id || !identifier) continue;
+    if (isBlockerSettled(c.stateType)) continue;
+    kept.push(c);
+  }
+
+  const memberIds = new Set(kept.map((c) => c.id!.trim()));
+
+  const members: BatchMember[] = kept.map((c) => ({
+    issueId: c.id!.trim(),
+    issueIdentifier: c.identifier!.trim(),
+    stateType: (c.stateType ?? "").trim() || "unknown",
+    priority: c.priority ?? 0,
+    containerRank: c.containerRank ?? 0,
+  }));
+
+  // Deterministic order: urgent priority first (none last), then container rank ascending, then the
+  // human identifier. Every downstream reader sees the same sequence, so admission is replayable.
+  members.sort(
+    (a, b) =>
+      priorityRank(a.priority) - priorityRank(b.priority) ||
+      a.containerRank - b.containerRank ||
+      a.issueIdentifier.localeCompare(b.issueIdentifier),
+  );
+
+  // Classify blockers in member order so edges and external blockers are deterministic. A blocker that
+  // is itself a selected member is an internal edge (a dependency to sequence); one outside the set that
+  // has not settled is an external blocker (a refusal); a settled external blocker is simply done.
+  const byId = new Map(kept.map((c) => [c.id!.trim(), c]));
+  const blocks: BatchBlockEdge[] = [];
+  const externalBlockers: ExternalBlocker[] = [];
+  const seenExternal = new Set<string>();
+  for (const m of members) {
+    const c = byId.get(m.issueId)!;
+    for (const b of c.blockers) {
+      const blockerId = b.id?.trim();
+      if (blockerId && memberIds.has(blockerId)) {
+        blocks.push({ blockerIssueId: blockerId, blockedIssueId: m.issueId });
+        continue;
+      }
+      if (isBlockerSettled(b.stateType)) continue;
+      const identifier = (b.identifier ?? "").trim() || "unknown";
+      if (seenExternal.has(identifier)) continue;
+      seenExternal.add(identifier);
+      externalBlockers.push({ identifier, stateName: (b.stateName ?? "").trim() || "unknown" });
+    }
+  }
+
+  return { members, blocks, externalBlockers };
+}
+
+/** The live `ParentBatchSource`, backed by a Linear bearer token. Uses the typed SDK: the parent's
+ *  `children`, each child's `state`/`priority`/`subIssueSortOrder`/`sortOrder`, and each child's
+ *  `inverseRelations` of type `blocks` resolved to `{id, identifier, state}`. Capped like the
+ *  neighbours read. */
+export function linearParentBatchSource(token: string): ParentBatchSource {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async children(parentIssueId) {
+      const parent = await client.issue(parentIssueId);
+      const conn = await parent.children({ first: MAX_BATCH_CHILDREN });
+      const children: RawChild[] = [];
+      for (const c of conn.nodes) {
+        const [state, inverse] = await Promise.all([
+          c.state,
+          // A `blocks` relation pointing AT the child means that issue is the child's blocker (the same
+          // direction `fetchOpenBlockers` reads). `relations` would return what the child blocks - the
+          // opposite question.
+          c.inverseRelations({ first: 25 }),
+        ]);
+        const blockers: RawBlocker[] = [];
+        for (const rel of inverse.nodes) {
+          if (rel.type !== "blocks") continue;
+          const other = await rel.issue;
+          if (!other) continue;
+          const bState = await other.state;
+          blockers.push({
+            ...(other.id ? { id: other.id } : {}),
+            ...(other.identifier ? { identifier: other.identifier } : {}),
+            ...(bState?.type ? { stateType: bState.type } : {}),
+            ...(bState?.name ? { stateName: bState.name } : {}),
+          });
+        }
+        // `subIssueSortOrder` is the rank within the parent; fall back to `sortOrder` when absent.
+        const containerRank =
+          (c as { subIssueSortOrder?: number }).subIssueSortOrder ?? c.sortOrder ?? 0;
+        children.push({
+          ...(c.id ? { id: c.id } : {}),
+          ...(c.identifier ? { identifier: c.identifier } : {}),
+          ...(state?.type ? { stateType: state.type } : {}),
+          ...(typeof c.priority === "number" ? { priority: c.priority } : {}),
+          containerRank,
+          blockers,
+        });
+      }
+      return children;
+    },
+  };
+}
+
+/**
+ * Take the parent-Batch snapshot for `parentIssueId` as a {@link ParentBatchSnapshot}, ready for the
+ * hub to persist. The single entry point the hub calls (mirrors `fetchRelatedIssues`). A hard failure
+ * (auth, network) propagates so the caller can log and proceed.
+ */
+export async function fetchParentBatchSource(
+  token: string,
+  parentIssueId: string,
+): Promise<ParentBatchSnapshot> {
+  return collectParentBatchSource(linearParentBatchSource(token), parentIssueId);
+}

package/src/comments.ts

@@ -0,0 +1,126 @@
+/**
+ * Fetch the comment thread on a Linear issue, so the hub can snapshot it into a run and surface it to
+ * the agent. Until now nothing in the harness read comment bodies at all: an agent saw only whatever
+ * Linear happened to inline in the webhook's `promptContext`, so the conversation that actually
+ * decided the shape of a ticket was invisible to the stage doing the work.
+ *
+ * The one piece of logic that is not a plain read: the app user's OWN comments are dropped. The
+ * harness posts its stage summaries back through `commentOnIssue`, so without this filter every stage
+ * would read the previous stage's summary as though a human had written it - the run talking to itself,
+ * with the noise compounding on each continuation.
+ *
+ * The `CommentSource` seam keeps the assembly pure and unit-testable: the live source
+ * (`linearCommentSource`) speaks GraphQL, while tests inject a fake.
+ */
+import { LinearClient } from "@linear/sdk";
+import type { IssueComment } from "@dahrk/contracts";
+
+/** A comment as returned by Linear before normalisation. */
+export interface RawComment {
+  id: string;
+  body?: string;
+  createdAt?: Date | string;
+  /** Author user id, compared against the app user id to drop the harness's own posts. */
+  authorId?: string;
+  /** Author display name, surfaced to the agent. */
+  authorName?: string;
+}
+
+/** The read seam the assembly depends on; the live impl wraps GraphQL, tests inject a fake. */
+export interface CommentSource {
+  /** The issue's comments, in whatever order Linear returns them. */
+  issueComments(issueId: string): Promise<RawComment[]>;
+  /** The id of the app user this token authenticates as, or null when it cannot be resolved. */
+  appUserId(): Promise<string | null>;
+}
+
+/** Normalise a timestamp Linear may hand back as a Date or a string into ISO 8601. */
+function isoOf(value: Date | string | undefined): string {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" && value.trim()) {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? "" : parsed.toISOString();
+  }
+  return "";
+}
+
+/**
+ * Collect an issue's comments from a source: drop the app user's own posts, drop empty bodies, and
+ * order oldest first so the thread reads as a conversation. Pure of any network - the source does the
+ * I/O.
+ *
+ * Comments with no resolvable timestamp sort last rather than being dropped: an unorderable comment is
+ * still content worth showing, and losing it silently would be worse than showing it out of order.
+ */
+export async function collectIssueComments(
+  source: CommentSource,
+  issueId: string,
+): Promise<IssueComment[]> {
+  const [raw, appUserId] = await Promise.all([source.issueComments(issueId), source.appUserId()]);
+  const out: IssueComment[] = [];
+  for (const comment of raw) {
+    if (appUserId && comment.authorId === appUserId) continue;
+    const body = (comment.body ?? "").trim();
+    if (!body) continue;
+    out.push({
+      id: comment.id,
+      author: (comment.authorName ?? "").trim(),
+      createdAt: isoOf(comment.createdAt),
+      body,
+    });
+  }
+  return out.sort((a, b) => {
+    if (!a.createdAt) return 1;
+    if (!b.createdAt) return -1;
+    return a.createdAt.localeCompare(b.createdAt);
+  });
+}
+
+/** The live `CommentSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export function linearCommentSource(token: string): CommentSource {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async issueComments(issueId) {
+      // Bounded, unpaginated cap, matching `linearDocumentSource.issueDocuments`: a thread longer than
+      // 100 comments silently drops the overflow. Deliberate, not a bug - the prompt inlines only the
+      // most recent few thousand characters anyway. Revisit with cursor pagination if it bites.
+      const issue = await client.issue(issueId);
+      const conn = await issue.comments({ first: 100 });
+      const nodes = await Promise.all(
+        conn.nodes.map(async (c) => {
+          // `user` is a lazy reference on the SDK's Comment; resolving it per comment is what lets us
+          // both filter the app user's posts and name the human author. A comment whose author does not
+          // resolve (a deleted user, an integration post) still rides through, unattributed.
+          const user = await c.user;
+          return {
+            id: c.id,
+            body: c.body,
+            createdAt: c.createdAt,
+            ...(user?.id ? { authorId: user.id } : {}),
+            ...(user?.displayName || user?.name ? { authorName: user.displayName ?? user.name } : {}),
+          } satisfies RawComment;
+        }),
+      );
+      return nodes;
+    },
+    async appUserId() {
+      try {
+        const viewer = await client.viewer;
+        return viewer?.id ?? null;
+      } catch {
+        // Failing to resolve the app user must not lose the thread. We return null and accept that the
+        // harness's own comments ride through this once, rather than dropping every comment.
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Fetch an issue's comment thread as contract `IssueComment`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 fetchIssueComments(token: string, issueId: string): Promise<IssueComment[]> {
+  return collectIssueComments(linearCommentSource(token), issueId);
+}

package/src/documents.ts

@@ -0,0 +1,162 @@
+/**
+ * Fetch the Linear Documents attached to an issue, so the hub can snapshot their content into a run
+ * and surface it to the agent (the harness was webhook-payload-only before, so a document reached the
+ * agent only as a URL, never as content). This is a read against the same per-connection Linear token
+ * the hub already uses to post back; fetching content is data assembly, not control flow.
+ *
+ * Two sources, de-duped by document id:
+ *  1. Documents directly associated with the issue (`issue.documents`).
+ *  2. Documents linked via the issue's attachments whose `url` is a Linear document URL
+ *     (`https://linear.app/<ws>/document/<...>-<slug>`), resolved through `document(id:)`.
+ *
+ * The `DocumentSource` seam keeps the assembly pure and unit-testable: the live source
+ * (`linearDocumentSource`) speaks GraphQL, while tests inject a fake.
+ */
+import { LinearClient } from "@linear/sdk";
+import type { AttachedDocument } from "@dahrk/contracts";
+
+/** A document as returned by Linear before slug normalisation (slugId is Linear's URL-safe slug). */
+export interface RawDocument {
+  id: string;
+  slugId?: string;
+  title?: string;
+  url?: string;
+  content?: string;
+}
+
+/** The read seam the assembly depends on; the live impl wraps GraphQL, tests inject a fake. */
+export interface DocumentSource {
+  /** Documents directly associated with the issue. */
+  issueDocuments(issueId: string): Promise<RawDocument[]>;
+  /** The issue's attachment URLs (only the `url` is needed to spot Linear document links). */
+  issueAttachmentUrls(issueId: string): Promise<string[]>;
+  /** Resolve a Linear document by the slug taken from its URL; null when it does not resolve. */
+  documentBySlug(slug: string): Promise<RawDocument | null>;
+}
+
+/** The Linear-document slug from an attachment URL, or null when the URL is not a Linear document
+ *  link. Linear document URLs look like `https://linear.app/<ws>/document/<title-slug>-<slugId>`;
+ *  the canonical slug Linear's `document(id:)` accepts is the trailing token (the slugId), which is
+ *  the substring after the final `-`. Falls back to the whole segment when there is no `-`. */
+export function documentSlugFromUrl(url: string): string | null {
+  const m = /\/document\/([^/?#]+)/.exec(url);
+  if (!m?.[1]) return null;
+  // The URL is attacker-influenceable (anyone who can attach a link to the issue). A malformed
+  // percent-escape makes decodeURIComponent throw; swallow it and skip this link rather than let it
+  // abort the whole fetch (which would discard the issue's other documents too).
+  let segment: string;
+  try {
+    segment = decodeURIComponent(m[1]);
+  } catch {
+    return null;
+  }
+  const dash = segment.lastIndexOf("-");
+  return dash >= 0 && dash < segment.length - 1 ? segment.slice(dash + 1) : segment;
+}
+
+/** A filesystem- and URL-safe slug for the scratch filename: prefer Linear's slugId, else slugify the
+ *  title, else the id. Bounded length so a long title cannot produce an unwieldy path. */
+export function documentSlug(doc: RawDocument): string {
+  if (doc.slugId && doc.slugId.trim()) return doc.slugId.trim();
+  const fromTitle = (doc.title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return fromTitle || doc.id;
+}
+
+/** Normalise a RawDocument into the contract shape, dropping ones with no usable content. */
+function toAttached(doc: RawDocument): AttachedDocument | null {
+  const content = doc.content ?? "";
+  if (!content.trim()) return null;
+  return {
+    id: doc.id,
+    slug: documentSlug(doc),
+    title: (doc.title ?? "").trim() || "Untitled document",
+    url: doc.url ?? "",
+    content,
+  };
+}
+
+/**
+ * Collect the issue's attached documents from a source, de-duped by id (issue documents first, then
+ * attachment-linked documents). Pure of any network: the source does the I/O. Best-effort - an
+ * attachment whose document does not resolve is skipped, never fatal.
+ */
+export async function collectAttachedDocuments(
+  source: DocumentSource,
+  issueId: string,
+): Promise<AttachedDocument[]> {
+  const out: AttachedDocument[] = [];
+  const seen = new Set<string>();
+  const add = (doc: RawDocument | null): void => {
+    if (!doc || seen.has(doc.id)) return;
+    const attached = toAttached(doc);
+    if (!attached) return;
+    seen.add(doc.id);
+    out.push(attached);
+  };
+
+  for (const doc of await source.issueDocuments(issueId)) add(doc);
+
+  const urls = await source.issueAttachmentUrls(issueId);
+  const slugs = [...new Set(urls.map(documentSlugFromUrl).filter((s): s is string => s !== null))];
+  for (const slug of slugs) {
+    try {
+      add(await source.documentBySlug(slug));
+    } catch {
+      // best-effort: a deleted/unauthorised document link is skipped, not fatal.
+    }
+  }
+  return out;
+}
+
+/** The live `DocumentSource`, backed by a Linear bearer token. Uses the typed SDK. */
+export function linearDocumentSource(token: string): DocumentSource {
+  const client = new LinearClient({ accessToken: token });
+  return {
+    async issueDocuments(issueId) {
+      // Bounded, unpaginated cap: an issue with more than 50 attached documents (or 100 attachments
+      // below) silently drops the overflow. That is a deliberate limit, not a bug; revisit with cursor
+      // pagination if real issues approach it.
+      const issue = await client.issue(issueId);
+      const conn = await issue.documents({ first: 50 });
+      return conn.nodes.map((d) => ({
+        id: d.id,
+        slugId: d.slugId,
+        title: d.title,
+        url: d.url,
+        content: d.content ?? undefined,
+      }));
+    },
+    async issueAttachmentUrls(issueId) {
+      const issue = await client.issue(issueId);
+      const conn = await issue.attachments({ first: 100 });
+      return conn.nodes.map((a) => a.url).filter((u) => u.length > 0);
+    },
+    async documentBySlug(slug) {
+      const doc = await client.document(slug);
+      return {
+        id: doc.id,
+        slugId: doc.slugId,
+        title: doc.title,
+        url: doc.url,
+        content: doc.content ?? undefined,
+      };
+    },
+  };
+}
+
+/**
+ * Fetch the documents attached to a Linear issue as contract `AttachedDocument`s, ready to snapshot
+ * into a run. The single entry point the hub calls; resolves the source from the token and runs the
+ * pure assembly. Never throws on a single bad document link (best-effort), but a hard failure (auth,
+ * network) propagates so the caller can log and proceed with none.
+ */
+export async function fetchAttachedDocuments(
+  token: string,
+  issueId: string,
+): Promise<AttachedDocument[]> {
+  return collectAttachedDocuments(linearDocumentSource(token), issueId);
+}