@tetherto/mdk-cli 0.0.0-stage → 0.12.1

package/templates/app-ui/ui-src/components/summary-panel.tsx

@@ -0,0 +1,24 @@
+// Component layer (@tetherto/mdk-react-devkit): renders what the hook shaped.
+// No fetching, no data logic.
+import { EmptyState, ErrorCard, Loader, SingleStatCard } from '@tetherto/mdk-react-devkit'
+
+import type { SummaryView } from '../hooks/use-summary'
+
+export const SummaryPanel = ({ view }: { view: SummaryView }) => {
+  switch (view.status) {
+    case 'loading':
+      return <Loader />
+    case 'error':
+      return <ErrorCard title="Could not load the summary" error={view.message} />
+    case 'no-kernel':
+      return <EmptyState description="The backend is up, but not connected to a Kernel yet." size="sm" />
+    case 'ready':
+      return (
+        <div className="__APP_CSS__-summary">
+          {view.stats.map((stat) => (
+            <SingleStatCard key={stat.label} name={stat.label} value={stat.value} />
+          ))}
+        </div>
+      )
+  }
+}

package/templates/app-ui/ui-src/data/summary.ts

@@ -0,0 +1,18 @@
+// Data layer (@tetherto/mdk-ui-foundation): the contract with the app's own
+// backend — the response type, its query key and the request. No React here.
+import { mdkFetch } from '@tetherto/mdk-ui-foundation'
+
+/** What the app's `summary` route returns (`plugin/controllers/summary.js`, `GET /api/<name>/summary`). */
+export type Summary = {
+  ok: boolean
+  kernelConnected: boolean
+  workerCount: number
+  deviceCount: number
+  workers: Array<{ workerId: string; devices: number }>
+}
+
+/** Query key for the summary at one URL. */
+export const summaryQueryKey = (url: string) => ['__APP_NAME__', 'summary', url] as const
+
+/** GET the summary, with the signed-in operator's token. */
+export const fetchSummary = (url: string): Promise<Summary> => mdkFetch<Summary>(url)

package/templates/app-ui/ui-src/hooks/use-summary.ts

