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

package/AUTHORING.md

@@ -1,7 +1,7 @@
 # Writing an artifact-console plugin
 
-A plugin adds to the console without changing it: a nav **panel**, an Overview **card**, a confirm-gated
-**action**, a scheduled **job**, an HTTP **route**, and a **setting** are all contributed from data + a small
+A plugin adds to the console without changing it: a nav **panel**, an Overview **card**, an
+**action** (a button whose modal is its confirmation), a scheduled **job**, an HTTP **route**, and a **setting** are all contributed from data + a small
 server module. The host validates the plugin's manifest before it runs any of the plugin's code, loads it at
 startup, and surfaces it at `GET /api/plugins`.
 
@@ -119,6 +119,12 @@ Rules the host enforces, at validation or load time:
   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
+  *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
+  same job id.
 - The manifest is the **declaration**; your server code supplies the runtime halves. An HTTP route and a job must
   be *declared here* or the host will refuse to serve/run them (see §2).
 
@@ -138,7 +144,7 @@ export const createPlugin: CreatePlugin = (host) => ({
       const greeting = (await host.settings.get("greeting")) ?? "hello"
       return Response.json({ greeting })
     })
-    // A confirm-gated action: the button, confirm and fields come from the manifest; the handler is here.
+    // An action: the button, its flags and the fields come from the manifest; the handler is here.
     host.actions.register({
       id: "hello.ping",
       run: async (input) => ({ echoed: input }),
@@ -174,10 +180,25 @@ export const createPlugin: CreatePlugin = (host) => ({
   fails naming the file and line (an installed third-party plugin is not covered).
 - **Action** — `host.actions.register({ id, run })`. The button, `confirm`/`danger` and the modal `fields` all
   come from the manifest; here you supply only `run(input)`. (The action's manifest metadata drives the shell
-  UI; registering a `run` for an id the manifest omits simply leaves it without a button.)
+  UI; registering a `run` for an id the manifest omits simply leaves it without a button.) Opening the modal is
+  the confirmation (#530): its primary button, labelled with the action's `title`, fires `run` on the **first**
+  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.
+  `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
-  `contributes.jobs`, on their 5-field cron `schedule`. `ctx.log` appends to that run's recorded log;
-  `ctx.signal` aborts at `timeoutSec`. `runOn: "host"` runs your `runJob` once, in the host process.
+  `contributes.jobs`, on their 5-field cron `schedule`. `ctx.log` appends to that run's recorded log (its last
+  50 lines are kept); the host prunes the run history when a run is recorded (#139): it keeps at most the
+  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`
+  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
   machine's own work through `host.agent.call(ctx.machine.id, …)`. A machine that doesn't answer when
@@ -392,6 +413,25 @@ cards -- reads when it is opened and after its own actions. Only Home is still r
 which remounts it for Refresh, the heartbeat and a return after a minute; Home's open-issues card keeps
 its count across those remounts, so within 15 minutes of its last load none of them re-reads it (#550).
 
+**A panel that must fit the viewport reads the shell header's height (#368).** The shell header is in normal
+flow and wraps, so its height changes with the viewport width and with what plugins put in it. The shell
+measures it (`offsetHeight`) and publishes it in whole px as the CSS custom property `--ac-shell-header-h` on
+`document.documentElement`: set before the first paint, kept current on a `ResizeObserver` on the header's
+border box and on window `resize`, and removed when the shell unmounts. A panel's CSS reads
+`var(--ac-shell-header-h, 0px)`; the `0px` fallback is what applies wherever the shell has not published it.
+The Artifacts panel at <=720 px is the example:
+`height: calc(100dvh - var(--ac-shell-header-h, 0px) - var(--rb-space-4))` with
+`margin-bottom: calc(-1 * var(--rb-space-4))`, because the shell's `<main>` pads every side by
+`var(--rb-space-4)` (the top is subtracted, the bottom cancelled), and its `position: fixed` drawer and scrim use
+`top: var(--ac-shell-header-h, 0px)` so the header's controls stay reachable with them open. Limits: the
+value is a whole number of px, so a header with a fractional real height leaves a panel sized against it up
+to half a pixel over or under; `dvh` follows a phone's collapsing address bar but the shell root's own
+`min-height` is `100vh`, so on a phone with the bar showing the page can scroll by the difference, and once
+it has scrolled by some amount the in-flow header moves up while a `fixed` overlay stays put, leaving that
+strip of the panel uncovered between the header and the overlay; and the panel itself resizes with `dvh` as
+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.
+
 ### The `@ac/host` browser module
 
 `@ac/host` (typed as `BrowserHostApi` in `@ac/contract`) is the one shared module instance the shell and every
@@ -435,6 +475,7 @@ const unregister = header.registerButton({ id: "hello-scan", label: "Scan", onCl
 `actions.open` opens the universal confirm modal for a registered action — the plugin's own, or another
 plugin's (`pluginId` names it; the Board and the Artifacts action bar open `provider-github`'s and others').
 `target` scopes the draft to a specific object, e.g. an issue number, when the action isn't `scope: "global"`.
+Opening the modal is the confirmation: the operator's first click on its primary button runs the action.
 It is fire-and-forget, held until the shell mounts, and dropped if it never does:
 
 ```ts
@@ -465,7 +506,7 @@ the listener is called once for every action the modal dispatched and got a resu
 and whoever opened it (your own `actions.open`, or the Ctrl/Cmd+K palette) — with the action's `pluginId`,
 `actionId`, `ok`, the `error` message on a failure, and the opened ref's `target` (absent when the ref had none,
 as from the palette) — what the action was opened *for*, not what the operator finally typed into the form. It
-carries no input. Cancelling, or closing before the confirm, calls nothing. Use it to
+carries no input. Cancelling, or closing the modal without clicking its primary button, calls nothing. Use it to
 refresh what an action changed — the Board refetches the card an `issue.*` action named, so a closed issue's row
 goes at once instead of at the next poll. It returns the unsubscribe; a listener that throws is logged and
 skipped, and never reaches the modal or another listener. It needs no shell to be mounted: it simply hears
@@ -507,6 +548,17 @@ A `hint` (optional, e.g. a category or the plugin id) is searched the same as `l
 `>hel` finds an item whose label doesn't contain "hel" but whose hint does — and renders as muted secondary
 text in the row.
 
+**Ctrl/Cmd+K from inside a same-origin iframe (#369).** A key pressed while an iframe has focus lands in the
+iframe's own document, never the shell's, so the palette does not open by itself. A panel that hosts a
+same-origin iframe (the Artifacts report preview does) forwards the hotkey: bind a `keydown` listener on the
+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.
+
 `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
 reads a provider's routes through this rather than a bare `window.fetch`; a card should reach for `cached`
@@ -558,7 +610,9 @@ the guide is written against hello, so this is exactly what it does:
 2. **The Vitest alias.** `@ac/host` only resolves for real through the host page's import map, which a plain
    Node test runner has no equivalent of. If you test the frontend through Vitest, alias the specifier to
    `packages/ui-shell/src/vendor/ac-host-entry.mjs` (the shell's own implementation — reuse it rather than
-   mocking), the way [`plugins/hello/vitest.config.ts`](../../plugins/hello/vitest.config.ts) does.
+   mocking), the way [`plugins/hello/vitest.config.ts`](../../plugins/hello/vitest.config.ts) does. (Leave out
+   that file's `setupFiles` line: it names this repo's own shared test-timeout script, which your plugin does not
+   have; set your own `waitFor` / test timeouts if your tests need more than Vitest's defaults.)
 3. **Leaving it external in the build.** Nothing extra is needed here as long as you build with plain `tsc`
    (§3, no bundler) — `tsc` only transpiles syntax, so `import { toast } from "@ac/host"` is emitted into
    `dist/ui.js` verbatim, unresolved, for the browser's import map to satisfy at runtime, exactly like the
@@ -915,7 +969,7 @@ what it's for.
 
 | Point | Declared in `contributes` | Supplied by |
 |---|---|---|
-| Panel | `panels[]` (`id`, `title`, `route`, `export`, `nav?`, `order?`) | a component export in `ui.js` |
+| Panel | `panels[]` (`id`, `title`, `route`, `export`, `nav?`, `order?`, `isolation?`) | a component export in `ui.js` |
 | Card | `cards[]` (`id`, `title`, `sizes`, `export`) | a component export in `ui.js` |
 | Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `fields?`) | `host.actions.register({ id, run })` |
 | Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`) | `runJob(ctx)` dispatching on `ctx.jobId` |
@@ -943,6 +997,10 @@ Ties break the same way, so the order is total. `order` is a hint the operator c
 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.
 
+**`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,
+declared or not. `"iframe"` is the only accepted value, and it belongs on a panel, not on a card or the manifest.
+
 A card never renders its own heading -- the wrapper supplies it from the manifest `title`
 (`HomeCards.tsx`'s `PluginCard`, `<Card><h3>{title}</h3>...</Card>`); a card rendering one of its
 own duplicates it on screen (#399).

package/dist/manifest.d.ts

@@ -27,6 +27,11 @@ export interface PanelContribution {
     order?: number;
     /** The export name in the plugin's frontend bundle. */
     export: string;
+    /**
+     * Reserved (design §4, #124): `"iframe"` asks the host to mount this panel in an iframe. Not
+     * implemented in 2.0; the host accepts and ignores it, so a panel declaring it still loads in-process.
+     */
+    isolation?: "iframe";
 }
 /** A contributed Overview card. */
 export interface CardContribution {
@@ -105,7 +110,11 @@ export interface JobContribution {
     id: string;
     /** 5-field cron expression. */
     schedule: string;
-    /** Per-run timeout in seconds. */
+    /**
+     * 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
+     */
     timeoutSec: number;
     runOn: JobRunOn;
     /** A `runOn: "agent"` job is not dispatched to a machine whose paired agent version compares lower

package/dist/slots.d.ts

@@ -118,6 +118,10 @@ export interface Identity {
     id: string;
     email?: string;
     name?: string;
+    /** `"machine"` for a non-person credential (a Cloudflare Access service token); absent or `"user"` for a
+     *  person. The host admits a machine identity on `GET`/`HEAD /api/readyz` only and refuses it on every other gated
+     *  route; any other value is treated as a non-person too (#552). */
+    kind?: "user" | "machine";
 }
 /** `auth@1`: resolve the identity for a request, or null in open mode. */
 export interface AuthProvider {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.39",
+  "version": "2.0.0-alpha.41",
   "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.",

package/schema.json

@@ -168,6 +168,11 @@
         "export": {
           "type": "string",
           "description": "The export name in the plugin's frontend bundle."
+        },
+        "isolation": {
+          "type": "string",
+          "const": "iframe",
+          "description": "Reserved (design §4, #124): `\"iframe\"` asks the host to mount this panel in an iframe. Not implemented in 2.0; the host accepts and ignores it, so a panel declaring it still loads in-process."
         }
       },
       "required": [
@@ -343,7 +348,8 @@
         },
         "timeoutSec": {
           "type": "number",
-          "description": "Per-run timeout in seconds."
+          "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
         },
         "runOn": {
           "$ref": "#/definitions/JobRunOn"