@aivi/tracker-github 0.0.0-stage → 1.0.0

package/dist/work.d.ts

@@ -0,0 +1,60 @@
+import type { Logger } from '@aivi/core';
+import type { AiviServices } from '@aivi/plugin';
+import type { GithubClient } from './client.ts';
+import type { GithubConfig } from './config.ts';
+/** The ticket's own words: what it is, what it says. This is the **summary**
+ *  `initWork` hands the orchestrator, and the orchestrator composes the
+ *  worker's first prompt around it — the same dossier for a queue pickup
+ *  and a plain walk claim: the ticket's text does not depend on how the
+ *  worker was reached. */
+export declare const issueDossier: (issue: {
+    identifier: string;
+    title: string;
+    description: string | null;
+}) => string;
+/** What the walk reads and what `initWork` opens through: the GitHub board,
+ *  in the installation's own credentials. */
+export interface GithubBoard {
+    projects(): string[];
+    tickets(projectId: string, lane: string): Promise<{
+        id: string;
+        blocked: boolean;
+    }[]>;
+    moveTo(projectId: string, ticketId: string, lane: string): Promise<void>;
+    /** The ticket fresh from the board, or undefined when a person deleted it. */
+    issue(ticketId: string): Promise<GithubIssueWords | undefined>;
+}
+/** The fields of a listed issue the tracker's stages speak with. */
+export interface GithubIssueWords {
+    identifier: string;
+    title: string;
+    description: string | null;
+    /** The repository — GitHub's team. */
+    teamId: string;
+    /** The ticket's Status on the board its repository feeds; '' when the
+     *  repository feeds no project. */
+    stateName: string;
+    /** GitHub names no branch; the tracker generates one (D8). */
+    branchName: string;
+}
+/**
+ * The GitHub board as the orchestrator's eligibility walk reads it
+ * (docs/orchestrator.md, "How work gets picked"): which projects this
+ * installation speaks for, what sits in a lane, and how a ticket enters one.
+ *
+ * A GitHub repository **is** the team: a project maps its repositories to one
+ * projectsV2 board (D1 — one tracker per project, and the walk visits the
+ * project's lanes as the board's Status options). The walk's order is each
+ * repository's open issues, newest created first — GitHub's own list order;
+ * the board's per-view ordering is a person's reading and no eligibility
+ * depends on it.
+ *
+ * What comes back **is** eligible work: closed tickets are out of the listing
+ * entirely, and out here go the tickets carrying the human-work label and the
+ * tickets with any `Agent` value — someone already speaks for them, aivi
+ * included (a hand-set `Agent` gets the fixed refusal in the module, and the
+ * walk starts nothing twice). A stop is not remembered here (ruled
+ * 2026-10-02): a stopped ticket goes back to the board, and "not that one
+ * again" is the human label's job, not a memory in somebody's database.
+ */
+export declare function githubBoard(config: GithubConfig, services: Pick<AiviServices, 'loaded'>, client: GithubClient, log: Logger): GithubBoard;

package/dist/work.js

