@aivi/tracker-linear 0.0.0-stage → 1.0.0

package/dist/setup-project.js

@@ -0,0 +1,254 @@
+/** Linear's project-setup contributor, at its `./setupProject` subpath: it
+ *  maps a new project to Linear teams and offers the project's lane array —
+ *  the board's states in board order, each asked what kind of lane it is
+ *  (agent, human, or none). It clones
+ *  nothing (a tracker has no checkout to give): it hands back the `linear`
+ *  section core writes under the project, and the **core** `lanes` array
+ *  core writes on the project. Everything Linear-specific — apps, teams,
+ *  workflow states — lives here; core only knows this plugin serves the
+ *  `tracker` role. */
+import { getLogger } from '@aivi/core';
+import { LANE_KIND, laneKindLines, PluginSetupCancelled, } from '@aivi/plugin';
+import { resolveTeams } from './client.js';
+import { clientFor } from './tracker.js';
+const log = getLogger(['aivi', 'projects']);
+/** The states the wizard asks about, in board order: deduped by name across
+ *  the picked teams (two mapped teams can share a state name, and one name
+ *  gets one lane). Nothing is dropped — **every state is asked**: what a
+ *  state is for is the person's answer to the lane question, not aivi's
+ *  guess from the state's type. Linear's `type` is
+ *  real API data, so it only sets which answer the question starts on. The
+ *  client already returns each team's states in board order (type group,
+ *  then position). Exported pure for the test that pins the dedupe. */
+export function boardStates(states) {
+    const seen = new Set();
+    return states.filter(state => {
+        if (seen.has(state.name))
+            return false;
+        seen.add(state.name);
+        return true;
+    });
+}
+/** Which answer the lane question starts on, from Linear's state type (real
+ *  API data): a `completed` state starts on Human — a person takes finished
+ *  work; `canceled` and `duplicate` start on None — they end out of the
+ *  workflow; everything else starts on Agent. A start is a highlight, not a
+ *  ruling: the person's answer wins. */
+export function laneKindDefault(type) {
+    if (type === 'completed')
+        return 'human';
+    if (type === 'canceled' || type === 'duplicate')
+        return 'none';
+    return 'agent';
+}
+/** The lanes the queue question may offer (ruled 2026-10-02): **one**
+ *  question after all lanes are configured, and its candidates are the
+ *  lanes that could legally hold the queue — a queue lane must feed a
+ *  worker lane, so a lane whose next works nobody is no candidate, and the
+ *  last lane feeds nothing at all. And a lane that has an agent is **never**
+ *  an option (ruled 2026-10-02): a queue is where people wait for a worker,
+ *  not a worker lane itself — the queue runs between the human lanes and
+ *  the working ones, like a real board's waiting column. A **human** lane is
+ *  a legal queue: that is what "used as a queue" means in the lane answer's
+ *  own words. Offering anything else would write a config the operator did
+ *  not mean. Exported pure, so the wizard's rules are testable apart from
+ *  prompts. */
+export function queueCandidates(lanes) {
+    return lanes.filter(lane => lane.agent === undefined && lanes[lanes.indexOf(lane) + 1]?.agent !== undefined);
+}
+/** 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, because a lane silently losing its worker is not a wizard. The
+ *  returned lines are what the caller logs; the marking itself follows
+ *  core's load rules: a queue lane works none and writes nothing. */
+export function markQueue(lanes, chosen) {
+    const lane = lanes.find(l => l.name === chosen);
+    if (!lane)
+        return [];
+    const said = [];
+    if (lane.agent !== undefined) {
+        delete lane.agent;
+        said.push(`"${chosen}" works nobody then — it waits work instead`);
+    }
+    delete lane.worktree;
+    lane.queue = true;
+    return said;
+}
+/** The app to ask for teams: one app is never asked of the person,
+ *  several are. */
+async function pickApp(ctx, appIds) {
+    if (appIds.length <= 1)
+        return undefined;
+    const picked = await ctx.prompts.select({
+        message: 'Ask which Linear app for teams',
+        options: appIds.map(name => ({ value: name, label: name })),
+    });
+    if (ctx.prompts.isCancel(picked))
+        throw new PluginSetupCancelled('no app chosen');
+    return picked;
+}
+/** The teams the app can see: the spinner says so, and a refusal ends the
+ *  setup — a wizard that went on after a dead app would be writing blind. */
+async function askedTeams(ctx, makeClient, config, app) {
+    const spinner = ctx.prompts.spinner();
+    spinner.start('Asking the app which teams it can see');
+    let teams;
+    try {
+        teams = await makeClient(config, app, log).listTeams();
+        spinner.stop(`The app can see ${teams.length} team${teams.length === 1 ? '' : 's'}`);
+    }
+    catch (error) {
+        spinner.error(error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+    if (!teams.length)
+        throw new Error('that Linear app sees no teams — a private team needs the app added to it');
+    return teams;
+}
+/** Which of the visible teams may work here: a pick-list, never typing. */
+async function pickTeams(ctx, teams) {
+    const pickedTeams = await ctx.prompts.multiselect({
+        message: 'Which teams may work in this project?',
+        options: teams.map(team => ({ value: team.id, label: `${team.key} — ${team.name}`, hint: team.id })),
+        required: true,
+    });
+    if (ctx.prompts.isCancel(pickedTeams))
+        throw new PluginSetupCancelled('no teams picked');
+    return pickedTeams;
+}
+/** One question per state: what kind of lane it is, in the kit's
+ *  `LANE_KIND` words. The question **starts on** the answer Linear's state
+ *  type suggests (`laneKindDefault`); the person's
+ *  answer wins. An `agent` answer is followed by the agent pick and, when a
+ *  forge is configured, the branch question. A `human` answer writes a bare
+ *  lane: the orchestrator's silence, and a legal queue or destination. A
+ *  `none` answer writes nothing: the state is not in the array, so aivi
+ *  neither reads it nor moves a ticket into it. */
+async function askLanes(ctx, states, agentNames) {
+    const lanes = [];
+    let explained = false;
+    for (const state of states) {
+        // One log entry before the first question, never repeated per state.
+        if (!explained) {
+            explained = true;
+            await ctx.prompts.log.message(laneKindLines('Linear names what a state is, so each question starts on the answer its type suggests. Your answer wins.').join('\n'));
+        }
+        const first = laneKindDefault(state.type);
+        const rest = ['agent', 'human', 'none'].filter(kind => kind !== first);
+        const picked = await ctx.prompts.select({
+            message: `What kind of lane is the "${state.name}" state?`,
+            options: [first, ...rest].map(kind => LANE_KIND[kind]),
+        });
+        if (ctx.prompts.isCancel(picked))
+            throw new PluginSetupCancelled('lane setup incomplete');
+        const kind = String(picked);
+        if (kind === 'none')
+            continue;
+        let agent = '';
+        if (kind === 'agent') {
+            const answer = await ctx.prompts.autocomplete({
+                message: `Which OpenCode agent works the "${state.name}" lane?`,
+                options: agentNames.map(name => ({ value: name, label: name })),
+                maxItems: 12,
+            });
+            if (ctx.prompts.isCancel(answer))
+                throw new PluginSetupCancelled('lane setup incomplete');
+            agent = String(answer).trim();
+        }
+        // A worked lane with git possible: does it work on the ticket's branch?
+        // The worktree belongs to the branch, not to writing: a review lane
+        // changes nothing yet must read the pull request's branch, and that
+        // branch lives nowhere but a worktree — a run on a branch reuses the
+        // worktree already holding it. Only a yes is written — core's default
+        // is false, and a key stating the default is noise. "No" means the
+        // project's own checkout; it is never a promise of read-only: that is
+        // the agent file's own deny, never aivi's. Without a forge there are
+        // no worktrees to promise, so nothing is asked.
+        let worktree = false;
+        if (agent && ctx.forgeConfigured) {
+            const onBranch = await ctx.prompts.select({
+                message: `Does work in the "${state.name}" lane happen on the ticket's branch (git worktree)?`,
+                options: [
+                    { value: 'yes', label: "yes — on the ticket's branch, in its own worktree" },
+                    { value: 'no', label: 'no — in the project checkout itself' },
+                ],
+            });
+            if (ctx.prompts.isCancel(onBranch))
+                throw new PluginSetupCancelled('lane setup incomplete');
+            worktree = onBranch === 'yes';
+        }
+        lanes.push({ name: state.name, ...(agent ? { agent } : {}), ...(worktree ? { worktree } : {}) });
+    }
+    return lanes;
+}
+/** The queue: ONE question for the whole workflow (ruled 2026-10-02,
+ *  after every lane is configured — never a per-lane ask). "-- None --"
+ *  leaves the workflow without a queue lane, which is the old shape. */
+async function askQueue(ctx, lanes) {
+    const candidates = queueCandidates(lanes);
+    if (candidates.length) {
+        const answer = await ctx.prompts.select({
+            message: 'Which lane waits with work while the working lanes are full (the queue)?',
+            options: [
+                ...candidates.map(lane => ({ value: lane.name, label: lane.name })),
+                { value: '', label: '-- None --' },
+            ],
+        });
+        if (ctx.prompts.isCancel(answer))
+            throw new PluginSetupCancelled('lane setup incomplete');
+        const chosen = String(answer).trim();
+        for (const line of chosen ? markQueue(lanes, chosen) : [])
+            await ctx.prompts.log.message(line);
+    }
+    else if (lanes.length)
+        await ctx.prompts.log.message('no lane sits before a working lane, so nothing can wait for a slot — a queue lane comes later with a worker lane');
+}
+/** The wizard, in its order: app, teams, the project's name, what kind of
+ *  lane each board state is (agent, human, or none), then the queue over
+ *  the no-agent lanes. Each step is its own question and its own honest
+ *  failure; the whole is the ruling. */
+function makeContributor(makeClient = clientFor) {
+    return {
+        role: 'tracker',
+        async setup(ctx) {
+            const config = ctx.config;
+            const app = await pickApp(ctx, Object.keys(config.apps ?? {}));
+            const teams = await askedTeams(ctx, makeClient, config, app);
+            const teamIds = await pickTeams(ctx, teams);
+            const chosen = teams.filter(team => teamIds.includes(team.id));
+            // The name: a tracker offers the first team's key, lower-cased, unless an
+            // earlier role (a forge) already settled it. A defaultValue, not just a
+            // placeholder: Enter takes it *and says so* — a hint is display-only,
+            // and an answered prompt that renders empty leaves the person guessing
+            // what was taken.
+            const suggested = (ctx.projectId ?? chosen[0].key).toLowerCase();
+            const idAnswer = await ctx.prompts.text({
+                message: "Project id — aivi's name for it; Linear never sees it.",
+                placeholder: suggested,
+                defaultValue: suggested,
+            });
+            if (ctx.prompts.isCancel(idAnswer))
+                throw new PluginSetupCancelled('no project id given');
+            const id = (String(idAnswer).trim() || suggested).toLowerCase();
+            // Lanes: core's ordered workflow (`projects.<id>.lanes`), and the board
+            // is the order — the client returns a team's states in board order
+            // (type group, then position).
+            // A pick-list, never typing: the agents OpenCode can run as a primary
+            // in this project's checkout. A service that answers with no agents
+            // means something is broken — aivi always ships at least two — so the
+            // setup says so and stops.
+            const agentNames = await ctx.agents(id);
+            if (!agentNames.length)
+                throw new Error('Unable to configure lanes: there appear to be no agents available.');
+            const lanes = await askLanes(ctx, boardStates(chosen.flatMap(team => team.states)), agentNames);
+            await askQueue(ctx, lanes);
+            if (!lanes.length)
+                await ctx.prompts.log.message('no lanes were written — the boards had no states, or every state was answered “None” — so aivi works no tickets until lanes exist');
+            const section = { teams: resolveTeams(teams, teamIds) };
+            return { id, section, ...(lanes.length ? { lanes } : {}), cloned: false };
+        },
+    };
+}
+export const contributor = makeContributor();
+export { makeContributor };
+export default contributor;

package/dist/setup.d.ts

@@ -0,0 +1,3 @@
+import { type PluginSetup } from '@aivi/plugin';
+declare const setup: PluginSetup;
+export default setup;