@dahrk/linear 0.1.1 → 0.3.0

package/src/index.ts

@@ -83,6 +83,43 @@ function directiveFromPromptContext(promptContext: string): { commentId?: string
   };
 }
 
+/**
+ * Compute the NAMES of the labels newly added by an `Issue`/`update` webhook (DHK-93). Positive
+ * evidence only: `updatedFrom` must carry a `labelIds` array (the pre-change set) - a title/description
+ * edit that never touched labels carries none, so it yields []. The new set is read from `data.labelIds`
+ * (falling back to the ids on `data.labels`), the added ids are the new-set minus the old-set, and each
+ * added id is resolved to a name via `data.labels` (`[{id,name}]`). An added id with no resolvable name
+ * is dropped, so a payload we cannot name from produces no false trigger. Pure; no LLM.
+ */
+function addedLabelNames(
+  data: Record<string, unknown> | undefined,
+  updatedFrom: Record<string, unknown> | null | undefined,
+): string[] {
+  if (!data || !updatedFrom) return [];
+  const oldIds = updatedFrom.labelIds;
+  if (!Array.isArray(oldIds)) return []; // labels were not part of this change
+  const oldSet = new Set(oldIds.filter((v): v is string => typeof v === "string"));
+  const labels = Array.isArray(data.labels)
+    ? (data.labels as unknown[]).filter(
+        (l): l is { id?: string; name?: string } => !!l && typeof l === "object",
+      )
+    : [];
+  const nameById = new Map<string, string>();
+  for (const l of labels) {
+    if (typeof l.id === "string" && typeof l.name === "string") nameById.set(l.id, l.name);
+  }
+  const newIds = Array.isArray(data.labelIds)
+    ? (data.labelIds as unknown[]).filter((v): v is string => typeof v === "string")
+    : labels.map((l) => l.id).filter((v): v is string => typeof v === "string");
+  const names: string[] = [];
+  for (const id of newIds) {
+    if (oldSet.has(id)) continue; // pre-existing, not part of the delta
+    const name = nameById.get(id);
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}
+
 /** Fixed 👍/👎 -> sentiment lookup. A reaction's sentiment comes from this table, never an LLM, so the
  *  determinism boundary holds. Returns undefined for any emoji we do not treat as feedback. */
 function reactionSentiment(emoji: string | undefined): "positive" | "negative" | undefined {
@@ -194,13 +231,17 @@ export function normalise(payload: LinearWebhookPayload, connectionId: string, t
     if (action === "issueUnassignedFromYou") {
       return { ...base, type: "issue-unassigned", subject: { issueId } };
     }
-    // Inbox notification: the issue's status changed. Only a move to a *canceled* workflow-state type is
-    // a disengagement signal (stop its run); any other status change falls through to ignored.
+    // Inbox notification: the issue's status changed. A move to a *canceled* or *completed* workflow-state
+    // type is a disengagement signal (stop its run); any other status change falls through to ignored.
+    // (A completed move only settles a run parked at a gate; that gate-open rule lives on the hub side.)
     if (action === "issueStatusChanged") {
       const stateType = n.issue?.state?.type ?? n.issueStatusType;
       if (stateType === "canceled") {
         return { ...base, type: "issue-canceled", subject: { issueId } };
       }
+      if (stateType === "completed") {
+        return { ...base, type: "issue-completed", subject: { issueId } };
+      }
     }
     // Inbox notification: a 👍/👎 reaction on a Dahrk response -> a feedback signal. A non-thumb emoji
     // falls through to ignored (never mis-dispatched).
@@ -261,7 +302,7 @@ export function normalise(payload: LinearWebhookPayload, connectionId: string, t
   if (payload.type === "Issue") {
     const p = payload as EntityWebhookPayloadWithIssueData & {
       issue?: { id?: string } | null;
-      data?: { state?: { type?: string } | null } | null;
+      data?: (Record<string, unknown> & { state?: { type?: string } | null }) | null;
       updatedFrom?: Record<string, unknown> | null;
     };
     // Live "Issue" entity webhooks carry the issue under `data`; tolerate a top-level `issue` too.
@@ -279,6 +320,13 @@ export function normalise(payload: LinearWebhookPayload, connectionId: string, t
     if (p.data?.state?.type === "triage" && p.updatedFrom && "stateId" in p.updatedFrom) {
       return { ...base, type: "triage-entry", subject: { issueId } };
     }
+    // Label add (DHK-93): a workflow-trigger label was applied. Emit a distinct `label-added` only on
+    // positive evidence - `updatedFrom` carries `labelIds` and at least one added label name resolves -
+    // so a pure removal, or any edit that never touched labels, still falls through to `issue-created`.
+    const addedLabels = addedLabelNames(p.data ?? undefined, p.updatedFrom);
+    if (addedLabels.length > 0) {
+      return { ...base, type: "label-added", subject: { issueId }, addedLabels };
+    }
     return { ...base, type: "issue-created", subject: { issueId } };
   }
 
@@ -312,7 +360,7 @@ export type StartIssueSkip =
  *  silently sitting In Progress. `moved` is true only when the issue was actually transitioned into a
  *  review state; otherwise `reason` says why not - benign (`already-there`, e.g. a closed issue or one
  *  already in the review state) vs a real gap (`no-review-state`: this team has no state named
- *  review/in review/qa and `SKAKEL_REVIEW_STATE_NAME` is unset/unmatched). */
+ *  review/in review/qa and `DAHRK_REVIEW_STATE_NAME` is unset/unmatched). */
 export type MoveToReviewOutcome =
   | { moved: true; stateName: string }
   | { moved: false; reason: MoveToReviewSkip };
@@ -470,7 +518,7 @@ export interface AgentSessionClient {
    *  instead of it vanishing (see `StartIssueOutcome`). */
   startIssue(sessionId: string): Promise<StartIssueOutcome>;
   /** Move the session's issue to a review-named state on run completion (configurable via
-   *  `SKAKEL_REVIEW_STATE_NAME`). Leaves it unchanged when no such state exists - never
+   *  `DAHRK_REVIEW_STATE_NAME`). Leaves it unchanged when no such state exists - never
    *  auto-completes, so a human keeps iterating and can re-summon @Dahrk on the same PR. Returns an
    *  outcome so a caller can surface a no-op (no matching state) rather than have the ticket silently
    *  stay In Progress (see `MoveToReviewOutcome`). */
@@ -518,7 +566,7 @@ export type {
 } from "./responding-client.js";
 export { createLinearClient } from "./linear-client.js";
 export { formatToolAction, formatToolResult, type ToolAction } from "./format-action.js";
-export { authorizeUrl, exchangeCode, refreshTokens, mintAppToken, fetchOrganizationId, probeToken, DEFAULT_AGENT_SCOPES } from "./oauth.js";
+export { authorizeUrl, exchangeCode, refreshTokens, revokeToken, mintAppToken, fetchOrganizationId, probeToken, DEFAULT_AGENT_SCOPES } from "./oauth.js";
 export type { LinearTokens, LinearProbe } from "./oauth.js";
 export {
   provisionLabels,
@@ -535,8 +583,8 @@ export {
 export type { LabelApi, ProvisionOptions, OpenBlocker } from "./labels.js";
 export { linearTeamsApi, listWorkspaceTeams } from "./teams.js";
 export type { Team, TeamsApi } from "./teams.js";
-export { linearTriageApi, linearClientAuth } from "./issues.js";
-export type { TriageApi } from "./issues.js";
+export { linearTriageApi, linearClientAuth, linearCaptureApi } from "./issues.js";
+export type { TriageApi, CaptureLinearApi, CaptureIssueResult } from "./issues.js";
 export {
   fetchAttachedDocuments,
   collectAttachedDocuments,
@@ -554,3 +602,18 @@ export {
   MAX_RELATED_ISSUES,
 } from "./issue-graph.js";
 export type { IssueGraphSource, RawEdge, RawRelatedIssue } from "./issue-graph.js";
+export { fetchIssueProjection } from "./issue-read.js";
+export type { IssueReadProjection } from "./issue-read.js";
+export {
+  fetchParentBatchSource,
+  collectParentBatchSource,
+  linearParentBatchSource,
+  MAX_BATCH_CHILDREN,
+} from "./batch-source.js";
+export type {
+  ParentBatchSource,
+  ParentBatchSnapshot,
+  RawChild,
+  RawBlocker,
+  ExternalBlocker,
+} from "./batch-source.js";

package/src/issue-read.ts

@@ -0,0 +1,52 @@
+/**
+ * Read one Linear issue as a bounded projection (DHK-1178), for the hub-owned workspace MCP server's
+ * `get_issue` tool. The hub performs the call with the tenant's own connection token; this module keeps
+ * the Linear SDK usage inside `@dahrk/linear` (as `documents.ts`/`issue-graph.ts` do) so the hub and the
+ * workspace-mcp package stay SDK-free.
+ *
+ * Deliberately a bounded projection, NOT the raw SDK object: only the fields a stage needs to reason
+ * about an issue, so nothing unexpected rides back to the agent.
+ */
+import { LinearClient } from "@linear/sdk";
+
+/** The fields `get_issue` returns. A subset of Linear's Issue, resolved from the id/identifier. */
+export interface IssueReadProjection {
+  id: string;
+  identifier?: string;
+  title?: string;
+  description?: string;
+  /** The workflow state's display name (e.g. "In Progress"). */
+  state?: string;
+  /** The assignee's display name, when one is set. */
+  assignee?: string;
+  /** The issue's label names. */
+  labels?: string[];
+  url?: string;
+}
+
+/**
+ * Fetch a single issue by its id (uuid) or human identifier (e.g. `DHK-1178`) and project it to
+ * {@link IssueReadProjection}. Returns null when Linear resolves no such issue. A hard failure (auth,
+ * network) propagates so the caller can surface it as a tool error.
+ */
+export async function fetchIssueProjection(token: string, id: string): Promise<IssueReadProjection | null> {
+  const client = new LinearClient({ accessToken: token });
+  const issue = await client.issue(id).catch(() => null);
+  if (!issue) return null;
+  // The nested reads (state, assignee, labels) are independent promises; run them together.
+  const [state, assignee, labels] = await Promise.all([
+    issue.state,
+    issue.assignee,
+    issue.labels({ first: 50 }),
+  ]);
+  return {
+    id: issue.id,
+    ...(issue.identifier ? { identifier: issue.identifier } : {}),
+    ...(issue.title ? { title: issue.title } : {}),
+    ...(issue.description ? { description: issue.description } : {}),
+    ...(state?.name ? { state: state.name } : {}),
+    ...(assignee?.displayName ? { assignee: assignee.displayName } : {}),
+    ...(labels.nodes.length > 0 ? { labels: labels.nodes.map((l) => l.name) } : {}),
+    ...(issue.url ? { url: issue.url } : {}),
+  };
+}

package/src/issues.ts

@@ -91,3 +91,52 @@ export function linearTriageApi(token: string): TriageApi {
     },
   };
 }
+
+/** 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

@@ -115,7 +115,7 @@ export async function provisionRepoLabels(
 /**
  * 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. `["skakel-site"]` - so the hub can bind every issue in that project to
+ * 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.

package/src/linear-client.ts

@@ -79,11 +79,10 @@ export interface StateLike {
   type: string;
 }
 
-/** The configured review-state name. `DAHRK_` is the name; the legacy `SKAKEL_` prefix is still
- *  honoured so a host provisioned before the rename keeps working (DHK-440). This package has no
- *  dependency on the hub, so it cannot reuse the hub's `envRenamed`. */
+/** The configured review-state name. This package has no dependency on the hub, so it cannot reuse the
+ *  hub's `envValue`. The pre-rename legacy twin was dropped: no current host sets it. */
 function reviewStateNameEnv(): string | undefined {
-  return process.env.DAHRK_REVIEW_STATE_NAME ?? process.env.SKAKEL_REVIEW_STATE_NAME;
+  return process.env.DAHRK_REVIEW_STATE_NAME;
 }
 
 /** Find the review-target state the way `moveIssueToReview` does, so `startIssue` can EXCLUDE it.

package/src/oauth.ts

@@ -11,13 +11,17 @@ 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;
-  /** Absent on some refresh responses; callers keep the prior refresh token when so. */
+  /** 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;
@@ -155,7 +159,20 @@ export async function probeToken(accessToken: string): Promise<LinearProbe> {
   return probe;
 }
 
-/** Rotate the access token using the stored refresh token (the hub calls this near expiry / on 401). */
+/**
+ * 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(),
@@ -168,7 +185,51 @@ export function refreshTokens(
       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}`);
 }
 
 /**