@@ -0,0 +1,54 @@
+// Hook layer (@tetherto/mdk-react-adapter): fetches the summary and shapes it
+// into exactly what the component renders, including loading and error states.
+import { MdkFetchError } from '@tetherto/mdk-ui-foundation'
+import { useMdkApp, useQuery } from '@tetherto/mdk-react-adapter'
+
+import { fetchSummary, summaryQueryKey } from '../data/summary'
+
+export type SummaryView =
+  | { status: 'loading' }
+  | { status: 'error'; message: string }
+  | { status: 'no-kernel' }
+  | { status: 'ready'; stats: Array<{ label: string; value: number }> }
+
+// The Gateway answered, but nothing serves this route: the app's runtime is
+// not running, or the route is not in plugin/mdk-plugin.json.
+const NOT_SERVED = 404
+// The Gateway or the app's runtime did not answer (a dev proxy reports a
+// stopped Gateway as 500).
+const UNREACHABLE = new Set([500, 502, 503, 504])
+
+const describeError = (error: unknown, url: string): string => {
+  if (error instanceof MdkFetchError && error.status === NOT_SERVED) {
+    return `Nothing serves ${url} yet (HTTP 404). The Gateway is up, but this app's backend runtime is not running or does not have this route.`
+  }
+  if (error instanceof MdkFetchError && UNREACHABLE.has(error.status)) {
+    return `The app's backend is not reachable (HTTP ${error.status}). Start the stack with \`mdk run\`.`
+  }
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** The app's summary, ready to render. */
+export const useSummary = (): SummaryView => {
+  // The app's routes live under the name the operator installed it as, so the
+  // URL comes from useMdkApp() rather than being hardcoded.
+  const { apiUrl } = useMdkApp()
+  const url = apiUrl('/api/__APP_NAME__/summary')
+
+  const query = useQuery({
+    queryKey: summaryQueryKey(url),
+    queryFn: () => fetchSummary(url),
+    retry: false,
+  })
+
+  if (query.isPending) return { status: 'loading' }
+  if (query.isError) return { status: 'error', message: describeError(query.error, url) }
+  if (!query.data.kernelConnected) return { status: 'no-kernel' }
+  return {
+    status: 'ready',
+    stats: [
+      { label: 'Workers', value: query.data.workerCount },
+      { label: 'Devices', value: query.data.deviceCount },
+    ],
+  }
+}

package/templates/app-ui/ui-src/index.tsx

@@ -0,0 +1,15 @@
+// The app's UI entry, built to ../ui/index.js (`npm run build:ui` in the app). The dashboard
+// imports it and mounts what it exports: pages under /app/<name>/ and panels on
+// its own pages.
+import { defineMdkApp, MDK_APP_PANEL_SLOT } from '@tetherto/mdk-react-adapter'
+
+import { OverviewPage, SummaryHomePanel } from './pages/overview-page'
+import './styles.css'
+
+export default defineMdkApp({
+  // Must equal `id` in mdk-app.yaml: the dashboard refuses a mismatch.
+  id: '__APP_ID__',
+  displayName: '__APP_DISPLAY_NAME__',
+  routes: [{ path: '', component: OverviewPage }],
+  panels: [{ id: 'summary', slot: MDK_APP_PANEL_SLOT.HOME, component: SummaryHomePanel }],
+})

package/templates/app-ui/ui-src/pages/overview-page.tsx

@@ -0,0 +1,18 @@
+// Page: thin glue — read the hook, hand its output to the component.
+import { Typography } from '@tetherto/mdk-react-devkit'
+
+import { SummaryPanel } from '../components/summary-panel'
+import { useSummary } from '../hooks/use-summary'
+
+export const OverviewPage = () => (
+  <section className="__APP_CSS__-page">
+    <Typography variant="heading1">__APP_DISPLAY_NAME__</Typography>
+    <Typography variant="secondary">
+      Your app&apos;s starter page. Edit ui-src/ and rebuild with npm run build:ui.
+    </Typography>
+    <SummaryPanel view={useSummary()} />
+  </section>
+)
+
+/** The same summary as a card on the dashboard's Home. */
+export const SummaryHomePanel = () => <SummaryPanel view={useSummary()} />

package/templates/app-ui/ui-src/styles.css

@@ -0,0 +1,13 @@
+/* Built to ui/style.css; the dashboard adds it to the page with the app. */
+.__APP_CSS__-page {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 24px;
+}
+
+.__APP_CSS__-summary {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+}

package/templates/app-ui/ui-src/styles.d.ts

@@ -0,0 +1,3 @@
+// `index.tsx` imports its stylesheet for the side effect; Vite bundles the CSS.
+// TypeScript 7 checks side-effect imports, so it needs to know they resolve.
+declare module '*.css'

package/templates/app-ui/ui-src/vite.config.ts

@@ -0,0 +1,26 @@
+// Builds index.tsx to ../ui/index.js (+ ../ui/style.css) for the MDK dashboard.
+// Run from the app root with `npm run build:ui`.
+//
+// React and the MDK packages stay external: the dashboard lends the app its own
+// instances through an import map, so the app ships none of them (a second
+// React would break hooks).
+import { MDK_APP_SHARED_MODULES } from '@tetherto/mdk-ui-foundation/app-shared-modules'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [react()],
+  define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+  build: {
+    // The app package ships ui/, not this source: build one level up.
+    outDir: '../ui',
+    emptyOutDir: true,
+    lib: {
+      entry: 'index.tsx',
+      formats: ['es'],
+      fileName: () => 'index.js',
+      cssFileName: 'style',
+    },
+    rollupOptions: { external: [...MDK_APP_SHARED_MODULES] },
+  },
+})

package/templates/worker/README.md

