@aivi/plugin 0.0.0-stage → 0.1.0

package/dist/plugin.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The registry declaration an installable plugin package makes at its `./config`
+ * subpath. The `aivi-plugins` list in `<home>/app/package.json` names packages —
+ * what npm installs, what `aivi add` takes; this declaration carries the other
+ * identity a plugin has, its **module id**: the key of its block in `config.json`
+ * (`plugins.<id>`), the logger category, the id `/status` reports. A third-party
+ * package brings its own id, so npm names and config keys can never collide.
+ *
+ * The subpath is deliberately light: the CLI imports it for every command to
+ * compose the config schema and mount commands, so it pulls the schema and not
+ * the platform SDK — `createModule` reaches for the module code itself, lazily.
+ */
+import type { z } from 'zod';
+import type { AiviModule } from './module.ts';
+/** What the registry finds at a plugin package's `./config` subpath. */
+export interface AiviPlugin<C = unknown> {
+    /** The module id: the `plugins.<id>` config key, the logger category, the `/status` id. */
+    id: string;
+    /** The block's own schema: defaults, required fields and cross-field rules all live
+     *  here. A plugin listed with no block is parsed against `configSchema.parse({})` —
+     *  defaults, or this schema's own "enabled but unconfigured" complaint. */
+    configSchema: z.ZodType<C>;
+    /** The plugin's own project-section schemas: `projectSchema` is the shape of
+     *  `projects.<id>.<id>` under every project, `projectDefaultsSchema` the shape of
+     *  its section under `projectDefaults`, both keyed by module id. Core keeps the
+     *  core vocabulary of a project (`enabled`, `knowledge`) and nothing else; a
+     *  project key is valid only because core defines it or a registered plugin
+     *  declares it here — the same closure the `plugins` blocks get. They ride the
+     *  light `./config` subpath because the registry composes the schema before any
+     *  module runs. The plugin reads its sections back from the loaded config; core
+     *  never interprets them. */
+    projectSchema?: z.ZodType;
+    projectDefaultsSchema?: z.ZodType;
+    /** Build the module `aivi serve` runs. `home` is the aivi home: a config path that
+     *  was written relative resolves against it here — the plugin knows its own fields,
+     *  core never does. */
+    createModule(config: C, home: string): AiviModule | Promise<AiviModule>;
+}

package/dist/plugin.js

@@ -0,0 +1,13 @@
+/**
+ * The registry declaration an installable plugin package makes at its `./config`
+ * subpath. The `aivi-plugins` list in `<home>/app/package.json` names packages —
+ * what npm installs, what `aivi add` takes; this declaration carries the other
+ * identity a plugin has, its **module id**: the key of its block in `config.json`
+ * (`plugins.<id>`), the logger category, the id `/status` reports. A third-party
+ * package brings its own id, so npm names and config keys can never collide.
+ *
+ * The subpath is deliberately light: the CLI imports it for every command to
+ * compose the config schema and mount commands, so it pulls the schema and not
+ * the platform SDK — `createModule` reaches for the module code itself, lazily.
+ */
+export {};

