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

package/dist/views.d.ts

@@ -0,0 +1,262 @@
+import type { ActionField, JobRunOn } from "./manifest.js";
+/**
+ * The `GET /api/plugins` and `GET /api/cards` response item shapes (#32/#33) — additive-only wire
+ * contracts (design.md's additive-only rule) shared by the host (which builds them,
+ * `packages/host/src/plugins/view.ts` / `packages/host/src/cards/config-cards.ts`) and the shell
+ * (which renders them, `packages/ui-shell/src/plugins.ts` / `packages/ui-shell/src/cards/`), so the
+ * two sides cannot silently drift on a field (#148). Not part of the plugin manifest schema
+ * (`gen-schema.mjs` generates only from `AcPluginManifest` in `./manifest.js`).
+ */
+export interface PluginPanelView {
+    id: string;
+    title: string;
+    route: string;
+    nav?: string;
+    export: string;
+    navOwner: boolean;
+    /**
+     * This panel's position among every panel in the response (#472): a non-negative integer, lower
+     * first, resolved by the host per request from the operator's `tab_order` setting, then each
+     * manifest's `order`, then the existing order (`packages/host/src/plugins/rank.ts`). The tab strip,
+     * the nav drawer and the quickcast panel list all sort by it, so the shell needs no second fetch and
+     * the three surfaces cannot disagree. A shell reading a response with no `rank` (an older host) keeps
+     * the order it arrived in.
+     */
+    rank: number;
+}
+export interface PluginCardView {
+    id: string;
+    title: string;
+    sizes: string[];
+    export: string;
+}
+/**
+ * A confirm-gated action the shell builds a button + form from (#34). Unlike panels/cards, an action is
+ * pure data (no `export`), so it is surfaced for any loadable plugin regardless of whether it ships a
+ * frontend bundle. `confirm`/`danger` are normalised to booleans and `fields` to an array for the shell.
+ */
+export interface PluginActionView {
+    id: string;
+    title: string;
+    scope: string;
+    confirm: boolean;
+    danger: boolean;
+    fields: ActionField[];
+}
+/**
+ * A job this plugin declares (#83) — the sched mini card's own source, since no Admin jobs table
+ * exists yet (E8). Like actions, pure data (no `export`), so it is surfaced for any loadable plugin
+ * regardless of whether it ships a frontend bundle. `runOn` is carried because `GET /api/jobs/
+ * :pluginId/:jobId/runs`'s response already exposes it per call, and this card's row model
+ * (`SchedRow.runOn`) plumbs it through end to end even though its current render doesn't surface it
+ * (found in review, round 2 — a candidate for a future small UI addition, not a bug).
+ * `timeoutSec`/`minAgentVersion` are deliberately left off instead, independent of that: the runs
+ * route's `skipped` reason already reflects a `minAgentVersion` gate as a per-machine fact, so
+ * duplicating the threshold itself here would have no reader.
+ */
+export interface PluginJobView {
+    id: string;
+    /** 5-field cron expression, exactly as declared — no parsing/formatting here. */
+    schedule: string;
+    runOn: JobRunOn;
+}
+/**
+ * Where a plugin was discovered from (#183): `bundled` under the image's own `plugins/` dir, `installed`
+ * under an operator-installed-plugins dir. Derived from the scan root a plugin was found under, never
+ * from the manifest — a plugin cannot declare itself first-party. Until the install path exists (E2's
+ * #35 follow-up) every plugin is `bundled`.
+ */
+export type PluginOrigin = "bundled" | "installed";
+export interface PluginView {
+    id: string;
+    enabled: boolean;
+    /** Required even on an errored entry — it is a property of where the plugin came from, not of loading. */
+    origin: PluginOrigin;
+    error?: string;
+    installedVersion?: string;
+    sidecar?: {
+        state: "healthy" | "degraded";
+    };
+    /** URL to `import()` the single frontend bundle; present only for a loadable in-process plugin. */
+    frontend?: string;
+    panels?: PluginPanelView[];
+    cards?: PluginCardView[];
+    actions?: PluginActionView[];
+    /** Jobs this plugin declares (#83), pure data like `actions` above; present only when non-empty --
+     *  what the `overview` plugin's `sched` mini card lists one row per. */
+    jobs?: PluginJobView[];
+    /** Host-agent capabilities this plugin declares (#50), sorted; present only when non-empty --
+     *  what the Agents panel's Grants grid lists one row per. */
+    capabilities?: string[];
+    /** #78: mirrors the manifest's `contributes.attention` -- present (`true`) only when this plugin
+     *  serves `GET /api/x/<id>/attention`, so the needs-attention rollup discovers contributors from
+     *  this ONE `/api/plugins` read rather than a second manifest fetch per plugin. */
+    attention?: true;
+}
+/**
+ * `GET /api/server` (#43): a cheap liveness/identity probe the shell's heartbeat polls to tell a
+ * restarted process (changed `pid`/`startedAt`) from a merely slow one, and to show uptime/version.
+ * Additive-only, like the other wire contracts in this file; `ok` is always `true` here (a fetch
+ * failure or non-200, not a `false` field, is how the shell learns the host is unreachable).
+ */
+export interface ServerStatus {
+    ok: true;
+    pid: number;
+    startedAt: string;
+    uptimeSeconds: number;
+    version: string;
+    apiVersion: number;
+}
+/** One field of a declarative card's template — a dot-path into the validated response. */
+export interface CardField {
+    label: string;
+    /** A dot-path into the validated response, e.g. "status" or "data.uptime". */
+    path: string;
+}
+/**
+ * A no-code declarative card (#33): a host-relative route URL, a JSON Schema for its response, and a
+ * field-list template. Authored in `config.toml`'s `[[card]]` array-of-tables, served at
+ * `GET /api/cards`, and rendered by the shell's `DeclarativeCard`.
+ */
+export interface DeclarativeCardDef {
+    id: string;
+    title: string;
+    url: string;
+    /** A JSON Schema for the fetched response; a response that fails it renders the card's error state. */
+    schema: object;
+    template: {
+        fields: CardField[];
+    };
+}
+/** What started a task: a manually-triggered job (#31), an agent run (E4), or a sidecar run (E4/E6). */
+export type TaskKind = "job" | "agent" | "sidecar";
+/** `queued` (#51): an agent-job task waiting on an unreachable machine, badged red in the drawer. */
+export type TaskStatus = "running" | "done" | "failed" | "queued";
+/**
+ * The `GET /api/tasks` list item (#42) — the host's in-memory task registry's view of one run. Not a
+ * durable record: `id`s are per-process (`t<seq>`) and the list empties on restart; `job_runs` (#31)
+ * stays the durable history for jobs specifically.
+ */
+export interface TaskView {
+    id: string;
+    kind: TaskKind;
+    label: string;
+    status: TaskStatus;
+    startedAt: string;
+    endedAt?: string;
+}
+/**
+ * One machine's row in `JobsService.machineRuns` / `GET /api/jobs/:pluginId/:jobId/runs` (#51). A host
+ * job (`runOn: "host"`) is always exactly one entry with both ids `null`. An agent job has one entry
+ * per currently paired machine: `lastRun` when that machine has a recorded run, `queued` when a job is
+ * currently waiting in the durable queue for it. The two are independent and CAN both be set -- a
+ * machine with an earlier successful run that has since gone unreachable shows both its last known
+ * run and the current wait, rather than losing the last-run fact while queued.
+ */
+export interface JobMachineRun {
+    machineId: string | null;
+    machineName: string | null;
+    lastRun?: {
+        startedAt: string;
+        ok: boolean;
+    };
+    queued?: {
+        queuedAt: string;
+        reason: string;
+    };
+    /** This machine's paired agent version compares lower than the job's declared `minAgentVersion`
+     *  (#372, #80) -- computed live from the machine's CURRENT version every call, never persisted, so
+     *  it always reflects "would a dispatch right now skip this machine", not a stale historical fact.
+     *  Independent of `lastRun`/`queued`, which can still be set from before the machine fell behind. */
+    skipped?: {
+        reason: string;
+    };
+}
+/**
+ * The Overview home-cards layout (#44), 1.x-compatible: `GET /api/layout` / `POST /api/layout` shape,
+ * and the localStorage `ac-layout` mirror. `order`/`hidden` are card ids (`config:<id>` for a
+ * declarative card, `plugin:<pluginId>:<cardId>` for a plugin's — the scheme E8's `import-v1` targets);
+ * `sizes` is a sparse per-card height-tier override. The store is id-dumb — it never validates an id
+ * against a real card, so a card added/removed/renamed in a later plugin build never needs a server
+ * change (`packages/host/src/layouts/store.ts`'s `cleanLayout`).
+ */
+export interface DashLayout {
+    order: string[];
+    hidden: string[];
+    sizes: Record<string, {
+        h: 1 | 2 | 3;
+    }>;
+}
+/**
+ * `GET /api/agents` (#48): one paired machine, as the console's `machines` table sees it. Never
+ * carries the bearer token the console sends it (`packages/host/src/agents/store.ts`'s `list`/`get`
+ * don't select it) -- the row is safe to render straight into the Agents panel.
+ */
+export interface MachineView {
+    id: string;
+    name: string;
+    url: string;
+    certFingerprint: string;
+    agentVersion: string;
+    apiVersion: number;
+    lastSeenAt?: string;
+    createdAt: string;
+    /** Whether this machine can open a `claude://` link, as its agent last reported on `GET
+     *  /v1/health` (#457): `true` (a handler is registered), `false` (the agent looked and found no
+     *  handler), or `null` -- the agent did not say: it predates the field, it holds no conclusive answer
+     *  yet (it omits the field until it does), or the machine has not been probed since it was paired.
+     *  Optional in the type so no pre-existing fixture has to name it; this host always sets it, and a
+     *  consumer treats `undefined` exactly like `null`. `POST /deeplink` refuses only a known `false`. */
+    claudeDesktop?: boolean | null;
+    /** This machine's current grants, plugin id -> capabilities (#50). */
+    grants?: Record<string, string[]>;
+    /** `grantsRevision` of the row above -- what `HostApi.agent.call` sends so a stale agent can
+     *  answer 409 and self-heal instead of enforcing against data the console has already changed. */
+    grantsRevision?: string;
+}
+/**
+ * The outcome of `HostApi.agent.call` (#50). `kind` tells a plugin which refusals are its own to
+ * show verbatim (`grant`: the agent's 403 text) from ones that are the console's problem to
+ * describe differently (`unknown-machine`; `refused`: not a verb the service will forward; `pin`:
+ * the agent's certificate no longer matches; `network`; `http`: an unexpected status).
+ */
+export type AgentCallOutcome<T> = {
+    ok: true;
+    status: number;
+    body: T;
+} | {
+    ok: false;
+    error: {
+        kind: "unknown-machine" | "refused" | "grant" | "pin" | "network" | "http";
+        status?: number;
+        reason: string;
+    };
+};
+/**
+ * `POST /api/agents/:id/preflight` (#55): the agent's own `GET /v1/preflight` report, relayed
+ * verbatim by the host. `missing`/`broken` on a `required: true` row means the install isn't
+ * finished; on an optional one (`chromium`) it just degrades one output. `off-path` is installed
+ * but invisible to a service-started agent (a version-manager node, say) -- a PATH fix, not a
+ * reinstall. `unauthenticated` is `gh`-only: present and running, but `gh auth status` failed.
+ * Independently defined here from the agent's own (identically-shaped) internal type -- the host
+ * never depends on `@rackbops/ac-agent` at runtime, only as a devDependency for its integration
+ * tests, matching `grants.ts`'s own id/capability pattern.
+ */
+export type PreflightStatus = "ok" | "missing" | "broken" | "off-path" | "unauthenticated";
+export interface PreflightRow {
+    cmd: string;
+    label: string;
+    status: PreflightStatus;
+    required: boolean;
+    path: string;
+    why: string;
+    version: string;
+    detail: string;
+}
+export interface PreflightReport {
+    machine: string;
+    checkedAt: string;
+    searchPath: "registry" | "process";
+    rows: PreflightRow[];
+}
+//# sourceMappingURL=views.d.ts.map

