@aivi/tracker-github 0.0.0-stage → 1.0.0

package/dist/client.js

@@ -0,0 +1,528 @@
+/** Everything GitHub-shaped that the tracker asks of the API: the board
+ *  reads and writes (Status and the `Agent` field), the issue facts, the
+ *  comment trail, labels and reactions. Authentication is `@aivi/github`'s —
+ *  one app, one installation, octokit's cached installation token — this file
+ *  is only the queries and what they answer.
+ *
+ *  The issue id in aivi's hands is `owner/repo#47`, the words a person
+ *  types; the GraphQL node ids live here and nowhere above. Reads that lag
+ *  their writes (live, 2026-10-07: a re-read right after a mutation answered
+ *  the old value) are not trusted — the mutation's own answer is the truth,
+ *  and the board's own webhook is the catch-up.
+ */
+import { GITHUB_WEBHOOK_SECRET_ENV, githubApp } from '@aivi/github';
+import { ConfigurationError } from '@aivi/plugin';
+import { AGENT_FIELD, STATUS_FIELD } from './config.js';
+const REPO_ISSUE = /^([^/]+)\/([^/#]+)#(\d+)$/;
+export function issueRef(id) {
+    const found = REPO_ISSUE.exec(id.trim());
+    if (!found)
+        throw new Error(`"${id}" is not a GitHub issue id (owner/repo#number)`);
+    return { owner: found[1], name: found[2], number: Number(found[3]) };
+}
+export const repoIssueId = (owner, name, number) => `${owner}/${name}#${number}`;
+/** What the board mutations need to name a value: the board, its item, and
+ *  the field. Absent board item is said, never guessed at. */
+const itemOn = (issue, boardNumber) => issue.projectItems.find(i => i.boardNumber === boardNumber);
+const optionNamed = (options, name) => options.find(o => o.name === name)?.id;
+/** The dependency verdict in GitHub's words: closed is closed, whatever the
+ *  reason — a `not_planned` blocker holds nothing back any more than a
+ *  `completed` one does. */
+export const dependencyCompleted = (state) => state === 'closed';
+/** Whether GitHub says the thing **does not exist** rather than "try
+ *  again": a deleted issue answers its comments, its board item and its own
+ *  node with 404 (REST) or `Could not resolve to a Node` (GraphQL). A
+ *  closing owed to such a surface is dropped, not retried — the Linear
+ *  tracker learned that on a grave (live, 2026-10-06). Anything else —
+ *  a 502, a rate limit — is a retry. */
+export const isGoneError = (error) => {
+    const e = error;
+    if (e?.status === 404 || e?.status === 410)
+        return true;
+    return typeof e?.message === 'string' && e.message.includes('Could not resolve to a Node');
+};
+const ISSUE_FACTS = /* GraphQL */ `
+  query IssueFacts($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      issue(number: $number) {
+        id databaseId number title body url state stateReason
+        labels(first: 50) { nodes { id name } }
+        assignees(first: 10) { nodes { id login } }
+        projectItems(first: 50, includeArchived: false) { nodes {
+          id
+          project { number }
+          fieldValues(first: 30) { nodes {
+            ... on ProjectV2ItemFieldSingleSelectValue {
+              name optionId
+              field { ... on ProjectV2SingleSelectField { name } }
+            }
+          } }
+        } }
+        blockedBy(first: 20) { nodes {
+          number state stateReason
+          repository { owner { login } name }
+        } }
+      }
+    }
+  }
+`;
+const OPEN_ISSUES = /* GraphQL */ `
+  query OpenIssues($owner: String!, $repo: String!, $first: Int!) {
+    repository(owner: $owner, name: $repo) {
+      issues(states: [OPEN], first: $first, orderBy: { field: CREATED_AT, direction: DESC }) {
+        nodes {
+          id databaseId number title body url state stateReason
+          labels(first: 20) { nodes { id name } }
+          assignees(first: 10) { nodes { id login } }
+          projectItems(first: 20, includeArchived: false) { nodes {
+            id
+            project { number }
+            fieldValues(first: 30) { nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                name optionId
+                field { ... on ProjectV2SingleSelectField { name } }
+              }
+            } }
+          } }
+          blockedBy(first: 10) { nodes {
+            number state stateReason
+            repository { owner { login } name }
+          } }
+        }
+      }
+    }
+  }
+`;
+const BOARD_FIELDS = /* GraphQL */ `
+  query BoardFields($owner: String!, $number: Int!) {
+    organization(login: $owner) {
+      projectV2(number: $number) {
+        id
+        fields(first: 60) { nodes {
+          ... on ProjectV2Field { id name databaseId }
+          ... on ProjectV2SingleSelectField { id name options { id name } }
+        } }
+      }
+    }
+  }
+`;
+const ADD_ITEM = /* GraphQL */ `
+  mutation AddItem($projectId: ID!, $contentId: ID!) {
+    addProjectV2ItemById(input: { projectId: $projectId, contentId: $contentId }) { item { id } }
+  }
+`;
+const NODE_REF = /* GraphQL */ `
+  query NodeRef($id: ID!) {
+    node(id: $id) {
+      ... on Issue {
+        number
+        repository { owner { login } name }
+      }
+    }
+  }
+`;
+const SET_SELECT = /* GraphQL */ `
+  mutation SetSelect($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+    updateProjectV2ItemFieldValue(
+      input: { projectId: $projectId, itemId: $itemId, fieldId: $fieldId, value: { singleSelectOptionId: $optionId } }
+    ) { projectV2Item { id } }
+  }
+`;
+const CLEAR_SELECT = /* GraphQL */ `
+  mutation ClearSelect($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
+    clearProjectV2ItemFieldValue(input: { projectId: $projectId, itemId: $itemId, fieldId: $fieldId }) {
+      projectV2Item { id }
+    }
+  }
+`;
+/** Map one GraphQL issue node into the client's shape. The board values ride
+ *  as `projectItems`; everything GitHub-flavored is translated to aivi words
+ *  here and stops existing above this file. The `number` is the
+ *  repository-local one — `databaseId` is a global row id (billions for a
+ *  repo's 52nd issue) and appears in no id aivi builds. */
+function mapIssue(owner, name, node) {
+    const repo = `${owner}/${name}`;
+    const ref = repoIssueId(owner, name, node.number);
+    return {
+        id: node.id,
+        ref,
+        repo,
+        number: node.number,
+        title: node.title,
+        body: node.body ?? null,
+        url: node.url,
+        state: node.state === 'CLOSED' ? 'closed' : 'open',
+        stateReason: node.stateReason ? String(node.stateReason).toLowerCase() : null,
+        labels: (node.labels?.nodes ?? []).map(l => ({ id: l.id, name: l.name })),
+        assignees: (node.assignees?.nodes ?? []).map(a => ({ id: a.id, name: a.login })),
+        projectItems: (node.projectItems?.nodes ?? []).map(item => ({
+            itemId: item?.id ?? '',
+            boardNumber: Number(item?.project?.number),
+            values: (item?.fieldValues?.nodes ?? [])
+                .filter((v) => Boolean(v?.field?.name))
+                .map(v => ({ field: v.field.name, name: v.name ?? '', optionId: v.optionId ?? '' })),
+        })),
+        blockedBy: (node.blockedBy?.nodes ?? []).map(d => ({
+            id: repoIssueId(d.repository.owner.login, d.repository.name, d.number),
+            completed: dependencyCompleted(d.state === 'CLOSED' ? 'closed' : 'open'),
+        })),
+    };
+}
+/** The tracker's GitHub client: the app's octokit (from `@aivi/github`) with
+ *  the board's queries and the issue REST on it. One per process, shared
+ *  with nothing else: the forge's pull-request facts never come through here. */
+export class GithubClient {
+    app;
+    boards = new Map();
+    constructor(app) {
+        this.app = app;
+    }
+    /** Whose account made the grant (the org whose boards aivi reads). */
+    get org() {
+        return this.app.accountLogin;
+    }
+    /** The app's own login, GitHub's way: the bot suffix rides every post, and
+     *  inbound filtering reads it back. */
+    get botLogin() {
+        return `${this.app.appSlug}[bot]`;
+    }
+    /** The `Agent` option aivi delegates to: the option named for the app
+     *  itself (D5) — the same word on every board, resolved to a per-board
+     *  option id on use. */
+    get delegateName() {
+        return this.app.appSlug;
+    }
+    /** Resolve a board's `Status` and `Agent` fields and their options, once.
+     *  A board missing either is said by name — aivi never creates or renames
+     *  a Status option (D4), and the `Agent` field is setup's job. */
+    async boardFields(boardNumber) {
+        const known = this.boards.get(boardNumber);
+        if (known)
+            return known;
+        const { organization } = await this.app.octokit.graphql(BOARD_FIELDS, {
+            owner: this.org,
+            number: boardNumber,
+        });
+        const project = organization?.projectV2;
+        if (!project)
+            throw new Error(`board ${boardNumber} is not visible to the app in ${this.org}`);
+        let status;
+        let agent;
+        for (const field of project.fields?.nodes ?? [])
+            if (field?.name === STATUS_FIELD)
+                status = field;
+            else if (field?.name === AGENT_FIELD)
+                agent = field;
+        if (!status)
+            throw new Error(`board ${boardNumber} of ${this.org} has no "${STATUS_FIELD}" single-select field; lanes map onto its options and aivi never creates them`);
+        if (!agent)
+            throw new Error(`board ${boardNumber} of ${this.org} has no "${AGENT_FIELD}" single-select field; run the project setup — the Agent field is aivi's delegate surface (apps cannot be assignees)`);
+        const fields = {
+            projectId: project.id,
+            number: boardNumber,
+            statusFieldId: status.id,
+            statusOptions: (status.options ?? []).map(o => ({ id: o.id, name: o.name })),
+            agentFieldId: agent.id,
+            agentOptions: (agent.options ?? []).map(o => ({ id: o.id, name: o.name })),
+        };
+        this.boards.set(boardNumber, fields);
+        return fields;
+    }
+    /** The board's Status options, in board order — the lane names a mapping
+     *  is validated against. */
+    async laneOptions(boardNumber) {
+        return (await this.boardFields(boardNumber)).statusOptions;
+    }
+    async issue(id) {
+        const { owner, name, number } = issueRef(id);
+        const { repository } = await this.app.octokit.graphql(ISSUE_FACTS, {
+            owner,
+            repo: name,
+            number,
+        });
+        if (!repository?.issue)
+            throw new Error(`${id} answers nothing: the issue is gone or the app was not given it`);
+        return mapIssue(owner, name, repository.issue);
+    }
+    /** A repository's open issues, newest created first, each with its board
+     *  facts: the walk's read (the plan's per-issue `projectItems`, paid in one
+     *  round trip). Capped; a truncated read is said, never silently short. */
+    async openIssues(repo, cap = 100) {
+        const [owner, name] = repo.split('/');
+        const { repository } = await this.app.octokit.graphql(OPEN_ISSUES, {
+            owner,
+            repo: name,
+            first: cap,
+        });
+        const nodes = repository?.issues?.nodes ?? [];
+        return { issues: nodes.map(n => mapIssue(owner, name, n)), truncated: nodes.length >= cap };
+    }
+    /** The issue's lane on one board, read from its item: undefined when the
+     *  issue is not on that board at all. */
+    async laneOn(id, boardNumber) {
+        const issue = await this.issue(id);
+        return this.laneOf(issue, boardNumber);
+    }
+    laneOf(issue, boardNumber) {
+        const item = itemOn(issue, boardNumber);
+        const status = item?.values.find(v => v.field === STATUS_FIELD);
+        return status?.name ? { name: status.name, optionId: status.optionId } : undefined;
+    }
+    /** The issue's `Agent` value on one board: the option's name, or undefined
+     *  when nobody speaks for the ticket. */
+    agentOn(issue, boardNumber) {
+        const item = itemOn(issue, boardNumber);
+        const agent = item?.values.find(v => v.field === AGENT_FIELD);
+        return agent?.name || undefined;
+    }
+    /** Move an issue into a board's Status option: onto the board first (the
+     *  add is idempotent — a re-drive lands as nothing), then the option. The
+     *  mutation's own answer is the truth; a re-read right after lags. */
+    async setLane(id, boardNumber, lane) {
+        const fields = await this.boardFields(boardNumber);
+        const optionId = optionNamed(fields.statusOptions, lane);
+        if (!optionId)
+            throw new Error(`board ${boardNumber} of ${this.org} has no Status option "${lane}": map the lane to an option that exists — aivi never creates one`);
+        const issue = await this.issue(id);
+        let item = itemOn(issue, boardNumber);
+        if (!item) {
+            const { addProjectV2ItemById } = await this.app.octokit.graphql(ADD_ITEM, {
+                projectId: fields.projectId,
+                contentId: issue.id,
+            });
+            item = { itemId: addProjectV2ItemById?.item?.id ?? '', boardNumber, values: [] };
+        }
+        if (item.values.find(v => v.field === STATUS_FIELD)?.name === lane)
+            return; // already there
+        await this.app.octokit.graphql(SET_SELECT, {
+            projectId: fields.projectId,
+            itemId: item.itemId,
+            fieldId: fields.statusFieldId,
+            optionId,
+        });
+    }
+    /** Set (or with null, clear) the `Agent` field — the delegate in GitHub's
+     *  honest words (D5: an app cannot be an assignee, proven 403). */
+    async setAgent(id, boardNumber, delegate) {
+        const fields = await this.boardFields(boardNumber);
+        const issue = await this.issue(id);
+        const item = itemOn(issue, boardNumber);
+        if (!item)
+            throw new Error(`${id} is not on board ${boardNumber}; it has no Agent value to ${delegate ? 'set' : 'clear'}`);
+        if (!delegate) {
+            if (!this.agentOn(issue, boardNumber))
+                return; // nothing standing to clear
+            await this.app.octokit.graphql(CLEAR_SELECT, {
+                projectId: fields.projectId,
+                itemId: item.itemId,
+                fieldId: fields.agentFieldId,
+            });
+            return;
+        }
+        const optionId = optionNamed(fields.agentOptions, delegate);
+        if (!optionId)
+            throw new Error(`board ${boardNumber} of ${this.org} has no Agent option "${delegate}": run the project setup to create it`);
+        if (this.agentOn(issue, boardNumber) === delegate)
+            return; // already speaks
+        await this.app.octokit.graphql(SET_SELECT, {
+            projectId: fields.projectId,
+            itemId: item.itemId,
+            fieldId: fields.agentFieldId,
+            optionId,
+        });
+    }
+    /** Open an issue in a repository — the desk's escape hatch. Labels are
+     *  added by name (GitHub's own add is not create-on-demand, so each name
+     *  is ensured first). Landing on the board in a lane is `setLane`'s. */
+    async createIssue(repo, input) {
+        const [owner, name] = repo.split('/');
+        const made = await this.app.octokit.rest.issues.create({
+            owner: owner,
+            repo: name,
+            title: input.title,
+            ...(input.body !== undefined ? { body: input.body } : {}),
+        });
+        const id = repoIssueId(owner, name, made.data.number);
+        for (const label of input.labels ?? []) {
+            await this.ensureLabel(repo, label);
+            await this.app.octokit.rest.issues.addLabels({
+                owner: owner,
+                repo: name,
+                issue_number: made.data.number,
+                labels: [label],
+            });
+        }
+        return this.issue(id);
+    }
+    /** Rewrite the issue's own words; only what is named is touched. */
+    async updateIssue(id, changes) {
+        const { owner, name, number } = issueRef(id);
+        await this.app.octokit.rest.issues.update({
+            owner,
+            repo: name,
+            issue_number: number,
+            ...(changes.title !== undefined ? { title: changes.title } : {}),
+            ...(changes.description !== undefined ? { body: changes.description } : {}),
+        });
+        return this.issue(id);
+    }
+    /** The comment trail, oldest first, with the author in GitHub's words —
+     *  `authorIsBot` is how aivi's own posts are filtered inbound. */
+    async comments(id, cap = 300) {
+        const { owner, name, number } = issueRef(id);
+        const out = [];
+        for (let page = 1; out.length < cap; page += 1) {
+            const { data } = await this.app.octokit.rest.issues.listComments({
+                owner,
+                repo: name,
+                issue_number: number,
+                per_page: 100,
+                page,
+                sort: 'created',
+                direction: 'asc',
+            });
+            out.push(...data.map(c => ({
+                id: c.id,
+                author: c.user?.login ?? null,
+                authorIsBot: c.user?.type === 'Bot',
+                body: c.body ?? '',
+                at: c.created_at ?? c.updated_at ?? '',
+            })));
+            if (data.length < 100)
+                break;
+        }
+        return out;
+    }
+    /** Post a comment and answer with GitHub's own id — `startSession` hands
+     *  that back as the run's conversation handle (D6). */
+    async createComment(id, body) {
+        const { owner, name, number } = issueRef(id);
+        const made = await this.app.octokit.rest.issues.createComment({ owner, repo: name, issue_number: number, body });
+        return { id: made.data.id, url: made.data.html_url };
+    }
+    async updateComment(id, commentId, body) {
+        const { owner, name } = issueRef(id);
+        await this.app.octokit.rest.issues.updateComment({ owner, repo: name, comment_id: commentId, body });
+    }
+    /** One comment's body by id — the status comment's own read, the only
+     *  surface a progress edit may build on (never a remembered body). */
+    async getComment(id, commentId) {
+        const { owner, name } = issueRef(id);
+        try {
+            const { data } = await this.app.octokit.rest.issues.getComment({ owner, repo: name, comment_id: commentId });
+            return data.body ?? '';
+        }
+        catch (error) {
+            if (isGoneError(error))
+                return undefined;
+            throw error;
+        }
+    }
+    async deleteComment(id, commentId) {
+        const { owner, name } = issueRef(id);
+        await this.app.octokit.rest.issues.deleteComment({ owner, repo: name, comment_id: commentId });
+    }
+    /** The `owner/repo#n` behind a GraphQL node id — the `projects_v2_item`
+     *  payload names its issue only by node, and the board's events are worth
+     *  nothing until that resolves. The number is the repository-local one;
+     *  the node's `databaseId` is a global row id and resolves to no issue.
+     *  Non-issue nodes answer undefined. */
+    async nodeRef(nodeId) {
+        const { node } = await this.app.octokit.graphql(NODE_REF, { id: nodeId });
+        if (!node?.repository || node.number === undefined)
+            return undefined;
+        return repoIssueId(node.repository.owner.login, node.repository.name, node.number);
+    }
+    /** The repository's label catalogue — every name it knows. */
+    async repoLabels(repo, cap = 500) {
+        const [owner, name] = repo.split('/');
+        const out = [];
+        for (let page = 1; out.length < cap; page += 1) {
+            const { data } = await this.app.octokit.rest.issues.listLabelsForRepo({
+                owner: owner,
+                repo: name,
+                per_page: 100,
+                page,
+            });
+            out.push(...data.map(l => l.name));
+            if (data.length < 100)
+                break;
+        }
+        return out;
+    }
+    /** Put one label on the ticket, creating it in the repository when none
+     *  carries the name (add only, as the tool promises). */
+    async addLabel(id, label) {
+        const { owner, name, number } = issueRef(id);
+        await this.ensureLabel(id.slice(0, id.indexOf('#')), label);
+        await this.app.octokit.rest.issues.addLabels({ owner, repo: name, issue_number: number, labels: [label] });
+    }
+    async removeLabel(id, label) {
+        const { owner, name, number } = issueRef(id);
+        try {
+            await this.app.octokit.rest.issues.removeLabel({ owner, repo: name, issue_number: number, name: label });
+        }
+        catch (error) {
+            if (error.status === 404)
+                return; // not on the ticket: already off, said as done
+            throw error;
+        }
+    }
+    /** Create a label in the repository when none carries the name. The human
+     *  label does not exist on a GitHub repository until aivi makes it —
+     *  unlike Linear, where it must pre-exist. */
+    async ensureLabel(repo, name) {
+        const [owner, repoName] = repo.split('/');
+        try {
+            await this.app.octokit.rest.issues.getLabel({ owner: owner, repo: repoName, name });
+        }
+        catch (error) {
+            if (error.status !== 404)
+                throw error;
+            await this.app.octokit.rest.issues.createLabel({ owner: owner, repo: repoName, name, color: 'ededed' });
+        }
+    }
+    /** The assistant's marks (D10): reactions on the issue itself — `eyes`
+     *  while the assistant works, `rocket` when it answers. An assistive
+     *  surface only: no run state rides a reaction. */
+    async addReaction(id, content) {
+        const { owner, name, number } = issueRef(id);
+        await this.app.octokit.rest.reactions.createForIssue({ owner, repo: name, issue_number: number, content });
+    }
+    /** Take the assistant's own `eyes` off (a person's reactions are nobody to
+     *  touch: only reactions by aivi's bot are removed). */
+    async removeOwnReaction(id, content) {
+        const { owner, name, number } = issueRef(id);
+        for (let page = 1; page <= 3; page += 1) {
+            const { data } = await this.app.octokit.rest.reactions.listForIssue({
+                owner,
+                repo: name,
+                issue_number: number,
+                content,
+                per_page: 100,
+                page,
+            });
+            for (const reaction of data)
+                if (reaction.user?.login === this.botLogin)
+                    await this.app.octokit.rest.reactions.deleteForIssue({
+                        owner,
+                        repo: name,
+                        issue_number: number,
+                        reaction_id: reaction.id,
+                    });
+            if (data.length < 100)
+                break;
+        }
+    }
+}
+/** The tracker's client over the home's one app: connect through
+ *  `@aivi/github`, and the webhook secret is read where it lives. A missing
+ *  secret is a ConfigurationError the operator fixes in `<home>/.env` — no
+ *  delivery is verifiable without it, so the module refuses to start. */
+export async function githubClient(log) {
+    const app = await githubApp({ ...(log ? { log } : {}) });
+    const webhookSecret = process.env[GITHUB_WEBHOOK_SECRET_ENV];
+    if (!webhookSecret)
+        throw new ConfigurationError(`tracker-github: ${GITHUB_WEBHOOK_SECRET_ENV} is not set. Put the webhook secret you pasted on the app's settings page in <home>/.env; without it every delivery is unverifiable.`);
+    return { client: new GithubClient(app), webhookSecret };
+}

package/dist/config.d.ts

@@ -0,0 +1,60 @@
+import type { AiviPlugin } from '@aivi/plugin';
+import { z } from 'zod';
+/** The module id: the key of this plugin's block in `config.json`
+ *  (`plugins.tracker-github`), its `/status` id and its log category — the
+ *  package's short name, ruled 2026-09-30. What deliberately keeps the
+ *  shorter `github` is everything naming the **platform**: the SQLite table
+ *  prefix, the conversation prefix (`github:…`), the webhook route
+ *  (`/github/webhooks`) and the session origin. */
+export declare const MODULE_ID = "tracker-github";
+/** The board's own field names, as aivi created them (D5): the delegate
+ *  lives in `Agent`, the lane lives in `Status`. One pair of names for every
+ *  board; a board that lacks them fails setup with the remedy, not a guess. */
+export declare const STATUS_FIELD = "Status";
+export declare const AGENT_FIELD = "Agent";
+export declare const githubSchema: z.ZodObject<{
+    agent: z.ZodOptional<z.ZodString>;
+    humanLabel: z.ZodDefault<z.ZodString>;
+    pool: z.ZodDefault<z.ZodString>;
+    progress: z.ZodDefault<z.ZodEnum<{
+        silent: "silent";
+        status: "status";
+        tools: "tools";
+    }>>;
+    trust: z.ZodDefault<z.ZodEnum<{
+        everyone: "everyone";
+        members: "members";
+    }>>;
+}, z.core.$strict>;
+export type GithubConfig = z.infer<typeof githubSchema>;
+/** The plugin's section under a project entry (`projects.<id>.tracker-github`).
+ *  Core reads none of it. */
+export declare const githubProjectSchema: z.ZodObject<{
+    board: z.ZodNumber;
+    repos: z.ZodArray<z.ZodString>;
+    createLane: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type GithubProjectEntry = z.infer<typeof githubProjectSchema>;
+/** The plugin's section under `projectDefaults`. */
+export declare const githubProjectDefaultsSchema: z.ZodObject<{
+    createLane: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type GithubProjectDefaults = z.infer<typeof githubProjectDefaultsSchema>;
+/** The project's GitHub routing as it takes effect: which board speaks for it
+ *  and which repositories feed it. Lanes are not here — they are core's
+ *  ordered workflow on the `Project` itself, mapped onto the board's Status
+ *  options. */
+export interface ProjectGithub {
+    board: number;
+    repos: string[];
+    createLane?: string;
+}
+/** The assistant's agent name: `tracker-github.agent`, else the one assistant
+ *  everyone gets. */
+export declare function assistantAgent(github: GithubConfig | undefined): string;
+/** The registry entry: the block holds no paths (the credential is the
+ *  environment's, the board is named by number), so `home` finds nothing to
+ *  resolve here; the module code loads lazily. The project sections are
+ *  contributed here — core passes them through and this plugin reads them
+ *  back. */
+export declare const plugin: AiviPlugin<GithubConfig>;

package/dist/config.js

@@ -0,0 +1,99 @@
+/** The GitHub tracker's registry declaration, at its `./config` subpath: the
+ *  module id, the block's own schema, and the bridge to the module code. The
+ *  CLI imports this for every command, so nothing here pulls octokit.
+ *
+ *  One board is one project's whole board (ruled 2026-10-07): the block names
+ *  the projectsV2 board by number, the repositories whose issues feed it, and
+ *  nothing else. The **lanes are core's** (`projects.<id>.lanes`, ordered);
+ *  they map onto the board's own `Status` options, and aivi never creates or
+ *  renames one (D4) — a lane whose option is missing is said, never guessed
+ *  past. The `Agent` single-select field is aivi's own (D5): apps cannot be
+ *  assignees (proven 403), so the board carries the delegate in a field aivi
+ *  created. The app's identity is the environment's — `GITHUB_APP_ID` and
+ *  `GITHUB_APP_PRIVATE_KEY` in `<home>/.env`, shared with the forge through
+ *  `@aivi/github`.
+ */
+import { PROJECT_ID } from '@aivi/core';
+import { z } from 'zod';
+const id = z.string().regex(PROJECT_ID);
+/** The module id: the key of this plugin's block in `config.json`
+ *  (`plugins.tracker-github`), its `/status` id and its log category — the
+ *  package's short name, ruled 2026-09-30. What deliberately keeps the
+ *  shorter `github` is everything naming the **platform**: the SQLite table
+ *  prefix, the conversation prefix (`github:…`), the webhook route
+ *  (`/github/webhooks`) and the session origin. */
+export const MODULE_ID = 'tracker-github';
+/** The board's own field names, as aivi created them (D5): the delegate
+ *  lives in `Agent`, the lane lives in `Status`. One pair of names for every
+ *  board; a board that lacks them fails setup with the remedy, not a guess. */
+export const STATUS_FIELD = 'Status';
+export const AGENT_FIELD = 'Agent';
+export const githubSchema = z.strictObject({
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The OpenCode agent that answers people on GitHub — comment mentions no run is working: the assistant. Default: the aivi name.'),
+    humanLabel: z
+        .string()
+        .min(1)
+        .default('needs-human')
+        .describe('Issues carrying this label are never worked automatically; setup creates it in each mapped repository.'),
+    pool: id.default('default').describe('Dispatcher pool an assistant turn takes a slot in.'),
+    progress: z
+        .enum(['silent', 'status', 'tools'])
+        .default('tools')
+        .describe('What the status comment shows while a worker runs: silent, the one line, or the line with its tool.'),
+    trust: z
+        .enum(['members', 'everyone'])
+        .default('members')
+        .describe('Who comments may reach aivi — form answers, run steering, the assistant. `members`: GitHub’s OWNER, MEMBER and COLLABORATOR only; a CONTRIBUTOR or a stranger is heard as nothing, not a word and not a log line. `everyone`: any GitHub user.'),
+});
+/** The plugin's section under a project entry (`projects.<id>.tracker-github`).
+ *  Core reads none of it. */
+export const githubProjectSchema = z.strictObject({
+    board: z
+        .number()
+        .int()
+        .positive()
+        .describe('The projectsV2 board number — the number at the end of the board’s URL (`.../projects/<org>/1` is board 1). Its Status options are the lanes; aivi never edits them.'),
+    repos: z
+        .array(z.string().min(3))
+        .min(1)
+        .describe('Repositories whose issues belong to this project, as `owner/name`. A repository maps to at most one project.'),
+    createLane: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Where `aivi_ticket_create` lands a new ticket — a Status option name. Default: the project’s first configured lane; with none matching, the repository’s own default.'),
+});
+/** The plugin's section under `projectDefaults`. */
+export const githubProjectDefaultsSchema = z.strictObject({
+    createLane: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Where `aivi_ticket_create` lands a new ticket in every project unless it names its own.'),
+});
+/** The assistant's agent name: `tracker-github.agent`, else the one assistant
+ *  everyone gets. */
+export function assistantAgent(github) {
+    return github?.agent ?? 'assistant';
+}
+/** The registry entry: the block holds no paths (the credential is the
+ *  environment's, the board is named by number), so `home` finds nothing to
+ *  resolve here; the module code loads lazily. The project sections are
+ *  contributed here — core passes them through and this plugin reads them
+ *  back. */
+export const plugin = {
+    id: MODULE_ID,
+    configSchema: githubSchema,
+    projectSchema: githubProjectSchema,
+    projectDefaultsSchema: githubProjectDefaultsSchema,
+    // The lazy load is the design: the CLI reads this file's schema without
+    // pulling the host's world in, and the module arrives only when the host
+    // actually builds. The cycle back into this file (the module imports its
+    // own schema) is that design, not a tangle.
+    // fallow-ignore-next-line circular-dependency
+    createModule: config => import('./module.js').then(m => m.createGithubModule(config)),
+};