@aivi/tracker-github 0.0.0-stage → 0.0.0

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+/** The GitHub tracker module's operator commands, mounted into the server CLI
+ *  through the `./cli` subpath contract (@aivi/plugin's `(ctx) => Command`):
+ *  status and resolve, over the same conversation store the module runs on.
+ *  The command keeps the platform's short name — `aivi github` — for the same
+ *  reason the conversations and the route do: they say who a conversation is
+ *  on, not which package speaks for it. */
+import type { PluginCliContext } from '@aivi/plugin';
+import { Command } from 'commander';
+export default _default;
+declare function _default(ctx: PluginCliContext): Command;

package/dist/cli.js

@@ -0,0 +1,34 @@
+import { resolveBlocked } from '@aivi/plugin';
+import { Command } from 'commander';
+const enabled = async (ctx) => {
+    const loaded = await ctx.loaded();
+    const config = loaded.config.plugins['tracker-github'];
+    if (!config)
+        throw new Error('the GitHub tracker is not configured in config.json (no plugins.tracker-github block)');
+    return config;
+};
+export default (ctx) => {
+    const github = new Command('github').description('the GitHub tracker');
+    github
+        .command('status')
+        .description('Inspect GitHub conversations (workers and the assistant)')
+        .action(async () => {
+        await enabled(ctx);
+        const { describeWorkers, openGithubStore } = await import('./index.js');
+        await ctx.withStore(store => {
+            const inbox = openGithubStore(store);
+            ctx.print({ conversations: describeWorkers(inbox) });
+        });
+    });
+    github
+        .command('resolve <id>')
+        .description('Release a blocked worker')
+        .requiredOption('--reason <text>', 'what was found and done')
+        .requiredOption('--confirm-stopped', 'the external side has stopped')
+        .action(async (id, options) => {
+        await enabled(ctx);
+        const { openGithubStore } = await import('./index.js');
+        await resolveBlocked(ctx, id, options.reason, store => openGithubStore(store));
+    });
+    return github;
+};

package/dist/client.d.ts