@@ -0,0 +1,83 @@
+import { projectForIssue, projectGithub } from './projects.js';
+/** The ticket's own words: what it is, what it says. This is the **summary**
+ *  `initWork` hands the orchestrator, and the orchestrator composes the
+ *  worker's first prompt around it — the same dossier for a queue pickup
+ *  and a plain walk claim: the ticket's text does not depend on how the
+ *  worker was reached. */
+export const issueDossier = (issue) => `<issue identifier="${issue.identifier}"><title>${issue.title}</title><description>${issue.description ?? ''}</description></issue>`;
+/**
+ * The GitHub board as the orchestrator's eligibility walk reads it
+ * (docs/orchestrator.md, "How work gets picked"): which projects this
+ * installation speaks for, what sits in a lane, and how a ticket enters one.
+ *
+ * A GitHub repository **is** the team: a project maps its repositories to one
+ * projectsV2 board (D1 — one tracker per project, and the walk visits the
+ * project's lanes as the board's Status options). The walk's order is each
+ * repository's open issues, newest created first — GitHub's own list order;
+ * the board's per-view ordering is a person's reading and no eligibility
+ * depends on it.
+ *
+ * What comes back **is** eligible work: closed tickets are out of the listing
+ * entirely, and out here go the tickets carrying the human-work label and the
+ * tickets with any `Agent` value — someone already speaks for them, aivi
+ * included (a hand-set `Agent` gets the fixed refusal in the module, and the
+ * walk starts nothing twice). A stop is not remembered here (ruled
+ * 2026-10-02): a stopped ticket goes back to the board, and "not that one
+ * again" is the human label's job, not a memory in somebody's database.
+ */
+export function githubBoard(config, services, client, log) {
+    /** A ticket the walk may start: not a person's to work, and nobody already
+     *  speaks for it — not eligible, and never knocked twice. */
+    const walkable = (issue) => !issue.completed && !issue.labels.some(l => l.name === config.humanLabel) && !issue.agent;
+    return {
+        projects: () => services.loaded.projects.filter(p => !p.removed && projectGithub(services.loaded, p.id)).map(p => p.id),
+        tickets: async (projectId, lane) => {
+            const github = projectGithub(services.loaded, projectId);
+            if (!github)
+                return [];
+            const out = [];
+            for (const repo of github.repos) {
+                const read = await client.openIssues(repo);
+                if (read.truncated)
+                    log.warn('walk.board.truncated', { project: projectId, lane, repo });
+                for (const issue of read.issues) {
+                    const standing = client.laneOf(issue, github.board);
+                    if (!standing || standing.name !== lane)
+                        continue; // not on this board, not in this lane
+                    if (!walkable({
+                        completed: issue.state === 'closed',
+                        labels: issue.labels,
+                        agent: client.agentOn(issue, github.board),
+                    }))
+                        continue;
+                    out.push({ id: issue.ref, blocked: issue.blockedBy.some(b => !b.completed) });
+                }
+            }
+            return out;
+        },
+        moveTo: async (projectId, ticketId, lane) => {
+            const github = projectGithub(services.loaded, projectId);
+            if (!github)
+                throw new Error(`project ${projectId} has no GitHub board: ${ticketId} cannot enter lane "${lane}"`);
+            // Idempotence is the board's promise: the orchestrator re-drives an
+            // owed move after a retry and from the next boot, and a move that
+            // already landed lands here as nothing — no second word to GitHub.
+            // (The client holds that check: onto the board first, then the option,
+            // and an option it lacks is said by name, never created.)
+            await client.setLane(ticketId, github.board, lane);
+        },
+        issue: async (ticketId) => {
+            const issue = await client.issue(ticketId);
+            const github = projectForIssue(services.loaded, { repo: issue.repo })?.github;
+            const lane = github ? client.laneOf(issue, github.board) : undefined;
+            return {
+                identifier: issue.ref,
+                title: issue.title,
+                description: issue.body,
+                teamId: issue.repo,
+                stateName: lane?.name ?? '',
+                branchName: '',
+            };
+        },
+    };
+}

package/docs/github-tracker.md