package/dist/run.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The **run** domain: what a run is, in platform-neutral words, as both sides
+ * of the contract read it. A run is one attempt at one ticket — not the
+ * ticket (which outlives it) and not any tracker's session. The orchestrator
+ * records these shapes; a tracker renders them on its platform and never
+ * drives them. This is the vocabulary the host's engine and every module
+ * share — which is why it lives here, below both.
+ *
+ * Core words are `tracker` and `forge`, never a platform's name: Linear, Jira
+ * and GitHub Issues all spell these differently on their own side, and nothing
+ * here notices which one is speaking. The orchestrator knows tickets, lanes
+ * and OpenCode — a conversation string is no orchestrator fact, and delivery
+ * of anything to a platform is the tracker's own business.
+ */
+/**
+ * A run's life, as the orchestrator holds it. There is **no capacity gate in
+ * this version**: admission and a lease arrive with the dispatcher, so
+ * `preparing` is entered the moment work is requested and only ever means
+ * "the work environment and session are being made".
+ *
+ * - `preparing` — requested; the work environment and the session are being made.
+ * - `working` — a turn is running or queued.
+ * - `awaiting_input` — parked on an open elicitation: the OpenCode form is
+ *   the durable record of the wait; the keep-alive says how long the slot
+ *   is held for it, and after that the ticket waits without one. The run
+ *   keeps its session and its claim either way.
+ * - `completed` / `failed` / `cancelled` — terminal; only a completion tool
+ *   call, a failure, or a stop puts a run here. Never a text, never idleness.
+ */
+export type RunState = 'preparing' | 'working' | 'awaiting_input' | 'completed' | 'failed' | 'cancelled';
+/** Terminal means nothing more can happen to this run. */
+export declare function isTerminal(state: RunState): boolean;
+/**
+ * One question's options, in neutral words; a tracker renders them its way
+ * (Linear shows its `select` signal, GitHub a numbered comment). `label` is
+ * what the person sees; `value` is what an answer arrives as (they may also
+ * answer in free text — platforms that render options emit the chosen value
+ * as an ordinary message).
+ */
+export interface RunOption {
+    label: string;
+    value: string;
+}
+/**
+ * A question the worker asked — one shape, seen from both sides: the
+ * orchestrator records it, the tracker renders it. `formId` is the OpenCode
+ * session form that holds the durable copy: the worker created it through
+ * `ask`, it reads `pending` until a human answers it, and it is the
+ * *discriminator* between an answer and an interjection. The form is the
+ * record; this is the rendering a tracker shows, and a platform that reads
+ * only the text and options ignores `formId` without losing anything.
+ */
+export interface RunQuestion {
+    question: string;
+    options?: RunOption[];
+    formId?: string;
+}
+/**
+ * What the completion tool says the worker did, and the reason a run ends.
+ * This is an application protocol, not an OpenCode type: the worker authored
+ * it, the orchestrator parsed and validated it, and a tracker decides how —
+ * and whether — to show it. `success` and `failure` are the worker's
+ * knowledge; which lane each lands the ticket in is the orchestrator's lane
+ * config, never the worker's report.
+ */
+export type RunOutcome = {
+    kind: 'success';
+    summary: string;
+} | {
+    kind: 'failure';
+    reason: string;
+    code?: FailureCode;
+};
+/** Why aivi — not the worker — ended a run, in machine-readable words: a
+ *  tracker renders help for its platform from the code, never by reading
+ *  English. `kill-unconfirmed`: the dispatcher struck the session the
+ *  configured number of times and it would not die; the person watching
+ *  the ticket should know a worker may still be loose.
+ *  `stop-unconfirmed`: a person asked to stop and OpenCode would not answer
+ *  the interrupt at all, so the same may be true of a stop. */
+export type FailureCode = 'kill-unconfirmed' | 'stop-unconfirmed';
+/**
+ * A run as anyone outside the orchestrator may read it: enough to speak
+ * about one, never enough to drive it. It names the ticket, not a tracker's
+ * session — the tracker holds that pair in its own store.
+ */
+export interface RunView {
+    readonly id: string;
+    readonly projectId: string;
+    readonly trackerId: string;
+    readonly ticketId: string;
+    readonly lane: string;
+    readonly agent: string;
+    readonly state: RunState;
+    readonly sessionId?: string;
+    /** The directory the worker works in: the checkout, or the worktree a
+     *  `worktree: true` lane got on the ticket's branch. */
+    readonly worktree?: string;
+    readonly outcome?: RunOutcome;
+    /** The lane the lane order chose for a finished run's ticket: the
+     *  orchestrator's decision; performing the move is the tracker's. Absent:
+     *  the ticket stays — a stop moves nothing, an unmapped lane goes silent. */
+    readonly targetLane?: string;
+    /** When the run last changed: a tracker's rendering watermark reads
+     *  endings through it, so nothing that arrived while aivi slept is
+     *  missed and nothing already rendered is said twice. */
+    readonly updatedAt: number;
+}
+/**
+ * The worker's plan: a session-level checklist it keeps current while it
+ * works, in neutral words. `content` is the step; `status` where it stands.
+ * The whole array arrives at every update — replacing the plan wholesale is
+ * the shape the platforms that render one (Linear's agent plan) accept, and
+ * it keeps the worker's tool honest: no diffing, no partial truths.
+ */
+export interface RunPlanStep {
+    content: string;
+    status: 'pending' | 'inProgress' | 'completed' | 'canceled';
+}
+export interface RunPlan {
+    steps: RunPlanStep[];
+}
+/**
+ * What work is asked of the orchestrator: one ticket, in a lane, worked by
+ * an agent in a directory, opened with the tracker's summary. The shape the
+ * walk builds when it claims a ticket; the door stays the walk's.
+ */
+export interface WorkRequest {
+    projectId: string;
+    trackerId: string;
+    ticketId: string;
+    lane: string;
+    agent: string;
+    /** Where the worker works: the checkout, or a worktree the delegator made. */
+    directory: string;
+    /** The tracker's own summary of the ticket, composed into the worker's
+     *  first prompt with the orchestrator's contract around it. */
+    summary: string;
+    /** The ticket's branch name, as the platform names it: what a worktree
+     *  lane checks out. The push door did its platform side already, so
+     *  `initWork` is not asked twice; a worktree lane whose request carries
+     *  no branch is refused visibly, never named by guess. */
+    branch?: string;
+}