@@ -0,0 +1,93 @@
+# __WORKER_NAME__
+
+An MDK **Worker Plugin** — the code that translates between MDK and a family of
+physical devices. It ships only an [`mdk-contract.json`](./mdk-contract.json) (its capability manifest)
+plus [`src/`](./src/) handler files, a device "vendor SDK" client, and a mock device
+server. It exports no module of its own; it is **directory-loaded** by
+`WorkerRuntimeV2`, which the MDK CLI constructs (`mdk run worker <name>`) — the
+package never constructs or depends on the runtime itself.
+
+This scaffold is a working example that talks to a hypothetical device over a
+tiny HTTP JSON API. Replace the device client, mock, contract, and handlers with
+your own device's protocol.
+
+## Layout
+
+```
+mdk-contract.json     # capability manifest (telemetry channels + commands)
+src/client.js         # your device "vendor SDK" — binds to this device once, per instance
+src/telemetry/*.js    # telemetry handlers (metrics read live from the device)
+src/commands/*.js     # command handlers (reboot, set-power-mode, ...)
+mock/server.js        # a standalone device simulator (createServer)
+smoke.config.js       # the device spec `mdk validate worker --smoke` checks against
+```
+
+Handlers are plain `(params)` functions — they call `require('../client')` for
+their device's client, which itself binds once (at `require` time) to the
+ambient `@tetherto/mdk-worker/device` for this instance's connection opts.
+There is one such module registry per configured device, so each handler
+always talks to its own device.
+
+## Run it
+
+Add the worker to your stack's `mdk.yaml` by **local path** and describe its
+seed devices under `config`:
+
+```yaml
+spec:
+  workers:
+    - name: __WORKER_NAME__
+      package: ./workers/__WORKER_NAME__
+      config:
+        mock: true          # start mock/server.js per device (dev only)
+        devices:
+          - id: dev-0
+            opts: { host: 127.0.0.1, port: 18080, serial: DEV-0 }
+```
+
+Then:
+
+```bash
+mdk run worker __WORKER_NAME__     # boots the worker (+ its mocks with mock: true)
+```
+
+With `mock: true` the CLI starts one simulator from [`mock/server.js`](./mock/server.js) per device
+so the worker talks to a simulator instead of hardware. Drop `mock` (or set it
+`false`) and point `opts.host`/`opts.port` at real devices for production.
+
+## Check it
+
+```bash
+mdk validate worker __WORKER_NAME__                  # the contract and handler files, without running them
+mdk validate worker --path . --smoke                 # also runs every handler against the simulator
+```
+
+`--smoke` starts the simulator through [`smoke.config.js`](./smoke.config.js), calls every telemetry
+handler and each sample command it lists, then stops the simulator and expects every handler to fail
+with an `ERR_*` error code. Add a sample to `commands` for each command you add, unless it interrupts
+the device.
+
+## Builtin per-device health check
+
+`WorkerRuntimeV2` answers a `telemetry.pull` query of `type: 'health'` for any
+device automatically — no contract or handler changes needed. It works by
+registering `health` as a plain handler in the same table any contract-declared
+telemetry channel lives in, so it is dispatched with zero special-casing, the
+same way `status`/`hashrate_rt`/etc. would be. That means it behaves exactly
+like any other named channel:
+
+- Requires a `deviceId` — a query with no `deviceId` returns
+  `{ error: 'ERR_DEVICE_ID_REQUIRED: health' }`, same as any other named channel.
+- The response comes back in the standard named-channel shape,
+  `{ name: 'health', value: { status, id, opts, env, config, workerId } }` —
+  that device's own ambient config, useful for verifying that Gateway → Kernel
+  → Worker routing reaches the right device instance (e.g. a query addressed
+  to `dev-3` always comes back with `dev-3`'s own `opts`, never a sibling
+  device's).
+- It also shows up as a `health` key inside the default `type: 'metrics'`
+  aggregate for every device, since that aggregate iterates the very same
+  handler table.
+
+If your own contract declares a `health` telemetry channel, that one is used
+instead — the builtin never overrides a plugin-declared handler of the same
+name.

package/templates/worker/mdk-contract.json

@@ -0,0 +1,26 @@
+{
+  "metadata": {
+    "provider": "demo",
+    "deviceFamily": "device",
+    "brand": "DEMO",
+    "modelsSupported": ["DEMO_V1"],
+    "overview": "Template Worker Plugin — talks to a device's HTTP JSON API over src/client.js. Replace the client, mock, contract and handlers with your own device's protocol."
+  },
+  "capabilities": {
+    "telemetry": [
+      { "name": "hashrate_rt", "unit": "TH/s", "type": "number", "handler": "src/telemetry/hashrate-rt.js", "description": "Real-time throughput from the device's summary endpoint." },
+      { "name": "power", "unit": "W", "type": "number", "handler": "src/telemetry/power.js", "description": "Current power draw." },
+      { "name": "temperature", "unit": "C", "type": "number", "handler": "src/telemetry/temperature.js", "description": "Device temperature." },
+      { "name": "power_mode", "type": "string", "handler": "src/telemetry/power-mode.js", "description": "Active power mode: eco, normal or high." }
+    ],
+    "commands": [
+      { "name": "reboot", "handler": "src/commands/reboot.js", "description": "Restarts the device controller.", "constraints": "Do not call more than once per 5 minutes.", "params": [] },
+      { "name": "setPowerMode", "handler": "src/commands/set-power-mode.js", "description": "Changes the power mode: eco, normal or high (low is accepted as an alias for eco).", "params": [{ "name": "mode", "type": "string" }] }
+    ],
+    "health": { "supportedStates": ["OK", "OFFLINE"] },
+    "errors": {
+      "ERR_BAD_POWER_MODE": "The device rejected the requested power mode.",
+      "ERR_DEVICE_CALL_FAILED": "The device's HTTP API call failed or returned an error."
+    }
+  }
+}

package/templates/worker/mock/server.js

@@ -0,0 +1,93 @@
+'use strict'
+
+const http = require('http')
+const debug = require('debug')('mdk:worker:__WORKER_NAME__:mock')
+
+// A standalone device simulator: a small HTTP JSON API (GET /api/v3/summary,
+// POST /api/v3/command) matching src/client.js. It knows nothing about MDK —
+// it is the device-side surface the Worker Plugin translates against, the way
+// a real device on the LAN would be. Replace with your own device's protocol.
+
+const POWER_MODES = {
+  eco: { power: 0.8, hashrate: 0.85 },
+  normal: { power: 1, hashrate: 1 },
+  high: { power: 1.15, hashrate: 1.1 }
+}
+
+function jitter (value) {
+  return Math.round(value * (0.99 + Math.random() * 0.02) * 100) / 100
+}
+
+function createServer ({ host, port, serial, hashrateThs, powerW }) {
+  const state = {
+    serial: serial || 'DEV-0000',
+    baseHashrateThs: hashrateThs || 180,
+    basePowerW: powerW || 3400,
+    powerMode: 'normal',
+    bootTime: Date.now()
+  }
+
+  const summary = () => {
+    const scale = POWER_MODES[state.powerMode]
+    return {
+      serial: state.serial,
+      model: 'DEMO_V1',
+      firmware: 'v1.0.0',
+      uptime_s: Math.floor((Date.now() - state.bootTime) / 1000),
+      power_mode: state.powerMode,
+      hashrate_ths: jitter(state.baseHashrateThs * scale.hashrate),
+      power_w: jitter(state.basePowerW * scale.power),
+      board_temp_c: jitter(62 + (scale.power - 1) * 20)
+    }
+  }
+
+  const command = (body) => {
+    switch (body.cmd) {
+      case 'reboot':
+        state.bootTime = Date.now()
+        return { ok: true, rebooting: true }
+      case 'set-power-mode':
+        if (!POWER_MODES[body.mode]) throw new Error(`ERR_BAD_POWER_MODE: ${body.mode}`)
+        state.powerMode = body.mode
+        return { ok: true, power_mode: state.powerMode }
+      default:
+        throw new Error(`ERR_UNKNOWN_CMD: ${body.cmd}`)
+    }
+  }
+
+  const server = http.createServer((req, res) => {
+    const reply = (code, body) => {
+      res.writeHead(code, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(body))
+    }
+
+    if (req.method === 'GET' && req.url === '/api/v3/summary') return reply(200, summary())
+
+    if (req.method === 'POST' && req.url === '/api/v3/command') {
+      let buf = ''
+      req.on('data', (chunk) => { buf += chunk })
+      req.on('end', () => {
+        try {
+          reply(200, command(JSON.parse(buf || '{}')))
+        } catch (err) {
+          reply(400, { ok: false, error: err.message })
+        }
+      })
+      return
+    }
+
+    reply(404, { ok: false, error: 'ERR_NOT_FOUND' })
+  })
+
+  server.listen(port, host || '127.0.0.1', () => {
+    debug('device mock %s listening on %s:%d', state.serial, host, port)
+  })
+
+  return {
+    server,
+    state,
+    exit () { server.close() }
+  }
+}
+
+module.exports = { createServer }

package/templates/worker/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__WORKER_NAME__",
+  "version": "0.12.1",
+  "description": "MDK Worker Plugin — an mdk-contract.json plus src/ handler files, loaded from this directory and instantiated per device by WorkerRuntimeV2 (see `mdk run worker`). It exports no module of its own.",
+  "keywords": [
+    "mdk",
+    "mdk-worker"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "mock": "node -e \"require('./mock/server').createServer({ host: '127.0.0.1', port: 18080, serial: 'DEV-0' })\""
+  },
+  "dependencies": {
+    "@tetherto/mdk-worker": "^0.12.1",
+    "debug": "4.4.1"
+  },
+  "devDependencies": {
+    "brittle": "3.18.0"
+  }
+}

