beflow 0.1.0

package/src/trackers/plane/client.ts

@@ -0,0 +1,302 @@
+import type {
+    Paginated,
+    RawAttachment,
+    RawComment,
+    RawCycle,
+    RawCycleWorkItem,
+    RawIntakeIssue,
+    RawLabel,
+    RawLink,
+    RawModule,
+    RawProject,
+    RawState,
+    RawWorkItem,
+    RawWorkItemRelations,
+    RawWorkItemType,
+} from "./types.ts";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export class PlaneHttpError extends Error {
+    public constructor(
+        public readonly status: number,
+        message: string,
+    ) {
+        super(message);
+        this.name = "PlaneHttpError";
+    }
+}
+
+export interface PlaneClientOptions {
+    baseUrl?: string;
+    workspaceSlug: string;
+    apiKey: string;
+    fetch?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+}
+
+interface ListWorkItemsOptions {
+    expand?: string;
+    order_by?: string;
+}
+
+const MAX_RETRIES = 2;
+const DEFAULT_BASE_URL = "https://api.plane.so";
+
+async function realSleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+
+// Deserialization trust boundary: the caller declares the response shape T.
+function hasShape<T>(_value: unknown): _value is T {
+    return true;
+}
+
+function decodeBody<T>(value: unknown): T {
+    if (!hasShape<T>(value)) {
+        throw new Error("plane: response body did not match expected shape");
+    }
+    return value;
+}
+
+export class PlaneClient {
+    private readonly baseUrl: string;
+    private readonly slug: string;
+    private readonly apiKey: string;
+    private readonly fetch: FetchLike;
+    private readonly sleep: (ms: number) => Promise<void>;
+
+    public constructor(options: PlaneClientOptions) {
+        this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+        this.slug = options.workspaceSlug;
+        this.apiKey = options.apiKey;
+        this.fetch = options.fetch ?? (globalThis.fetch as FetchLike);
+        this.sleep = options.sleep ?? realSleep;
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "X-API-Key": this.apiKey,
+        };
+    }
+
+    private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+        const url = `${this.baseUrl}${path}`;
+        const init: RequestInit = { headers: this.headers(), method };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+
+        let attempt = 0;
+        for (;;) {
+            const response = await this.fetch(url, init);
+
+            if (response.status === 429 && attempt < MAX_RETRIES) {
+                const retryAfter = Number(response.headers.get("Retry-After") ?? "1");
+                const seconds = Number.isFinite(retryAfter) ? retryAfter : 1;
+                await this.sleep(seconds * 1000);
+                attempt += 1;
+                continue;
+            }
+
+            if (!response.ok) {
+                const snippet = (await response.text()).slice(0, 500);
+                throw new PlaneHttpError(
+                    response.status,
+                    `plane: ${method} ${path} failed with ${String(response.status)}: ${snippet}`,
+                );
+            }
+
+            if (response.status === 204) {
+                return decodeBody<T>(undefined);
+            }
+            const text = await response.text();
+            if (text === "") {
+                return decodeBody<T>(undefined);
+            }
+            const parsed: unknown = JSON.parse(text);
+            return decodeBody<T>(parsed);
+        }
+    }
+
+    private projectBase(projectId: string): string {
+        return `/api/v1/workspaces/${this.slug}/projects/${projectId}`;
+    }
+
+    private async paginate<T>(basePath: string): Promise<T[]> {
+        const results: T[] = [];
+        let cursor: string | undefined;
+        for (;;) {
+            const sep = basePath.includes("?") ? "&" : "?";
+            const path =
+                cursor === undefined
+                    ? `${basePath}${sep}per_page=100`
+                    : `${basePath}${sep}per_page=100&cursor=${encodeURIComponent(cursor)}`;
+            const page = await this.request<Paginated<T>>("GET", path);
+            results.push(...page.results);
+            if (!page.next_page_results) {
+                break;
+            }
+            cursor = page.next_cursor;
+        }
+        return results;
+    }
+
+    public async createProject(body: { identifier: string; name: string }): Promise<RawProject> {
+        return this.request<RawProject>("POST", `/api/v1/workspaces/${this.slug}/projects/`, body);
+    }
+
+    public async getWorkItemByIdentifier(key: string): Promise<RawWorkItem> {
+        const path = `/api/v1/workspaces/${this.slug}/work-items/${key}/?expand=state,labels`;
+        return this.request<RawWorkItem>("GET", path);
+    }
+
+    public async listWorkItems(projectId: string, options: ListWorkItemsOptions = {}): Promise<RawWorkItem[]> {
+        const expand = options.expand ?? "state,labels";
+        const params = new URLSearchParams({ expand });
+        if (options.order_by !== undefined && options.order_by !== "") {
+            params.set("order_by", options.order_by);
+        }
+        const path = `${this.projectBase(projectId)}/work-items/?${params.toString()}`;
+        return this.paginate<RawWorkItem>(path);
+    }
+
+    public async getWorkItem(projectId: string, id: string): Promise<RawWorkItem> {
+        const path = `${this.projectBase(projectId)}/work-items/${id}/?expand=state,labels`;
+        return this.request<RawWorkItem>("GET", path);
+    }
+
+    public async createWorkItem(projectId: string, body: unknown): Promise<RawWorkItem> {
+        return this.request<RawWorkItem>("POST", `${this.projectBase(projectId)}/work-items/`, body);
+    }
+
+    public async patchWorkItem(projectId: string, id: string, body: unknown): Promise<RawWorkItem> {
+        return this.request<RawWorkItem>("PATCH", `${this.projectBase(projectId)}/work-items/${id}/`, body);
+    }
+
+    // Relations are returned as a single grouped object (blocking, blocked_by, …),
+    // each group a bare array of work-item UUIDs — NOT the paginated {results}
+    // Envelope, so this must not paginate.
+    public async listRelations(projectId: string, id: string): Promise<RawWorkItemRelations> {
+        return this.request<RawWorkItemRelations>("GET", `${this.projectBase(projectId)}/work-items/${id}/relations/`);
+    }
+
+    public async createComment(projectId: string, id: string, body: { comment_html: string }): Promise<RawComment> {
+        return this.request<RawComment>("POST", `${this.projectBase(projectId)}/work-items/${id}/comments/`, body);
+    }
+
+    public async listComments(projectId: string, id: string): Promise<RawComment[]> {
+        return this.paginate<RawComment>(`${this.projectBase(projectId)}/work-items/${id}/comments/`);
+    }
+
+    public async createLink(projectId: string, id: string, body: { url: string; title?: string }): Promise<RawLink> {
+        return this.request<RawLink>("POST", `${this.projectBase(projectId)}/work-items/${id}/links/`, body);
+    }
+
+    public async listLinks(projectId: string, id: string): Promise<RawLink[]> {
+        return this.paginate<RawLink>(`${this.projectBase(projectId)}/work-items/${id}/links/`);
+    }
+
+    // UNVERIFIED endpoint shape — confirm during live dogfood. Returns the raw
+    // Response as-is (NOT paginated); the adapter catches any failure and fails closed.
+    public async listAttachments(projectId: string, id: string): Promise<RawAttachment[]> {
+        return this.request<RawAttachment[]>("GET", `${this.projectBase(projectId)}/work-items/${id}/attachments/`);
+    }
+
+    // UNVERIFIED endpoint shape — confirm during live dogfood. The adapter fails
+    // Closed on any error (→ null → unfiltered dispatch), so a wrong shape can't halt.
+    public async listCycles(projectId: string): Promise<RawCycle[]> {
+        return this.paginate<RawCycle>(`${this.projectBase(projectId)}/cycles/`);
+    }
+
+    // VERIFIED live (2026-06-18): the membership endpoint is `cycle-issues/` (not
+    // `cycle-work-items/`, which 404s); each result IS the full work item, so its `id` is
+    // the work-item uuid (RawCycleWorkItem reads `work_item ?? id`). Fails closed via the adapter.
+    public async listCycleWorkItems(projectId: string, cycleId: string): Promise<RawCycleWorkItem[]> {
+        return this.paginate<RawCycleWorkItem>(`${this.projectBase(projectId)}/cycles/${cycleId}/cycle-issues/`);
+    }
+
+    public async listStates(projectId: string): Promise<RawState[]> {
+        return this.paginate<RawState>(`${this.projectBase(projectId)}/states/`);
+    }
+
+    public async listLabels(projectId: string): Promise<RawLabel[]> {
+        return this.paginate<RawLabel>(`${this.projectBase(projectId)}/labels/`);
+    }
+
+    public async listModules(projectId: string): Promise<RawModule[]> {
+        return this.paginate<RawModule>(`${this.projectBase(projectId)}/modules/`);
+    }
+
+    public async listTypes(projectId: string): Promise<RawWorkItemType[]> {
+        // The work-item-types endpoint returns a bare array, NOT the cursor-paginated
+        // {results} envelope the other list endpoints use — so it must not paginate.
+        return this.request<RawWorkItemType[]>("GET", `${this.projectBase(projectId)}/work-item-types/`);
+    }
+
+    public async createState(projectId: string, body: unknown): Promise<RawState> {
+        return this.request<RawState>("POST", `${this.projectBase(projectId)}/states/`, body);
+    }
+
+    public async updateState(projectId: string, id: string, body: unknown): Promise<RawState> {
+        return this.request<RawState>("PATCH", `${this.projectBase(projectId)}/states/${id}/`, body);
+    }
+
+    public async createLabel(projectId: string, body: unknown): Promise<RawLabel> {
+        return this.request<RawLabel>("POST", `${this.projectBase(projectId)}/labels/`, body);
+    }
+
+    public async updateLabel(projectId: string, id: string, body: unknown): Promise<RawLabel> {
+        return this.request<RawLabel>("PATCH", `${this.projectBase(projectId)}/labels/${id}/`, body);
+    }
+
+    public async createModule(projectId: string, body: unknown): Promise<RawModule> {
+        return this.request<RawModule>("POST", `${this.projectBase(projectId)}/modules/`, body);
+    }
+
+    public async updateModule(projectId: string, id: string, body: unknown): Promise<RawModule> {
+        return this.request<RawModule>("PATCH", `${this.projectBase(projectId)}/modules/${id}/`, body);
+    }
+
+    public async deleteModule(projectId: string, id: string): Promise<void> {
+        return this.request<undefined>("DELETE", `${this.projectBase(projectId)}/modules/${id}/`);
+    }
+
+    public async deleteLabel(projectId: string, id: string): Promise<void> {
+        return this.request<undefined>("DELETE", `${this.projectBase(projectId)}/labels/${id}/`);
+    }
+
+    public async createType(projectId: string, body: unknown): Promise<RawWorkItemType> {
+        return this.request<RawWorkItemType>("POST", `${this.projectBase(projectId)}/work-item-types/`, body);
+    }
+
+    public async updateType(projectId: string, id: string, body: unknown): Promise<RawWorkItemType> {
+        return this.request<RawWorkItemType>("PATCH", `${this.projectBase(projectId)}/work-item-types/${id}/`, body);
+    }
+
+    public async updateProjectFeatures(
+        projectId: string,
+        features: { is_issue_type_enabled: boolean; intake_view: boolean; module_view: boolean },
+    ): Promise<void> {
+        return this.request<undefined>("PATCH", `${this.projectBase(projectId)}/`, features);
+    }
+
+    public async listIntake(projectId: string): Promise<RawIntakeIssue[]> {
+        return this.paginate<RawIntakeIssue>(`${this.projectBase(projectId)}/intake-issues/`);
+    }
+
+    // VERIFIED live (2026-06-18): status updates require the /status/ suffix and
+    // must use the ISSUE id (item.issueId), NOT the intake record id (item.id).
+    // Plain PATCH intake-issues/<id>/ rejects status with HTTP 400.
+    public async updateIntakeStatus(projectId: string, issueId: string, status: number): Promise<RawIntakeIssue> {
+        return this.request<RawIntakeIssue>(
+            "PATCH",
+            `${this.projectBase(projectId)}/intake-issues/${issueId}/status/`,
+            { status },
+        );
+    }
+}

