@rackbops/ac-plugin-contract 2.0.0-alpha.33

package/dist/issue-filter.js

@@ -0,0 +1,152 @@
+// ---- tokens (#464a) ---------------------------------------------------------------------------------
+//
+// The person and ladder shortcuts 1.x's filter bar offers ("me", "unassigned", "bots", "High and above",
+// "none"), carried inside the existing `SetFilter` so no new filter shape exists: a value is a token only
+// when it is exactly one of the five spellings below, and everything else is the plain exact match it
+// always was -- so every filter written before tokens existed means what it meant (a label named
+// `@needs-review` still filters on `tags`), and an `@...` a LATER version defines matches nothing here
+// unless a label or login is literally spelled that way. A label named exactly like a token (`@me`) cannot
+// be selected as a plain value. A saved view (`views.yaml`) may use the tokens as-is.
+/** The viewer: an assignee/author login equal to `MatchContext.me`, compared ignoring case. */
+export const FILTER_ME = "@me";
+/** Nobody: on `assignee`, a record with no assignee; on `author`, a record with no author. */
+export const FILTER_UNASSIGNED = "@unassigned";
+/** A bot: an assignee/author whose `Person.isBot` is true -- GitHub's own flag, never a guess from the login. */
+export const FILTER_BOTS = "@bots";
+/** Any label of the axis's ladder (`priority`/`effort`/`type`). `is-not @any` is 1.x's "none". */
+export const FILTER_ANY = "@any";
+const UPTO_PREFIX = "@upto:";
+/**
+ * "At or before this rung of the ladder" (`priority`/`effort`): the record carries the label named
+ * `name` or any label the axis's ladder lists BEFORE it -- "High and above" on the priority ladder
+ * (critical first), "S and below" on the effort ladder (XS first): one rule, two wordings. `name` is the
+ * full label name, as the ladder carries it.
+ */
+export function filterUpTo(name) {
+    return `${UPTO_PREFIX}${name}`;
+}
+/**
+ * A value as a token, or `undefined` for a plain value (one not starting with `@`). For the UIs' chip
+ * labels; the predicate reads values through it too, so what a chip says and what a filter does cannot
+ * disagree about what is a token. An `@...` that is not one of the five tokens comes back as `unknown`,
+ * which the predicate treats as a plain value.
+ */
+export function parseFilterToken(value) {
+    if (!value.startsWith("@"))
+        return undefined;
+    if (value === FILTER_ME)
+        return { kind: "me" };
+    if (value === FILTER_UNASSIGNED)
+        return { kind: "unassigned" };
+    if (value === FILTER_BOTS)
+        return { kind: "bots" };
+    if (value === FILTER_ANY)
+        return { kind: "any" };
+    if (value.startsWith(UPTO_PREFIX) && value.length > UPTO_PREFIX.length) {
+        return { kind: "upto", name: value.slice(UPTO_PREFIX.length) };
+    }
+    return { kind: "unknown", value };
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Bucket boundaries are inclusive upper bounds ("1d" is "at most 24h old"): a record exactly 24h old
+// is "1d", not "1w" -- ageBucket below uses `<=`, never `<`, at every boundary.
+const BUCKET_BOUNDS_MS = [
+    ["1d", 1 * DAY_MS],
+    ["1w", 7 * DAY_MS],
+    ["1m", 30 * DAY_MS],
+    ["3m", 90 * DAY_MS],
+];
+/** The bucket of `now - isoTimestamp`, in ascending-boundary order; anything past the last bound is `older`. */
+function ageBucket(isoTimestamp, now) {
+    const elapsed = now - Date.parse(isoTimestamp);
+    for (const [bucket, bound] of BUCKET_BOUNDS_MS) {
+        if (elapsed <= bound)
+            return bucket;
+    }
+    return "older";
+}
+/** `is` matches when ANY of the filter's values hits; `is-not` when none does. `hit` reads one value. */
+function matchesSet(filter, hit) {
+    if (filter === undefined)
+        return true;
+    const present = filter.values.some(hit);
+    return filter.op === "is" ? present : !present;
+}
+/** Whether one value of a label axis hits a record's label names: a plain value (an `@...` that is none of
+ *  the five tokens included) is exact membership; a token is resolved against the axis's ladder, and only
+ *  `@any` (any ladder axis) and `@upto:` (priority and effort) mean anything here -- every other token, and
+ *  any token at all on `tags`, hits nothing. */
+function labelHit(axis, labelNames, ctx) {
+    const ladder = axis === "tags" ? undefined : ctx?.ladders?.[axis];
+    return (value) => {
+        const token = parseFilterToken(value);
+        if (token === undefined || token.kind === "unknown")
+            return labelNames.includes(value);
+        if (ladder === undefined)
+            return false;
+        if (token.kind === "any")
+            return labelNames.some((n) => ladder.includes(n));
+        if (token.kind === "upto" && axis !== "type") {
+            const rung = ladder.indexOf(token.name);
+            if (rung < 0)
+                return false;
+            return labelNames.some((n) => {
+                const at = ladder.indexOf(n);
+                return at >= 0 && at <= rung;
+            });
+        }
+        return false;
+    };
+}
+/** Whether one value of a person axis hits a record's people (its assignees, or its author alone): a plain
+ *  value is an exact login; `@me`, `@unassigned` and `@bots` are resolved as `MatchContext`/`Person.isBot`
+ *  say; the other two tokens (`@any`, `@upto:`) hit nothing here. An unknown `@...` is a plain login
+ *  compare, which matches nothing (a GitHub login cannot start with `@`). */
+function personHit(people, ctx) {
+    const me = ctx?.me === undefined || ctx.me === "" ? undefined : ctx.me.toLowerCase();
+    return (value) => {
+        const token = parseFilterToken(value);
+        if (token === undefined || token.kind === "unknown")
+            return people.some((p) => p.login === value);
+        if (token.kind === "me")
+            return me !== undefined && people.some((p) => p.login.toLowerCase() === me);
+        if (token.kind === "unassigned")
+            return people.length === 0;
+        if (token.kind === "bots")
+            return people.some((p) => p.isBot === true);
+        return false;
+    };
+}
+function matchesAge(bucket, filter) {
+    if (filter === undefined)
+        return true;
+    const present = filter.buckets.includes(bucket);
+    return filter.op === "is" ? present : !present;
+}
+function matchesSearch(record, query) {
+    if (query === undefined || query === "")
+        return true;
+    const trimmed = query.trim();
+    const asNumber = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+    if (asNumber !== "" && /^\d+$/.test(asNumber) && Number(asNumber) === record.number)
+        return true;
+    return record.title.toLowerCase().includes(trimmed.toLowerCase());
+}
+/**
+ * Pure AND across every present axis. An empty `filter` (`{}`) matches every record. `ctx` (#464a) is what
+ * the filter's tokens resolve against (the viewer, the ladders); omit it and every plain value behaves
+ * exactly as it always did, while a token that needs `ctx` matches nothing.
+ */
+export function matchesIssue(record, filter, now, ctx) {
+    const labelNames = record.labels.map((l) => l.name);
+    return (matchesSet(filter.priority, labelHit("priority", labelNames, ctx)) &&
+        matchesSet(filter.effort, labelHit("effort", labelNames, ctx)) &&
+        matchesSet(filter.type, labelHit("type", labelNames, ctx)) &&
+        matchesSet(filter.tags, labelHit("tags", labelNames, ctx)) &&
+        matchesSet(filter.assignee, personHit(record.assignees, ctx)) &&
+        matchesSet(filter.author, personHit(record.author ? [record.author] : [], ctx)) &&
+        matchesAge(ageBucket(record.createdAt, now), filter.age) &&
+        matchesAge(ageBucket(record.updatedAt, now), filter.activity) &&
+        matchesSearch(record, filter.search));
+}
+//# sourceMappingURL=issue-filter.js.map

package/dist/manifest.d.ts

@@ -0,0 +1,217 @@
+/**
+ * The `acPlugin` manifest block and its contribution points — the data the host validates before
+ * loading any plugin code (design.md §4). This file is the JSON-Schema generation target
+ * (`gen-schema.mjs` -> `schema.json`), so keep it self-contained (no relative imports) and every
+ * shape a plain data object. Field names are shared verbatim with the discord-bot index
+ * (`hostApiVersion`, `env[]`).
+ */
+/** How the host runs a plugin. */
+export type PluginKind = "in-process" | "sidecar";
+/** A contributed nav tab (panel). */
+export interface PanelContribution {
+    id: string;
+    title: string;
+    /** Route the panel mounts at, e.g. "/board". */
+    route: string;
+    /** Named nav slot this panel wants to own (e.g. "issues"); optional. */
+    nav?: string;
+    /**
+     * Where this panel wants to sit among the tabs (#472): a finite number, lower first, after the fixed
+     * `Home` tab. Unset keeps the panel after every ordered one, in the existing order (plugin directory
+     * name, then declaration order), so declaring `order` on one panel never moves a panel that did not.
+     * A hint, not a claim: the operator's `tab_order` setting outranks it, and among the ordered panels an
+     * `installed` plugin's never precedes a `bundled` plugin's, so a third-party package declaring a small
+     * number cannot jump ahead of the bundled ordered panels (it still precedes every panel that declares
+     * no `order`). Additive; a manifest without it validates as before.
+     */
+    order?: number;
+    /** The export name in the plugin's frontend bundle. */
+    export: string;
+}
+/** A contributed Overview card. */
+export interface CardContribution {
+    id: string;
+    title: string;
+    /** Allowed grid sizes, e.g. ["2x1", "3x1"]. */
+    sizes: string[];
+    /** The export name in the plugin's frontend bundle. */
+    export: string;
+}
+/**
+ * Input control kind for an action field; the shell renders each `fields` entry by its `type`.
+ * `multiselect` (#463) is a set of choices whose submitted value is a `string[]`; `hidden` (#463) is a
+ * value with no control at all -- a snapshot the operator must not type into (the seed, the stored draft
+ * or the default is submitted unchanged). Both are additive; every earlier type behaves as before.
+ */
+export type ActionFieldType = "string" | "text" | "number" | "boolean" | "select" | "multiselect" | "hidden";
+/**
+ * Where a `select` / `multiselect` field's choices come from when they are not a fixed `options` list
+ * (#463): a `GET` route the DECLARING plugin itself registers, answering an `ActionOptionsResponse`
+ * (`action-options.ts`). The host validates it at manifest-load time (`plugins/validate.ts`).
+ */
+export interface ActionOptionsSource {
+    /**
+     * The route, relative to the declaring plugin's own namespace: the shell fetches
+     * `/api/x/<plugin-id><route>`. It must start with `/`, carry no query string, fragment, `..`, `//`, `%`
+     * or `\`, and be one of the plugin's own declared `GET` routes (`contributes.routes`).
+     */
+    route: string;
+    /**
+     * Names of OTHER fields of the same action whose current values are sent as query parameters (so a
+     * route can answer for the repo the operator has typed, say). The route is not fetched while any of
+     * them is empty, and is fetched again when one changes.
+     */
+    params?: string[];
+}
+/** One field of an action's form; the shell builds a labelled control from it. */
+export interface ActionField {
+    /** Key the submitted value is collected under. */
+    name: string;
+    label: string;
+    type: ActionFieldType;
+    /**
+     * Choices for a `select`. A bare string is both value and label; the object form allows a distinct
+     * display label (so a later value≠label select is additive, not a breaking `string[]`→object change).
+     */
+    options?: (string | {
+        value: string;
+        label: string;
+    })[];
+    /**
+     * Choices fetched from a plugin route instead (#463), for a `select` or `multiselect` only -- the
+     * validator rejects it on any other type, and beside a non-empty `options` (one source of choices,
+     * not two). When the route cannot be loaded the shell degrades the field
+     * to a text box (a `multiselect`'s text is a comma-separated list) and shows the reason, so an action
+     * is never blocked by its picker. Additive.
+     */
+    optionsFrom?: ActionOptionsSource;
+}
+/** A confirm-gated action; the shell builds its button + modal from these fields (#34). */
+export interface ActionContribution {
+    id: string;
+    /** Button/label text; the shell falls back to `id` when omitted. */
+    title?: string;
+    /** What the action operates on, e.g. "issue" | "report" | "global". */
+    scope: string;
+    confirm?: boolean;
+    danger?: boolean;
+    /** The form the shell builds the action's modal from; omit for a no-input action. */
+    fields?: ActionField[];
+}
+/** Where a contributed job runs: in the host, or fanned out to the paired agents (E4). */
+export type JobRunOn = "host" | "agent";
+/** A scheduled job. */
+export interface JobContribution {
+    id: string;
+    /** 5-field cron expression. */
+    schedule: string;
+    /** Per-run timeout in seconds. */
+    timeoutSec: number;
+    runOn: JobRunOn;
+    /** A `runOn: "agent"` job is not dispatched to a machine whose paired agent version compares lower
+     *  than this (#372, #80); the run row records the skip with its reason instead. Ignored for a
+     *  `runOn: "host"` job. Additive; absent means every paired machine is always dispatched, as
+     *  before this field existed. */
+    minAgentVersion?: string;
+}
+/** HTTP method for a contributed route. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** An HTTP route; the host mounts it under `/api/x/<plugin-id>/<path>`. */
+export interface RouteContribution {
+    method: HttpMethod;
+    /** Path under the plugin's namespace, e.g. "/feed". */
+    path: string;
+}
+/** JSON scalar type of a plugin setting (rendered by Admin). */
+export type SettingType = "string" | "integer" | "number" | "boolean";
+/** A plugin setting. */
+export interface SettingContribution {
+    key: string;
+    type: SettingType;
+    default?: string | number | boolean;
+}
+/** A theme contributed as token JSON only (no code). */
+export interface ThemeContribution {
+    id: string;
+    title?: string;
+}
+/** A named, versioned slot this plugin provides or consumes. */
+export interface SlotRef {
+    /** The slot name, one of the `SLOTS` ids, e.g. "issues". */
+    slot: string;
+    /** Integer slot version; the host resolves provider/consumer by exact equality. */
+    version: number;
+}
+/** The contribution points a plugin offers. Every field is optional; a plugin contributes a subset. */
+export interface Contributes {
+    panels?: PanelContribution[];
+    cards?: CardContribution[];
+    actions?: ActionContribution[];
+    jobs?: JobContribution[];
+    routes?: RouteContribution[];
+    settings?: SettingContribution[];
+    themes?: ThemeContribution[];
+    provides?: SlotRef[];
+    consumes?: SlotRef[];
+    /** #78: the plugin serves `GET /api/x/<id>/attention` -> `{ ok: true, items: AttentionItem[] }`
+     *  (`attention.ts`). The `overview` plugin's rollup card discovers contributors via
+     *  `PluginView.attention` (`views.ts`) rather than a second manifest read. Additive; always `true`
+     *  when present (a boolean, not a route list, since the path is fixed). */
+    attention?: true;
+}
+/** A declared environment variable (field names shared verbatim with the discord-bot index). */
+export interface EnvVar {
+    key: string;
+    /** Anchored regex the value must match, e.g. "^[0-9]+$". */
+    format?: string;
+    required?: boolean;
+    secret?: boolean;
+}
+/** A sidecar plugin's image and health path. Present when `kind === "sidecar"`. */
+export interface SidecarSpec {
+    image: string;
+    healthPath: string;
+}
+/**
+ * The `acPlugin` block of a plugin's package.json — everything the host needs before it loads any
+ * code. The host validates this against the generated JSON Schema (issue #26). `hostApiVersion` is
+ * an integer that must equal the host's `HOST_API_VERSION`.
+ */
+export interface AcPluginManifest {
+    /** Permanent id: state key, route namespace (`/api/x/<id>/`), log prefix. Never rename. */
+    id: string;
+    /** Integer, equal to the host's HOST_API_VERSION. */
+    hostApiVersion: number;
+    kind: PluginKind;
+    /** Server entry exporting `createPlugin(host)`; required for `kind: "in-process"`. */
+    server?: string;
+    /** Frontend ESM entry; omitted by a plugin that contributes no UI. */
+    frontend?: string;
+    /** Image + health path; required when `kind: "sidecar"`. */
+    sidecar?: SidecarSpec;
+    /** Host-agent capabilities the plugin may use, each granted per machine in Admin (E4). */
+    capabilities?: string[];
+    contributes?: Contributes;
+    env?: EnvVar[];
+}
+/**
+ * The host-side state the host keeps per plugin (design.md §3). Not part of the manifest; lives in
+ * SQLite and is surfaced by Admin. A plugin being `enabled` is distinct from being configured — an
+ * enabled-but-misconfigured plugin loads and reports its `error`, it is not dropped.
+ */
+export interface PluginStateEntry {
+    id: string;
+    enabled: boolean;
+    /** The version currently loaded, if the plugin came from an index. */
+    installedVersion?: string;
+    /** The last load/validation/activation error, if any (shown by Admin, never fatal to the host). */
+    error?: string;
+    /** Host-agent capabilities granted to this plugin, by machine (E4). Unused; grants live in
+     *  `/api/agents`, #50. */
+    grantedCapabilities?: string[];
+    /** For a `kind: "sidecar"` plugin, its health as of the last poll (#29); absent for in-process. */
+    sidecar?: {
+        state: "healthy" | "degraded";
+    };
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.js

@@ -0,0 +1,9 @@
+/**
+ * The `acPlugin` manifest block and its contribution points — the data the host validates before
+ * loading any plugin code (design.md §4). This file is the JSON-Schema generation target
+ * (`gen-schema.mjs` -> `schema.json`), so keep it self-contained (no relative imports) and every
+ * shape a plain data object. Field names are shared verbatim with the discord-bot index
+ * (`hostApiVersion`, `env[]`).
+ */
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/ov-widgets.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The 16 1.x `OV_WIDGETS` ids (E7 #77), ported byte-identical from
+ * `frontend/src/layout.ts`'s own `id`/`label`/`h` (its `size` field is always `"third"` in 1.x and
+ * has no 2.0 equivalent -- height tiers are `h` alone here). Each row also names its 2.0 OWNER
+ * plugin (plan §5 decision 1): the registry id `HomeCards` actually renders is
+ * `plugin:<owner>:<id>` (`ovRegistryId` below), never the bare 1.x id -- a saved 1.x
+ * `dashboard-layout.json` needs the one-time upgrade in `shell/layout.ts`'s `upgradeLegacyLayout`
+ * to round-trip. RENAMING an `id` here orphans every stored layout that references it, the same as
+ * 1.x's own comment warns; adding/reordering rows is safe.
+ */
+export type OverviewOwner = "overview" | "metrics-claude" | "repos" | "artifacts" | "provider-github";
+export interface OverviewWidget {
+    id: string;
+    label: string;
+    owner: OverviewOwner;
+    h: 1 | 2 | 3;
+}
+export declare const OV_WIDGETS: readonly OverviewWidget[];
+/** The registry id `HomeCards` actually renders for one `OV_WIDGETS` row: `plugin:<owner>:<id>`. */
+export declare function ovRegistryId(widget: OverviewWidget): string;
+//# sourceMappingURL=ov-widgets.d.ts.map

package/dist/ov-widgets.js

@@ -0,0 +1,33 @@
+/**
+ * The 16 1.x `OV_WIDGETS` ids (E7 #77), ported byte-identical from
+ * `frontend/src/layout.ts`'s own `id`/`label`/`h` (its `size` field is always `"third"` in 1.x and
+ * has no 2.0 equivalent -- height tiers are `h` alone here). Each row also names its 2.0 OWNER
+ * plugin (plan §5 decision 1): the registry id `HomeCards` actually renders is
+ * `plugin:<owner>:<id>` (`ovRegistryId` below), never the bare 1.x id -- a saved 1.x
+ * `dashboard-layout.json` needs the one-time upgrade in `shell/layout.ts`'s `upgradeLegacyLayout`
+ * to round-trip. RENAMING an `id` here orphans every stored layout that references it, the same as
+ * 1.x's own comment warns; adding/reordering rows is safe.
+ */
+export const OV_WIDGETS = [
+    { id: "attention", label: "Needs attention", owner: "overview", h: 2 },
+    { id: "actions", label: "Action ledger", owner: "artifacts", h: 2 },
+    { id: "sched", label: "Scheduled tasks", owner: "overview", h: 2 },
+    { id: "recent", label: "Recent activity", owner: "artifacts", h: 2 },
+    { id: "trend", label: "Store growth", owner: "artifacts", h: 2 },
+    { id: "reviews", label: "Code review status", owner: "artifacts", h: 2 },
+    { id: "prs", label: "PR review & auto-merge", owner: "provider-github", h: 3 },
+    { id: "issues", label: "Open issues", owner: "provider-github", h: 3 },
+    { id: "projects", label: "Build & release status", owner: "provider-github", h: 3 },
+    { id: "actions-usage", label: "Actions usage", owner: "provider-github", h: 3 },
+    { id: "context-pressure", label: "Context pressure", owner: "metrics-claude", h: 3 },
+    { id: "memory-footprint", label: "Memory footprint", owner: "metrics-claude", h: 3 },
+    { id: "subagent-cost", label: "Subagent cost", owner: "metrics-claude", h: 3 },
+    { id: "latest", label: "Latest by category", owner: "artifacts", h: 3 },
+    { id: "distribution", label: "Category distribution", owner: "artifacts", h: 3 },
+    { id: "repo-currency", label: "Repo currency", owner: "repos", h: 3 },
+];
+/** The registry id `HomeCards` actually renders for one `OV_WIDGETS` row: `plugin:<owner>:<id>`. */
+export function ovRegistryId(widget) {
+    return `plugin:${widget.owner}:${widget.id}`;
+}
+//# sourceMappingURL=ov-widgets.js.map

package/dist/slots.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The four composition slots v2.0 defines (design.md §4). A slot is a named, versioned TypeScript
+ * interface one plugin `provides` and others `consume`; the host refuses to activate a consumer
+ * whose slot has no provider and says why (issue #30). The slot names/versions live in `version.ts`
+ * (`SLOTS`) and are irreversible.
+ *
+ * These are the v1 seams. The rich record shapes are enriched additively by the consuming epics —
+ * `issues@1` by E5 (`ac-provider-github`, #56), `artifacts@1` by E6 (`ac-artifacts`, #68) — so add
+ * fields backward-compatibly and bump the slot version for a breaking change.
+ *
+ * `issues@1` was enriched by 56a (E5 #56): `labels`/`assignees` grew from bare strings into
+ * `Label`/`Person` records (colour for the Board's hex chips, avatar for people), and `IssuesProvider`
+ * gained `listPullRequests`/`counts` -- still `issues@1`, no shipped consumer existed yet (panels are
+ * built later in E5), so completing the v1 shape here is not a breaking change.
+ */
+/** A forge-agnostic reference to a repository (design §4: forge-agnostic records). */
+export interface RepoRef {
+    owner: string;
+    name: string;
+}
+/** A GitHub label, carrying its colour for the Board's hex chips. `color` is the 6-hex RGB with no '#'.
+ *  `description` is additive (#86c-labels): populated for a label sourced from the org standard
+ *  (labels.json), omitted for a label sourced from an issue/PR's own `labels[]` -- neither existing
+ *  consumer (the Board's chips, the issue/PR label lists) needs it, so it stays optional rather than
+ *  forcing every `mapLabels` call site to fetch it. */
+export interface Label {
+    name: string;
+    color: string;
+    description?: string;
+}
+/** A GitHub account (assignee/author). */
+export interface Person {
+    login: string;
+    avatarUrl?: string;
+    /** GitHub's own flag for a bot account (`type === "Bot"`): true for one, OMITTED for everyone else (never
+     *  `false`, so existing records and fixtures are unchanged). Never guessed from the login (#464a). */
+    isBot?: boolean;
+}
+/** A forge-agnostic issue record (v1 seam; E5 #56 enriches). */
+export interface IssueRecord {
+    repo: RepoRef;
+    number: number;
+    title: string;
+    state: "open" | "closed";
+    labels: Label[];
+    assignees: Person[];
+    author?: Person;
+    commentsCount: number;
+    createdAt: string;
+    updatedAt: string;
+    url: string;
+}
+/** An open/closed pull request. `body` is kept for the closes-#N priority inference (pulse priority.ts). */
+export interface PullRequestRecord {
+    repo: RepoRef;
+    number: number;
+    title: string;
+    state: "open" | "closed";
+    body: string;
+    labels: Label[];
+    author?: Person;
+    createdAt: string;
+    updatedAt: string;
+    url: string;
+}
+/** Open/closed issue counts for a repo. */
+export interface IssueCounts {
+    open: number;
+    closed: number;
+}
+/** Latest repo-level CI/Pages signals for the Board (E5 #64). A null conclusion = not applicable
+ *  (no workflows / no Pages) — the Board renders a transparent CI border and a neutral globe, never red. */
+export interface RepoSignals {
+    /** Latest Actions workflow-run conclusion ("success"|"failure"|"cancelled"|…), or null if the repo has no runs. */
+    workflowConclusion: string | null;
+    /** Latest GitHub Pages build conclusion ("built"|"errored"|…), or null if Pages is not configured. */
+    pagesConclusion: string | null;
+}
+/** The org label standard, read live from Rackbops/Tooling's labels.json (E5 #58). Arrays preserve
+ *  labels.json order (the filter pickers render in this order). `exclusive` names the single-select groups. */
+export interface LabelStandard {
+    priority: Label[];
+    effort: Label[];
+    type: Label[];
+    exclusive: string[];
+}
+/** `issues@1`: list/search/labels/people/mutate over forge-agnostic records. */
+export interface IssuesProvider {
+    /** List issues for a repo in a given state. */
+    listIssues(repo: RepoRef, state: "open" | "closed" | "all"): Promise<IssueRecord[]>;
+    /** List pull requests for a repo in a given state. */
+    listPullRequests(repo: RepoRef, state: "open" | "closed" | "all"): Promise<PullRequestRecord[]>;
+    /** Open/closed issue counts for a repo. */
+    counts(repo: RepoRef): Promise<IssueCounts>;
+    /** Latest workflow-run + Pages-run signals for a repo (E5 #64). */
+    signals(repo: RepoRef): Promise<RepoSignals>;
+    /** The org label standard, read live from Rackbops/Tooling's labels.json (E5 #58). */
+    standard(): Promise<LabelStandard>;
+    /** A repo's own labels, independent of the standard (E5 #58). */
+    repoLabels(repo: RepoRef): Promise<Label[]>;
+}
+/** A node in the artifacts report tree (v1 seam; E6 #68 enriches). */
+export interface ArtifactNode {
+    id: string;
+    title: string;
+    kind: "category" | "run" | "report";
+    children?: ArtifactNode[];
+}
+/** `artifacts@1`: tree/read/search/render-status. */
+export interface ArtifactsProvider {
+    /** The report tree. */
+    tree(): Promise<ArtifactNode[]>;
+    /** Raw source of one report by id. */
+    read(id: string): Promise<string>;
+}
+/** An authenticated identity. */
+export interface Identity {
+    id: string;
+    email?: string;
+    name?: string;
+}
+/** `auth@1`: resolve the identity for a request, or null in open mode. */
+export interface AuthProvider {
+    /** Resolve the identity from a request's headers, or null when unauthenticated. */
+    identify(headers: Record<string, string | undefined>): Promise<Identity | null>;
+}
+/** Severity of a notification, for styling/routing. */
+export type NotifySeverity = "info" | "warning" | "error";
+/** A message to fan out through a notify provider. */
+export interface NotifyMessage {
+    title: string;
+    body: string;
+    severity?: NotifySeverity;
+}
+/** `notify@1`: fan out a message to this provider's channel. */
+export interface NotifyProvider {
+    send(message: NotifyMessage): Promise<void>;
+}
+//# sourceMappingURL=slots.d.ts.map

package/dist/slots.js

@@ -0,0 +1,17 @@
+/**
+ * The four composition slots v2.0 defines (design.md §4). A slot is a named, versioned TypeScript
+ * interface one plugin `provides` and others `consume`; the host refuses to activate a consumer
+ * whose slot has no provider and says why (issue #30). The slot names/versions live in `version.ts`
+ * (`SLOTS`) and are irreversible.
+ *
+ * These are the v1 seams. The rich record shapes are enriched additively by the consuming epics —
+ * `issues@1` by E5 (`ac-provider-github`, #56), `artifacts@1` by E6 (`ac-artifacts`, #68) — so add
+ * fields backward-compatibly and bump the slot version for a breaking change.
+ *
+ * `issues@1` was enriched by 56a (E5 #56): `labels`/`assignees` grew from bare strings into
+ * `Label`/`Person` records (colour for the Board's hex chips, avatar for people), and `IssuesProvider`
+ * gained `listPullRequests`/`counts` -- still `issues@1`, no shipped consumer existed yet (panels are
+ * built later in E5), so completing the v1 shape here is not a breaking change.
+ */
+export {};
+//# sourceMappingURL=slots.js.map

package/dist/version.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Version constants for the plugin contract. These are additive-only, irreversible identifiers:
+ * a plugin's manifest declares `hostApiVersion` and the four slot names, and a deployed plugin
+ * resolves against them, so a bump or rename must be deliberate (pinned by `version.test.ts`).
+ */
+/** The host API version. A plugin's manifest `hostApiVersion` must equal this (integer equality). */
+export declare const HOST_API_VERSION = 1;
+/**
+ * The four composition slots v2.0 ships, each a `name@version`. The `name` strings are the ids a
+ * plugin puts in `contributes.provides` / `contributes.consumes`; renaming one orphans every
+ * plugin that named it, so they are treated as irreversible (CLAUDE.md, "Irreversible identifiers").
+ */
+export declare const SLOTS: {
+    readonly issues: {
+        readonly name: "issues";
+        readonly version: 1;
+    };
+    readonly artifacts: {
+        readonly name: "artifacts";
+        readonly version: 1;
+    };
+    readonly auth: {
+        readonly name: "auth";
+        readonly version: 1;
+    };
+    readonly notify: {
+        readonly name: "notify";
+        readonly version: 1;
+    };
+};
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,19 @@
+/**
+ * Version constants for the plugin contract. These are additive-only, irreversible identifiers:
+ * a plugin's manifest declares `hostApiVersion` and the four slot names, and a deployed plugin
+ * resolves against them, so a bump or rename must be deliberate (pinned by `version.test.ts`).
+ */
+/** The host API version. A plugin's manifest `hostApiVersion` must equal this (integer equality). */
+export const HOST_API_VERSION = 1;
+/**
+ * The four composition slots v2.0 ships, each a `name@version`. The `name` strings are the ids a
+ * plugin puts in `contributes.provides` / `contributes.consumes`; renaming one orphans every
+ * plugin that named it, so they are treated as irreversible (CLAUDE.md, "Irreversible identifiers").
+ */
+export const SLOTS = {
+    issues: { name: "issues", version: 1 },
+    artifacts: { name: "artifacts", version: 1 },
+    auth: { name: "auth", version: 1 },
+    notify: { name: "notify", version: 1 },
+};
+//# sourceMappingURL=version.js.map