@aivi/tracker-github 0.0.0-stage → 1.0.0

package/dist/desk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The GitHub tracker's answer to the ticket desk (the `TicketDesk` contract
+ * at `@aivi/plugin/tracker`). The host owns the `aivi_ticket_*` tools and the
+ * ground truth of the call — this file answers what each one *is* on GitHub:
+ * which ticket a plain comment lands on, which repository a new ticket is
+ * born in, what the repository's label catalogue means. GitHub has one app
+ * and no sessions to speak through, so every call arrives on the app's own
+ * feed: `GITHUB_FEED` is the desk's whole conversation.
+ */
+import type { LoadedConfig } from '@aivi/core';
+import type { Platform, TicketDesk } from '@aivi/plugin/tracker';
+import type { GithubConfig } from './config.ts';
+export declare function createGithubDesk(loaded: LoadedConfig, _config: GithubConfig, platform: Platform): TicketDesk;

package/dist/desk.js

@@ -0,0 +1,67 @@
+import { ToolError } from '@aivi/plugin';
+import { projectGithub } from './projects.js';
+import { GITHUB_FEED } from './tracker.js';
+export function createGithubDesk(loaded, _config, platform) {
+    const ticket = (run) => platform.issue(GITHUB_FEED, run.ticketId);
+    /** Where a new ticket is born: the project's repositories, the create lane
+     *  as it takes effect (project's `createLane`, defaults', else the
+     *  project's first configured lane). An explicit create lane must be a
+     *  Status option on the board — a wrong name is said, never guessed past;
+     *  the fallback lane lands where GitHub's own default sends new issues
+     *  when no board carries its name. */
+    const createTarget = async (projectId) => {
+        const github = projectGithub(loaded, projectId);
+        if (!github?.repos.length)
+            throw new ToolError(409, 'this project has no GitHub repositories; aivi_ticket_create has nowhere to create.');
+        const explicit = github.createLane;
+        const lane = explicit ?? loaded.projects.find(p => p.id === projectId)?.lanes?.[0]?.name;
+        if (lane) {
+            const states = await platform.laneStates(GITHUB_FEED, github.repos[0]);
+            if (states.some(s => s.name === lane))
+                return { repo: github.repos[0], lane };
+        }
+        if (explicit)
+            throw new ToolError(409, `createLane "${explicit}" names no Status option on this project's board — fix createLane in config.`);
+        return { repo: github.repos[0] };
+    };
+    return {
+        async read(run) {
+            const issue = await ticket(run);
+            return {
+                identifier: issue.identifier,
+                title: issue.title,
+                description: issue.description,
+                lane: issue.state.name,
+                labels: issue.labels.map(l => l.name),
+                url: issue.url,
+            };
+        },
+        comments(run) {
+            return platform.ticketComments(GITHUB_FEED, run.ticketId);
+        },
+        async labels(run) {
+            const issue = await ticket(run);
+            return { team: await platform.teamLabels(GITHUB_FEED, issue.teamId), on: issue.labels.map(l => l.name) };
+        },
+        async edit(run, changes) {
+            const issue = await platform.editIssue(GITHUB_FEED, run.ticketId, changes);
+            return { identifier: issue.identifier, title: issue.title, url: issue.url };
+        },
+        comment(run, text) {
+            return platform.addComment(GITHUB_FEED, run.ticketId, text);
+        },
+        async create(run, input) {
+            const target = await createTarget(run.projectId);
+            const issue = await platform.createIssue(GITHUB_FEED, {
+                teamId: target.repo,
+                title: input.title,
+                description: input.description,
+                ...(target.lane ? { lane: target.lane } : {}),
+            });
+            return { identifier: issue.identifier, url: issue.url, lane: issue.state.name };
+        },
+        async label(run, label, on) {
+            await platform.apply(GITHUB_FEED, run.ticketId, { kind: 'label', label, on });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export type { BoardFields, BoardItem, GithubComment, GithubIssue, IssueDependency, IssueRef, ItemSelectValue, } from './client.ts';
+export { dependencyCompleted, GithubClient, githubClient, isGoneError, issueRef, repoIssueId } from './client.ts';
+export type { GithubConfig, GithubProjectDefaults, GithubProjectEntry, ProjectGithub } from './config.ts';
+export { AGENT_FIELD, assistantAgent, githubProjectDefaultsSchema, githubProjectSchema, githubSchema, MODULE_ID, plugin, STATUS_FIELD, } from './config.ts';
+export { createGithubDesk } from './desk.ts';
+export type { RunLink } from './links.ts';
+export { RunLinks } from './links.ts';
+export type { MakeBoard, MakeTracker } from './module.ts';
+export { createGithubModule, describeWorkers, GITHUB, openGithubStore } from './module.ts';
+export type { RoutedProject } from './projects.ts';
+export { githubRepoCollisions, projectForIssue, projectGithub, writeProjectGithub } from './projects.ts';
+export type { RunProgressOptions } from './runprogress.ts';
+export { RunProgress } from './runprogress.ts';
+export type { StatusBody } from './tracker.ts';
+export { GITHUB_FEED, GITHUB_WEBHOOK_PATH, GithubPlatform, issueChanges, parseStatus, registerWebhookRoute, renderStatus, } from './tracker.ts';
+export type { GithubDeliveryHeaders, GithubTrust, IssueCommentPayload, IssuesPayload, ProjectsV2ItemPayload, } from './webhook.ts';
+export { DeliveryLedger, editedFieldName, GITHUB_DELIVERY_HEADER, GITHUB_EVENT_HEADER, isBotAuthor, trustedAuthor, } from './webhook.ts';
+export type { GithubBoard, GithubIssueWords } from './work.ts';
+export { githubBoard, issueDossier } from './work.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { dependencyCompleted, GithubClient, githubClient, isGoneError, issueRef, repoIssueId } from './client.js';
+export { AGENT_FIELD, assistantAgent, githubProjectDefaultsSchema, githubProjectSchema, githubSchema, MODULE_ID, plugin, STATUS_FIELD, } from './config.js';
+export { createGithubDesk } from './desk.js';
+export { RunLinks } from './links.js';
+export { createGithubModule, describeWorkers, GITHUB, openGithubStore } from './module.js';
+export { githubRepoCollisions, projectForIssue, projectGithub, writeProjectGithub } from './projects.js';
+export { RunProgress } from './runprogress.js';
+export { GITHUB_FEED, GITHUB_WEBHOOK_PATH, GithubPlatform, issueChanges, parseStatus, registerWebhookRoute, renderStatus, } from './tracker.js';
+export { DeliveryLedger, editedFieldName, GITHUB_DELIVERY_HEADER, GITHUB_EVENT_HEADER, isBotAuthor, trustedAuthor, } from './webhook.js';
+export { githubBoard, issueDossier } from './work.js';

package/dist/links.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The GitHub tracker's own durable pair: the **status comment** ↔ the
+ * OpenCode session ↔ the ticket. GitHub has no agent session for an app to
+ * work in (apps cannot be assignees, proven 403), so the run's conversation
+ * is the status comment `startSession` creates (D6) — and the follower keeps
+ * that join itself, which is the whole reason a webhook naming a ticket can
+ * find its worker's OpenCode session without asking anybody, and the list a
+ * boot pass reconciles against GitHub.
+ *
+ * Its own namespace, its own table (the `Store.migrate` contract every module
+ * has: namespaced tables, never host tables). The pair's key is the session
+ * id `owner/repo#47:c123` — the ticket with the status comment's id on it.
+ */
+import type { Store } from '@aivi/plugin';
+export interface RunLink {
+    agentSession: string;
+    ticketId: string;
+    opencodeSession?: string;
+    /** When the closing landed — the pair is settled and boot asks GitHub
+     *  about it no more. Absent means the closing is still owed. */
+    endedAt?: number;
+}
+export declare class RunLinks {
+    private readonly store;
+    constructor(store: Store);
+    /** The status comment exists: record it and its ticket. The OpenCode
+     *  session joins when the orchestrator's `ready` stage names this ticket's
+     *  run. */
+    bind(agentSession: string, ticketId: string, now?: number): void;
+    /** The run's session exists: attach it to the newest unattached pair for
+     *  the ticket. Absent means the pair was already recorded — a replay of
+     *  the same session says nothing, never stealing an older pair. */
+    attach(ticketId: string, opencodeSession: string): boolean;
+    byAgentSession(agentSession: string): RunLink | undefined;
+    byOpencodeSession(opencodeSession: string): RunLink | undefined;
+    /** The newest pair for a ticket, settled or not: a person's comment on a
+     *  ticket GitHub names (not a session, as Linear's events do) finds the
+     *  run it belongs to through here. */
+    byTicket(ticketId: string): RunLink | undefined;
+    /** Every pair whose closing has not landed: the boot pass reads the run
+     *  state for each and catches GitHub up wherever the run has ended. A
+     *  settled pair is absent — its closing spoke GitHub's own state once, and
+     *  asking again forever was Linear's bug (live, 2026-10-06). Follow-up
+     *  routing never comes through here: it asks `byTicket` directly, settled
+     *  or not. The lane move is not this list's business: it is the
+     *  orchestrator's own debt in its own ledger. */
+    owed(): RunLink[];
+    /** The closing landed: settle the pair. The row stays — it is still the
+     *  route a person's later message finds its run through. */
+    closingLanded(agentSession: string, now?: number): void;
+    /** Retire a pair for good. Its use today is the gone-closing: GitHub
+     *  answers the status comment with `404` — the ticket was deleted — so
+     *  there is nothing left to pay and no reason for the next boot to ask
+     *  again. */
+    drop(agentSession: string): void;
+}

package/dist/links.js

@@ -0,0 +1,94 @@
+const map = (r) => ({
+    agentSession: String(r.agent_session),
+    ticketId: String(r.ticket_id),
+    ...(r.opencode_session === null ? {} : { opencodeSession: String(r.opencode_session) }),
+    ...(r.ended_at === null ? {} : { endedAt: Number(r.ended_at) }),
+});
+const migrations = [
+    `CREATE TABLE tracker_github_run_links(
+     agent_session TEXT PRIMARY KEY, ticket_id TEXT NOT NULL, opencode_session TEXT UNIQUE,
+     created_at INTEGER NOT NULL);
+   CREATE INDEX tracker_github_run_links_ticket ON tracker_github_run_links(ticket_id);`,
+    // The boot pass reads only the pairs whose closing has not landed, so the
+    // index is **partial**: it holds the owed rows and nothing else, and the
+    // settled history never weighs on a boot.
+    `ALTER TABLE tracker_github_run_links ADD COLUMN ended_at INTEGER;
+   CREATE INDEX tracker_github_run_links_owed ON tracker_github_run_links(created_at) WHERE ended_at IS NULL;`,
+];
+export class RunLinks {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.migrate('tracker-github', migrations);
+    }
+    /** The status comment exists: record it and its ticket. The OpenCode
+     *  session joins when the orchestrator's `ready` stage names this ticket's
+     *  run. */
+    bind(agentSession, ticketId, now = Date.now()) {
+        this.store.db
+            .prepare(`INSERT INTO tracker_github_run_links(agent_session, ticket_id, created_at) VALUES(?,?,?)
+         ON CONFLICT(agent_session) DO UPDATE SET ticket_id=excluded.ticket_id`)
+            .run(agentSession, ticketId, now);
+    }
+    /** The run's session exists: attach it to the newest unattached pair for
+     *  the ticket. Absent means the pair was already recorded — a replay of
+     *  the same session says nothing, never stealing an older pair. */
+    attach(ticketId, opencodeSession) {
+        const changed = this.store.db
+            .prepare(`UPDATE tracker_github_run_links SET opencode_session=?
+         WHERE agent_session = (
+           SELECT agent_session FROM tracker_github_run_links
+           WHERE ticket_id=? AND opencode_session IS NULL ORDER BY created_at DESC LIMIT 1)
+           AND opencode_session IS NULL
+           AND NOT EXISTS (SELECT 1 FROM tracker_github_run_links WHERE opencode_session=?)`)
+            .run(opencodeSession, ticketId, opencodeSession);
+        return changed.changes > 0;
+    }
+    byAgentSession(agentSession) {
+        const row = this.store.db
+            .prepare('SELECT * FROM tracker_github_run_links WHERE agent_session=?')
+            .get(agentSession);
+        return row && map(row);
+    }
+    byOpencodeSession(opencodeSession) {
+        const row = this.store.db
+            .prepare('SELECT * FROM tracker_github_run_links WHERE opencode_session=?')
+            .get(opencodeSession);
+        return row && map(row);
+    }
+    /** The newest pair for a ticket, settled or not: a person's comment on a
+     *  ticket GitHub names (not a session, as Linear's events do) finds the
+     *  run it belongs to through here. */
+    byTicket(ticketId) {
+        const row = this.store.db
+            .prepare('SELECT * FROM tracker_github_run_links WHERE ticket_id=? ORDER BY created_at DESC LIMIT 1')
+            .get(ticketId);
+        return row && map(row);
+    }
+    /** Every pair whose closing has not landed: the boot pass reads the run
+     *  state for each and catches GitHub up wherever the run has ended. A
+     *  settled pair is absent — its closing spoke GitHub's own state once, and
+     *  asking again forever was Linear's bug (live, 2026-10-06). Follow-up
+     *  routing never comes through here: it asks `byTicket` directly, settled
+     *  or not. The lane move is not this list's business: it is the
+     *  orchestrator's own debt in its own ledger. */
+    owed() {
+        return this.store.db
+            .prepare('SELECT * FROM tracker_github_run_links WHERE opencode_session IS NOT NULL AND ended_at IS NULL ORDER BY created_at')
+            .all().map(map);
+    }
+    /** The closing landed: settle the pair. The row stays — it is still the
+     *  route a person's later message finds its run through. */
+    closingLanded(agentSession, now = Date.now()) {
+        this.store.db
+            .prepare('UPDATE tracker_github_run_links SET ended_at=? WHERE agent_session=?')
+            .run(now, agentSession);
+    }
+    /** Retire a pair for good. Its use today is the gone-closing: GitHub
+     *  answers the status comment with `404` — the ticket was deleted — so
+     *  there is nothing left to pay and no reason for the next boot to ask
+     *  again. */
+    drop(agentSession) {
+        this.store.db.prepare('DELETE FROM tracker_github_run_links WHERE agent_session=?').run(agentSession);
+    }
+}

package/dist/module.d.ts

@@ -0,0 +1,36 @@
+import { ConversationStore } from '@aivi/host';
+import type { AiviModule, AiviServices, Store } from '@aivi/plugin';
+import type { ChannelPlatform, Turn } from '@aivi/plugin/channel';
+import type { GithubConfig } from './config.ts';
+import { GithubPlatform } from './tracker.ts';
+import type { GithubBoard } from './work.ts';
+/**
+ * The platform: a ticket is an assistant conversation, a status comment is a
+ * run conversation — `github:owner/repo#47` and `github:owner/repo#47:c123`.
+ * Assistant turns have effects beyond their reply, so a restart mid-turn
+ * blocks instead of discarding.
+ */
+export declare const GITHUB: ChannelPlatform;
+export declare function openGithubStore(store: Store): ConversationStore;
+/** Where the module's tracker comes from: GitHub's adapter by default, a
+ *  fake tracker in a test of the decisions below. The concrete class is the
+ *  point — the closing speaks the GitHub-only words (`markClosing`,
+ *  `freezeStatus`) the neutral contract does not carry. */
+export type MakeTracker = (services: AiviServices) => Promise<GithubPlatform>;
+/** The board, pull-shaped, for the orchestrator's walk; a test hands its own
+ *  lanes the way it hands its own tracker. */
+export type MakeBoard = (services: AiviServices, tracker: GithubPlatform) => GithubBoard;
+export declare function createGithubModule(config: GithubConfig, makeTracker?: MakeTracker, makeBoard?: MakeBoard): AiviModule;
+/** The branch a ticket works on (D8): GitHub names none, so the tracker
+ *  generates `aivi/<number>-<slug>` — the words a worktree lane checks out,
+ *  human-readable and stable across retries. */
+export declare function branchFor(ticketId: string, title: string): string;
+/** For `aivi github status`: what each assistant conversation is doing.
+ *  Workers live in the orchestrator's ledger now; their lines join this view
+ *  when the status command is formalized with the extraction. */
+export declare function describeWorkers(store: ConversationStore): {
+    conversation: string;
+    agent: string | null;
+    issue: string | null;
+    turn: Turn;
+}[];