package/src/trackers/plane/map.ts

@@ -0,0 +1,168 @@
+import type { Issue, StateGroup } from "../../model/types.ts";
+import { parseIssueMeta } from "../../resolve/metadata.ts";
+import type { IntakeItem } from "../tracker.ts";
+import type { RawCycle, RawIntakeIssue, RawLabel, RawModule, RawState, RawWorkItem, RawWorkItemType } 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 VALID_STATE_GROUPS: ReadonlySet<StateGroup> = new Set<StateGroup>([
+    "backlog",
+    "unstarted",
+    "started",
+    "completed",
+    "cancelled",
+]);
+
+function isStateGroup(group: string): group is StateGroup {
+    return (VALID_STATE_GROUPS as ReadonlySet<string>).has(group);
+}
+
+export function mapStateGroup(group: string): StateGroup {
+    if (!isStateGroup(group)) {
+        throw new Error(
+            `plane: unsupported state group "${group}" (expected one of backlog|unstarted|started|completed|cancelled; our board never uses triage states)`,
+        );
+    }
+    return group;
+}
+
+function escapeHtml(text: string): string {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export function toCommentHtml(text: string): string {
+    return text
+        .split(/\n{2,}/)
+        .map((paragraph) => escapeHtml(paragraph).replace(/\n/g, "<br>"))
+        .map((paragraph) => `<p>${paragraph}</p>`)
+        .join("");
+}
+
+// Returns the first cycle currently in range. `todayIso` and the cycle dates are
+// `YYYY-MM-DD` strings, for which lexicographic comparison is also chronological.
+// A cycle missing either bound can't be confirmed active and is skipped.
+export function pickActiveCycle(cycles: RawCycle[], todayIso: string): RawCycle | null {
+    for (const cycle of cycles) {
+        const { start_date, end_date } = cycle;
+        if (start_date === undefined || start_date === null || end_date === undefined || end_date === null) {
+            continue;
+        }
+        if (start_date <= todayIso && todayIso <= end_date) {
+            return cycle;
+        }
+    }
+    return null;
+}
+
+export function keyOf(identifier: string, sequenceId: number): string {
+    return `${identifier}-${String(sequenceId)}`;
+}
+
+export interface MapContext {
+    identifier: string;
+    statesById: Map<string, RawState>;
+    labelsById: Map<string, RawLabel>;
+    modulesById: Map<string, RawModule>;
+    typesById: Map<string, RawWorkItemType>;
+}
+
+function resolveState(raw: RawWorkItem, ctx: MapContext): { name: string; group: StateGroup } {
+    const { state } = raw;
+    if (state === undefined) {
+        throw new Error(`plane: work item ${raw.id} has no state`);
+    }
+    if (typeof state === "object") {
+        return { group: mapStateGroup(state.group), name: state.name };
+    }
+    const resolved = ctx.statesById.get(state);
+    if (resolved === undefined) {
+        throw new Error(`plane: cannot resolve state uuid "${state}" for work item ${raw.id}`);
+    }
+    return { group: mapStateGroup(resolved.group), name: resolved.name };
+}
+
+function resolveLabels(raw: RawWorkItem, ctx: MapContext): string[] {
+    const labels = raw.labels ?? [];
+    return labels.map((label) => {
+        if (typeof label === "object") {
+            return label.name;
+        }
+        const resolved = ctx.labelsById.get(label);
+        if (resolved === undefined) {
+            throw new Error(`plane: cannot resolve label uuid "${label}" for work item ${raw.id}`);
+        }
+        return resolved.name;
+    });
+}
+
+function resolveAreas(raw: RawWorkItem, ctx: MapContext): string[] {
+    // Plane's work-item serializer may omit module_ids; an empty/absent value
+    // Yields []. Confirmed best-effort pending live verification.
+    const moduleIds = raw.module_ids ?? [];
+    return moduleIds.map((id) => {
+        const resolved = ctx.modulesById.get(id);
+        if (resolved === undefined) {
+            throw new Error(`plane: cannot resolve module uuid "${id}" for work item ${raw.id}`);
+        }
+        return resolved.name;
+    });
+}
+
+function resolveType(raw: RawWorkItem, ctx: MapContext): string | undefined {
+    // Plane returns the type as a UUID (in `type`/`type_id`), not its name, and
+    // Expand=state,labels does not expand it — so resolve the UUID → name via the
+    // Types cache. A bare UUID would silently break mode auto-detect (Spike→triage).
+    const type = raw.type ?? raw.type_id;
+    if (type === undefined || type === null) {
+        return undefined;
+    }
+    if (typeof type === "object") {
+        return type.name;
+    }
+    return ctx.typesById.get(type)?.name;
+}
+
+export function mapWorkItem(raw: RawWorkItem, ctx: MapContext): Issue {
+    const labels = resolveLabels(raw, ctx);
+    const body = raw.description_stripped ?? "";
+    return {
+        archived: raw.archived_at !== null && raw.archived_at !== undefined,
+        areas: resolveAreas(raw, ctx),
+        body,
+        id: raw.id,
+        key: keyOf(ctx.identifier, raw.sequence_id),
+        labels,
+        meta: parseIssueMeta(body, labels),
+        ...(raw.parent !== null && raw.parent !== undefined ? { parentId: raw.parent } : {}),
+        priority: raw.priority,
+        state: resolveState(raw, ctx),
+        title: raw.name,
+        type: resolveType(raw, ctx),
+    };
+}
+
+export function mapIntakeItem(raw: RawIntakeIssue): IntakeItem {
+    const detail = raw.issue_detail;
+    return {
+        body: detail.description_stripped ?? detail.description ?? "",
+        id: raw.id,
+        issueId: raw.issue,
+        priority: detail.priority,
+        status: raw.status,
+        title: detail.name,
+    };
+}

package/src/trackers/plane/types.ts

@@ -0,0 +1,134 @@
+export interface RawProject {
+    id: string;
+}
+
+export interface Paginated<T> {
+    next_cursor: string;
+    prev_cursor: string;
+    next_page_results: boolean;
+    prev_page_results: boolean;
+    count: number;
+    total_pages: number;
+    total_results: number;
+    results: T[];
+}
+
+export interface RawState {
+    id: string;
+    name: string;
+    group: string;
+    color: string;
+    sequence?: number;
+    is_triage?: boolean;
+    default?: boolean;
+}
+
+export interface RawLabel {
+    id: string;
+    name: string;
+    color?: string;
+    description?: string;
+}
+
+export interface RawModule {
+    id: string;
+    name: string;
+    description?: string;
+    status?: string;
+}
+
+export interface RawWorkItemType {
+    id: string;
+    name: string;
+    description?: string;
+}
+
+export interface RawWorkItem {
+    id: string;
+    name: string;
+    sequence_id: number;
+    description_html?: string;
+    description_stripped?: string;
+    priority?: string;
+    // State is a uuid string, or an expanded object when ?expand=state.
+    state?: string | RawState;
+    // Labels are uuid strings, or expanded objects when ?expand=labels.
+    labels?: (string | RawLabel)[];
+    module_ids?: string[];
+    // Parent work item uuid (epic or grouping item); null/absent when top-level.
+    parent?: string | null;
+    // `null` on a project with issue-types disabled (live shape); the mapper guards it.
+    type_id?: string | null;
+    // Type may be expanded to an object carrying its name; `null` when types are disabled.
+    type?: string | { id: string; name: string } | null;
+    // Set when the work item has been archived; null/absent means active.
+    archived_at?: string | null;
+}
+
+// Plane attachment shape, reconciled against the live MCP surface (2026-06-17):
+// the list exposes a top-level `name` (older builds nest it under `attributes`);
+// the download URL is a SEPARATE call, so `asset_url` is frequently absent. Every
+// field is optional; the adapter keeps any named attachment (URL or not).
+export interface RawAttachment {
+    id: string;
+    asset_url?: string;
+    name?: string;
+    attributes?: { name?: string };
+}
+
+export interface RawIntakeIssue {
+    id: string;
+    issue: string;
+    issue_detail: {
+        id: string;
+        name: string;
+        description?: string;
+        description_stripped?: string;
+        priority?: string;
+        sequence_id?: number;
+    };
+    source?: string;
+    status: number;
+}
+
+// The work-item relations endpoint groups related work items by relation type,
+// each group being a bare array of work-item UUIDs (NOT expanded objects). We
+// only consume blocked_by; the other groups are declared for shape fidelity.
+export interface RawWorkItemRelations {
+    blocking?: string[];
+    blocked_by?: string[];
+    duplicate?: string[];
+    relates_to?: string[];
+    start_after?: string[];
+    start_before?: string[];
+    finish_after?: string[];
+    finish_before?: string[];
+}
+
+// Plane's cycles endpoints are UNVERIFIED against our live API notes, so every
+// Field is optional/tolerant and the adapter fails closed on any fetch error.
+export interface RawCycle {
+    id: string;
+    name?: string;
+    start_date?: string | null;
+    end_date?: string | null;
+}
+
+export interface RawCycleWorkItem {
+    id?: string;
+    work_item?: string;
+}
+
+export interface RawComment {
+    id: string;
+    comment_html?: string;
+    created_at?: string;
+    created_by?: string;
+    comment_stripped?: string;
+}
+
+export interface RawLink {
+    id: string;
+    url: string;
+    title?: string;
+}