@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/dist/projects.d.ts

@@ -0,0 +1,40 @@
+import { type LoadedConfig, type Project, type ProjectLaneInput } from '@aivi/core';
+import type { ProjectLinear } from './config.ts';
+/** The project's Linear routing as it takes effect: which teams speak for it
+ *  and in which workspace. Lanes are not here — they are core's ordered
+ *  workflow on the `Project` itself (`projects.<id>.lanes`), which the
+ *  orchestrator reads to decide moves and this plugin only ever performs. */
+export declare function projectLinear(loaded: LoadedConfig, projectId: string): ProjectLinear | undefined;
+/** A checkout receives one issue stream, so a Linear team may belong to
+ *  exactly one project. Said for every collision, not just the first. */
+export declare function linearTeamCollisions(loaded: LoadedConfig): string[];
+/** A project checkout and the Linear routing that claims issues for it. */
+export interface RoutedProject {
+    project: Project;
+    linear: ProjectLinear;
+}
+/** Which aivi project an issue belongs to: by the issue's Linear team, and by
+ *  workspace when one is configured. */
+export declare function projectForIssue(loaded: LoadedConfig, issue: {
+    teamId: string;
+    organizationId: string;
+}): RoutedProject | undefined;
+/**
+ * Point a project at Linear teams, and optionally (re)write its lanes: teams
+ * go to `projects.<id>.tracker-linear.teams`, lanes to the project's **core**
+ * `lanes` array — the ordered workflow, which core validates and the
+ * orchestrator decides moves from. Nothing else in the file is touched; an
+ * existing `lanes` stays as it was when none is passed. The written file must
+ * hold: the core config must still load (which validates the lane order and
+ * every `complete`/`return` reference), the section must parse against this
+ * plugin's own schema, and no team may belong to two projects — if any check
+ * fails, the previous bytes are restored and the error stands.
+ */
+export declare function writeProjectLinear(configPath: string, id: string, options: {
+    teams: string[];
+    lanes?: ProjectLaneInput[];
+}): Promise<{
+    id: string;
+    teams: string[];
+    lanes?: ProjectLaneInput[];
+}>;

package/dist/projects.js

