@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-worker-plugin/references/worker-base-api.md

@@ -0,0 +1,152 @@
+# Worker base API — `@tetherto/mdk-worker`
+
+Load this when hosting a plugin, debugging envelope dispatch, or deciding what
+belongs in the plugin vs the caller. Two Worker Plugin shapes exist side by
+side: the module-exporting shape below, hosted on `WorkerRuntime`, and the
+directory-loaded shape (see [Directory-loaded plugins](#directory-loaded-plugins-workerruntimev2)
+below), hosted on `WorkerRuntimeV2` — the shape `mdk create worker` scaffolds
+today. Source: [`backend/core/mdk-worker/lib/worker-runtime.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime.js),
+[`lib/worker-runtime-v2.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime-v2.js), and
+[`lib/plugin-loader.js`](../../../../../../backend/core/mdk-worker/lib/plugin-loader.js);
+package entry [`backend/core/mdk-worker/index.js`](../../../../../../backend/core/mdk-worker/index.js) exports
+`{ WorkerRuntime, WorkerRuntimeV2, loadPlugin, loadContract, createInstance, createModuleContext }`.
+
+## The plugin contract (`loadPlugin`)
+
+A Worker Plugin is `{ contract, dir, connect, disconnect? }`:
+
+- `contract` — the parsed `mdk-contract.json`.
+- `dir` — `__dirname` of the plugin; handler paths resolve against it.
+- `connect(config, { deviceId }) => device` — build (and probe) one device
+  client. Throwing here holds the device `offline` without failing the boot.
+- `disconnect(device, { deviceId })` — optional; close sockets etc.
+
+`loadPlugin` **eagerly requires every handler** declared under
+`capabilities.telemetry` and `capabilities.commands` — a missing file,
+non-function export, missing `handler` field, or duplicate name aborts with
+`ERR_PLUGIN_HANDLER_NOT_FOUND` / `ERR_PLUGIN_HANDLER_NOT_FUNCTION` /
+`ERR_PLUGIN_HANDLER_MISSING` / `ERR_PLUGIN_DUPLICATE_NAME`. Nothing loads
+lazily at request time. It returns
+`{ contract, publishedContract, handlers, connect, disconnect }` where
+`publishedContract` has all `handler` paths stripped (that copy is what
+`capability.response` sends).
+
+## Handler signature
+
+Telemetry and command handlers are identical in shape:
+
+```js
+module.exports = async (ctx, params) => result
+```
+
+`ctx` is frozen per device: `{ deviceId, device, config, services }`.
+`device` is whatever `connect()` returned; `services` is `null` unless the
+caller injected worker-infra services. Handlers never see envelopes or
+transport — the runtime wraps their return value (or thrown error) into the
+response envelope.
+
+## `new WorkerRuntime(plugin, opts)`
+
+| Option | Required | Meaning |
+| --- | --- | --- |
+| `workerId` | yes | Identity string; `ERR_WORKER_ID_REQUIRED` otherwise |
+| `devices` | yes* | `[{ deviceId, config? }]`; duplicates/missing ids throw. *`allowEmptyDevices: true` permits a device-less provisioning-first boot |
+| `kernelTopic` | no | Hex string or Buffer; when set, the runtime announces on this DHT topic |
+| `store` | no | Persistent store (Hyperbee-style) for the DHT/RPC seeds → stable public key across restarts; without it keys are random per boot |
+| `storeDir` | no | Directory for file-backed DHT/RPC seeds (same stability as `store`, for hosts that do not own a Hyperbee). Ignored when `store` is set |
+| `services` | no | Worker-infra services (logs, settings, stats, comments, provisioning…). Served as built-ins ahead of plugin handlers and exposed to handlers as `ctx.services` |
+| `bootstrap` | no | Custom DHT bootstrap nodes (hermetic tests use `hyperdht/testnet`) |
+
+One runtime hosts N same-type devices behind one HRPC channel. The device
+list is fixed at construction.
+
+## Lifecycle
+
+- `await start()` — opens device contexts (`connect` per device; failures →
+  `offline`), starts the HRPC server responding on the `'mdk'` method, and —
+  if `kernelTopic` is set — joins the topic in server mode, writing its public
+  key to each incoming connection and re-announcing every 30 s. Returns
+  `{ publicKey }`.
+- `await stop()` — tears down swarm/RPC/DHT and calls `disconnect` per online
+  device.
+- `getPublicKey()` — HRPC public key (null before `start`).
+- `getDeviceContext(deviceId)` — the frozen ctx of an *online* device, for the
+  process that owns the runtime (e.g. a sampler loop); null while offline. On
+  `WorkerRuntimeV2` this returns `{ deviceId, config, services }` with no
+  `device` key — see [below](#directory-loaded-plugins-workerruntimev2).
+- `await handleRequest(envelope)` — the entire protocol surface; usable
+  directly in-process for tests (no `start()` needed for identity/capability;
+  device-touching actions need contexts opened by `start()`).
+
+## Directory-loaded plugins (`WorkerRuntimeV2`)
+
+A directory-loaded Worker Plugin exports no module of its own: the package
+ships only `mdk-contract.json` at its root plus the handler files it declares
+under `src/`. There is no `plugin/index.js` and no `connect()`/`disconnect()`.
+`new WorkerRuntimeV2(dir, opts)` takes the package's directory in place of a
+plugin object — it calls `loadContract(dir)` internally to resolve the
+contract and every handler path, then builds one plugin instance per
+configured device via `createInstance({ dir, entries, device })` when each
+device's context opens.
+
+- **Handler signature**: `async (params) => result` — no `ctx` argument.
+  Handlers instead `require('@tetherto/mdk-worker/device')`, an ambient module
+  giving `{ id, opts, env, config, logger }` for the device the handler is
+  currently bound to. `opts` is that device's own connection config (the
+  `config` entry from `opts.devices` at construction); `env` and `config` are
+  the plugin-wide blocks passed as `opts.env`/`opts.config` to the runtime.
+- **Isolation**: `WorkerRuntimeV2` loads the package's files into a private
+  module registry per device, so a client module that binds to the ambient
+  device at load time already gets one instance per device with no explicit
+  per-device construction, and `require('../client')` inside one device's
+  handlers always resolves to that device's own instance.
+- **No boot-time probe, no offline state**: every declared device reports
+  `online` as soon as `runtime.start()` returns. An unreachable device
+  surfaces as an error inside the telemetry payload for the channel that
+  touched the network (or `status: 'FAILED'` for a command), not as
+  `ERR_DEVICE_UNAVAILABLE`.
+- **No `disconnect()`**: whatever a handler module opens at load time (a
+  socket, a file handle) lives until the process exits; nothing closes it
+  automatically.
+- **Builtin `health` channel**: every directory-loaded plugin answers
+  `telemetry.pull { query: { type: 'health' } }` automatically — `{ status,
+  id, workerId }` for the addressed device (never `env`, `opts` or `config`)
+  — unless the contract itself declares a `health` channel, which always wins.
+
+`loadContract(dir)` and `createInstance({ dir, entries, device })` are also
+usable directly, without a runtime, for contract-level tests — see
+[`local-testing.md`](./local-testing.md).
+
+## Envelope dispatch (`handleRequest`)
+
+| Action | Behaviour |
+| --- | --- |
+| `identity.request` | `{ workerId, devices: [{ deviceId }] }` |
+| `capability.request` | `{ contract: publishedContract }` (built-in commands merged in when services are present) |
+| `telemetry.pull` | `query.type` routing — see [`../../mdk/references/protocol.md`](../../mdk/references/protocol.md). `metrics` runs every telemetry handler; a channel name runs one; `list` returns device statuses; service built-ins (`logs`, `settings`, `stats`, …) take precedence over plugin channels |
+| `command.request` | Built-ins first (provisioning/store commands work for offline devices); then device must exist and be online; unknown command → `ERR_UNKNOWN_COMMAND`; handler success → `{ commandId, status: 'SUCCESS', result }`, throw → `{ status: 'FAILED', error }` |
+| `health.ping` | `{ status: 'OK' }` |
+| `state.pull` | `{ state: { <deviceId>: { status } }, deviceCount, workerId }` |
+| `write.calls.request` | Only when `services.actions` is injected |
+| anything else | `ERR_UNKNOWN_ACTION` |
+
+Failure isolation: a handler that throws poisons only that field
+(`metrics.<name> = { error }`) or that command — never the Worker. An offline
+device answers `ERR_DEVICE_UNAVAILABLE`; a wrong id `ERR_DEVICE_NOT_FOUND`.
+
+## Param normalization
+
+Legacy write paths dispatch positionally (`{ value: x }` or
+`{ args: [...] }`). The runtime maps those onto your contract-declared param
+names before your handler runs, so handlers only ever see named params —
+provided the contract declares params accurately.
+
+## What the runtime does NOT do
+
+- It does not validate contracts against the JSON Schema (that's
+  [`../scripts/validate-contract.mjs`](../scripts/validate-contract.mjs) and the catalogue lint).
+- It does not enforce param types or `min`/`max` bounds — the **Kernel's**
+  dispatcher does, and only for declared bounds. In-process callers of
+  `handleRequest` bypass that check (the smoke harness replicates it).
+- It has no HTTP mode and no CLI — a caller process constructs it (see
+  the minimal caller in [`local-testing.md`](./local-testing.md#3-standalone-protocol-check-workerruntimev2-real-envelopes-still-no-kernel)).

package/dist/skills/mdk-worker-plugin/scripts/validate-contract.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Validate a worker's mdk-contract.json against ../references/mdk-contract.schema.json.
+//
+//   node validate-contract.mjs <path/to/mdk-contract.json>                 # exit 0/1
+//   node validate-contract.mjs --schema-only <path/to/mdk-contract.json>   # skip semantic checks
+//
+// Zero-dependency: implements the JSON Schema subset the schema uses, plus
+// semantic checks the schema cannot express — handler files exist, names are
+// unique, and number params declare min/max (the Kernel enforces
+// ERR_PARAM_RANGE only for declared bounds).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+const SCHEMA_PATH = path.resolve(SCRIPT_DIR, '..', 'references', 'mdk-contract.schema.json')
+
+function jsonType (v) {
+  if (Array.isArray(v)) return 'array'
+  if (v === null) return 'null'
+  return typeof v
+}
+
+function matchesType (expected, v) {
+  if (expected === 'integer') return typeof v === 'number' && Number.isInteger(v)
+  if (expected === 'array') return Array.isArray(v)
+  if (expected === 'object') return jsonType(v) === 'object'
+  return typeof v === expected
+}
+
+function validateNode (schema, value, at, errors) {
+  if (schema.type && !matchesType(schema.type, value)) {
+    errors.push(`ERR_CONTRACT_TYPE: ${at} expected ${schema.type}, got ${jsonType(value)}`)
+    return
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`ERR_CONTRACT_ENUM: ${at} is ${JSON.stringify(value)}, allowed: ${schema.enum.join(' | ')}`)
+  }
+  if (jsonType(value) === 'object') {
+    for (const key of schema.required || []) {
+      if (!(key in value)) errors.push(`ERR_CONTRACT_REQUIRED: ${at} missing required property '${key}'`)
+    }
+    const props = schema.properties || {}
+    for (const [key, v] of Object.entries(value)) {
+      if (props[key]) {
+        validateNode(props[key], v, `${at}/${key}`, errors)
+      } else if (schema.additionalProperties === false) {
+        errors.push(`ERR_CONTRACT_UNEXPECTED: ${at} has unexpected property '${key}'`)
+      } else if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+        validateNode(schema.additionalProperties, v, `${at}/${key}`, errors)
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((v, i) => validateNode(schema.items, v, `${at}/${i}`, errors))
+  }
+}
+
+function semanticChecks (contract, contractDir, errors) {
+  const caps = contract.capabilities
+  if (jsonType(caps) !== 'object') return
+
+  for (const section of ['telemetry', 'commands']) {
+    const entries = Array.isArray(caps[section]) ? caps[section] : []
+    const seen = new Set()
+    entries.forEach((entry, i) => {
+      const at = `/capabilities/${section}/${i}`
+      if (jsonType(entry) !== 'object') return
+      if (entry.name) {
+        if (seen.has(entry.name)) errors.push(`ERR_CONTRACT_DUPLICATE_NAME: ${at} '${entry.name}' already declared in ${section}`)
+        seen.add(entry.name)
+      }
+      if (typeof entry.handler === 'string' && entry.handler) {
+        const file = path.resolve(contractDir, entry.handler)
+        if (!fs.existsSync(file)) errors.push(`ERR_CONTRACT_HANDLER_NOT_FOUND: ${at} handler '${entry.handler}' does not exist (resolved: ${file})`)
+      }
+    })
+  }
+
+  const commands = Array.isArray(caps.commands) ? caps.commands : []
+  commands.forEach((cmd, i) => {
+    if (jsonType(cmd) !== 'object' || !Array.isArray(cmd.params)) return
+    cmd.params.forEach((p, j) => {
+      if (jsonType(p) !== 'object' || p.type !== 'number') return
+      const at = `/capabilities/commands/${i}/params/${j}`
+      if (typeof p.min !== 'number' || typeof p.max !== 'number') {
+        errors.push(`ERR_CONTRACT_PARAM_BOUNDS_MISSING: ${at} ('${cmd.name}'.'${p.name}') — number params must declare min and max so the Kernel can enforce ERR_PARAM_RANGE`)
+      } else if (p.min > p.max) {
+        errors.push(`ERR_CONTRACT_PARAM_BOUNDS_INVALID: ${at} min ${p.min} > max ${p.max}`)
+      }
+    })
+  })
+}
+
+const args = process.argv.slice(2)
+const schemaOnly = args.includes('--schema-only')
+const target = args.find((a) => !a.startsWith('--'))
+if (!target) {
+  console.error('usage: node validate-contract.mjs [--schema-only] <path/to/mdk-contract.json>')
+  process.exit(1)
+}
+
+const contractPath = path.resolve(process.cwd(), target)
+if (!fs.existsSync(contractPath)) {
+  console.error(`ERR_CONTRACT_FILE_NOT_FOUND: ${contractPath}`)
+  process.exit(1)
+}
+
+let contract
+try {
+  contract = JSON.parse(fs.readFileSync(contractPath, 'utf8'))
+} catch (err) {
+  console.error(`ERR_CONTRACT_PARSE: ${contractPath}: ${err.message}`)
+  process.exit(1)
+}
+
+const schema = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'))
+const errors = []
+validateNode(schema, contract, '', errors)
+if (!schemaOnly) semanticChecks(contract, path.dirname(contractPath), errors)
+
+if (errors.length) {
+  console.error(`FAIL: ${target} — ${errors.length} problem(s):`)
+  for (const err of errors) console.error(`  ${err}`)
+  process.exit(1)
+}
+
+console.log(`OK: ${target} conforms to mdk-contract.schema.json${schemaOnly ? '' : ' (+ semantic checks)'}`)

package/dist/skills/mdk-worker-plugin/scripts/worker-smoke.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// In-process smoke harness for a Worker Plugin — no Kernel, no DHT.
+//
+//   node worker-smoke.mjs <worker-dir> [--config <json | path>]
+//
+// Device opts come from --config (inline JSON or a .json file) or from
+// <worker-dir>/smoke.config.js exporting { setup } -> { config, commands?,
+// env?, pluginConfig?, teardown? }. Asserts: the contract loads, every
+// declared telemetry handler returns the contract-declared type, bounded
+// number params reject out-of-range values, and each smoke.config command
+// executes. Uses WorkerRuntimeV2's loadContract + createInstance path
+// (directory-loaded plugin, plain (params) handlers, ambient device context).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+
+const TYPE_OK = {
+  number: (v) => typeof v === 'number' && Number.isFinite(v),
+  string: (v) => typeof v === 'string',
+  boolean: (v) => typeof v === 'boolean',
+  array: (v) => Array.isArray(v),
+  object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+// Replica of the Kernel dispatcher's pre-dispatch validation
+// (CommandDispatcher._validateCommand) — bounds are enforced Kernel-side,
+// so an in-process harness must check them itself. Kept in sync manually.
+function validateCommand (capabilities, command, params) {
+  if (!capabilities.commands) return { valid: true }
+  const commands = capabilities.commands
+  const cmdDef = Array.isArray(commands)
+    ? commands.find((c) => c.name === command)
+    : commands[command]
+
+  if (!cmdDef) return { valid: false, error: `ERR_COMMAND_NOT_IN_CAPABILITIES: ${command}` }
+
+  if (cmdDef.params && Array.isArray(cmdDef.params) && params) {
+    for (const paramDef of cmdDef.params) {
+      const value = params[paramDef.name]
+      if (value === undefined) continue
+      if (paramDef.type === 'number' && typeof value !== 'number') {
+        return { valid: false, error: `ERR_PARAM_TYPE: ${paramDef.name} must be number` }
+      }
+      if (paramDef.type === 'string' && typeof value !== 'string') {
+        return { valid: false, error: `ERR_PARAM_TYPE: ${paramDef.name} must be string` }
+      }
+      if (paramDef.type === 'number') {
+        if (paramDef.min !== undefined && value < paramDef.min) {
+          return { valid: false, error: `ERR_PARAM_RANGE: ${paramDef.name} below min ${paramDef.min}` }
+        }
+        if (paramDef.max !== undefined && value > paramDef.max) {
+          return { valid: false, error: `ERR_PARAM_RANGE: ${paramDef.name} above max ${paramDef.max}` }
+        }
+      }
+    }
+  }
+  return { valid: true }
+}
+
+// Monorepo fallback for a checkout without node_modules links: walk up from
+// this script's own dir (never the worker dir, which may be untrusted) and stop
+// at the repo root (the first dir holding .git). The candidate must really be
+// @tetherto/mdk-worker.
+function findMonorepoWorkerBase () {
+  let dir = SCRIPT_DIR
+  for (;;) {
+    const candidate = path.join(dir, 'backend', 'core', 'mdk-worker')
+    if (fs.existsSync(path.join(candidate, 'lib', 'contract-loader.js'))) {
+      try {
+        if (JSON.parse(fs.readFileSync(path.join(candidate, 'package.json'), 'utf8')).name === '@tetherto/mdk-worker') return candidate
+      } catch {}
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir || fs.existsSync(path.join(dir, '.git'))) return null
+    dir = parent
+  }
+}
+
+function parseArgs (argv) {
+  const args = { workerDir: null, config: null }
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--config') args.config = argv[++i]
+    else if (!args.workerDir) args.workerDir = argv[i]
+  }
+  return args
+}
+
+const { workerDir: workerDirArg, config: configArg } = parseArgs(process.argv.slice(2))
+if (!workerDirArg) {
+  console.error('usage: node worker-smoke.mjs <worker-dir> [--config <json | path>]')
+  process.exit(1)
+}
+
+const workerDir = path.resolve(process.cwd(), workerDirArg)
+const pluginDir = fs.existsSync(path.join(workerDir, 'plugin', 'mdk-contract.json'))
+  ? path.join(workerDir, 'plugin')
+  : workerDir
+if (!fs.existsSync(path.join(pluginDir, 'mdk-contract.json'))) {
+  console.error(`ERR_SMOKE_NO_PLUGIN: no mdk-contract.json under ${workerDir}`)
+  process.exit(1)
+}
+
+const requireFromWorker = createRequire(path.join(workerDir, 'noop.js'))
+const requireFromScript = createRequire(path.join(SCRIPT_DIR, 'noop.js'))
+
+let loadContract
+let createInstance
+// Resolution order: explicit MDK_WORKER_BASE, then the worker's declared
+// @tetherto/mdk-worker dependency, then a monorepo checkout around this script.
+function useBase (base) {
+  loadContract = requireFromScript(path.join(base, 'lib', 'contract-loader.js')).loadContract
+  createInstance = requireFromScript(path.join(base, 'lib', 'instance-loader.js')).createInstance
+}
+if (process.env.MDK_WORKER_BASE) {
+  useBase(path.resolve(process.env.MDK_WORKER_BASE))
+} else {
+  let mdkWorker = null
+  try {
+    mdkWorker = requireFromWorker('@tetherto/mdk-worker')
+  } catch {}
+  if (mdkWorker) {
+    loadContract = mdkWorker.loadContract
+    createInstance = mdkWorker.createInstance
+  } else {
+    const base = findMonorepoWorkerBase()
+    if (!base) {
+      console.error('ERR_SMOKE_NO_WORKER_BASE: cannot resolve @tetherto/mdk-worker from the worker dir (run npm install there, or set MDK_WORKER_BASE)')
+      process.exit(1)
+    }
+    useBase(base)
+  }
+}
+
+const failures = []
+let checks = 0
+function check (ok, label, detail) {
+  checks++
+  if (ok) {
+    console.log(`  ok    ${label}`)
+  } else {
+    failures.push(`${label}${detail ? ` — ${detail}` : ''}`)
+    console.error(`  FAIL  ${label}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+
+async function resolveSpec () {
+  if (configArg) {
+    if (configArg.trim().startsWith('{')) return { config: JSON.parse(configArg) }
+    const p = path.resolve(process.cwd(), configArg)
+    if (p.endsWith('.json')) return { config: JSON.parse(fs.readFileSync(p, 'utf8')) }
+    const mod = requireFromWorker(p)
+    return mod.setup ? mod.setup() : { config: mod }
+  }
+  const smokeConfig = path.join(workerDir, 'smoke.config.js')
+  if (!fs.existsSync(smokeConfig)) {
+    console.error(`ERR_SMOKE_NO_CONFIG: no --config given and no ${smokeConfig}`)
+    process.exit(1)
+  }
+  return requireFromWorker(smokeConfig).setup()
+}
+
+async function main () {
+  const { contract, entries, dir } = loadContract(pluginDir)
+  const declaredTel = (contract.capabilities.telemetry || []).length
+  const declaredCmd = (contract.capabilities.commands || []).length
+  console.log(`smoke: ${contract.metadata.brand} (${contract.metadata.deviceFamily}) — ${declaredTel} telemetry, ${declaredCmd} commands`)
+  check(true, 'contract loads (loadContract: mdk-contract.json + every handler path)')
+
+  const spec = await resolveSpec()
+  const deviceId = 'smoke-0'
+
+  let instance = null
+  try {
+    instance = createInstance({
+      dir,
+      entries,
+      device: {
+        id: deviceId,
+        opts: Object.freeze({ ...(spec.config || {}) }),
+        env: Object.freeze({ ...(spec.env || {}) }),
+        config: Object.freeze({ ...(spec.pluginConfig || {}) }),
+        workerId: 'smoke',
+        logger: () => {}
+      }
+    })
+    check(true, 'createInstance binds handlers for one device')
+  } catch (err) {
+    check(false, 'createInstance binds handlers for one device', err.message)
+  }
+
+  if (instance) {
+    for (const entry of contract.capabilities.telemetry || []) {
+      const typeOk = TYPE_OK[entry.type] || ((v) => v !== undefined)
+      try {
+        const value = await instance.telemetry.get(entry.name)({})
+        check(value !== undefined && typeOk(value),
+          `telemetry '${entry.name}' returns a ${entry.type}`,
+          value === undefined ? 'returned undefined' : `returned ${JSON.stringify(value)}`)
+      } catch (err) {
+        check(false, `telemetry '${entry.name}' returns a ${entry.type}`, err.message)
+      }
+    }
+
+    for (const cmd of contract.capabilities.commands || []) {
+      for (const p of cmd.params || []) {
+        if (p.type !== 'number' || p.min === undefined || p.max === undefined) continue
+        const below = validateCommand(contract.capabilities, cmd.name, { [p.name]: p.min - 1 })
+        check(!below.valid && /ERR_PARAM_RANGE/.test(below.error || ''),
+          `command '${cmd.name}' rejects ${p.name}=${p.min - 1} (below min)`, below.error || 'accepted')
+        const above = validateCommand(contract.capabilities, cmd.name, { [p.name]: p.max + 1 })
+        check(!above.valid && /ERR_PARAM_RANGE/.test(above.error || ''),
+          `command '${cmd.name}' rejects ${p.name}=${p.max + 1} (above max)`, above.error || 'accepted')
+        const atBounds = validateCommand(contract.capabilities, cmd.name, { [p.name]: p.min }).valid &&
+          validateCommand(contract.capabilities, cmd.name, { [p.name]: p.max }).valid
+        check(atBounds, `command '${cmd.name}' accepts ${p.name} at [${p.min}, ${p.max}]`)
+      }
+    }
+
+    for (const [name, params] of Object.entries(spec.commands || {})) {
+      const gate = validateCommand(contract.capabilities, name, params)
+      if (!gate.valid) {
+        check(false, `command '${name}' executes with sample params`, gate.error)
+        continue
+      }
+      const handler = instance.commands.get(name)
+      if (!handler) {
+        check(false, `command '${name}' executes with sample params`, 'not declared in contract')
+        continue
+      }
+      try {
+        await handler(params)
+        check(true, `command '${name}' executes with sample params`)
+      } catch (err) {
+        check(false, `command '${name}' executes with sample params`, err.message)
+      }
+    }
+  }
+
+  if (spec.teardown) await spec.teardown()
+
+  if (failures.length) {
+    console.error(`\nSMOKE FAIL: ${failures.length}/${checks} check(s) failed`)
+    process.exit(1)
+  }
+  console.log(`\nSMOKE PASS: ${checks} check(s)`)
+  process.exit(0)
+}
+
+main().catch((err) => {
+  console.error(`ERR_SMOKE: ${err.message}`)
+  process.exit(1)
+})

package/package.json

@@ -1 +1,47 @@
-{"name":"@tetherto/mdk-skill","version":"0.0.0"}
+{
+  "name": "@tetherto/mdk-skill",
+  "version": "0.12.1",
+  "description": "MDK Developer Skill Suite — Agent Skills (SKILL.md) bundle assembled from the MDK monorepo's real artifacts and versioned to track the MDK release line. Copy-only assembler: each library owns its artifacts, this package curates them into dist/skills/ and installs them flat into .cursor/skills/ or .claude/skills/.",
+  "keywords": [
+    "tether",
+    "mdk",
+    "agent-skills"
+  ],
+  "author": "Tether",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
+      "default": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/*.mjs",
+    "src/index.d.ts",
+    "src/sources.map.json"
+  ],
+  "scripts": {
+    "assemble": "node src/assemble.mjs",
+    "compile:envelope": "node src/skills/mdk-site-sizing/scripts/compile-envelope.mjs",
+    "test": "node src/skills/mdk-site-sizing/scripts/compile-envelope.mjs && node src/assemble.mjs && node --test tests/site-sizing.test.mjs tests/install.test.mjs tests/install-cli.test.mjs tests/scan-packages.test.mjs && node src/skills/mdk-site-sizing/scripts/eval-held-out.mjs",
+    "install:skills": "node src/assemble.mjs && node src/install.mjs",
+    "prepack": "node src/assemble.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetherto/mdk.git",
+    "directory": "packages/mdk-skill"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/assemble.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// CLI wrapper around the programmatic `assemble()` (see index.mjs).
+import { assemble } from './index.mjs'
+
+try {
+  const { files, version } = assemble()
+  console.log(`assembled ${files} file(s) (mdk ${version}) -> dist/skills`)
+} catch (err) {
+  console.error(`ERR_ASSEMBLE: ${err instanceof Error ? err.message : String(err)}`)
+  process.exit(1)
+}

package/src/index.d.ts

@@ -0,0 +1,57 @@
+export type SkillClient = 'cursor' | 'claude' | 'all';
+
+export interface InstalledEntry {
+  client: string;
+  dir: string;
+  /** Stale MDK-shipped skill dirs removed from `dir` because the current suite no longer ships them. */
+  removed: string[];
+}
+
+export interface SkippedEntry {
+  client: string;
+  skill: string;
+  dir: string;
+  reason: string;
+}
+
+export interface InstallResult {
+  skills: string[];
+  installed: InstalledEntry[];
+  /** Existing skill dirs left untouched: symlinks, or not marked `metadata.suite: mdk-developer-skill`. */
+  skipped: SkippedEntry[];
+}
+
+export interface InstallOptions {
+  /** Target client(s). Defaults to `'all'`. */
+  client?: SkillClient;
+  /** Project root to install into. Defaults to `process.cwd()`. */
+  target?: string;
+  /** Assemble the suite first if `dist/skills/` is empty. Defaults to `true`. */
+  assembleIfMissing?: boolean;
+  /** Called once per skipped skill dir. Defaults to `console.warn`. */
+  onWarn?: (message: string) => void;
+}
+
+export interface AssembleResult {
+  files: number;
+  version: string;
+}
+
+export declare const CLIENT_DIRS: Record<string, string[]>;
+
+/** True when the source map and repo root are available to assemble from. */
+export declare function canAssemble(): boolean;
+
+/** True when `dist/skills/` already holds at least one assembled skill. */
+export declare function isAssembled(): boolean;
+
+/** Assemble the skill suite from source artifacts into `dist/skills/`. */
+export declare function assemble(): AssembleResult;
+
+/**
+ * Install the assembled skills into a project's client skills directories.
+ * Throws if a client dir segment under the target is a symlink; skips (and
+ * warns about) existing same-named skill dirs that are not suite skills. Stale
+ * MDK-shipped skills are swept; user-authored skills are left untouched.
+ */
+export declare function installSkills(options?: InstallOptions): InstallResult;