package/dist/views.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=views.js.map

package/host.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for the shell's own import of `@ac/host` (#38). At runtime the specifier resolves through the
+ * host page's import map to `/vendor/ac-host.js` — the SAME module instance every plugin imports — which
+ * is what lets the shell register its chrome (toast portal, confirm modal #41, quickcast palette #142)
+ * into the module plugins call. The implementation is `vendor/ac-host-entry.mjs` (plain JS); this declaration
+ * types it against `@ac/contract`'s `BrowserHostApi` for the shell's TypeScript. In Vitest the
+ * specifier is aliased to the entry file (see `vite.config.ts` `test.alias`); in the Vite build it
+ * stays external (`vendor.config.mjs` `EXTERNALS`).
+ *
+ * The marker pair below (search this file for "SHELL-INTERNAL", #450) wraps the chrome-registration
+ * declarations that are shell-internal, never plugin-facing — `packages/plugin-contract/build.mjs`
+ * strips everything between them when it generates the published `@rackbops/ac-plugin-contract/host`
+ * declaration for out-of-repo plugin authors, and fails loudly (never publishes a partial/guessed
+ * result) if a marker goes missing, or if either wrapped name survives the strip regardless. This
+ * comment deliberately does not spell either name out literally, so it can never itself be mistaken
+ * for a leftover.
+ */
+declare module "@ac/host" {
+  import type {
+    ActionOpenRef,
+    ActionSettledEvent,
+    BrowserHostApi,
+    FilterToken,
+    HeaderButtonSpec,
+    IssueFilter,
+    IssueRecord,
+    MatchContext,
+    QuickcastItem,
+    ToastSeverity,
+  } from "@rackbops/ac-plugin-contract"
+
+  export const hostApiVersion: number
+  export const theme: BrowserHostApi["theme"]
+  export const toast: BrowserHostApi["toast"]
+  export const header: BrowserHostApi["header"]
+  export const actions: BrowserHostApi["actions"]
+  export const quickcast: BrowserHostApi["quickcast"]
+  export const fetch: BrowserHostApi["fetch"]
+  export const cached: BrowserHostApi["cached"]
+  export const invalidate: BrowserHostApi["invalidate"]
+  /** The shared filter predicate (E5 #56, decision 4/9/10): pure, `now`-injected, over `IssueRecord`.
+   *  Both the Board (#63) and Classic (#59) panels apply this same function so their counts agree by
+   *  construction. The filter *types* (`IssueFilter`, `SetFilter`, `AgeFilter`, `AgeBucket`, `FilterOp`)
+   *  are compile-time only -- a plugin's own `.ts` imports those directly from `@ac/contract` with
+   *  `import type` (erased at build time, so it is never a runtime import the import map would need an
+   *  entry for); only this function and the filter tokens below need re-exporting through `@ac/host`. `ctx` (#464a) is what
+   *  the filter tokens below resolve against -- the viewer's login and each ladder's label names. */
+  // biome-ignore format: ONE line, so each plugin's ac-host-drift.test.ts pins the whole signature and not only its first line
+  export function matchesIssue(record: IssueRecord, filter: IssueFilter, now: number, ctx?: MatchContext): boolean
+  /** The filter tokens (#464a, `@ac/contract`'s `issue-filter.ts`): the values `@me`, `@unassigned`, `@bots`,
+   *  `@any` and `@upto:<label>` in a `SetFilter` -- the viewer, nobody, bots, any ladder label, and "this rung
+   *  or before it". */
+  export const FILTER_ME: string
+  export const FILTER_UNASSIGNED: string
+  export const FILTER_BOTS: string
+  export const FILTER_ANY: string
+  export function filterUpTo(name: string): string
+  export function parseFilterToken(value: string): FilterToken | undefined
+
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rackbops/ac-plugin-contract",
+  "version": "2.0.0-alpha.33",
+  "private": false,
+  "type": "module",
+  "description": "The artifact-console plugin ABI for out-of-repo plugin authors: HostApi, the acPlugin manifest contribution points, the generated manifest JSON Schema, and the @ac/host ambient browser declaration.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rackbops/artifact-console",
+    "directory": "packages/plugin-contract"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./schema.json": "./schema.json",
+    "./host": {
+      "types": "./host.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schema.json",
+    "host.d.ts",
+    "AUTHORING.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@octokit/rest": "22.0.1"
+  },
+  "devDependencies": {
+    "@ac/contract": "0.0.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.0",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}