@t4h.framework/vite-panel-plugin 0.0.0

package/README.md

@@ -0,0 +1,193 @@
+# @t4h.framework/vite-panel-plugin
+
+The panel of the framework: the workflows of an app with a form to start runs
+from their input schema, the runs with filters and a live execution trace
+(activities as a waterfall, child runs nested under the activity that started
+them, input, output, duration, logs, the activity that failed), and an inbox of
+activities waiting for an external advance.
+
+It ships with `@t4h.framework/dev`, which plugs it into the Vite instance it
+runs in middleware mode, so there is nothing to install or configure: run
+`framework dev` and open the printed base URL. API paths (`/projects/*`,
+`/_dev/*`) keep going to the dev server; everything else is the panel.
+
+## Hosting the panel elsewhere
+
+The package is a Vite plugin (`apply: 'serve'`) that serves the pre-built SPA
+from `dist/client` and injects the host configuration in the page:
+
+```ts
+import panel from '@t4h.framework/vite-panel-plugin'
+
+panel({
+  config: {
+    basePath: '/panel',
+    apiUrl: '/tenants/acme/projects/billing/versions/v3',
+    api: { manifest: '/manifest.json' },
+    project: 'billing',
+    metadata: { tenant: 'acme', version: 'v3' },
+    fields: {
+      run: 'input,output,rejectedReason,activities(pendingStatus,childrenCount)',
+      runActivity: 'pendingStatus,childrenCount,input,output,pendings,children',
+    },
+    capabilities: {
+      trigger: false,
+      advance: false,
+      events: false,
+      rebuild: false,
+    },
+    routes: {
+      runs: {
+        method: 'POST',
+        path: '/tenants/:tenant/projects/:project/versions/:version/workflows/:workflow/runs',
+      },
+      advance: {
+        method: 'PATCH',
+        path: '/tenants/:tenant/projects/:project/versions/:version/workflows/:workflow/runs/:run/activities/:activity',
+      },
+    },
+  },
+})
+```
+
+| Option                 | Default (local dev server)                                                                          | Meaning                                                                                                                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                | `Framework Panel`                                                                                   | Name shown in the sidebar and the browser tab                                                                                                                                            |
+| `basePath`             | `''` (root)                                                                                         | Path the panel is mounted at; the plugin only answers under it and injects `<base href>` so the relative asset URLs resolve                                                              |
+| `apiUrl`               | `/_dev`                                                                                             | Where the panel API described below lives, exactly as the panel should call it: a same-origin path or an absolute URL, with the route paths appended                                     |
+| `project`              | the manifest id                                                                                     | Project (app) id, the one id the core defines; shown in the top bar and filled into `:project` of the mirror routes                                                                      |
+| `metadata`             | `{}`                                                                                                | `{ [key]: string }` labels of the host about this panel (the runtime sends `tenant` and `version`); each one is a box in the top bar and fills the `:key` of the same name in the routes |
+| `fields`               | `{}`                                                                                                | The `q` the panel sends on `api.runs` (`runs`), `api.run` (`run`) and `api.runActivity` (`runActivity`), in the host's own field-selection grammar; omitted, no `q` is sent              |
+| `api`                  | the paths of the local dev server (`/manifest`, `/runs/:run`, `/runs/:run/activities/:activity`, …) | Where each read and write of the panel API lives under `apiUrl`, as path templates with `:workflow`, `:run` and `:activity`; the panel knows what it asks, not where a host mounts it    |
+| `capabilities.trigger` | `true`                                                                                              | The host exposes `POST {apiUrl}/workflows/:id/runs` without authorization; otherwise the Run button becomes "Copy as curl" of the mirror route                                           |
+| `capabilities.advance` | `true`                                                                                              | Same for `POST {apiUrl}/activities/:id/advance` and the inbox                                                                                                                            |
+| `capabilities.events`  | `true`                                                                                              | The host streams `GET {apiUrl}/events`; otherwise the panel never polls and the top bar gets a Refresh button                                                                            |
+| `capabilities.rebuild` | `true`                                                                                              | The host rebuilds the app and starts over, like the dev server: the top bar shows the build state and empty lists mention the last build; off for a host that keeps its runs             |
+| `routes`               | `POST /projects/:project/workflows/:workflow/runs` and `PATCH .../runs/:run/activities/:activity`   | `{ method, path, headers? }` of the authorized routes a client must call, shown as `curl` examples with those headers; `path` is expanded with `project` and `metadata`                  |
+
+The configuration is read from `window.__T4H_PANEL__`, written by the plugin in
+place of the `<!--panel-config-->` marker of `index.html`; `<!--panel-base-->`
+receives the `<base href>`. The host forwards `basePath` requests to the Vite
+middlewares; everything else stays with the host.
+
+## Hosting without Vite
+
+A host that has no Vite (the production runtime) takes the same pieces from
+`@t4h.framework/vite-panel-plugin/node`, which imports nothing from `vite`:
+
+```ts
+import {
+  createPanelAssetsHandler,
+  createPanelHandler,
+  render,
+  resolvePanelConfig,
+} from '@t4h.framework/vite-panel-plugin/node'
+```
+
+| Export                     | Use                                                                                                                                              |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createPanelHandler`       | The whole panel as one `node:http` middleware — the page for a navigation under `basePath`, the assets for everything else. What the plugin uses |
+| `createPanelAssetsHandler` | The hashed assets, cached forever, for a host that mounts them at a shared public path; `index: false` so a miss falls through                   |
+| `render`                   | `index.html` with the config and the `<base href>` in place; `{ baseHref }` overrides the default `` `${basePath}/` ``                           |
+| `resolvePanelConfig`       | Fills the local defaults into a partial config, what `render` expects; `createPanelHandler` does it for you                                      |
+| `PANEL_CLIENT_DIST`        | `dist/client`, the built SPA                                                                                                                     |
+| `PANEL_CLIENT_ASSETS_DIR`  | `dist/client/assets`, safe to serve publicly and cache forever — the names are hashed and `index.html` is not in there                           |
+| `assertPanelBuilt`         | Throws when the package was not built                                                                                                            |
+
+The runtime serves one panel per project version, so `basePath` carries the
+tenant and the version while the assets live at a single shared path. Splitting
+the two is what `baseHref` is for:
+
+```ts
+app.use('/panel/assets', createPanelAssetsHandler())
+
+// inside the authenticated controller of `.../versions/:version/panel`
+return render(
+  resolvePanelConfig({
+    basePath: `/tenants/${tenant}/projects/${project}/versions/${version}/panel`,
+    apiUrl: `/tenants/${tenant}/projects/${project}/versions/${version}/panel/api`,
+    project,
+    metadata: { tenant, version },
+    capabilities: { trigger: false, advance: false, events: false },
+  }),
+  { baseHref: '/panel/' },
+)
+```
+
+Every link the SPA renders is absolute (`basePath` is the router `basename`)
+and `fetch` goes to `apiUrl` as given, so a `<base href>` that does not match
+`basePath` only affects where the assets are looked up.
+
+## Panel API
+
+A host implements these routes under `apiUrl`, at the paths below or wherever
+`api` relocates them. Dates are ISO strings;
+`input`, `output`, `result`, `payload` and `args` are framework tagged JSON.
+Every listing is a page: the panel asks for `limit` items from `offset` (25 at
+a time, never more than 50) and the host answers the `count` of everything that
+matched alongside, so the panel never holds more than one page. Child runs are
+the exception: "show more" under an activity fetches the next page of 15 and
+keeps the ones already on screen.
+
+| Method | Route                                                                                                    | Answer                                                                                                                                                      |
+| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET`  | `/manifest`                                                                                              | `{ id, description, workflows: [{ id, description, schema, authorization? }], authorization? }`; a host may leave `authorization` out                       |
+| `GET`  | `/state`                                                                                                 | `{ state: 'idle' \| 'starting' \| 'ready' \| 'exited' }`; only called with `capabilities.rebuild`                                                           |
+| `GET`  | `/runs?status&workflow&id&parentRunId&parentActivityId&rootOnly&createdAfter&createdBefore&limit&offset` | `{ count, runs: Run[] }` newest first; `id` is a prefix, `createdAfter`/`createdBefore` are epoch milliseconds                                              |
+| `GET`  | `/runs/:id?q`                                                                                            | `Run & { input, output, rejectedReason }`; `q` is `fields.run`                                                                                              |
+| `GET`  | `/runs/:id/activities?limit&offset&q`                                                                    | `{ count, activities: Activity[] }` newest first; `q` is `fields.runActivities`                                                                             |
+| `GET`  | `/runs/:id/activities/:activityId?q`                                                                     | `Activity & { input, output }`; `q` is `fields.runActivity`                                                                                                 |
+| `GET`  | `/runs/:id/activities/:activityId/pendings?limit&offset&q`                                               | `{ count, pendings: Pending[] }` newest first; `q` is `fields.runActivityPendings`                                                                          |
+| `GET`  | `/runs/:id/logs?limit&offset`                                                                            | `{ count, logs: [{ level, args, at }] }` newest first                                                                                                       |
+| `GET`  | `/activities/waiting?limit&offset`                                                                       | `{ count, activities: [{ id, pendingId, runId, workflowId, type, schema, timeoutAt }] }` newest first                                                       |
+| `GET`  | `/events`                                                                                                | SSE: `manifest`, `build:status`, `build:fail`, `app:exit`, `run:created`, `run:updated` (both with a `Run`), `ping`; only opened with `capabilities.events` |
+| `POST` | `/workflows/:workflowId/runs`                                                                            | Only with `capabilities.trigger`; body is the input, answers `201 { id }`                                                                                   |
+| `POST` | `/activities/:activityId/advance`                                                                        | Only with `capabilities.advance`; body `{ payload }`, answers `{ id, type, status }`                                                                        |
+
+`Run` is `{ id, workflow, status, rejectedActivityId, parentWorkflowRunId,
+parentWorkflowRunActivityId, createdAt, updatedAt }` with `status` in
+`running | fulfilled | rejected`. `Activity` is `{ id, type, kind, createdAt }`
+plus, on request, `hasChildren`, `input` and `output`; an async one (`kind:
+'async'`) also carries `completedAt` and, on request, `pendingStatus` (status
+of its last pending). `Pending` is `{ id, previousId, status, schema, timeoutAt,
+result, payload, createdAt, updatedAt }`.
+
+No answer embeds a list: a run does not carry its activities, an activity does
+not carry its pendings or the runs it started. Each is its own paged route,
+newest first, and the trace reads one page at a time when the reader gets
+there: the activities of the run, the pendings of an open async activity, and
+the runs an activity started as `GET /runs?parentActivityId=…`, 15 at a time
+behind "show more", since a `startWorkflowMany` can fan out to hundreds of
+thousands. A sync activity records no completion: the trace
+takes the next activity starting, or the run ending, as its end. Every listing
+is newest first, logs included.
+
+`q` is opaque to the panel: it sends `fields.run` and `fields.runActivity`
+from its configuration, verbatim, and a host that answers the full shape
+without one (the local dev server) leaves them out. The panel reads a run's
+activities as summaries and asks for one activity's input, output, pendings
+and children only when the reader opens it, so a trace of hundreds of
+activities costs one request until then.
+
+## Developing the panel
+
+Inside the SPA every read of the API is a TanStack Query (`src/queries.ts`,
+which also holds the mutations and the cache writes each server event turns
+into) and the single `EventSource` lives in `src/events.tsx`: nothing
+subscribes to events on its own — a component reads a query and the stream
+keeps it current; nothing polls, and a host with `capabilities.events` off
+gets a Refresh button in the top bar that invalidates every query. The filters of the runs page are
+typed URL state through nuqs (`src/filters.ts`), which is where the query
+string of a shared link is defined.
+
+Every instant on screen is measured by the server; what is still going counts
+against the browser clock through `useTimer` (`src/hooks/useTimer.ts`), one
+timer per rate shared by every counter, read in the leaf that shows the number
+so a tick never re-renders the page around it. `yarn test` covers the three.
+
+`yarn dev` starts Vite on the panel sources with `/_dev` proxied to a dev
+server on port 3000, so run `framework dev` on any project first. `yarn build`
+produces `dist/client` (the SPA, validated by the Vite build) and the two entry
+points `dist/index.js` (the Vite plugin) and `dist/node.js` (the Vite-free
+handler), type-checked by `check-types`; the published package ships all of
+them.