beflow 0.1.0

package/src/trackers/linear/client.ts

@@ -0,0 +1,264 @@
+import type { LinearClient } from "@linear/sdk";
+
+import type { RawBlocker, RawComment, RawIssue, RawLabel, RawWorkflowState } from "./types.ts";
+
+export interface ListIssuesQuery {
+    stateName?: string;
+    stateType?: string;
+}
+
+export interface CreateIssueInput {
+    title: string;
+    description: string;
+    priority?: number;
+    labelIds?: string[];
+    stateId?: string;
+    assigneeId?: string;
+}
+
+// The narrow async surface the adapter depends on. The SDK lives ONLY behind
+// LinearSdkGateway; the adapter + mappers depend on this interface so tests
+// Can supply a fake without touching @linear/sdk or the network.
+export interface LinearGateway {
+    getIssueByIdentifier(identifier: string): Promise<RawIssue>;
+    getBlockers(issueId: string): Promise<RawBlocker[]>;
+    createIssue(teamKey: string, input: CreateIssueInput): Promise<RawIssue>;
+    listIssues(teamKey: string, query?: ListIssuesQuery): Promise<RawIssue[]>;
+    listTriage(teamKey: string): Promise<RawIssue[]>;
+    updateIssueState(issueId: string, stateId: string): Promise<void>;
+    updateIssueAssignee(issueId: string, assigneeId: string): Promise<void>;
+    updateIssueLabels(issueId: string, labelIds: string[]): Promise<void>;
+    createComment(issueId: string, body: string): Promise<void>;
+    listComments(issueId: string): Promise<RawComment[]>;
+    createAttachment(issueId: string, url: string, title: string): Promise<void>;
+    listStates(teamKey: string): Promise<RawWorkflowState[]>;
+    listLabels(teamKey: string): Promise<RawLabel[]>;
+    createState(teamKey: string, state: { name: string; type: StateGroupLike; color: string }): Promise<void>;
+    createLabel(teamKey: string, label: { name: string; color?: string }): Promise<void>;
+    createTeam(input: { key: string; name: string }): Promise<{ id: string }>;
+    deleteLabel(labelId: string): Promise<void>;
+}
+
+// beflow's spelling for the cancelled state group. The Linear SDK uses the American
+// spelling "canceled" (one L); fromLinearStateType / toLinearStateType normalize at
+// the gateway boundary so all other code always sees "cancelled".
+export type StateGroupLike = "backlog" | "unstarted" | "started" | "completed" | "cancelled" | "triage";
+
+export function fromLinearStateType(type: string): string {
+    return type === "canceled" ? "cancelled" : type;
+}
+
+export function toLinearStateType(type: string): string {
+    return type === "cancelled" ? "canceled" : type;
+}
+
+// The SDK Issue type as returned by client.issue() / client.issues().nodes.
+// resolveIssue depends only on the structural subset declared below; deriving
+// the type from the SDK avoids an unsafe narrowing cast.
+type SdkIssueSource = Awaited<ReturnType<LinearClient["issue"]>>;
+
+const DEFAULT_STATE_COLOR = "#95a2b3";
+const DEFAULT_LABEL_COLOR = "#bec2c8";
+
+export class LinearSdkGateway implements LinearGateway {
+    private readonly client: LinearClient;
+    private readonly teamIdByKey = new Map<string, string>();
+
+    public constructor(client: LinearClient) {
+        this.client = client;
+    }
+
+    private async resolveIssue(issue: SdkIssueSource): Promise<RawIssue> {
+        const [state, labelConn, team] = await Promise.all([issue.state, issue.labels(), issue.team]);
+        if (state === undefined) {
+            throw new Error(`linear: issue ${issue.identifier} has no state`);
+        }
+        if (team === undefined) {
+            throw new Error(`linear: issue ${issue.identifier} has no team`);
+        }
+        return {
+            archivedAt: issue.archivedAt?.toISOString() ?? null,
+            description: issue.description ?? undefined,
+            id: issue.id,
+            identifier: issue.identifier,
+            labels: labelConn.nodes.map((l) => ({ id: l.id, name: l.name })),
+            priority: issue.priority,
+            state: { id: state.id, name: state.name, type: fromLinearStateType(state.type) },
+            team: { id: team.id, key: team.key },
+            title: issue.title,
+        };
+    }
+
+    private async teamId(teamKey: string): Promise<string> {
+        const cached = this.teamIdByKey.get(teamKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const conn = await this.client.teams({
+            filter: { key: { eq: teamKey } },
+        });
+        const team = conn.nodes[0];
+        if (team === undefined) {
+            throw new Error(`linear: unknown team key "${teamKey}"`);
+        }
+        this.teamIdByKey.set(teamKey, team.id);
+        return team.id;
+    }
+
+    public async getIssueByIdentifier(identifier: string): Promise<RawIssue> {
+        const issue = await this.client.issue(identifier);
+        return this.resolveIssue(issue);
+    }
+
+    // The issues that BLOCK this one. An inverseRelation of type "blocks" has its
+    // SOURCE issue (node.issue) as the blocker; node.relatedIssue is this issue.
+    public async getBlockers(issueId: string): Promise<RawBlocker[]> {
+        const issue = await this.client.issue(issueId);
+        const inv = await issue.inverseRelations();
+        const blockers: RawBlocker[] = [];
+        for (const node of inv.nodes) {
+            if (node.type !== "blocks") {
+                continue;
+            }
+            const src = await node.issue;
+            if (src === undefined) {
+                continue;
+            }
+            const st = await src.state;
+            blockers.push({ identifier: src.identifier, stateType: fromLinearStateType(st?.type ?? "") });
+        }
+        return blockers;
+    }
+
+    public async createIssue(teamKey: string, input: CreateIssueInput): Promise<RawIssue> {
+        const payload = await this.client.createIssue({
+            assigneeId: input.assigneeId,
+            description: input.description,
+            labelIds: input.labelIds,
+            priority: input.priority,
+            stateId: input.stateId,
+            teamId: await this.teamId(teamKey),
+            title: input.title,
+        });
+        const issue = await payload.issue;
+        if (issue === undefined) {
+            throw new Error(`linear: createIssue for team ${teamKey} returned no issue`);
+        }
+        return this.resolveIssue(issue);
+    }
+
+    public async listIssues(teamKey: string, query: ListIssuesQuery = {}): Promise<RawIssue[]> {
+        const filter: Record<string, unknown> = { team: { key: { eq: teamKey } } };
+        if (query.stateName !== undefined) {
+            filter.state = { name: { eq: query.stateName } };
+        } else if (query.stateType !== undefined) {
+            filter.state = { type: { eq: toLinearStateType(query.stateType) } };
+        }
+        return this.fetchIssues(filter);
+    }
+
+    public async listTriage(teamKey: string): Promise<RawIssue[]> {
+        return this.fetchIssues({
+            state: { type: { eq: "triage" } },
+            team: { key: { eq: teamKey } },
+        });
+    }
+
+    private async fetchIssues(filter: Record<string, unknown>): Promise<RawIssue[]> {
+        const results: RawIssue[] = [];
+        let connection = await this.client.issues({ filter, first: 100 });
+        for (;;) {
+            for (const node of connection.nodes) {
+                results.push(await this.resolveIssue(node));
+            }
+            if (!connection.pageInfo.hasNextPage) {
+                break;
+            }
+            connection = await connection.fetchNext();
+        }
+        return results;
+    }
+
+    public async updateIssueState(issueId: string, stateId: string): Promise<void> {
+        await this.client.updateIssue(issueId, { stateId });
+    }
+
+    public async updateIssueAssignee(issueId: string, assigneeId: string): Promise<void> {
+        await this.client.updateIssue(issueId, { assigneeId });
+    }
+
+    public async updateIssueLabels(issueId: string, labelIds: string[]): Promise<void> {
+        await this.client.updateIssue(issueId, { labelIds });
+    }
+
+    public async createComment(issueId: string, body: string): Promise<void> {
+        await this.client.createComment({ body, issueId });
+    }
+
+    public async listComments(issueId: string): Promise<RawComment[]> {
+        const issue = await this.client.issue(issueId);
+        const conn = await issue.comments();
+        const comments: RawComment[] = [];
+        for (const node of conn.nodes) {
+            const user = await node.user;
+            comments.push({
+                ...(user?.id !== undefined ? { authorId: user.id } : {}),
+                body: node.body,
+                createdAt: node.createdAt.toISOString(),
+                id: node.id,
+            });
+        }
+        return comments;
+    }
+
+    public async createAttachment(issueId: string, url: string, title: string): Promise<void> {
+        await this.client.createAttachment({ issueId, title, url });
+    }
+
+    public async listStates(teamKey: string): Promise<RawWorkflowState[]> {
+        const team = await this.client.team(await this.teamId(teamKey));
+        const conn = await team.states();
+        return conn.nodes.map((s) => ({ id: s.id, name: s.name, type: fromLinearStateType(s.type) }));
+    }
+
+    public async listLabels(teamKey: string): Promise<RawLabel[]> {
+        const team = await this.client.team(await this.teamId(teamKey));
+        const conn = await team.labels();
+        return conn.nodes.map((l) => ({ id: l.id, name: l.name }));
+    }
+
+    public async createState(
+        teamKey: string,
+        state: { name: string; type: StateGroupLike; color: string },
+    ): Promise<void> {
+        await this.client.createWorkflowState({
+            color: state.color,
+            name: state.name,
+            teamId: await this.teamId(teamKey),
+            type: toLinearStateType(state.type),
+        });
+    }
+
+    public async createLabel(teamKey: string, label: { name: string; color?: string }): Promise<void> {
+        await this.client.createIssueLabel({
+            color: label.color ?? DEFAULT_LABEL_COLOR,
+            name: label.name,
+            teamId: await this.teamId(teamKey),
+        });
+    }
+
+    public async deleteLabel(labelId: string): Promise<void> {
+        await this.client.deleteIssueLabel(labelId);
+    }
+
+    public async createTeam(input: { key: string; name: string }): Promise<{ id: string }> {
+        const payload = await this.client.createTeam({ key: input.key, name: input.name });
+        const team = await payload.team;
+        if (team === undefined) {
+            throw new Error(`linear: createTeam "${input.name}" returned no team`);
+        }
+        return { id: team.id };
+    }
+}
+
+export { DEFAULT_STATE_COLOR, DEFAULT_LABEL_COLOR };

package/src/trackers/linear/map.ts

@@ -0,0 +1,113 @@
+import type { Issue, StateGroup } from "../../model/types.ts";
+import { parseIssueMeta } from "../../resolve/metadata.ts";
+import type { IntakeItem } from "../tracker.ts";
+import type { RawIssue } from "./types.ts";
+
+const PRIORITY_RANK: Record<string, number> = {
+    high: 1,
+    low: 3,
+    medium: 2,
+    none: 4,
+    urgent: 0,
+};
+
+export function priorityRank(priority?: string): number {
+    if (priority === undefined) {
+        return 4;
+    }
+    const rank = PRIORITY_RANK[priority];
+    return rank ?? 4;
+}
+
+const PRIORITY_BY_NUMBER: Record<number, string> = {
+    0: "none",
+    1: "urgent",
+    2: "high",
+    3: "medium",
+    4: "low",
+};
+
+export function mapPriority(n?: number): string | undefined {
+    if (n === undefined) {
+        return undefined;
+    }
+    return PRIORITY_BY_NUMBER[n];
+}
+
+const PRIORITY_BY_NAME: Record<string, number> = {
+    high: 2,
+    low: 4,
+    medium: 3,
+    none: 0,
+    urgent: 1,
+};
+
+export function priorityToInt(priority?: string): number | undefined {
+    if (priority === undefined) {
+        return undefined;
+    }
+    const value = PRIORITY_BY_NAME[priority];
+    if (value === undefined) {
+        throw new Error(`linear: unknown priority "${priority}" (expected one of urgent|high|medium|low|none)`);
+    }
+    return value;
+}
+
+const VALID_STATE_GROUPS: ReadonlySet<StateGroup> = new Set<StateGroup>([
+    "backlog",
+    "unstarted",
+    "started",
+    "completed",
+    "cancelled",
+]);
+
+function isStateGroup(type: string): type is StateGroup {
+    return (VALID_STATE_GROUPS as ReadonlySet<string>).has(type);
+}
+
+export function mapStateType(type: string): StateGroup {
+    if (type === "triage") {
+        throw new Error(
+            "linear: triage states are not queue states (triage issues arrive via listInbox, never as queue issues)",
+        );
+    }
+    if (!isStateGroup(type)) {
+        throw new Error(
+            `linear: unsupported state type "${type}" (expected one of backlog|unstarted|started|completed|cancelled)`,
+        );
+    }
+    return type;
+}
+
+export function mapIssue(raw: RawIssue): Issue {
+    const labels = raw.labels.map((l) => l.name);
+    const body = raw.description ?? "";
+    return {
+        archived: raw.archivedAt !== null && raw.archivedAt !== undefined,
+        id: raw.id,
+        key: raw.identifier,
+        title: raw.title,
+        body,
+        // Linear has no native work-item type in this mapping; left undefined.
+        type: undefined,
+        state: { group: mapStateType(raw.state.type), name: raw.state.name },
+        labels,
+        // Linear has no modules; areas === labels so module_repo_map keyed by an
+        // Area name still resolves a repo (DESIGN §3).
+        areas: labels,
+        priority: mapPriority(raw.priority),
+        meta: parseIssueMeta(body, labels),
+    };
+}
+
+export function mapIntakeItem(raw: RawIssue): IntakeItem {
+    return {
+        id: raw.id,
+        // Linear has no numeric intake status; 0 stands for "in triage / pending".
+        status: 0,
+        title: raw.title,
+        body: raw.description ?? "",
+        issueId: raw.id,
+        priority: mapPriority(raw.priority),
+    };
+}

package/src/trackers/linear/types.ts

@@ -0,0 +1,44 @@
+// Plain, already-resolved shapes the Linear gateway returns to the adapter +
+// Pure mappers. The SDK exposes state/labels/team as Promises; the gateway
+// Awaits them and hands back these flat objects so map.ts stays sync + pure.
+
+export interface RawWorkflowState {
+    id: string;
+    name: string;
+    type: string; // Backlog|unstarted|started|completed|cancelled|triage
+}
+
+export interface RawLabel {
+    id: string;
+    name: string;
+}
+
+export interface RawTeam {
+    id: string;
+    key: string;
+}
+
+export interface RawComment {
+    authorId?: string;
+    body: string;
+    createdAt: string; // ISO
+    id: string;
+}
+
+export interface RawBlocker {
+    identifier: string;
+    stateType: string; // workflow state type: completed/cancelled ⇒ done
+}
+
+// A Linear issue with its async sub-fields already resolved by the gateway.
+export interface RawIssue {
+    id: string;
+    identifier: string; // Human key, e.g. "ENG-42"
+    title: string;
+    description?: string; // Markdown, may be undefined
+    priority?: number; // 0 none, 1 urgent, 2 high, 3 medium, 4 low
+    state: RawWorkflowState;
+    labels: RawLabel[];
+    team: RawTeam;
+    archivedAt?: string | null; // ISO timestamp when archived; null/absent means active
+}

package/src/trackers/marker.ts

@@ -0,0 +1,20 @@
+export const BEFLOW_MARKER = "\n\n— beflow";
+
+export function withMarker(body: string): string {
+    if (hasMarker(body)) {
+        return body;
+    }
+    return body + BEFLOW_MARKER;
+}
+
+export function hasMarker(text: string): boolean {
+    return text.includes("— beflow");
+}
+
+export function stripMarker(text: string): string {
+    const idx = text.lastIndexOf("\n\n— beflow");
+    if (idx === -1) {
+        return text.trimEnd();
+    }
+    return text.slice(0, idx).trimEnd();
+}