anbaric-plugins 1.7.0

package/README.md

@@ -0,0 +1,87 @@
+# anbaric-plugins
+
+Open-source plugins for the Anbaric platform dashboard. A plugin registers
+pages and widgets on the platform's root app: pages appear in the side nav,
+widgets are React components rendered into a page's `<main>`.
+
+This package ships the plugins the platform loads by default:
+
+| Plugin module | What it registers |
+| --- | --- |
+| `anbaric-plugins/state-machines` | The `/` Dashboard page with the state machines and jobs overview |
+
+## How plugins work
+
+A plugin is a TypeScript module that exports a `plugin` object. The platform
+server (`anbaric-cloud-hosting`) loads the modules named in the
+`ANBARIC_PLUGINS` environment variable (comma-separated) at boot, compiles
+each one into a browser bundle, and serves it to the dashboard, which renders
+the components. The dashboard's own build is plugin-agnostic — installing a
+plugin is configuration only:
+
+```
+npm install some-plugin-package
+ANBARIC_PLUGINS=some-plugin-package,anbaric-plugins/state-machines
+```
+
+If `ANBARIC_PLUGINS` is unset the platform loads
+`anbaric-plugins/state-machines`, so the Dashboard is there by default.
+Setting the variable replaces the default list, so include it explicitly if
+you still want the Dashboard.
+
+## Writing a plugin
+
+```tsx
+import type { Plugin } from 'anbaric-cloud-hosting'
+import { Card } from '@anbaric/design-system/components/Card'
+
+function GreetingWidget({ fetchData }: { fetchData: (parameters?: Record<string, string>) => Promise<any> }) {
+  return <Card>Hello from a plugin.</Card>
+}
+
+const plugin: Plugin = {
+  name: 'greeting',
+  pages: [{ path: '/greeting', title: 'Greeting', icon: 'waving_hand', navOrder: 50 }],
+  widgets: [
+    {
+      page: '/greeting',
+      id: 'greeting',
+      component: GreetingWidget,
+      data: async (parameters) => ({ greeted: parameters.name ?? 'world' }),
+    },
+  ],
+}
+
+export { plugin }
+```
+
+- **Pages** are registered by path; `/` is the homepage. Plugin page paths
+  take precedence over deployed apps with the same name; `icon` is a
+  Material Symbols name; lower `navOrder` sorts higher in the nav.
+- **Widgets** attach to any page path — including pages registered by other
+  plugins. `position` orders widgets on a page; a `title` renders a heading
+  above the widget.
+- **`data`** is an optional server-side function. The widget's component
+  receives a `fetchData(parameters?)` prop that invokes it on the platform
+  (`GET /plugins/data?plugin=<name>&widget=<id>&…`) and resolves with its
+  JSON-serialisable return value. Because the function's code is also
+  carried (unexecuted) in the browser bundle, do not import server-only
+  modules at the top level of files that components also live in.
+- Components render with the **platform's own React and design system**:
+  imports of `react`, `react-dom` and `@anbaric/design-system/components/*`
+  are provided by the dashboard at runtime, not bundled. Style with design
+  system components and tokens; a plugin's own `.css` imports are ignored.
+  The chart components (`Graph`, `ConcentrationCurve`, `ExposureBars`) are
+  not available to plugins.
+
+A package can ship several plugins by exposing one module per plugin via
+`exports` subpaths, as this package does.
+
+## Layout
+
+One folder per plugin under `src/`, exported as a subpath:
+
+```
+src/state-machines/index.tsx        the plugin object
+src/state-machines/StateMachinesWidget.tsx
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "anbaric-plugins",
+  "version": "1.7.0",
+  "description": "Open-source Anbaric platform plugins: pages and widgets loaded by the hosting server via ANBARIC_PLUGINS",
+  "license": "MIT",
+  "author": "chris@anbaric.ai",
+  "type": "module",
+  "exports": {
+    "./state-machines": "./src/state-machines/index.tsx"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@anbaric/design-system": "file:../anbaric-design-system",
+    "@types/react": "^19.2.14",
+    "anbaric-cloud-hosting": "^1.7.0",
+    "react": "^19.2.6",
+    "typescript": "^7.0.2"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/modules.d.ts

@@ -0,0 +1,5 @@
+declare module '*.css'
+declare module '*.svg' {
+  const url: string
+  export default url
+}

package/src/state-machines/StateMachinesWidget.tsx

@@ -0,0 +1,230 @@
+import { useEffect, useState, type CSSProperties } from 'react'
+
+import { Alert } from '@anbaric/design-system/components/Alert'
+import { Badge } from '@anbaric/design-system/components/Badge'
+import { Card } from '@anbaric/design-system/components/Card'
+
+interface StateMachine {
+  workflowId: string
+  url: string
+}
+
+interface Job {
+  id: string
+  state: string
+  workflowId?: string
+  properties: Record<string, unknown>
+  startedAt?: string
+  startedBy?: string
+  lastUpdated?: string
+  transitions?: Array<{ from: string; to: string; actor: string }>
+}
+
+const formatDate = (iso?: string) =>
+  iso
+    ? new Date(iso).toLocaleString(undefined, {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+      })
+    : '—'
+
+const machineHeading: CSSProperties = {
+  margin: 0,
+  fontFamily: 'var(--font-title)',
+  fontSize: '1.15rem',
+  textTransform: 'var(--title-transform)' as CSSProperties['textTransform'],
+}
+
+const cell: CSSProperties = {
+  textAlign: 'left',
+  padding: 'calc(var(--space-sm) / 2) var(--space-sm)',
+  borderBottom: '1px solid color-mix(in srgb, var(--color-grey) 12%, transparent)',
+}
+
+const headerCell: CSSProperties = {
+  ...cell,
+  fontSize: '0.72rem',
+  textTransform: 'uppercase',
+  letterSpacing: '0.06em',
+  color: 'var(--color-foreground-tint-2)',
+}
+
+const mono: CSSProperties = {
+  fontFamily: 'var(--font-mono)',
+  fontSize: '0.78rem',
+}
+
+const muted: CSSProperties = {
+  color: 'var(--color-foreground-tint-2)',
+}
+
+function PropertyList({ job }: { job: Job }) {
+  const entries: Array<[string, unknown]> = [['id', job.id], ...Object.entries(job.properties)]
+  return (
+    <dl style={{ margin: 0, display: 'flex', flexDirection: 'column', gap: '2px' }}>
+      {entries.map(([name, value]) => (
+        <div key={name} style={{ display: 'flex', gap: 'var(--space-sm)', alignItems: 'baseline' }}>
+          <dt style={{ ...mono, ...muted, flex: 'none' }}>{name}</dt>
+          <dd style={{ margin: 0, overflowWrap: 'anywhere' }}>{String(value)}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}
+
+function TransitionHistory({ transitions }: { transitions: Job['transitions'] }) {
+  if (!transitions || transitions.length === 0) {
+    return <span style={muted}>—</span>
+  }
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '2px' }}>
+      {transitions.map((transition, index) => (
+        <div key={index}>
+          {transition.from} → {transition.to}{' '}
+          <span style={{ ...muted, fontSize: '0.78rem' }}>by {transition.actor}</span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function JobsTable({ jobs }: { jobs: Job[] }) {
+  if (jobs.length === 0) {
+    return <p style={{ margin: 0, color: 'var(--color-foreground-tint-2)' }}>No jobs yet.</p>
+  }
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse' }}>
+      <thead>
+        <tr>
+          <th style={headerCell}>Properties</th>
+          <th style={headerCell}>State</th>
+          <th style={headerCell}>Started</th>
+          <th style={headerCell}>Updated</th>
+          <th style={headerCell}>History</th>
+        </tr>
+      </thead>
+      <tbody>
+        {jobs.map((job) => (
+          <tr key={job.id}>
+            <td style={cell}>
+              <PropertyList job={job} />
+            </td>
+            <td style={cell}>
+              <Badge tone="primary" dot>
+                {job.state}
+              </Badge>
+            </td>
+            <td style={cell}>
+              {formatDate(job.startedAt)}
+              <div style={{ ...muted, fontSize: '0.78rem' }}>by {job.startedBy ?? 'system'}</div>
+            </td>
+            <td style={cell}>{formatDate(job.lastUpdated)}</td>
+            <td style={cell}>
+              <TransitionHistory transitions={job.transitions} />
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+
+function StateMachinesWidget() {
+  const [machines, setMachines] = useState<StateMachine[] | undefined>(undefined)
+  const [jobs, setJobs] = useState<Job[] | undefined>(undefined)
+  const [failed, setFailed] = useState(false)
+
+  useEffect(() => {
+    void (async () => {
+      try {
+        const [machinesResponse, jobsResponse] = await Promise.all([
+          fetch('/state-machines'),
+          fetch('/jobs'),
+        ])
+        if (!machinesResponse.ok || !jobsResponse.ok) {
+          setFailed(true)
+          return
+        }
+        setMachines(await machinesResponse.json())
+        setJobs(await jobsResponse.json())
+      } catch {
+        setFailed(true)
+      }
+    })()
+  }, [])
+
+  const registered = new Set((machines ?? []).map((machine) => machine.workflowId))
+  const workflowIds = [
+    ...new Set([
+      ...registered,
+      ...(jobs ?? [])
+        .map((job) => job.workflowId)
+        .filter((workflowId): workflowId is string => Boolean(workflowId)),
+    ]),
+  ].sort()
+  const unassigned = (jobs ?? []).filter((job) => !job.workflowId)
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-lg)' }}>
+      {failed ? (
+        <Alert variant="danger" title="Could not load the platform state">
+          The platform rejected the request — try reloading the page.
+        </Alert>
+      ) : null}
+      {machines && workflowIds.length === 0 ? (
+        <Card>
+          <p style={{ margin: 0 }}>
+            No state machines yet. Deploy an app with <code>anbaric deploy</code> and its
+            machines will appear here.
+          </p>
+        </Card>
+      ) : null}
+      {workflowIds.map((workflowId) => {
+        const machineJobs = (jobs ?? []).filter((job) => job.workflowId === workflowId)
+        return (
+          <Card key={workflowId}>
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'space-between',
+                gap: 'var(--space-md)',
+                marginBottom: 'var(--space-md)',
+              }}
+            >
+              <h2 style={machineHeading}>{workflowId}</h2>
+              <div style={{ display: 'flex', gap: 'var(--space-sm)' }}>
+                <Badge tone="neutral">
+                  {machineJobs.length} {machineJobs.length === 1 ? 'job' : 'jobs'}
+                </Badge>
+                {registered.has(workflowId) ? (
+                  <Badge tone="success" dot>
+                    consumer connected
+                  </Badge>
+                ) : (
+                  <Badge tone="warning" dot>
+                    no consumer
+                  </Badge>
+                )}
+              </div>
+            </div>
+            <JobsTable jobs={machineJobs} />
+          </Card>
+        )
+      })}
+      {unassigned.length > 0 ? (
+        <Card>
+          <h2 style={{ ...machineHeading, marginBottom: 'var(--space-md)' }}>
+            Unassigned jobs
+          </h2>
+          <JobsTable jobs={unassigned} />
+        </Card>
+      ) : null}
+    </div>
+  )
+}
+
+export { StateMachinesWidget }

package/src/state-machines/index.tsx

@@ -0,0 +1,11 @@
+import type { Plugin } from 'anbaric-cloud-hosting'
+
+import { StateMachinesWidget } from './StateMachinesWidget'
+
+const plugin: Plugin = {
+  name: 'state-machines',
+  pages: [{ path: '/', title: 'Dashboard', icon: 'dashboard', navOrder: 0 }],
+  widgets: [{ page: '/', id: 'state-machines', component: StateMachinesWidget }],
+}
+
+export { plugin }