package/dist/run.js

@@ -0,0 +1,18 @@
+/**
+ * The **run** domain: what a run is, in platform-neutral words, as both sides
+ * of the contract read it. A run is one attempt at one ticket — not the
+ * ticket (which outlives it) and not any tracker's session. The orchestrator
+ * records these shapes; a tracker renders them on its platform and never
+ * drives them. This is the vocabulary the host's engine and every module
+ * share — which is why it lives here, below both.
+ *
+ * Core words are `tracker` and `forge`, never a platform's name: Linear, Jira
+ * and GitHub Issues all spell these differently on their own side, and nothing
+ * here notices which one is speaking. The orchestrator knows tickets, lanes
+ * and OpenCode — a conversation string is no orchestrator fact, and delivery
+ * of anything to a platform is the tracker's own business.
+ */
+/** Terminal means nothing more can happen to this run. */
+export function isTerminal(state) {
+    return state === 'completed' || state === 'failed' || state === 'cancelled';
+}

package/dist/setup-project.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The **project-setup** contract: how a plugin helps set up a new project for
+ * the *role* it plays (`forge` or `tracker` — core's system vocabulary, never
+ * a plugin name). `aivi projects add` walks the roles in order and, for each,
+ * runs the one configured plugin that serves it; the plugin asks its own
+ * platform questions and hands back the config section core writes under the
+ * project. Core writes bytes and reads none of them — the types live in the
+ * plugin's own `projectSchema`. A forge owns the checkout (it clones); a
+ * plugin that clones says so, and with no forge the setup leaves an untracked
+ * directory instead.
+ *
+ * Everything platform-specific lives in the plugin; the runner only wires the
+ * context (the same clack, fetch and store the plugin's `./setup` gets) and
+ * threads the project name from one role to the next so it is asked once.
+ */
+import type { OutputBlock, ProjectLaneInput, ProjectRole } from '@aivi/core';
+import type * as prompts from '@clack/prompts';
+import type { Store } from './module.ts';
+import { PluginSetupCancelled } from './setup.ts';
+export { PluginSetupCancelled };
+/** What the runner hands a project contributor. */
+export interface ProjectSetupContext {
+    /** The aivi home that owns `config.json` and `.env`. */
+    home: string;
+    configPath: string;
+    /** The plugin's own config block (`config.plugins.<id>`) as written — its
+     *  credentials live in the environment, so this is ids and options. */
+    config: Record<string, unknown>;
+    /** The plugin's own `projectDefaults.<id>` section as written — the
+     *  company-wide convention this project inherits unless it says otherwise.
+     *  Core hands the plugin its own section and reads nothing in it. */
+    projectDefaults?: Record<string, unknown>;
+    /** The project name chosen by an earlier role, or undefined when this role
+     *  is the first to settle it (and so offers the default). */
+    projectId?: string;
+    /** Whether a forge is configured in this home — so a checkout (and once
+     *  a forge gives them, worktrees) is possible for this project. Core
+     *  computes it from the configured plugins; contributors that could work
+     *  a lane with git ask their own worktree questions with it. */
+    forgeConfigured: boolean;
+    /** The repository an earlier role (a forge) settled, as `owner/repo` —
+     *  undefined when no forge named one. A tracker offers it as the answer
+     *  that is right most of the time instead of asking a person to repeat
+     *  what they just told the wizard. */
+    forgeRepository?: string;
+    /** Raw JSON on stdout when the value is for copying (core's `print`). */
+    print(value: unknown, output?: OutputBlock[] | string): void;
+    /** The very `@clack/prompts` the runner renders with; a cancelled prompt
+     *  throws `PluginSetupCancelled` and nothing further is written. */
+    prompts: typeof prompts;
+    /** Platform calls the contributor verifies with; the runner supplies fetch. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** The OpenCode agents that can work this project: what the project's
+     *  checkout directory defines (its `.opencode/`), plus the global ones,
+     *  minus the subagent-only ones — a lane works as the session's primary.
+     *  The runner starts an OpenCode service when none answers, and a failure
+     *  to reach or start one stops the setup — it is never swallowed. */
+    agents(projectId: string): Promise<string[]>;
+    /** The home's SQLite store, open for the callback and closed after. */
+    withStore<T>(fn: (store: Store) => T | Promise<T>): Promise<T>;
+}
+/** What a project contributor hands back for the project. */
+export interface ProjectSetupResult {
+    /** The project name, settled here: the role's own default (a forge's repo
+     *  name, a tracker's team name) or the one handed in by an earlier role. */
+    id: string;
+    /** The section core writes at `projects.<id>.<moduleId>`, validated against
+     *  this plugin's own `projectSchema`; absent means the role wrote nothing. */
+    section?: Record<string, unknown>;
+    /** The project's **core** `lanes` array — the ordered tracker workflow,
+     *  written at `projects.<id>.lanes` and validated by core (unique names,
+     *  every `next`/`previous` a lane of the array, the queue lane's rules).
+     *  Lanes are core's fact;
+     *  whoever knows the board — the tracker role — offers its order, and two
+     *  contributors naming one workflow is an error, not a merge. */
+    lanes?: ProjectLaneInput[];
+    /** True when this contributor leaves a git checkout at `projects/<id>/source`
+     *  — it cloned one, or the checkout was already there for the repository the
+     *  person named. A forge owns the clone because cloning reaches `origin`.
+     *  With no clone the setup leaves an untracked directory. */
+    cloned?: boolean;
+    /** The repository this contributor settled, as `owner/repo`: a forge names
+     *  the one it cloned so a later role can offer it instead of asking again.
+     *  Absent means no repository was settled. */
+    repository?: string;
+}
+/** The declaration a plugin package makes at its `./setupProject` subpath:
+ *  the role it serves and the flow that sets a project up for it. A package
+ *  with no `./setupProject` export serves no role and is never offered. */
+export interface ProjectContributor {
+    /** The role this contributor serves from core's system vocabulary. Absent
+     *  means it serves **no role**: it jumps in *after* the roles (forge, then
+     *  tracker) are done, and adds its own project section — a plugin that wants
+     *  a say in a new project without claiming to be the source host or the
+     *  ticket system. */
+    role?: ProjectRole;
+    setup(ctx: ProjectSetupContext): Promise<ProjectSetupResult>;
+}
+/** The three answers to the lane question — "What kind of lane is this?" —
+ *  in the person's own words. Every tracker wizard asks in these words: the
+ *  explanation prints the labels, the question offers them, so they live in
+ *  the kit once. `agent` asks who
+ *  works the lane; `human` writes a bare lane — aivi ignores its tickets,
+ *  and a finished run may move one in; `none` leaves the option out of the
+ *  array: aivi never reads it and never moves a ticket into it. */
+export declare const LANE_KIND: {
+    readonly agent: {
+        readonly value: 'agent';
+        readonly label: 'Agent: aivi delegates tickets in this lane to an agent';
+    };
+    readonly human: {
+        readonly value: 'human';
+        readonly label: 'Human: aivi ignores tickets in this lane; it is only ever used as a queue or a destination';
+    };
+    readonly none: {
+        readonly value: 'none';
+        readonly label: 'None: this lane is not part of aivi’s workflow';
+    };
+};
+/** The three answers as a type: whatever the person picked is one of them. */
+export type LaneKind = (typeof LANE_KIND)[keyof typeof LANE_KIND]['value'];
+/** The explanation — **one log entry before the first lane question**,
+ *  never repeated per option. The queue sentence belongs in the same entry:
+ *  a queue is the other thing a no-agent lane can be, and the difference
+ *  between the two no-agent answers is the whole
+ *  point of asking. `note` is the wizard's own first line — a tracker that
+ *  cannot tell what an option means (GitHub) says so here. */
+export declare function laneKindLines(note?: string): string[];

package/dist/setup-project.js

@@ -0,0 +1,48 @@
+/**
+ * The **project-setup** contract: how a plugin helps set up a new project for
+ * the *role* it plays (`forge` or `tracker` — core's system vocabulary, never
+ * a plugin name). `aivi projects add` walks the roles in order and, for each,
+ * runs the one configured plugin that serves it; the plugin asks its own
+ * platform questions and hands back the config section core writes under the
+ * project. Core writes bytes and reads none of them — the types live in the
+ * plugin's own `projectSchema`. A forge owns the checkout (it clones); a
+ * plugin that clones says so, and with no forge the setup leaves an untracked
+ * directory instead.
+ *
+ * Everything platform-specific lives in the plugin; the runner only wires the
+ * context (the same clack, fetch and store the plugin's `./setup` gets) and
+ * threads the project name from one role to the next so it is asked once.
+ */
+import { PluginSetupCancelled } from './setup.js';
+export { PluginSetupCancelled };
+/** The three answers to the lane question — "What kind of lane is this?" —
+ *  in the person's own words. Every tracker wizard asks in these words: the
+ *  explanation prints the labels, the question offers them, so they live in
+ *  the kit once. `agent` asks who
+ *  works the lane; `human` writes a bare lane — aivi ignores its tickets,
+ *  and a finished run may move one in; `none` leaves the option out of the
+ *  array: aivi never reads it and never moves a ticket into it. */
+export const LANE_KIND = {
+    agent: { value: 'agent', label: 'Agent: aivi delegates tickets in this lane to an agent' },
+    human: {
+        value: 'human',
+        label: 'Human: aivi ignores tickets in this lane; it is only ever used as a queue or a destination',
+    },
+    none: { value: 'none', label: 'None: this lane is not part of aivi’s workflow' },
+};
+/** The explanation — **one log entry before the first lane question**,
+ *  never repeated per option. The queue sentence belongs in the same entry:
+ *  a queue is the other thing a no-agent lane can be, and the difference
+ *  between the two no-agent answers is the whole
+ *  point of asking. `note` is the wizard's own first line — a tracker that
+ *  cannot tell what an option means (GitHub) says so here. */
+export function laneKindLines(note) {
+    return [
+        ...(note ? [note] : []),
+        'Every option is asked, in board order. What each answer means:',
+        `  ${LANE_KIND.agent.label}`,
+        `  ${LANE_KIND.human.label}`,
+        `  ${LANE_KIND.none.label}`,
+        'A queue is where tickets wait while the working lanes are full: aivi moves the next ticket out of it as soon as a slot is free.',
+    ];
+}

package/dist/setup.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The install contract an installable plugin package may fill. `aivi add`
+ * npm-installs the package into the server home and then runs its `./setup`
+ * entry — if it has one: a plugin whose `./config` export is its whole say at
+ * add time joins the list on that alone, the editor schema composed from it.
+ * The CLI knows nothing platform-specific. Everything the flow needs arrives
+ * through the context, so the flow prints its own platform instructions and
+ * is testable without a terminal or a platform account.
+ */
+import type { OutputBlock } from '@aivi/core';
+import type * as prompts from '@clack/prompts';
+import type { Store } from './module.ts';
+/** A prompt the person cancelled; the runner says it stopped and writes nothing further. */
+export declare class PluginSetupCancelled extends Error {
+}
+/** Clack answers Ctrl+C with its cancel symbol and an empty Enter with
+ *  nothing — neither is an answer. The flow stops with
+ *  `PluginSetupCancelled` and the runner says the one cancel line; prompts
+ *  that must not be empty say so in their `validate`, so clack re-asks
+ *  before this ever sees the gap. */
+export declare function settled<T>(ctx: PluginSetupContext, answer: T): Exclude<NonNullable<T>, symbol>;
+export interface PluginSetupContext {
+    /** The aivi home that owns `config.json` and `.env`. */
+    home: string;
+    configPath: string;
+    /** The persona from config.json `identity.name` — what the bot is called on the platform. */
+    identityName: string;
+    /** The raw parsed `config.json`, so a flow can see what is already configured. */
+    config: Record<string, unknown>;
+    /** The command output record on stdout: raw JSON text on the terminal when the
+     *  value is for copying (core's `print`), so paste-able output stays paste-able. */
+    print(value: unknown, output?: OutputBlock[] | string): void;
+    /** The very `@clack/prompts` module the runner renders with, handed over
+     *  so a flow draws all its own lines — notes, log lines, prompts,
+     *  spinners — with the same instance and style as the runner's intro and
+     *  cancel line. Whoever is called owns the screen: two clacks animating
+     *  one terminal mangle each other (measured 2026-09-27), so a flow opens
+     *  one animation at a time, prints nothing beside it, and settles it
+     *  before returning or throwing. A prompt cancelled on Ctrl+C is no
+     *  answer: the flow throws `PluginSetupCancelled` and nothing further
+     *  is written. */
+    prompts: typeof prompts;
+    /** Platform calls the flow verifies with; the runner supplies the real fetch. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    /** The home's SQLite store, open for the callback and closed after, whatever
+     *  the callback does. A flow reads what the server has recorded (a webhook's
+     *  diary) without importing the server: `Store` is named here as a type, the
+     *  runner opens the database. */
+    withStore<T>(fn: (store: Store) => T | Promise<T>): Promise<T>;
+    /** Write this plugin's block into `config.json`; the file must load again or the old bytes return. */
+    writeConfigBlock(path: string[], value: unknown): Promise<void>;
+    /** Replace-or-append one key in `<home>/.env`, kept 0600; the value is never echoed. */
+    writeSecret(key: string, value: string): Promise<void>;
+}
+export interface PluginSetupResult {
+    /** The module the flow enabled — the id `aivi add` watches in `/status`. */
+    module: string;
+    /** The verified last line: what is true now, never what may happen. */
+    summary: string;
+}
+/** Every plugin's `./setup` entry: one default-exported function. */
+export type PluginSetup = (ctx: PluginSetupContext) => Promise<PluginSetupResult>;

package/dist/setup.js

@@ -0,0 +1,24 @@
+/**
+ * The install contract an installable plugin package may fill. `aivi add`
+ * npm-installs the package into the server home and then runs its `./setup`
+ * entry — if it has one: a plugin whose `./config` export is its whole say at
+ * add time joins the list on that alone, the editor schema composed from it.
+ * The CLI knows nothing platform-specific. Everything the flow needs arrives
+ * through the context, so the flow prints its own platform instructions and
+ * is testable without a terminal or a platform account.
+ */
+/** A prompt the person cancelled; the runner says it stopped and writes nothing further. */
+export class PluginSetupCancelled extends Error {
+}
+/** Clack answers Ctrl+C with its cancel symbol and an empty Enter with
+ *  nothing — neither is an answer. The flow stops with
+ *  `PluginSetupCancelled` and the runner says the one cancel line; prompts
+ *  that must not be empty say so in their `validate`, so clack re-asks
+ *  before this ever sees the gap. */
+export function settled(ctx, answer) {
+    if (ctx.prompts.isCancel(answer))
+        throw new PluginSetupCancelled('a prompt was cancelled');
+    if (answer === undefined)
+        throw new PluginSetupCancelled('a prompt was submitted empty');
+    return answer;
+}