@@ -0,0 +1,122 @@
+# GitHub — the tracker's configuration
+
+The `plugins.tracker-github` block is the GitHub tracker's whole setup; the
+module runs when `@aivi/tracker-github` stands in the `aivi-plugins` list. The
+key is the package name; the database's prefix, the conversation ids
+(`github:…`), the webhook route `/github/webhooks` and the `aivi github`
+command keep the platform's short name, since those say who a conversation is
+on rather than which package speaks for it.
+
+```json
+{
+  "plugins": {
+    "tracker-github": {
+      "agent": "assistant",
+      "humanLabel": "needs-human",
+      "pool": "default",
+      "progress": "tools",
+      "trust": "members"
+    }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `agent` | The OpenCode agent that answers people on GitHub — comment mentions no run is working: the **assistant**. A hand delegation is never its to answer: those get the fixed refusal. Default: `assistant` |
+| `humanLabel` | Issues carrying this label are never worked automatically; a failed closing and a hand-delegation refusal mark with it. Unlike Linear, where it must pre-exist, `aivi projects add` **creates** it in every mapped repository |
+| `pool` | Dispatcher pool an assistant turn takes a slot in (must exist in `dispatcher.pools` when pools are configured) |
+| `progress` | `silent`, `status` or `tools`: what the status comment shows while a worker runs |
+| `trust` | Who comments may reach aivi — form answers, run steering, the assistant. `members`: GitHub's own `author_association` of OWNER, MEMBER or COLLABORATOR only; `everyone`: any GitHub user. A read per delivery, so a promotion or a removal lands at once. Default: `members` |
+
+On a public repository anyone may comment. The trust line sits on the
+comment event alone — one gate for all three paths — and a comment below it
+is heard as nothing: no reply (silence does not advertise the bot), no log
+line (drive-by comments are a public repository's weather). The other two
+events need no gate: a lane or label move needs write access GitHub itself
+enforces.
+
+The project entry names its **board** and the **repositories** that hold
+its issues. The board's own deliveries name the board and route by its id;
+the ticket's own deliveries — comments and labels — name only the
+repository, so `repos` is what claims them for the project. The ticket's
+words live in the repository too: its title, body, comments, reactions, and
+the `needs-human` label. One board is one project's whole board; a
+repository feeds at most one project. The workflow
+is not a GitHub field: it is **core's** lane array on the project,
+`projects.<id>.lanes` — left to right, the order **is** the priority, and the
+names are the board's own `Status` options:
+
+```json
+{
+  "projects": {
+    "website": {
+      "tracker-github": { "board": 1, "repos": ["acme/shop"] },
+      "lanes": [
+        { "name": "Todo", "queue": true },
+        { "name": "In Progress", "agent": "dev", "worktree": true },
+        { "name": "Review", "agent": "reviewer" }
+      ]
+    }
+  }
+}
+```
+
+A lane naming an `agent` is worked; one naming none is worked by humans; a
+Status option named nowhere in the array is silence. `queue: true` marks the
+workflow's **one** queue lane, with the same load rules as Linear's wizard.
+**GitHub says nothing about what a Status option means** — options carry no
+state flag, and a board workflow's rule is not in the API. So the wizard
+asks what every option is, in board order:
+**Agent** (aivi delegates tickets there to an agent), **Human** (aivi ignores
+tickets there; it is only ever used as a queue or a destination), or **None**
+(the option is not part of aivi's workflow: never read, never moved into).
+A ticket's open or closed state is the board's workflows' business; aivi
+never works a closed ticket and ignores everything else about it.
+`aivi projects add` writes the array for you. `board` and `repos` are never
+defaulted.
+
+The board's `Status` options are the lanes, and aivi **never creates or
+renames** them (D4): a lane whose option the board does not carry is said, not
+guessed past. The delegate is the board's `Agent` single-select, with the
+option named for the app itself (`aivi-agent`) — apps cannot be assignees on
+GitHub (proven 403), so the board carries the delegation in a field aivi
+created (D5). `aivi projects add` creates that field on a yes and appends it
+to every view's visible fields — the view configuration **replaces**, so each
+view is read first and written back whole; running the wizard twice writes
+nothing the second time. Routing reads the field, not the view; the view is
+so operators can see the delegation.
+
+Credentials are never in JSON, and the app is never the tracker's own. The
+forge and the tracker are **one app** (D3): its identity is the bare
+`GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` in `<home>/.env`, shared with
+`@aivi/forge-github` through `@aivi/github` — installing either asks once. The
+webhook's HMAC secret is `GITHUB_WEBHOOK_SECRET`, beside them — the installer
+asks for it only when the home does not already hold one, and the wait proves
+whichever it has. The app's
+webhook must deliver `issue_comment`, `issues` and `projects_v2_item` to
+`<host.public>/github/webhooks`.
+
+`aivi add @aivi/tracker-github` proves the grant before it writes a byte:
+the app's own JWT reads the permissions (Issues and Organization projects,
+both write), the subscribed events, and where the webhook points. Then one
+wait proves the secret against a live delivery: the installer re-asks GitHub
+for the newest `installation` delivery in its last 25 and watches the replay
+land at this aivi's route with a seal that verifies. When the history holds
+none — the app was installed before this webhook pointed here — or GitHub
+refuses the replay, **no wait runs**: a trigger that cannot come is never sat
+out. The person reinstalls the app and retries, or skips webhook
+verification, and the summary says UNVERIFIED. This installer **writes
+nothing at GitHub**. A live aivi is asked as a choice,
+never presumed: no health answer offers "I started the server. Retry" or
+"Continue anyway", and continuing writes the configuration with UNVERIFIED —
+the unproved fact is precisely "GitHub can reach this machine" — in the
+summary. The board itself is probed by `aivi projects add`, where the board
+id is in hand: a test card pays the tracker's every mutation — Status moves
+to the next option in board order the card is not on — and the diary must
+echo each delivery back seal-verified. The eyes reaction is paid and read
+back, not waited for: GitHub posts reaction events only to subscribers, and
+aivi is not one. Then the card is cleared, archived, its reaction and comment
+deleted, and closed not-planned — unless a workflow on the board closed the
+card first, in which case aivi says how GitHub left it. GitHub has no API to
+delete an issue. Restart `aivi serve` to load the tracker.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@aivi/tracker-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "The GitHub tracker for aivi: the projectsV2 board the walk reads, the issues a worker works, and the status comment that is the run's conversation.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "development": "./src/config.ts",
+      "default": "./dist/config.js"
+    },
+    "./setup": {
+      "development": "./src/setup.ts",
+      "default": "./dist/setup.js"
+    },
+    "./setupProject": {
+      "development": "./src/setup-project.ts",
+      "default": "./dist/setup-project.js"
+    },
+    "./cli": {
+      "development": "./src/cli.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=26.1.0 <27"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aivi-hq/aivi.git",
+    "directory": "packages/tracker-github"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "tsc -b tsconfig.build.json"
+  },
+  "dependencies": {
+    "@aivi/core": "^1.0.0",
+    "@aivi/github": "^1.0.0",
+    "@aivi/host": "^1.0.0",
+    "@aivi/plugin": "^1.0.0",
+    "commander": "15.0.0",
+    "zod": "4.1.13"
+  },
+  "peerDependencies": {
+    "@aivi/host": "^1.0.0"
+  },
+  "devDependencies": {
+    "@aivi/host": "^1.0.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.