@aivi/tracker-github 0.0.0-stage → 1.0.0

package/dist/runprogress.js

@@ -0,0 +1,122 @@
+/**
+ * The worker run's **progress stream**: while a run works, its OpenCode
+ * session is mirrored into the ticket through the platform's transient
+ * progress surface (`Platform.progress`) — GitHub edits the run's status
+ * comment in place, the one line that says what the worker is doing right
+ * now (ruled 2026-10-02: ephemeral by contract — a replaced line must not
+ * linger, and GitHub has no ephemeral activity, so one comment edited is the
+ * honest equivalent). 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 edit 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 edit 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.edit.failed', { error }));
+    }
+}

package/dist/setup-project.d.ts

@@ -0,0 +1,125 @@
+import { type Logger, type ProjectLaneInput } from '@aivi/core';
+import { type GitHubApp } from '@aivi/github';
+import { type ProjectContributor } from '@aivi/plugin';
+/** One Status option, as GitHub answers it: an id, a name, and nothing
+ *  else. **GitHub says nothing about what an option means**:
+ *  `ProjectV2SingleSelectFieldOption` carries
+ *  `color, description, descriptionHTML, id, name, nameHTML` and no state
+ *  flag — asking for `status` fails the whole read, because GraphQL rejects a
+ *  query naming a field that does not exist. What a Status change does to an
+ *  issue is the board's workflows, and a workflow's rule is not in the API
+ *  either (`ProjectV2Workflow` answers id, name, number, enabled and dates).
+ *  So the person decides what each option is: see `askLanes`. The org node id
+ *  (on the board) is what a field creation is addressed to. */
+export interface SetupBoardOption {
+    id: string;
+    name: string;
+}
+export interface SetupBoard {
+    id: string;
+    /** The board's number in the org — what the `tracker-github` section stores. */
+    number: number;
+    orgId: string;
+    title: string;
+    statusOptions: SetupBoardOption[];
+    /** The `Status` field's own id — the probe mutates it directly. */
+    statusFieldId: string;
+    agentFieldId?: string;
+    /** The `Agent` field's options; empty when the board has no such field yet. */
+    agentOptions: {
+        id: string;
+        name: string;
+    }[];
+}
+/** The board probe's test card: what the wait must hear back (`asked` names
+ *  the signals — probe.ts's `BOARD_SIGNALS` words), and everything cleanup
+ *  needs. `statusSkipped` is a board with a single Status option, where no
+ *  move can be shown: said as skipped, never as a failure. */
+export interface ProbeHandles {
+    ref: string;
+    number: number;
+    /** The issue's node id: board deliveries name no number, only this. */
+    nodeId: string;
+    itemId: string;
+    projectId: string;
+    agentFieldId: string;
+    commentId: number;
+    asked: string[];
+    statusSkipped: boolean;
+}
+/** The wizard's crossing to GitHub, injectable like Linear's `MakeTeamsClient`:
+ *  the questions, their order, and the written config are the unit under test;
+ *  the GraphQL round trips are the live gate's. `delegate` is the `Agent`
+ *  option name the app delegates as — its own login (D5). */
+export interface GithubSetupClient {
+    readonly delegate: string;
+    readBoard(boardNumber: number): Promise<SetupBoard>;
+    createAgentField(board: SetupBoard, delegate: string): Promise<void>;
+    /** Append the `Agent` field to every view that does not show it — the
+     *  mutation replaces, so each view is read first and written back whole.
+     *  Answers the view names it changed; idempotent. */
+    showAgentOnViews(board: SetupBoard, agentFieldId: string): Promise<string[]>;
+    repositories(): Promise<{
+        id: string;
+    }[]>;
+    ensureLabel(repo: string, label: string): Promise<void>;
+    /** Pay the tracker's mutations on one throwaway issue: open, add to board,
+     *  move Status, set Agent, comment, react — everything the tracker will
+     *  ever do, and everything the diary must echo back (the reaction aside:
+     *  paid and read back, no delivery subscribes). */
+    openProbe(repo: string, board: SetupBoard): Promise<ProbeHandles>;
+    /** Lay the test card to rest: Agent cleared, item archived, own reaction
+     *  removed, comment deleted — then close, **unless GitHub's own workflow
+     *  already closed it**: answers one line saying how the card rests, in
+     *  GitHub's real terms. GitHub has no API to delete an issue. */
+    closeProbe(handles: ProbeHandles): Promise<string>;
+}
+export type MakeSetupClient = (log: Logger) => Promise<GithubSetupClient>;
+/** The production crossing: the home's app (D3 — the wizard and the module
+ *  speak through one credential), read through the tracker's own client.
+ *  Exported for the test that scripts GitHub's answers and proves the probe's
+ *  own choices — which Status option it pays, the reaction it reads back, and
+ *  whose close it reports. */
+export declare class BoardSetupClient implements GithubSetupClient {
+    private readonly app;
+    private readonly tracker;
+    constructor(app: GitHubApp);
+    get delegate(): string;
+    readBoard(boardNumber: number): Promise<SetupBoard>;
+    createAgentField(board: SetupBoard, delegate: string): Promise<void>;
+    showAgentOnViews(board: SetupBoard, agentFieldId: string): Promise<string[]>;
+    repositories(): Promise<{
+        id: string;
+    }[]>;
+    ensureLabel(repo: string, label: string): Promise<void>;
+    openProbe(repo: string, board: SetupBoard): Promise<ProbeHandles>;
+    closeProbe(handles: ProbeHandles): Promise<string>;
+}
+/** The lanes the queue question may offer (ruled 2026-10-02, mirrored from
+ *  Linear's wizard): a queue lane must feed a worker lane, so a lane whose next
+ *  works nobody is no candidate, the last lane feeds nothing at all, and a lane
+ *  that has an agent is never an option — a queue is where people wait for a
+ *  worker, not a worker lane itself. A **human** lane is a legal queue: that is
+ *  what "used as a queue" means in the answer's own words. */
+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. The
+ *  returned lines are what the caller logs. */
+export declare function markQueue(lanes: ProjectLaneInput[], chosen: string): string[];
+/** The project name a board title suggests: GitHub's `My Board` becomes aivi's
+ *  `my-board`, the shape a project directory takes (the forge's rule for repo
+ *  names, turned on a title). Anything the id rule does not allow becomes a
+ *  dash, and a name that no longer starts with a letter keeps one. */
+export declare function boardSuggestion(title: string): string;
+/** The wizard, in its order: the health gate as a choice, the board, the
+ *  delegate surface and its view visibility, the repositories, the project's
+ *  name, what kind of lane each Status option is (agent, human, or none),
+ *  the queue over the no-agent lanes,
+ *  the human label in every mapped repository — and, when a live aivi was
+ *  there to watch, the board probe last: it pays real mutations, so it comes
+ *  after everything it tests. Each step is its own question and its own
+ *  honest failure; the whole is the ruling. */
+declare function makeContributor(makeClient?: MakeSetupClient): ProjectContributor;
+export declare const contributor: ProjectContributor;
+export { makeContributor };
+export default contributor;