@@ -0,0 +1,119 @@
+/** Linear's project sections: the write path the `aivi projects` wizard uses,
+ *  the routing the module consults, and the cross-project checks the plugin
+ *  owns because core reads nothing inside a contributed section. Teams are
+ *  Linear's own; the **lanes are core's** — this file writes them into the
+ *  project's core `lanes` array and reads nothing back from it. */
+import { renameSync, rmSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { loadConfig, PROJECT_ID } from '@aivi/core';
+import { linearProjectSchema } from './config.js';
+/** The module id, which is also the key of this plugin's section under every
+ *  project and under `projectDefaults`: core writes what it is keyed by, so one
+ *  word names both and a person never guesses which is which. */
+const SECTION = 'tracker-linear';
+/** The `tracker-linear` section of a project entry as written — typed, or
+ *  undefined. Core passes the section through; reading it is this plugin's
+ *  business. */
+const writtenLinear = (loaded, projectId) => loaded.config.projects[projectId]?.[SECTION];
+/** The `tracker-linear` section of `projectDefaults` as written. */
+const writtenDefaults = (loaded) => loaded.config.projectDefaults[SECTION];
+/** The project's Linear routing as it takes effect: which teams speak for it
+ *  and in which workspace. Lanes are not here — they are core's ordered
+ *  workflow on the `Project` itself (`projects.<id>.lanes`), which the
+ *  orchestrator reads to decide moves and this plugin only ever performs. */
+export function projectLinear(loaded, projectId) {
+    const entry = writtenLinear(loaded, projectId);
+    if (!entry)
+        return undefined;
+    const workspaceId = entry.workspaceId ?? writtenDefaults(loaded)?.workspaceId;
+    const createLane = entry.createLane ?? writtenDefaults(loaded)?.createLane;
+    return { teams: entry.teams, ...(workspaceId ? { workspaceId } : {}), ...(createLane ? { createLane } : {}) };
+}
+/** A checkout receives one issue stream, so a Linear team may belong to
+ *  exactly one project. Said for every collision, not just the first. */
+export function linearTeamCollisions(loaded) {
+    const owners = new Map();
+    const collisions = [];
+    for (const project of Object.keys(loaded.config.projects))
+        for (const team of writtenLinear(loaded, project)?.teams ?? []) {
+            const owner = owners.get(team);
+            if (owner && owner !== project)
+                collisions.push(`projects.${project}.${SECTION}.teams: this Linear team is already mapped to project ${owner}`);
+            owners.set(team, project);
+        }
+    return collisions;
+}
+/** Which aivi project an issue belongs to: by the issue's Linear team, and by
+ *  workspace when one is configured. */
+export function projectForIssue(loaded, issue) {
+    for (const project of loaded.projects) {
+        if (project.removed)
+            continue;
+        const linear = projectLinear(loaded, project.id);
+        if (!linear)
+            continue;
+        if (linear.teams.includes(issue.teamId) && (!linear.workspaceId || linear.workspaceId === issue.organizationId))
+            return { project, linear };
+    }
+    return undefined;
+}
+/**
+ * Point a project at Linear teams, and optionally (re)write its lanes: teams
+ * go to `projects.<id>.tracker-linear.teams`, lanes to the project's **core**
+ * `lanes` array — the ordered workflow, which core validates and the
+ * orchestrator decides moves from. Nothing else in the file is touched; an
+ * existing `lanes` stays as it was when none is passed. The written file must
+ * hold: the core config must still load (which validates the lane order and
+ * every `complete`/`return` reference), the section must parse against this
+ * plugin's own schema, and no team may belong to two projects — if any check
+ * fails, the previous bytes are restored and the error stands.
+ */
+export async function writeProjectLinear(configPath, id, options) {
+    if (!PROJECT_ID.test(id))
+        throw new Error(`Project id "${id}" must match ${PROJECT_ID}`);
+    if (!options.teams.length)
+        throw new Error('Set at least one Linear team');
+    const before = await readFile(configPath, 'utf8');
+    const raw = JSON.parse(before);
+    const projects = (raw.projects ?? {});
+    raw.projects = projects;
+    const entry = (projects[id] ?? {});
+    projects[id] = entry;
+    const linear = (entry[SECTION] ?? {});
+    entry[SECTION] = linear;
+    linear.teams = options.teams;
+    if (options.lanes)
+        entry.lanes = options.lanes;
+    await writeWhole(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+    try {
+        const loaded = await loadConfig(configPath);
+        linearProjectSchema.parse(linear);
+        // A checkout receives one issue stream: the teams just written may not
+        // belong to another project too. Collisions between other projects are
+        // not this write's doing; the module's start check says those.
+        const mine = new Set(linear.teams);
+        for (const other of Object.keys(loaded.config.projects)) {
+            if (other === id)
+                continue;
+            const shared = (writtenLinear(loaded, other)?.teams ?? []).filter(team => mine.has(team));
+            if (shared.length)
+                throw new Error(`Linear team ${shared.join(', ')} is already mapped to project ${other}; a team belongs to one project`);
+        }
+    }
+    catch (error) {
+        await writeWhole(configPath, before);
+        throw error;
+    }
+    const lanes = entry.lanes;
+    return { id, teams: options.teams, ...(lanes ? { lanes } : {}) };
+}
+/** Bytes land whole or not at all: temp next door, rename over the live
+ *  path. A kill mid-write used to leave truncated JSON where the config
+ *  was — the restore-on-refusal pattern below protects against a bad
+ *  write, not against a half one. */
+async function writeWhole(path, contents) {
+    const temp = `${path}.aivi-tmp`;
+    rmSync(temp, { force: true });
+    await writeFile(temp, contents);
+    renameSync(temp, path);
+}

package/dist/routes.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from '@aivi/core';
+import type { PublicRoutes } from '@aivi/plugin';
+import { type LinearWebhook } from './webhook.ts';
+/** An app's own stream, at `app/<id>`: agent-session events — and, for the
+ * primary, the workspace's **Issues** data changes on the same route. */
+export declare const appWebhookPath: (app: string) => string;
+export interface WebhookApp {
+    id: string;
+    webhookSecret: string;
+}
+/**
+ * One public route per app. Failures of `dispatch` are logged, never
+ * returned: a retry would only replay what already failed. Bad signatures
+ * are logged with the delivery id, never the body.
+ */
+export declare function registerWebhookRoutes(routes: PublicRoutes, apps: WebhookApp[], dispatch: (app: string, payload: LinearWebhook) => Promise<void>, log?: Logger): () => void;

package/dist/routes.js

@@ -0,0 +1,40 @@
+import { getLogger } from '@aivi/core';
+import { MODULE_ID } from './config.js';
+import { verifyWebhook } from './webhook.js';
+/** An app's own stream, at `app/<id>`: agent-session events — and, for the
+ * primary, the workspace's **Issues** data changes on the same route. */
+export const appWebhookPath = (app) => `/linear/webhooks/app/${app}`;
+/** Verify, acknowledge at once (Linear retries anything but a 200), then dispatch. */
+const route = (label, webhookSecret, dispatch, log) => {
+    return async (request) => {
+        if (request.method !== 'POST')
+            return { status: 405, body: { error: 'Use POST' } };
+        const verdict = verifyWebhook({
+            body: request.body,
+            signature: request.headers['linear-signature'],
+            secret: webhookSecret,
+        });
+        const delivery = request.headers['linear-delivery'];
+        if (!verdict.ok) {
+            log.warn('linear.webhook.refused', { ...label, delivery, reason: verdict.reason });
+            return { status: verdict.status, body: { error: verdict.reason } };
+        }
+        log.debug('linear.webhook', { ...label, delivery, type: verdict.payload.type, action: verdict.payload.action });
+        dispatch(verdict.payload).catch(error => {
+            log.warn('linear.webhook.failed', { ...label, delivery, error });
+        });
+        return { status: 200, body: { ok: true } };
+    };
+};
+/**
+ * One public route per app. Failures of `dispatch` are logged, never
+ * returned: a retry would only replay what already failed. Bad signatures
+ * are logged with the delivery id, never the body.
+ */
+export function registerWebhookRoutes(routes, apps, dispatch, log = getLogger(['aivi', MODULE_ID])) {
+    const unregister = apps.map(app => routes.register(appWebhookPath(app.id), route({ app: app.id }, app.webhookSecret, p => dispatch(app.id, p), log)));
+    return () => {
+        for (const off of unregister)
+            off();
+    };
+}

package/dist/runprogress.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The worker run's **progress stream**: while a run works, its OpenCode
+ * session is mirrored into the agent session through the platform's
+ * transient progress surface (`Platform.progress`) — Linear shows it as
+ * ephemeral `thought` and `action` activities (ruled 2026-10-02: "thoughts
+ * and action types, marked as ephemeral to prevent spamming"). The reducer
+ * and the renderer are the host's own channel machinery, so the worker's
+ * line and a chat placeholder say the same thing in the same words.
+ *
+ * No polling and no interval: besides the throttle's trailing edge, the
+ * only timer waits for the next instant the rendered line changes on its
+ * own (the long-turn suffix, the idle notice, an elapsed refresh). The
+ * follower pauses while a question awaits a person — nothing happens then —
+ * and resumes when the answer lands.
+ */
+import type { Logger } from '@aivi/core';
+import { type ProgressClock } from '@aivi/host';
+import type { SessionEvents } from '@aivi/plugin/module';
+import type { Platform } from '@aivi/plugin/tracker';
+export interface RunProgressOptions {
+    /** `status` shows the one line; `tools` lets a running tool speak as an `action`. */
+    mode: 'status' | 'tools';
+    events: SessionEvents;
+    log: Logger;
+    /** At most one activity per window: the first at once, later ones coalesced. */
+    throttleMs?: number;
+    clock?: Partial<ProgressClock>;
+}
+export declare class RunProgress {
+    private readonly platform;
+    private readonly conversation;
+    private readonly sessionId;
+    private readonly mode;
+    private readonly events;
+    private readonly log;
+    private readonly throttleMs;
+    private readonly clock;
+    private state;
+    private shown;
+    private lastPostAt;
+    private unwatch;
+    private trailing;
+    private change;
+    private inflight;
+    private following;
+    constructor(platform: Platform, conversation: string, sessionId: string, options: RunProgressOptions);
+    /** Follow the session: watch and arm. Idempotent; a stopped follower
+     *  resumes with its history — the elapsed line keeps counting, because
+     *  the worker did. */
+    start(): void;
+    /** Say nothing more: unwatch, disarm, let the in-flight activity land. */
+    stop(): Promise<void>;
+    /** Wait for the next instant the line changes by itself. */
+    private arm;
+    private schedule;
+    /** One activity per visible change — and only when the text actually
+     *  changed, so the stream says each moment once. A running tool is
+     *  offered as a tool; a `status`-mode follower keeps it inside the line. */
+    private flush;
+}

package/dist/runprogress.js

@@ -0,0 +1,120 @@
+/**
+ * The worker run's **progress stream**: while a run works, its OpenCode
+ * session is mirrored into the agent session through the platform's
+ * transient progress surface (`Platform.progress`) — Linear shows it as
+ * ephemeral `thought` and `action` activities (ruled 2026-10-02: "thoughts
+ * and action types, marked as ephemeral to prevent spamming"). The reducer
+ * and the renderer are the host's own channel machinery, so the worker's
+ * line and a chat placeholder say the same thing in the same words.
+ *
+ * No polling and no interval: besides the throttle's trailing edge, the
+ * only timer waits for the next instant the rendered line changes on its
+ * own (the long-turn suffix, the idle notice, an elapsed refresh). The
+ * follower pauses while a question awaits a person — nothing happens then —
+ * and resumes when the answer lands.
+ */
+import { DEFAULT_CLOCK, nextRenderChange, reduceProgress, renderProgress, startProgress, } from '@aivi/host';
+export class RunProgress {
+    platform;
+    conversation;
+    sessionId;
+    mode;
+    events;
+    log;
+    throttleMs;
+    clock;
+    state;
+    shown;
+    lastPostAt;
+    unwatch;
+    trailing;
+    change;
+    inflight = Promise.resolve();
+    following = false;
+    constructor(platform, conversation, sessionId, options) {
+        this.platform = platform;
+        this.conversation = conversation;
+        this.sessionId = sessionId;
+        this.mode = options.mode;
+        this.events = options.events;
+        this.log = options.log;
+        this.throttleMs = options.throttleMs ?? 2_000;
+        this.clock = { ...DEFAULT_CLOCK, ...options.clock };
+        const now = Date.now();
+        this.state = startProgress(now);
+        this.shown = renderProgress(this.state, this.mode, now, this.clock);
+        this.lastPostAt = 0;
+    }
+    /** Follow the session: watch and arm. Idempotent; a stopped follower
+     *  resumes with its history — the elapsed line keeps counting, because
+     *  the worker did. */
+    start() {
+        if (this.following || !this.platform.progress)
+            return;
+        this.following = true;
+        this.unwatch = this.events.watch(this.sessionId, event => {
+            this.state = reduceProgress(this.state, event, Date.now());
+            this.schedule();
+        });
+        this.arm();
+    }
+    /** Say nothing more: unwatch, disarm, let the in-flight activity land. */
+    async stop() {
+        this.following = false;
+        this.unwatch?.();
+        this.unwatch = undefined;
+        clearTimeout(this.trailing);
+        this.trailing = undefined;
+        clearTimeout(this.change);
+        this.change = undefined;
+        await this.inflight;
+    }
+    /** Wait for the next instant the line changes by itself. */
+    arm() {
+        clearTimeout(this.change);
+        if (!this.following)
+            return;
+        const now = Date.now();
+        const at = nextRenderChange(this.state, now, this.clock);
+        this.change = setTimeout(() => this.schedule(), Math.max(0, at - now)).unref();
+    }
+    schedule() {
+        if (!this.following || this.trailing)
+            return;
+        const wait = this.lastPostAt + this.throttleMs - Date.now();
+        if (wait <= 0) {
+            this.flush();
+            return;
+        }
+        this.trailing = setTimeout(() => {
+            this.trailing = undefined;
+            this.flush();
+        }, wait).unref();
+    }
+    /** One activity per visible change — and only when the text actually
+     *  changed, so the stream says each moment once. A running tool is
+     *  offered as a tool; a `status`-mode follower keeps it inside the line. */
+    flush() {
+        if (!this.following)
+            return;
+        this.arm();
+        const now = Date.now();
+        const text = renderProgress(this.state, this.mode, now, this.clock);
+        if (text === this.shown)
+            return;
+        this.shown = text;
+        this.lastPostAt = now;
+        const running = this.mode === 'tools' ? this.state.tools.findLast(t => t.state === 'running' && !t.pending) : undefined;
+        const head = text.split('\n')[0];
+        const line = {
+            text: head,
+            ...(running ? { tool: { name: running.name, ...(running.detail ? { detail: running.detail } : {}) } } : {}),
+        };
+        this.inflight = this.inflight
+            .then(async () => {
+            if (this.following)
+                await this.platform.progress?.(this.conversation, line);
+        })
+            .catch(error => this.log.warn('progress.activity.failed', { error }));
+    }
+}

package/dist/setup-project.d.ts

@@ -0,0 +1,63 @@
+/** Linear's project-setup contributor, at its `./setupProject` subpath: it
+ *  maps a new project to Linear teams and offers the project's lane array —
+ *  the board's states in board order, each asked what kind of lane it is
+ *  (agent, human, or none). It clones
+ *  nothing (a tracker has no checkout to give): it hands back the `linear`
+ *  section core writes under the project, and the **core** `lanes` array
+ *  core writes on the project. Everything Linear-specific — apps, teams,
+ *  workflow states — lives here; core only knows this plugin serves the
+ *  `tracker` role. */
+import { type Logger, type ProjectLaneInput } from '@aivi/core';
+import { type LaneKind, type ProjectContributor } from '@aivi/plugin';
+import { type LinearTeam } from './client.ts';
+import type { LinearConfig } from './config.ts';
+/** The states the wizard asks about, in board order: deduped by name across
+ *  the picked teams (two mapped teams can share a state name, and one name
+ *  gets one lane). Nothing is dropped — **every state is asked**: what a
+ *  state is for is the person's answer to the lane question, not aivi's
+ *  guess from the state's type. Linear's `type` is
+ *  real API data, so it only sets which answer the question starts on. The
+ *  client already returns each team's states in board order (type group,
+ *  then position). Exported pure for the test that pins the dedupe. */
+export declare function boardStates(states: LinearTeam['states']): LinearTeam['states'];
+/** Which answer the lane question starts on, from Linear's state type (real
+ *  API data): a `completed` state starts on Human — a person takes finished
+ *  work; `canceled` and `duplicate` start on None — they end out of the
+ *  workflow; everything else starts on Agent. A start is a highlight, not a
+ *  ruling: the person's answer wins. */
+export declare function laneKindDefault(type: string): LaneKind;
+/** The lanes the queue question may offer (ruled 2026-10-02): **one**
+ *  question after all lanes are configured, and its candidates are the
+ *  lanes that could legally hold the queue — a queue lane must feed a
+ *  worker lane, so a lane whose next works nobody is no candidate, and the
+ *  last lane feeds nothing at all. And a lane that has an agent is **never**
+ *  an option (ruled 2026-10-02): a queue is where people wait for a worker,
+ *  not a worker lane itself — the queue runs between the human lanes and
+ *  the working ones, like a real board's waiting column. A **human** lane is
+ *  a legal queue: that is what "used as a queue" means in the lane answer's
+ *  own words. Offering anything else would write a config the operator did
+ *  not mean. Exported pure, so the wizard's rules are testable apart from
+ *  prompts. */
+export declare function queueCandidates(lanes: ProjectLaneInput[]): ProjectLaneInput[];
+/** Mark the chosen queue lane. The queue answer is the wizard's later
+ *  word, so a lane that just chose an agent gives it up — and says so out
+ *  loud, because a lane silently losing its worker is not a wizard. The
+ *  returned lines are what the caller logs; the marking itself follows
+ *  core's load rules: a queue lane works none and writes nothing. */
+export declare function markQueue(lanes: ProjectLaneInput[], chosen: string): string[];
+/** The crossing to Linear the wizard needs: the teams it can list.
+ *  Production is `clientFor`; a test answers with its own teams, because
+ *  the wizard's questions, order and written config are the unit — the
+ *  GraphQL round trip is client.test.ts's subject, and the live gate's. */
+export type LinearTeamsClient = {
+    listTeams(): Promise<LinearTeam[]>;
+};
+export type MakeTeamsClient = (config: LinearConfig, app: string | undefined, log: Logger) => LinearTeamsClient;
+/** The wizard, in its order: app, teams, the project's name, what kind of
+ *  lane each board state is (agent, human, or none), then the queue over
+ *  the no-agent lanes. Each step is its own question and its own honest
+ *  failure; the whole is the ruling. */
+declare function makeContributor(makeClient?: MakeTeamsClient): ProjectContributor;
+export declare const contributor: ProjectContributor;
+export { makeContributor };
+export default contributor;