@rackbops/ac-plugin-contract 2.0.0-alpha.41 → 2.0.0-alpha.43

package/AUTHORING.md

@@ -113,14 +113,21 @@ Rules the host enforces, at validation or load time:
   installed plugin errors, naming the bundled owner — and the bundled one keeps running unaffected. This
   is what stops a third-party package from disabling a bundled plugin (e.g. the auth provider, or `admin`
   itself) just by declaring its id. Two bundled plugins sharing an id is still a build/CI mistake and both
-  error, the same for two installed plugins with no bundled plugin in the collision.
+  error, the same for two installed plugins with no bundled plugin in the collision. **An installed plugin
+  may neither provide nor consume the `auth` slot** (#452b, #604): the install gate (`ac plugins install`
+  and the admin Plugins card's install, which share it) refuses a manifest whose `contributes.provides` or
+  `contributes.consumes` names `auth` (any version), and
+  at runtime `slots.provide`/`slots.resolve` refuse that slot to an installed plugin whatever its manifest
+  declares. Every other slot, `notify@1` included, is open to an installed plugin.
 - **`hostApiVersion`** must equal the host's `HOST_API_VERSION` (currently `1`); a mismatch is rejected.
 - **`kind: "in-process"`** must declare a `server` entry — the *loader* records an error and skips a plugin that
   doesn't (the schema itself requires only `id`, `hostApiVersion` and `kind`). `contributes` and every sub-field
   is optional in the schema — contribute only the points you use; each contribution's own required fields are
   schema-enforced.
-- **Jobs** (#137): a job's **`timeoutSec`** must be at least `1` (the schema's `minimum`; a zero or negative
-  timeout would fire at once and time out any run that awaits real I/O), and a job **`id`** must be unique
+- **Jobs** (#137, #580): a job's **`timeoutSec`** must be at least `1` and at most `2147483` (the schema's
+  `minimum` and `maximum`; a zero or negative timeout would fire at once and time out any run that awaits real
+  I/O, and about 24.8 days is the longest delay Node honours, so a longer or non-finite one would be fired at
+  once too), and a job **`id`** must be unique
   *within its plugin* -- two jobs with
   one id are rejected as `duplicate job id "<id>" within the plugin`, like a duplicate panel, card or action id.
   Job ids are plugin-scoped (a job is addressed as `<pluginId>/<jobId>`), so two different plugins may declare the
@@ -185,10 +192,16 @@ export const createPlugin: CreatePlugin = (host) => ({
   click, whether or not the manifest sets `confirm` -- there is no second "Confirm" click. `danger: true` gives
   that primary button the danger style, gives its Ctrl/Cmd+K palette row a danger badge, and stops Enter pressed in
   one of the form's fields from submitting it (a click on the button, or Enter or Space on the focused button,
-  still fires; Enter in a text area is a newline). A non-danger action still submits on Enter in any field,
-  including a checkbox or a radio (browsers treat that Enter as a submit): mark an action `danger` if it must
-  not fire from a stray Enter. The primary disables only while a request is in flight, so an action that
-  answers faster than an operator's second click can be run twice: make its `run` tolerate an overlapping call.
+  still fires; Enter in a text area is a newline). A non-danger action still submits on Enter in a text field;
+  Enter on a checkbox, a radio or a select never submits any action (#568), so ticking a label and pressing
+  Enter does not fire it: mark an action `danger` if it must not fire from a stray Enter in a text field either.
+  After a successful result the primary stays disabled until the modal closes, so an action that succeeded is
+  never run again from that modal, however fast it answers (a double-click whose first run resolves inside the
+  second click's interval, or a repeated Enter, cannot run it twice). The modal closes itself 1.5 s after the
+  success unless the user clicks in it first, and then it stays open, locked, until Cancel or Escape; opening the
+  same action again while that locked modal is up reuses it and does not re-run it. After a failed result the
+  primary is enabled again and a retry runs, so a double-click whose first run fails fast can run the action
+  twice (the second a retry): an action whose failure may have partly applied should tolerate that.
   `confirm` stays a valid manifest flag, so an existing manifest keeps loading, but neither the modal nor the
   palette acts on it.
 - **Job** — implement `runJob(ctx)` and dispatch on `ctx.jobId`. The host runs only jobs you declared in
@@ -197,7 +210,7 @@ export const createPlugin: CreatePlugin = (host) => ({
   newest 200 runs of that job (per machine, for a `runOn: "agent"` job) and drops runs older than 30 days,
   though never a job's (or machine's) newest run, so `host.jobs.lastRun` still answers for a job that runs
   less often than monthly. A job that runs every minute therefore no longer grows the run history without
-  bound. `ctx.signal` aborts at `timeoutSec` seconds (at least 1, #137). `runOn: "host"` runs your `runJob`
+  bound. `ctx.signal` aborts at `timeoutSec` seconds (1 to 2147483, #137, #580). `runOn: "host"` runs your `runJob`
   once, in the host process.
   `runOn: "agent"` (#51) also runs your `runJob` in the host process — the agent itself runs no plugin
   code — but once per currently paired machine, with `ctx.machine` set to `{ id, name }`; do the
@@ -432,6 +445,31 @@ strip of the panel uncovered between the header and the overlay; and the panel i
 the bar collapses. The layout arithmetic and the whole-pixel rounding were measured in desktop Chromium at
 375 px; the phone behaviours in this list are derived from the CSS, not observed on a phone.
 
+### A frontend that bundles a dependency (#98)
+
+"Only the import-map externals" is what keeps one React on the page; it does not forbid a plugin from
+bundling a library the import map does not carry. `plugins/ac-artifacts-weft` inlines
+`@lepid-labs/weft-embed` (a framework-free reader, 1.15 MB) and its stylesheet into `dist/ui.js`, and its
+`rollup.ui.config.mjs` is the reference. (The rollup configs of `issues-classic` and `ac-auth-cf-access`
+inline a dependency into their SERVER bundle, and every other plugin's UI config inlines nothing; none of
+them is a model for this.) What a bundled dependency changes:
+
+- **One file.** The host serves exactly the manifest's `frontend` and never a sibling, so a stylesheet is a
+  string in the bundle that the panel injects as a `<style>`, once (the config's `inlineCss` plugin turns
+  `import css from "pkg/style.css"` into that string), never a `<link>` to a `.css` file.
+- **Externals stay bare, everything else is inlined** (`@rollup/plugin-node-resolve`). The dependency goes in
+  `dependencies`, pinned exactly if its rendering is part of what you ship, and is absent at runtime: the
+  image carries `dist/` and no `node_modules`.
+- **A library without types** gets a `src/<lib>.d.ts` that declares the module, listed in the UI tsconfigs.
+- **Guard what shipped with a bundle test that runs the real build** (`src/bundle.test.ts` is the example):
+  anchor the import regex to the start of a line (inlined code carries doc comments such as ` * import
+  {unified} from 'unified'`), assert that no bare specifier outside the externals survives and that the
+  library is not one, that nothing needs `require(`, `import.meta` or `eval`, what the bundle exports, and a
+  size budget.
+- **A stylesheet you did not write must not restyle the shell.** Check its selectors for what is scoped (a
+  parser over the CSS is enough: weft's 0.2.0 rules are all scoped to its own root), and have the smoke spec
+  compare the shell's computed styles with and without it in the page.
+
 ### The `@ac/host` browser module
 
 `@ac/host` (typed as `BrowserHostApi` in `@ac/contract`) is the one shared module instance the shell and every
@@ -554,10 +592,13 @@ same-origin iframe (the Artifacts report preview does) forwards the hotkey: bind
 iframe's `contentDocument` (skip a frame whose `contentDocument` is null or throws: cross-origin), and on Ctrl
 or Cmd plus `k` with no Alt and no Shift, `preventDefault()` and dispatch `new CustomEvent("ac:quickcast-key")`
 on the parent `window`. The shell opens the palette under the keystroke's own guard: only when no other dialog
-is open, and an event while the palette is already open does nothing (closing stays with Ctrl/Cmd+K and
-Escape). Remove the listener when the frame goes away. Closing the palette with Escape leaves focus on the
-shell page rather than back inside the frame (observed in Chromium), so the user clicks the frame to type in
-it again.
+is open, and an event while the palette is already open leaves it open (closing stays with Ctrl/Cmd+K and
+Escape). Remove the listener when the frame goes away. Closing the palette with Escape or Ctrl/Cmd+K again
+returns focus to the frame element (#588): the native dialog's own restore does not put it back there for a
+palette opened from inside a frame (observed in Chromium), so the shell remembers the element that had focus
+when the event arrived and focuses it again when focus is nowhere useful after the close (on `body`, or
+still on a node of the palette that just closed). Which element inside the frame's own document has focus
+afterwards is the browser's call.
 
 `fetch` makes a same-origin, credentialed, CSRF-aware request to a host/plugin route — a relative `path`
 resolves against the console origin; a cross-origin absolute URL throws rather than being followed. A panel
@@ -995,7 +1036,25 @@ integer `rank` and the shell only sorts by it. The rule, in priority order:
 Ties break the same way, so the order is total. `order` is a hint the operator can always override with
 `tab_order`, so leave it off unless your panel belongs at the front (the Board declares `10`, Issues `20`,
 which puts them right after Home). `Home` is always first and is not orderable. A panel that lost a
-contested nav slot still has no tab, and still appears in quickcast at its ranked position.
+contested nav slot still has no tab, and still appears in quickcast at its ranked position (once the
+operator's choice has flipped the slot, the position the other panel's tab would hold: the two swap ranks, #629).
+
+**Contesting a nav slot (#65, #100).** A panel's `nav` names the slot it competes for the tab of. A slot with
+one panel is owned by it. When two or more panels from plugins that loaded without error name the same slot,
+the host picks one owner per request: the operator's choice, stored in the `nav.<slot>.panel` host setting
+(written through `POST /api/nav-slot` by the header's switcher, which renders only for a contested slot; an
+`AC_NAV_<SLOT>_PANEL` environment variable, when set, wins over it and pins the slot: the switcher for it is
+disabled, naming the variable, and `POST /api/nav-slot` answers `409`), else the smallest panel id. A panel
+that does not own its slot has no tab but keeps its route and its quickcast
+entry. The slot's tab stays where the default owner's would be, whichever panel owns it (#629), so a
+flip changes what the tab shows, not where it sits (a `tab_order` that names the chosen owner places it
+where the operator said). So declaring a `nav` another panel already has changes two things for every operator: the header gains
+the switcher, and the default owner is whichever panel id sorts first (an id that sorts after the existing
+owner leaves the default alone; one that sorts before it takes the tab from every operator who has not made a
+choice, and, since #629, also moves the slot's tab for an operator who has: its position is where the default
+owner's would be, and the default owner is the smallest id). The bundled example is the `artifacts` slot: the native viewer's `viewer` (`plugins/artifacts`, route
+`/artifacts`, the default) and the weft reader's `weft-reader` (`plugins/ac-artifacts-weft`, route
+`/artifacts-weft`).
 
 **`isolation` (#124).** A panel may declare `isolation: "iframe"`: the value is reserved (design §4) and the
 manifest accepts it, but nothing implements it in 2.0 and the host ignores it -- panels run in-process today,
@@ -1015,7 +1074,14 @@ refuses to activate a consumer whose slot has no provider, and says why (`resolv
 `packages/host/src/plugins/slots.ts`, re-exported from `plugins/index.ts`). `ac-auth-cf-access`
 (`auth@1`) and `ac-notify-discord` (`notify@1`) are the reference *providers*; see their own
 `src/server.ts` for `host.slots.provide(slot, version, impl)`, and `design.md` §4 for the slot
-contract itself. `hello` contributes none of the six points above via a slot (nor `attention` -- its own manifest
+contract itself. The consumer half is `host.slots.resolve<T>(slot, version)` (#97): the provider
+bound for a slot, or `null` when none is. It throws unless the plugin's own manifest lists the exact
+`{slot, version}` in `contributes.consumes`, and an installed plugin may not resolve `auth` at all. Call
+it at request time (inside a route handler or job), never in `activate()`: providers bind during
+activation in load order, so a consumer that activates first would read `null` there for good.
+`ac-artifacts-weft` (`artifacts@1`) is the reference consumer: the second plugin to declare `consumes`
+for it, after `artifacts`, which reads `provider-artifacts`' HTTP routes from the browser, and the first to
+call `resolve`. `hello` contributes none of the six points above via a slot (nor `attention` -- its own manifest
 declares panels/cards/actions/jobs/routes/settings only, matching the intro above) -- it's the
 reference for those six, not for slot provision or the attention rail; `plugins/scans` and
 `plugins/overview` are the worked examples for `contributes.attention` (§8 above).

package/dist/host-api.d.ts

@@ -175,6 +175,16 @@ export interface SlotRegistry {
     /** Register this plugin's provider instance for `slot@version`. Throws if that slot already has a
      *  provider (from this plugin or another) -- auth/notify are singletons, never a last-write-wins. */
     provide(slot: string, version: number, impl: unknown): void;
+    /** The provider bound for `slot@version`, cast to `T` (a slot's interface in `slots.ts`, e.g.
+     *  `ArtifactsProvider`), or `null` when nothing is bound. A plugin may resolve only a slot its
+     *  manifest lists in `contributes.consumes`; any other throws, naming the plugin and the slot. An
+     *  installed plugin may not resolve the `auth` slot at all, declared or not (as it may not provide it);
+     *  the install gate also refuses a manifest that declares `provides` or `consumes` for `auth` (#604),
+     *  so this call-time refusal is what remains for a plugin staged before that check.
+     *  Call it at request time (inside a route handler or job), never in `activate()`: providers bind
+     *  during activation in load order, so a consumer that activates before its provider would read `null`
+     *  there for good (#97). */
+    resolve<T = unknown>(slot: string, version: number): T | null;
 }
 /** A logger prefixed with the plugin id. */
 export interface LogService {

package/dist/manifest.d.ts

@@ -112,8 +112,11 @@ export interface JobContribution {
     schedule: string;
     /**
      * Per-run timeout in seconds. Must be at least 1: a zero or negative value would fire the timeout at
-     * once, timing out any run that awaits real I/O (#137).
+     * once, timing out any run that awaits real I/O (#137). And at most 2147483, about 24.8 days: Node
+     * clamps a longer or non-finite `setTimeout` delay to 1 ms, which fires it at once, the same failure
+     * (#580).
      * @minimum 1
+     * @maximum 2147483
      */
     timeoutSec: number;
     runOn: JobRunOn;

package/dist/slots.d.ts

@@ -99,19 +99,60 @@ export interface IssuesProvider {
     /** 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). */
+/** A node in the artifacts report tree (v1 seam; E6 #68 enriches).
+ *
+ *  A `report` node's `id` is its markdown source's path relative to the store's `artifacts/` directory
+ *  (`Code-Reviews/2026-09-01/summary.md`), the id `source`/`read` take; a report with no markdown source
+ *  (a rendered `.html` nothing in the store produced) falls back to its `href`. A `category` node's id is
+ *  `category:<name>` and a `run` node's `run:<category>/<run>`; neither names a readable source. */
 export interface ArtifactNode {
     id: string;
     title: string;
     kind: "category" | "run" | "report";
     children?: ArtifactNode[];
+    /** A report's markdown source path (the same relative path its `id` carries), absent when the report has
+     *  no markdown source. A node without it is a rendered `.html` only: `source`/`read` then answer that
+     *  rendered HTML, not markdown, so a consumer that expects markdown must skip such a node. Report nodes
+     *  only (#97). */
+    md?: string;
+    /** A report's viewer path: the rendered `.html` once rendered (`provider-artifacts`' `GET /render/<href>`
+     *  serves it from its docroot), else the `.md` source path, which that route does not serve (it reads the
+     *  docroot only; read the text through `source`). Report nodes only (#97). */
+    href?: string;
+}
+/** One `search` result: a section of one report. */
+export interface ArtifactSearchHit {
+    /** The id of the report the hit is in, built the same way as `ArtifactNode.id` for a report that has a
+     *  markdown source (search only reads markdown), so a hit opens through `source`/`read`. A report the
+     *  tree leaves out, such as a rendered `index` page, can still surface here. */
+    id: string;
+    /** The report's title as the search reads it (its first level-1 heading, else its file name with the
+     *  extension dropped and `-`/`_` shown as spaces). For a rendered report that can differ from the tree
+     *  node's title, which comes from the rendered page's `<title>`. */
+    title: string;
+    /** The matching section's heading id inside the rendered report, without a leading `#`. Absent when the
+     *  report is not rendered, when its rendered heading count disagrees with the source's, or when the
+     *  section has no id (a hit on the report's preamble, or an empty `id` attribute). */
+    anchor?: string;
+    /** A short excerpt around the match. */
+    snippet: string;
 }
-/** `artifacts@1`: tree/read/search/render-status. */
+/** `artifacts@1`: the report tree, one report's source by id, and ranked search over the markdown
+ *  sources. A consumer reaches it in-process through `HostApi.slots.resolve("artifacts", 1)` (#97). */
 export interface ArtifactsProvider {
     /** The report tree. */
     tree(): Promise<ArtifactNode[]>;
-    /** Raw source of one report by id. */
+    /** Raw source of one report by id; throws exactly when `source` would answer `null`. */
     read(id: string): Promise<string>;
+    /** Ranked cross-report search over the store's markdown sources, at most 50 hits (the cap `GET /search`
+     *  has); `CONTEXT.md`, `CONTENT.md`, `Archive/` and `.sync-inbox/` are not searched. An empty array for
+     *  an empty query. */
+    search(q: string): Promise<ArtifactSearchHit[]>;
+    /** Raw source of one report by id: `null` when no `.md` or `.html` resolves at that path inside the
+     *  store (or the path escapes it). The tree, not `source`, says what counts as a report: a path the tree
+     *  skips (an `index` page whose html exists, `CONTEXT.md`, anything under `Archive/`) still answers its
+     *  text here. */
+    source(id: string): Promise<string | null>;
 }
 /** An authenticated identity. */
 export interface Identity {

package/dist/views.d.ts

@@ -14,6 +14,15 @@ export interface PluginPanelView {
     nav?: string;
     export: string;
     navOwner: boolean;
+    /**
+     * Present (and only ever `"env"` today) on every contestant of a contested nav slot whose choice of owner
+     * an `AC_NAV_<SLOT>_PANEL` environment variable fixes (#628), so the shell can render that slot's switcher
+     * control disabled with the reason, and a script can expect `409` from `POST /api/nav-slot` for it. The
+     * variable pins the slot whatever its value is (one naming no contestant leaves the default owner, and the
+     * slot is still pinned). Absent otherwise (never `undefined`-valued). Optional, so a shell built before it
+     * ignores it.
+     */
+    navPinnedBy?: "env";
     /**
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.41",
+  "version": "2.0.0-alpha.43",
   "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.",
@@ -35,9 +35,9 @@
   },
   "devDependencies": {
     "@ac/contract": "0.0.0",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.6.3",
     "typescript": "^7.0.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.2"
   },
   "scripts": {
     "build": "node build.mjs",

package/schema.json

@@ -348,8 +348,9 @@
         },
         "timeoutSec": {
           "type": "number",
-          "description": "Per-run timeout in seconds. Must be at least 1: a zero or negative value would fire the timeout at once, timing out any run that awaits real I/O (#137).",
-          "minimum": 1
+          "description": "Per-run timeout in seconds. Must be at least 1: a zero or negative value would fire the timeout at once, timing out any run that awaits real I/O (#137). And at most 2147483, about 24.8 days: Node clamps a longer or non-finite `setTimeout` delay to 1 ms, which fires it at once, the same failure (#580).",
+          "minimum": 1,
+          "maximum": 2147483
         },
         "runOn": {
           "$ref": "#/definitions/JobRunOn"