@@ -0,0 +1,247 @@
+/** 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 type { Logger } from '@aivi/core';
+import { type GitHubApp } from '@aivi/github';
+/** `owner/repo#47` — the issue id aivi speaks, parsed. `owner` and `name`
+ *  are the two words octokit asks for; the full id is the string it came from. */
+export interface IssueRef {
+    owner: string;
+    name: string;
+    number: number;
+}
+export declare function issueRef(id: string): IssueRef;
+export declare const repoIssueId: (owner: string, name: string, number: number) => string;
+/** One single-select value of a board item: the option's name and id, and
+ *  which field it answers (`Status`, `Agent`). */
+export interface ItemSelectValue {
+    field: string;
+    name: string;
+    optionId: string;
+}
+/** One board item of an issue: the board's org-level number, the item's node
+ *  id, and its single-select values. */
+export interface BoardItem {
+    itemId: string;
+    boardNumber: number;
+    values: ItemSelectValue[];
+}
+/** A dependency as the issue reports it. */
+export interface IssueDependency {
+    id: string;
+    completed: boolean;
+}
+/** An issue as GitHub answers it — the client's own shape, before the
+ *  adapter translates. `projectItems` carries the board facts; a caller who
+ *  cares about one board filters by `boardNumber`. */
+export interface GithubIssue {
+    id: string;
+    ref: string;
+    repo: string;
+    number: number;
+    title: string;
+    body: string | null;
+    url: string;
+    state: 'open' | 'closed';
+    stateReason: string | null;
+    labels: {
+        id: string;
+        name: string;
+    }[];
+    assignees: {
+        id: string;
+        name: string;
+    }[];
+    projectItems: BoardItem[];
+    blockedBy: IssueDependency[];
+}
+/** A comment as GitHub answers it. */
+export interface GithubComment {
+    id: number;
+    author: string | null;
+    authorIsBot: boolean;
+    body: string;
+    at: string;
+}
+/** The board's own fields, resolved once per start (the options a walk
+ *  matches lanes against change when a person changes them, and a restart is
+ *  when aivi learns of that): the node ids of `Status` and `Agent` and their
+ *  options, in board order. */
+export interface BoardFields {
+    projectId: string;
+    number: number;
+    statusFieldId: string;
+    statusOptions: {
+        id: string;
+        name: string;
+    }[];
+    agentFieldId: string;
+    agentOptions: {
+        id: string;
+        name: string;
+    }[];
+}
+/** 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 declare const dependencyCompleted: (state: string) => boolean;
+/** The GraphQL node shapes these documents answer with: the looseness stays
+ *  in the query documents, the mapping code below speaks types. Shared with
+ *  setup-project, which reads the same board. */
+export type GqlOption = {
+    id: string;
+    name: string;
+};
+export type GqlField = {
+    id: string;
+    name?: string | null;
+    options?: GqlOption[] | null;
+};
+export type GqlView = {
+    id: string;
+    name?: string | null;
+    fields?: {
+        nodes?: {
+            id?: string | null;
+        }[];
+    } | null;
+};
+export type GqlBoard = {
+    id: string;
+    title: string;
+    fields?: {
+        nodes?: (GqlField | null)[];
+    } | null;
+    views?: {
+        nodes?: (GqlView | null)[];
+    } | null;
+};
+/** 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 declare const isGoneError: (error: unknown) => boolean;
+/** 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 declare class GithubClient {
+    private readonly app;
+    private readonly boards;
+    constructor(app: GitHubApp);
+    /** Whose account made the grant (the org whose boards aivi reads). */
+    get org(): string;
+    /** The app's own login, GitHub's way: the bot suffix rides every post, and
+     *  inbound filtering reads it back. */
+    get botLogin(): string;
+    /** 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(): string;
+    /** 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. */
+    boardFields(boardNumber: number): Promise<BoardFields>;
+    /** The board's Status options, in board order — the lane names a mapping
+     *  is validated against. */
+    laneOptions(boardNumber: number): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    issue(id: string): Promise<GithubIssue>;
+    /** 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. */
+    openIssues(repo: string, cap?: number): Promise<{
+        issues: GithubIssue[];
+        truncated: boolean;
+    }>;
+    /** The issue's lane on one board, read from its item: undefined when the
+     *  issue is not on that board at all. */
+    laneOn(id: string, boardNumber: number): Promise<{
+        name: string;
+        optionId: string;
+    } | undefined>;
+    laneOf(issue: GithubIssue, boardNumber: number): {
+        name: string;
+        optionId: string;
+    } | undefined;
+    /** The issue's `Agent` value on one board: the option's name, or undefined
+     *  when nobody speaks for the ticket. */
+    agentOn(issue: GithubIssue, boardNumber: number): string | 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. */
+    setLane(id: string, boardNumber: number, lane: string): Promise<void>;
+    /** Set (or with null, clear) the `Agent` field — the delegate in GitHub's
+     *  honest words (D5: an app cannot be an assignee, proven 403). */
+    setAgent(id: string, boardNumber: number, delegate: string | null): Promise<void>;
+    /** 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. */
+    createIssue(repo: string, input: {
+        title: string;
+        body?: string;
+        labels?: string[];
+    }): Promise<GithubIssue>;
+    /** Rewrite the issue's own words; only what is named is touched. */
+    updateIssue(id: string, changes: {
+        title?: string;
+        description?: string;
+    }): Promise<GithubIssue>;
+    /** The comment trail, oldest first, with the author in GitHub's words —
+     *  `authorIsBot` is how aivi's own posts are filtered inbound. */
+    comments(id: string, cap?: number): Promise<GithubComment[]>;
+    /** Post a comment and answer with GitHub's own id — `startSession` hands
+     *  that back as the run's conversation handle (D6). */
+    createComment(id: string, body: string): Promise<{
+        id: number;
+        url: string;
+    }>;
+    updateComment(id: string, commentId: number, body: string): Promise<void>;
+    /** 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). */
+    getComment(id: string, commentId: number): Promise<string | undefined>;
+    deleteComment(id: string, commentId: number): Promise<void>;
+    /** 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. */
+    nodeRef(nodeId: string): Promise<string | undefined>;
+    /** The repository's label catalogue — every name it knows. */
+    repoLabels(repo: string, cap?: number): Promise<string[]>;
+    /** Put one label on the ticket, creating it in the repository when none
+     *  carries the name (add only, as the tool promises). */
+    addLabel(id: string, label: string): Promise<void>;
+    removeLabel(id: string, label: string): Promise<void>;
+    /** 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. */
+    ensureLabel(repo: string, name: string): Promise<void>;
+    /** 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. */
+    addReaction(id: string, content: 'eyes' | 'rocket'): Promise<void>;
+    /** Take the assistant's own `eyes` off (a person's reactions are nobody to
+     *  touch: only reactions by aivi's bot are removed). */
+    removeOwnReaction(id: string, content: 'eyes' | 'rocket'): Promise<void>;
+}
+/** 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 declare function githubClient(log?: Logger): Promise<{
+    client: GithubClient;
+    webhookSecret: string;
+}>;