package/templates/worker/smoke.config.js

@@ -0,0 +1,31 @@
+'use strict'
+
+// Device spec for `mdk validate worker --path . --smoke`: setup() starts the
+// simulator from mock/server.js and returns how to reach it, one sample param
+// set per command to execute, and teardown() to stop it. After teardown() the
+// smoke run checks that every handler fails with an ERR_* instead of hanging
+// or returning a stale value.
+//
+// reboot is left out of `commands` on purpose: nobody watches the device
+// during an automated smoke run, so keep commands that interrupt it out.
+// A telemetry channel served from the worker's own store (a `history` log,
+// say) keeps answering after teardown(); list it as
+// `offlineTelemetry: ['history']` next to `teardown`.
+
+const { once } = require('node:events')
+const { createServer } = require('./mock/server')
+
+module.exports = {
+  async setup () {
+    const mock = createServer({ host: '127.0.0.1', port: 0, serial: 'SMOKE-0' })
+    await once(mock.server, 'listening')
+
+    return {
+      config: { host: '127.0.0.1', port: mock.server.address().port },
+      commands: {
+        setPowerMode: { mode: 'normal' }
+      },
+      teardown: () => mock.exit()
+    }
+  }
+}

package/templates/worker/src/client.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const { opts, env, config, logger } = require('@tetherto/mdk-worker/device')
+
+// The "vendor SDK" for your device's own HTTP JSON API. Plain device I/O — no
+// MDK concepts, no base classes. This is all a plugin author writes to talk
+// to their own device; replace it with your real protocol.
+//
+// The runtime loads this module fresh into a private registry per device, so
+// binding directly to the ambient device module here — rather than exporting
+// a `createClient(opts)` factory for a caller to invoke — already yields one
+// client per device with no extra plumbing.
+// Log only non-secret fields and key names: `env` carries credentials such as
+// DEVICE_TOKEN, and `opts`/`config` may too — never log their values.
+logger('config received: host=%s port=%s env keys=%o config keys=%o',
+  opts.host, opts.port, Object.keys(env || {}), Object.keys(config || {}))
+
+const base = `http://${opts.host || '127.0.0.1'}:${opts.port}`
+const auth = env.DEVICE_TOKEN ? { authorization: `Bearer ${env.DEVICE_TOKEN}` } : {}
+
+const call = async (path, callOpts) => {
+  let res, body
+  try {
+    res = await fetch(base + path, { ...callOpts, headers: { ...auth, ...(callOpts && callOpts.headers) } })
+    body = await res.json()
+  } catch (err) {
+    // An unreachable device or a non-JSON reply: surface it as this plugin's
+    // own error code, not fetch's bare "fetch failed".
+    throw new Error(`ERR_DEVICE_CALL_FAILED: ${(err.cause && err.cause.code) || err.message}`)
+  }
+  if (!res.ok || body.ok === false) {
+    throw new Error(body.error || `ERR_DEVICE_CALL_FAILED: ${res.status}`)
+  }
+  return body
+}
+
+const command = (cmd, args) => call('/api/v3/command', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ cmd, ...args })
+})
+
+module.exports = {
+  getSummary: () => call('/api/v3/summary'),
+  reboot: () => command('reboot'),
+  setPowerMode: (mode) => command('set-power-mode', { mode })
+}

package/templates/worker/src/commands/reboot.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async () => client.reboot()

package/templates/worker/src/commands/set-power-mode.js

@@ -0,0 +1,10 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async (params) => {
+  // Example vendor-agnostic-to-firmware translation: this device's API calls
+  // low "eco". Adjust to your own device's vocabulary.
+  const mode = params.mode === 'low' ? 'eco' : params.mode
+  return client.setPowerMode(mode)
+}

package/templates/worker/src/telemetry/hashrate-rt.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async () => (await client.getSummary()).hashrate_ths

package/templates/worker/src/telemetry/power-mode.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async () => (await client.getSummary()).power_mode

package/templates/worker/src/telemetry/power.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async () => (await client.getSummary()).power_w

package/templates/worker/src/telemetry/temperature.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const client = require('../client')
+
+module.exports = async () => (await client.getSummary()).board_temp_c