@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/lib/worker-smoke.js

@@ -0,0 +1,243 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { isAbsolute, join, resolve } from 'node:path';
+const require = createRequire(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),
+};
+function withDeadline(run, ms, label) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        // Deliberately not unref'd: against a hung handler this timer is the only
+        // handle on the event loop — unref it and node exits 0 before it fires.
+        const timer = setTimeout(() => rejectPromise(new Error(`ERR_SMOKE_TIMEOUT: ${label} did not settle within ${ms}ms`)), ms);
+        Promise.resolve()
+            .then(run)
+            .then(resolvePromise, rejectPromise)
+            .finally(() => clearTimeout(timer));
+    });
+}
+/** A value the runtime's param gate accepts for `p`, for params a probe is not about. */
+function gateValue(p) {
+    if (Array.isArray(p.enum) && p.enum.length)
+        return p.enum[0];
+    switch (p.type) {
+        case 'number':
+            return typeof p.min === 'number' ? p.min : typeof p.max === 'number' ? Math.min(p.max, 0) : 0;
+        case 'boolean':
+            return false;
+        case 'string':
+            return '';
+        default:
+            return {};
+    }
+}
+/**
+ * A param set for `cmd` that passes its gate: the smoke config's sample when
+ * it has one, every other required param filled with a valid value. The gate
+ * checks params in declaration order and `required` before range, so a probe
+ * that sends only the param under test fails on the first missing required
+ * param instead of the bound it means to test. Optional params stay absent —
+ * the gate skips them, and a filler value ('' / {} / false) could make the
+ * handler reject for its own reasons, passing the self-rejection check for
+ * the wrong one.
+ */
+function baselineParams(cmd, sample) {
+    const filled = Object.fromEntries((cmd.params ?? []).filter((p) => p.required === true).map((p) => [p.name, gateValue(p)]));
+    return { ...filled, ...(sample ?? {}) };
+}
+async function resolveSpec(workerDir, config) {
+    const requireFromWorker = createRequire(join(workerDir, 'noop.js'));
+    if (config) {
+        if (config.trim().startsWith('{'))
+            return { config: JSON.parse(config) };
+        const file = isAbsolute(config) ? config : resolve(config);
+        if (file.endsWith('.json'))
+            return { config: JSON.parse(readFileSync(file, 'utf8')) };
+        const mod = requireFromWorker(file);
+        return mod.setup ? mod.setup() : { config: mod };
+    }
+    const smokeConfig = join(workerDir, 'smoke.config.js');
+    if (!existsSync(smokeConfig)) {
+        throw new Error(`ERR_SMOKE_NO_CONFIG: no --smoke-config given and no ${smokeConfig}`);
+    }
+    return requireFromWorker(smokeConfig).setup();
+}
+/**
+ * Behavioural checks against the worker's own mock device — no Kernel, no DHT.
+ * Live pass: every declared telemetry handler returns its declared type, the
+ * runtime's param gate rejects out-of-range values, every smoke.config sample
+ * command executes, and a handler called with an out-of-range param rejects
+ * with an ERR_* of its own (the worker is reachable on its own RPC key, so it
+ * must not rely on the Kernel's gate). Stopped pass, after `teardown()`: every
+ * handler rejects with an ERR_* within the deadline — no hang, no crash, no
+ * stale value. Two exceptions: a `health` channel may instead report a non-OK
+ * status (its job is to say the device is down), and the smoke config's
+ * `offlineTelemetry` channels must return their declared type. Every handler
+ * call is bounded by `timeoutMs`.
+ */
+export async function runWorkerSmoke(workerDir, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const outcome = { passed: 0, failures: [], warnings: [] };
+    const check = (ok, label, detail) => {
+        if (ok)
+            outcome.passed++;
+        else
+            outcome.failures.push(`smoke: ${label}${detail ? ` — ${detail}` : ''}`);
+    };
+    const runtime = require('@tetherto/mdk-worker');
+    const pluginDir = existsSync(join(workerDir, 'plugin', 'mdk-contract.json')) ? join(workerDir, 'plugin') : workerDir;
+    const { contract, entries, dir } = runtime.loadContract(pluginDir);
+    const spec = await resolveSpec(workerDir, opts.config);
+    // setup() has started the mock: stop it however the checks end, or its open
+    // socket keeps the process alive after a handler fails to load.
+    let stopped = false;
+    const stop = async () => {
+        if (stopped || !spec.teardown)
+            return;
+        stopped = true;
+        await withDeadline(() => spec.teardown(), timeoutMs, 'teardown()');
+    };
+    try {
+        const instance = runtime.createInstance({
+            dir,
+            entries,
+            device: {
+                id: 'smoke-0',
+                opts: Object.freeze({ ...(spec.config ?? {}) }),
+                env: Object.freeze({ ...(spec.env ?? {}) }),
+                config: Object.freeze({ ...(spec.pluginConfig ?? {}) }),
+                workerId: 'smoke',
+                logger: () => { },
+            },
+        });
+        const telemetry = contract.capabilities.telemetry ?? [];
+        const commands = contract.capabilities.commands ?? [];
+        for (const entry of telemetry) {
+            const label = `telemetry '${entry.name}' returns a ${entry.type}`;
+            const typeOk = TYPE_OK[entry.type ?? ''] ?? ((v) => v !== undefined);
+            try {
+                const value = await withDeadline(() => instance.telemetry.get(entry.name)({}), timeoutMs, label);
+                check(value !== undefined && typeOk(value), label, value === undefined ? 'returned undefined' : `returned ${JSON.stringify(value)}`);
+            }
+            catch (error) {
+                check(false, label, message(error));
+            }
+        }
+        for (const cmd of commands) {
+            const base = baselineParams(cmd, spec.commands?.[cmd.name]);
+            for (const p of cmd.params ?? []) {
+                if (p.type !== 'number' || typeof p.min !== 'number' || typeof p.max !== 'number')
+                    continue;
+                const below = runtime.validateParams(cmd.params, { ...base, [p.name]: p.min - 1 });
+                check(below !== null && below.startsWith('ERR_PARAM_RANGE'), `param gate rejects '${cmd.name}' ${p.name}=${p.min - 1}`, below ?? 'accepted');
+                const above = runtime.validateParams(cmd.params, { ...base, [p.name]: p.max + 1 });
+                check(above !== null && above.startsWith('ERR_PARAM_RANGE'), `param gate rejects '${cmd.name}' ${p.name}=${p.max + 1}`, above ?? 'accepted');
+                const atMin = runtime.validateParams(cmd.params, { ...base, [p.name]: p.min });
+                const atMax = runtime.validateParams(cmd.params, { ...base, [p.name]: p.max });
+                check(atMin === null && atMax === null, `param gate accepts '${cmd.name}' ${p.name} at [${p.min}, ${p.max}]`, atMin ?? atMax ?? undefined);
+            }
+        }
+        for (const [name, params] of Object.entries(spec.commands ?? {})) {
+            const label = `command '${name}' executes with sample params`;
+            const cmd = commands.find((c) => c.name === name);
+            const handler = instance.commands.get(name);
+            if (!cmd || !handler) {
+                check(false, label, 'not declared in contract');
+                continue;
+            }
+            const gate = runtime.validateParams(cmd.params, params);
+            if (gate !== null) {
+                check(false, label, gate);
+                continue;
+            }
+            try {
+                await withDeadline(() => handler(params), timeoutMs, label);
+                check(true, label);
+            }
+            catch (error) {
+                check(false, label, message(error));
+            }
+        }
+        // The worker is reachable on its own RPC key, so each handler must reject
+        // bad input itself, not lean on the Kernel's gate.
+        for (const cmd of commands) {
+            const p = (cmd.params ?? []).find((q) => q.type === 'number' && typeof q.min === 'number');
+            if (!p)
+                continue;
+            const label = `command '${cmd.name}' itself rejects ${p.name}=${p.min - 1} with an ERR_*`;
+            // Otherwise valid params, so the handler rejects the bound, not a missing param.
+            const params = { ...baselineParams(cmd, spec.commands?.[cmd.name]), [p.name]: p.min - 1 };
+            await expectErr(() => instance.commands.get(cmd.name)(params), timeoutMs, label, check);
+        }
+        if (!spec.teardown) {
+            outcome.warnings.push('smoke: no teardown() in the smoke config — device-stopped behaviour not checked');
+            return outcome;
+        }
+        await stop();
+        const offline = new Set(spec.offlineTelemetry ?? []);
+        for (const name of offline) {
+            if (!telemetry.some((entry) => entry.name === name))
+                check(false, `offlineTelemetry '${name}' is a declared telemetry channel`);
+        }
+        for (const entry of telemetry) {
+            const read = () => instance.telemetry.get(entry.name)({});
+            if (offline.has(entry.name)) {
+                const label = `telemetry '${entry.name}' still returns a ${entry.type} from the worker's store when the device is stopped`;
+                const typeOk = TYPE_OK[entry.type ?? ''] ?? ((v) => v !== undefined);
+                try {
+                    const value = await withDeadline(read, timeoutMs, label);
+                    check(value !== undefined && typeOk(value), label, `returned ${JSON.stringify(value)}`);
+                }
+                catch (error) {
+                    check(false, label, message(error));
+                }
+            }
+            else if (entry.name === 'health') {
+                const label = `telemetry 'health' reports a non-OK status or fails with an ERR_* when the device is stopped`;
+                await expectErr(read, timeoutMs, label, check, (value) => isNonOkHealth(value));
+            }
+            else {
+                const label = `telemetry '${entry.name}' fails with an ERR_* when the device is stopped`;
+                await expectErr(read, timeoutMs, label, check);
+            }
+        }
+        for (const [name, params] of Object.entries(spec.commands ?? {})) {
+            const handler = instance.commands.get(name);
+            if (!handler)
+                continue;
+            const label = `command '${name}' fails with an ERR_* when the device is stopped`;
+            await expectErr(() => handler(params), timeoutMs, label, check);
+        }
+        return outcome;
+    }
+    finally {
+        await stop().catch(() => { });
+    }
+}
+async function expectErr(run, timeoutMs, label, check, 
+/** A resolved value that also counts as failing correctly. */
+acceptResolved) {
+    try {
+        const value = await withDeadline(run, timeoutMs, label);
+        check(acceptResolved?.(value) ?? false, label, `resolved with ${JSON.stringify(value)}`);
+    }
+    catch (error) {
+        const text = message(error);
+        check(/(^|: )ERR_[A-Z_]+/.test(text) && !text.startsWith('ERR_SMOKE_TIMEOUT'), label, text);
+    }
+}
+/** A health verdict that says the device is not fine: `{ status }` with any value but OK. */
+function isNonOkHealth(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const { status } = value;
+    return typeof status === 'string' && status !== '' && status !== 'OK';
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=worker-smoke.js.map

package/dist/lib/worker-smoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-smoke.js","sourceRoot":"","sources":["../../src/lib/worker-smoke.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync } from 'node:fs';\nimport { createRequire } from 'node:module';\nimport { isAbsolute, join, resolve } from 'node:path';\n\nconst require = createRequire(import.meta.url);\n\nconst TYPE_OK: Record<string, (v: unknown) => boolean> = {\n  number: (v) => typeof v === 'number' && Number.isFinite(v),\n  string: (v) => typeof v === 'string',\n  boolean: (v) => typeof v === 'boolean',\n  array: (v) => Array.isArray(v),\n  object: (v) => typeof v === 'object' && v !== null && !Array.isArray(v),\n};\n\ninterface ContractParam {\n  name: string;\n  type?: string;\n  required?: boolean;\n  enum?: unknown[];\n  min?: number;\n  max?: number;\n}\n\ninterface ContractEntry {\n  name: string;\n  type?: string;\n  params?: ContractParam[];\n}\n\ninterface MdkWorkerRuntime {\n  loadContract(dir: string): {\n    dir: string;\n    contract: {\n      metadata: { brand?: string; deviceFamily?: string };\n      capabilities: { telemetry?: ContractEntry[]; commands?: ContractEntry[] };\n    };\n    entries: { telemetry: Map<string, string>; commands: Map<string, string> };\n  };\n  createInstance(opts: {\n    dir: string;\n    entries: { telemetry: Map<string, string>; commands: Map<string, string> };\n    device: Record<string, unknown>;\n  }): { telemetry: Map<string, (params: object) => unknown>; commands: Map<string, (params: object) => unknown> };\n  validateParams(declared: ContractParam[] | undefined, params: object): string | null;\n}\n\n/** What smoke.config.js `setup()` resolves to: the mock device and how to reach it. */\ninterface SmokeSpec {\n  config?: Record<string, unknown>;\n  env?: Record<string, unknown>;\n  pluginConfig?: Record<string, unknown>;\n  /** Sample params per command name, executed against the mock. */\n  commands?: Record<string, object>;\n  /** Stops the mock device; its presence enables the device-stopped failure pass. */\n  teardown?: () => unknown;\n  /**\n   * Telemetry served from the worker's own store rather than the device (a\n   * `history` log, say), which keeps answering once it stops. These must still\n   * settle and return their declared type instead of failing with an ERR_*.\n   */\n  offlineTelemetry?: string[];\n}\n\nexport interface SmokeOutcome {\n  /** Checks that passed. */\n  passed: number;\n  /** One line per failed check. */\n  failures: string[];\n  /** Passes that could not run (no teardown to stop the mock with). */\n  warnings: string[];\n}\n\nfunction withDeadline<T>(run: () => T | Promise<T>, ms: number, label: string): Promise<T> {\n  return new Promise<T>((resolvePromise, rejectPromise) => {\n    // Deliberately not unref'd: against a hung handler this timer is the only\n    // handle on the event loop — unref it and node exits 0 before it fires.\n    const timer = setTimeout(() => rejectPromise(new Error(`ERR_SMOKE_TIMEOUT: ${label} did not settle within ${ms}ms`)), ms);\n    Promise.resolve()\n      .then(run)\n      .then(resolvePromise, rejectPromise)\n      .finally(() => clearTimeout(timer));\n  });\n}\n\n/** A value the runtime's param gate accepts for `p`, for params a probe is not about. */\nfunction gateValue(p: ContractParam): unknown {\n  if (Array.isArray(p.enum) && p.enum.length) return p.enum[0];\n  switch (p.type) {\n    case 'number':\n      return typeof p.min === 'number' ? p.min : typeof p.max === 'number' ? Math.min(p.max, 0) : 0;\n    case 'boolean':\n      return false;\n    case 'string':\n      return '';\n    default:\n      return {};\n  }\n}\n\n/**\n * A param set for `cmd` that passes its gate: the smoke config's sample when\n * it has one, every other required param filled with a valid value. The gate\n * checks params in declaration order and `required` before range, so a probe\n * that sends only the param under test fails on the first missing required\n * param instead of the bound it means to test. Optional params stay absent —\n * the gate skips them, and a filler value ('' / {} / false) could make the\n * handler reject for its own reasons, passing the self-rejection check for\n * the wrong one.\n */\nfunction baselineParams(cmd: ContractEntry, sample: object | undefined): Record<string, unknown> {\n  const filled = Object.fromEntries((cmd.params ?? []).filter((p) => p.required === true).map((p) => [p.name, gateValue(p)]));\n  return { ...filled, ...(sample ?? {}) };\n}\n\nasync function resolveSpec(workerDir: string, config: string | undefined): Promise<SmokeSpec> {\n  const requireFromWorker = createRequire(join(workerDir, 'noop.js'));\n  if (config) {\n    if (config.trim().startsWith('{')) return { config: JSON.parse(config) };\n    const file = isAbsolute(config) ? config : resolve(config);\n    if (file.endsWith('.json')) return { config: JSON.parse(readFileSync(file, 'utf8')) };\n    const mod = requireFromWorker(file);\n    return mod.setup ? mod.setup() : { config: mod };\n  }\n  const smokeConfig = join(workerDir, 'smoke.config.js');\n  if (!existsSync(smokeConfig)) {\n    throw new Error(`ERR_SMOKE_NO_CONFIG: no --smoke-config given and no ${smokeConfig}`);\n  }\n  return requireFromWorker(smokeConfig).setup();\n}\n\n/**\n * Behavioural checks against the worker's own mock device — no Kernel, no DHT.\n * Live pass: every declared telemetry handler returns its declared type, the\n * runtime's param gate rejects out-of-range values, every smoke.config sample\n * command executes, and a handler called with an out-of-range param rejects\n * with an ERR_* of its own (the worker is reachable on its own RPC key, so it\n * must not rely on the Kernel's gate). Stopped pass, after `teardown()`: every\n * handler rejects with an ERR_* within the deadline — no hang, no crash, no\n * stale value. Two exceptions: a `health` channel may instead report a non-OK\n * status (its job is to say the device is down), and the smoke config's\n * `offlineTelemetry` channels must return their declared type. Every handler\n * call is bounded by `timeoutMs`.\n */\nexport async function runWorkerSmoke(workerDir: string, opts: { config?: string; timeoutMs?: number } = {}): Promise<SmokeOutcome> {\n  const timeoutMs = opts.timeoutMs ?? 10_000;\n  const outcome: SmokeOutcome = { passed: 0, failures: [], warnings: [] };\n  const check = (ok: boolean, label: string, detail?: string): void => {\n    if (ok) outcome.passed++;\n    else outcome.failures.push(`smoke: ${label}${detail ? ` — ${detail}` : ''}`);\n  };\n\n  const runtime = require('@tetherto/mdk-worker') as MdkWorkerRuntime;\n  const pluginDir = existsSync(join(workerDir, 'plugin', 'mdk-contract.json')) ? join(workerDir, 'plugin') : workerDir;\n  const { contract, entries, dir } = runtime.loadContract(pluginDir);\n  const spec = await resolveSpec(workerDir, opts.config);\n\n  // setup() has started the mock: stop it however the checks end, or its open\n  // socket keeps the process alive after a handler fails to load.\n  let stopped = false;\n  const stop = async (): Promise<void> => {\n    if (stopped || !spec.teardown) return;\n    stopped = true;\n    await withDeadline(() => spec.teardown!(), timeoutMs, 'teardown()');\n  };\n\n  try {\n    const instance = runtime.createInstance({\n      dir,\n      entries,\n      device: {\n        id: 'smoke-0',\n        opts: Object.freeze({ ...(spec.config ?? {}) }),\n        env: Object.freeze({ ...(spec.env ?? {}) }),\n        config: Object.freeze({ ...(spec.pluginConfig ?? {}) }),\n        workerId: 'smoke',\n        logger: () => {},\n      },\n    });\n\n    const telemetry = contract.capabilities.telemetry ?? [];\n    const commands = contract.capabilities.commands ?? [];\n\n    for (const entry of telemetry) {\n      const label = `telemetry '${entry.name}' returns a ${entry.type}`;\n      const typeOk = TYPE_OK[entry.type ?? ''] ?? ((v: unknown) => v !== undefined);\n      try {\n        const value = await withDeadline(() => instance.telemetry.get(entry.name)!({}), timeoutMs, label);\n        check(value !== undefined && typeOk(value), label, value === undefined ? 'returned undefined' : `returned ${JSON.stringify(value)}`);\n      } catch (error) {\n        check(false, label, message(error));\n      }\n    }\n\n    for (const cmd of commands) {\n      const base = baselineParams(cmd, spec.commands?.[cmd.name]);\n      for (const p of cmd.params ?? []) {\n        if (p.type !== 'number' || typeof p.min !== 'number' || typeof p.max !== 'number') continue;\n        const below = runtime.validateParams(cmd.params, { ...base, [p.name]: p.min - 1 });\n        check(below !== null && below.startsWith('ERR_PARAM_RANGE'), `param gate rejects '${cmd.name}' ${p.name}=${p.min - 1}`, below ?? 'accepted');\n        const above = runtime.validateParams(cmd.params, { ...base, [p.name]: p.max + 1 });\n        check(above !== null && above.startsWith('ERR_PARAM_RANGE'), `param gate rejects '${cmd.name}' ${p.name}=${p.max + 1}`, above ?? 'accepted');\n        const atMin = runtime.validateParams(cmd.params, { ...base, [p.name]: p.min });\n        const atMax = runtime.validateParams(cmd.params, { ...base, [p.name]: p.max });\n        check(atMin === null && atMax === null, `param gate accepts '${cmd.name}' ${p.name} at [${p.min}, ${p.max}]`, atMin ?? atMax ?? undefined);\n      }\n    }\n\n    for (const [name, params] of Object.entries(spec.commands ?? {})) {\n      const label = `command '${name}' executes with sample params`;\n      const cmd = commands.find((c) => c.name === name);\n      const handler = instance.commands.get(name);\n      if (!cmd || !handler) {\n        check(false, label, 'not declared in contract');\n        continue;\n      }\n      const gate = runtime.validateParams(cmd.params, params);\n      if (gate !== null) {\n        check(false, label, gate);\n        continue;\n      }\n      try {\n        await withDeadline(() => handler(params), timeoutMs, label);\n        check(true, label);\n      } catch (error) {\n        check(false, label, message(error));\n      }\n    }\n\n    // The worker is reachable on its own RPC key, so each handler must reject\n    // bad input itself, not lean on the Kernel's gate.\n    for (const cmd of commands) {\n      const p = (cmd.params ?? []).find((q) => q.type === 'number' && typeof q.min === 'number');\n      if (!p) continue;\n      const label = `command '${cmd.name}' itself rejects ${p.name}=${p.min! - 1} with an ERR_*`;\n      // Otherwise valid params, so the handler rejects the bound, not a missing param.\n      const params = { ...baselineParams(cmd, spec.commands?.[cmd.name]), [p.name]: p.min! - 1 };\n      await expectErr(() => instance.commands.get(cmd.name)!(params), timeoutMs, label, check);\n    }\n\n    if (!spec.teardown) {\n      outcome.warnings.push('smoke: no teardown() in the smoke config — device-stopped behaviour not checked');\n      return outcome;\n    }\n    await stop();\n\n    const offline = new Set(spec.offlineTelemetry ?? []);\n    for (const name of offline) {\n      if (!telemetry.some((entry) => entry.name === name)) check(false, `offlineTelemetry '${name}' is a declared telemetry channel`);\n    }\n    for (const entry of telemetry) {\n      const read = (): unknown => instance.telemetry.get(entry.name)!({});\n      if (offline.has(entry.name)) {\n        const label = `telemetry '${entry.name}' still returns a ${entry.type} from the worker's store when the device is stopped`;\n        const typeOk = TYPE_OK[entry.type ?? ''] ?? ((v: unknown) => v !== undefined);\n        try {\n          const value = await withDeadline(read, timeoutMs, label);\n          check(value !== undefined && typeOk(value), label, `returned ${JSON.stringify(value)}`);\n        } catch (error) {\n          check(false, label, message(error));\n        }\n      } else if (entry.name === 'health') {\n        const label = `telemetry 'health' reports a non-OK status or fails with an ERR_* when the device is stopped`;\n        await expectErr(read, timeoutMs, label, check, (value) => isNonOkHealth(value));\n      } else {\n        const label = `telemetry '${entry.name}' fails with an ERR_* when the device is stopped`;\n        await expectErr(read, timeoutMs, label, check);\n      }\n    }\n    for (const [name, params] of Object.entries(spec.commands ?? {})) {\n      const handler = instance.commands.get(name);\n      if (!handler) continue;\n      const label = `command '${name}' fails with an ERR_* when the device is stopped`;\n      await expectErr(() => handler(params), timeoutMs, label, check);\n    }\n\n    return outcome;\n  } finally {\n    await stop().catch(() => {});\n  }\n}\n\nasync function expectErr(\n  run: () => unknown,\n  timeoutMs: number,\n  label: string,\n  check: (ok: boolean, label: string, detail?: string) => void,\n  /** A resolved value that also counts as failing correctly. */\n  acceptResolved?: (value: unknown) => boolean,\n): Promise<void> {\n  try {\n    const value = await withDeadline(run, timeoutMs, label);\n    check(acceptResolved?.(value) ?? false, label, `resolved with ${JSON.stringify(value)}`);\n  } catch (error) {\n    const text = message(error);\n    check(/(^|: )ERR_[A-Z_]+/.test(text) && !text.startsWith('ERR_SMOKE_TIMEOUT'), label, text);\n  }\n}\n\n/** A health verdict that says the device is not fine: `{ status }` with any value but OK. */\nfunction isNonOkHealth(value: unknown): boolean {\n  if (typeof value !== 'object' || value === null) return false;\n  const { status } = value as { status?: unknown };\n  return typeof status === 'string' && status !== '' && status !== 'OK';\n}\n\nfunction message(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"]}

package/dist/program.js

@@ -0,0 +1,58 @@
+import { Command } from 'commander';
+import { pkg } from './lib/pkg.js';
+import { configureHelp, examples } from './lib/help.js';
+import { registerOnboard } from './commands/onboard.js';
+import { registerCreate } from './commands/create.js';
+import { registerAdd } from './commands/add.js';
+import { registerValidate } from './commands/validate.js';
+import { registerRun } from './commands/run.js';
+import { registerStatus } from './commands/inspect.js';
+import { registerSkill } from './commands/agent.js';
+import { registerVersion } from './commands/meta.js';
+/** The help heading each top-level command is listed under. */
+const HELP_GROUPS = {
+    onboard: 'Set up:',
+    create: 'Build:',
+    add: 'Build:',
+    validate: 'Build:',
+    run: 'Run:',
+    status: 'Run:',
+    skill: 'Other:',
+    version: 'Other:',
+};
+/**
+ * Builds the full `mdk` command tree. Every command reads `mdk <verb> [noun]`.
+ *
+ * `onboard`, `create`, `add`, `validate`, `run`, `status`, `skill add` and
+ * `version` are implemented.
+ */
+export function buildProgram() {
+    const program = configureHelp(new Command());
+    program
+        .name('mdk')
+        .usage('<command> [options]')
+        .description('Build, run and check an MDK stack: workers, apps, the Kernel and the Gateway.')
+        .version(pkg.version, '--version', 'Print the CLI version')
+        .option('-o, --output <fmt>', 'Output format for data: table | json | yaml', 'table')
+        .option('-v, --verbose', 'Increase log detail', false)
+        .option('--debug', 'Print stack traces for unexpected failures', false)
+        .showHelpAfterError();
+    registerOnboard(program);
+    registerCreate(program);
+    registerAdd(program);
+    registerValidate(program);
+    registerRun(program);
+    registerStatus(program);
+    registerSkill(program);
+    registerVersion(program);
+    for (const command of program.commands) {
+        const group = HELP_GROUPS[command.name()];
+        if (group)
+            command.helpGroup(group);
+    }
+    // Its own instance: the one the subcommands inherited stays under their `Commands:`.
+    program.addHelpCommand(new Command('help').argument('[command]').description('Show help for a command').helpGroup('Other:'));
+    program.addHelpText('after', examples('mdk onboard                              # new project: writes mdk.yaml', 'mdk create app ops-center                # scaffold an app into apps/ops-center', 'mdk add worker @your-org/mdk-worker-rig      # install a worker from npm', 'mdk validate app ops-center              # check it before publishing', 'mdk run                                  # start the Kernel, workers, apps and Gateway') + '\nRun `mdk <command> --help` for the options of a command.\n');
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,+DAA+D;AAC/D,MAAM,WAAW,GAA2B;IAC1C,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,QAAQ;IACb,QAAQ,EAAE,QAAQ;IAClB,GAAG,EAAE,MAAM;IACX,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,QAAQ;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IAE7C,OAAO;SACJ,IAAI,CAAC,KAAK,CAAC;SACX,KAAK,CAAC,qBAAqB,CAAC;SAC5B,WAAW,CAAC,+EAA+E,CAAC;SAC5F,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,uBAAuB,CAAC;SAC1D,MAAM,CAAC,oBAAoB,EAAE,6CAA6C,EAAE,OAAO,CAAC;SACpF,MAAM,CAAC,eAAe,EAAE,qBAAqB,EAAE,KAAK,CAAC;SACrD,MAAM,CAAC,SAAS,EAAE,4CAA4C,EAAE,KAAK,CAAC;SACtE,kBAAkB,EAAE,CAAC;IAExB,eAAe,CAAC,OAAO,CAAC,CAAC;IACzB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,WAAW,CAAC,OAAO,CAAC,CAAC;IACrB,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC1B,WAAW,CAAC,OAAO,CAAC,CAAC;IACrB,cAAc,CAAC,OAAO,CAAC,CAAC;IACxB,aAAa,CAAC,OAAO,CAAC,CAAC;IACvB,eAAe,CAAC,OAAO,CAAC,CAAC;IAEzB,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1C,IAAI,KAAK;YAAE,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IACD,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE7H,OAAO,CAAC,WAAW,CACjB,OAAO,EACP,QAAQ,CACN,yEAAyE,EACzE,iFAAiF,EACjF,0EAA0E,EAC1E,uEAAuE,EACvE,wFAAwF,CACzF,GAAG,8DAA8D,CACnE,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import { Command } from 'commander';\nimport { pkg } from './lib/pkg.js';\nimport { configureHelp, examples } from './lib/help.js';\nimport { registerOnboard } from './commands/onboard.js';\nimport { registerCreate } from './commands/create.js';\nimport { registerAdd } from './commands/add.js';\nimport { registerValidate } from './commands/validate.js';\nimport { registerRun } from './commands/run.js';\nimport { registerStatus } from './commands/inspect.js';\nimport { registerSkill } from './commands/agent.js';\nimport { registerVersion } from './commands/meta.js';\n\n/** The help heading each top-level command is listed under. */\nconst HELP_GROUPS: Record<string, string> = {\n  onboard: 'Set up:',\n  create: 'Build:',\n  add: 'Build:',\n  validate: 'Build:',\n  run: 'Run:',\n  status: 'Run:',\n  skill: 'Other:',\n  version: 'Other:',\n};\n\n/**\n * Builds the full `mdk` command tree. Every command reads `mdk <verb> [noun]`.\n *\n * `onboard`, `create`, `add`, `validate`, `run`, `status`, `skill add` and\n * `version` are implemented.\n */\nexport function buildProgram(): Command {\n  const program = configureHelp(new Command());\n\n  program\n    .name('mdk')\n    .usage('<command> [options]')\n    .description('Build, run and check an MDK stack: workers, apps, the Kernel and the Gateway.')\n    .version(pkg.version, '--version', 'Print the CLI version')\n    .option('-o, --output <fmt>', 'Output format for data: table | json | yaml', 'table')\n    .option('-v, --verbose', 'Increase log detail', false)\n    .option('--debug', 'Print stack traces for unexpected failures', false)\n    .showHelpAfterError();\n\n  registerOnboard(program);\n  registerCreate(program);\n  registerAdd(program);\n  registerValidate(program);\n  registerRun(program);\n  registerStatus(program);\n  registerSkill(program);\n  registerVersion(program);\n\n  for (const command of program.commands) {\n    const group = HELP_GROUPS[command.name()];\n    if (group) command.helpGroup(group);\n  }\n  // Its own instance: the one the subcommands inherited stays under their `Commands:`.\n  program.addHelpCommand(new Command('help').argument('[command]').description('Show help for a command').helpGroup('Other:'));\n\n  program.addHelpText(\n    'after',\n    examples(\n      'mdk onboard                              # new project: writes mdk.yaml',\n      'mdk create app ops-center                # scaffold an app into apps/ops-center',\n      'mdk add worker @your-org/mdk-worker-rig      # install a worker from npm',\n      'mdk validate app ops-center              # check it before publishing',\n      'mdk run                                  # start the Kernel, workers, apps and Gateway',\n    ) + '\\nRun `mdk <command> --help` for the options of a command.\\n',\n  );\n\n  return program;\n}\n"]}

package/package.json

@@ -1 +1,59 @@
-{"name":"@tetherto/mdk-cli","version":"0.0.0"}
+{
+  "name": "@tetherto/mdk-cli",
+  "version": "0.12.1",
+  "description": "MDK command-line tool: onboard, scaffold, run and inspect an MDK stack.",
+  "type": "module",
+  "bin": {
+    "mdk": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:stack": "vitest run --config vitest.e2e.config.ts tests/e2e/stack.e2e.ts tests/e2e/split.e2e.ts",
+    "test:e2e:scaffold": "vitest run --config vitest.e2e.config.ts tests/e2e/scaffold.e2e.ts",
+    "prepack": "npm run clean && npm run build"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@tetherto/mdk-app-runtime": "^0.12.1",
+    "@tetherto/mdk-client": "^0.12.1",
+    "@tetherto/mdk-core": "^0.12.1",
+    "@tetherto/mdk-gateway": "^0.12.1",
+    "@tetherto/mdk-mcp": "^0.12.1",
+    "@tetherto/mdk-skill": "^0.12.1",
+    "@tetherto/mdk-worker": "^0.12.1",
+    "commander": "^15.0.0",
+    "degit": "^3.6.6",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tetherto/mdk.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/app/README.md

@@ -0,0 +1,66 @@
+# __PLUGIN_NAME__
+
+An MDK **app** — HTTP endpoints that aggregate data from your workers'
+devices over the MDK protocol. An app is an app manifest ([`mdk-app.yaml`](./mdk-app.yaml))
+plus its plugin: a route manifest ([`plugin/mdk-plugin.json`](./plugin/mdk-plugin.json)) and one controller module per route;
+`mdk run` runs it in its own process and the Gateway forwards each route to it. There is no root export.
+
+## Layout
+
+```
+mdk-app.yaml                # app manifest: id, version, displayName, permissions, config defaults
+plugin/mdk-plugin.json      # route manifest: id, handler, http.method + http.path
+plugin/lib/client.js        # ambient MDK client from @tetherto/mdk-gateway/plugin
+plugin/controllers/*.js     # one module per route: async (req) => result
+```
+
+Each controller receives `req` (`{ params, query, body, headers }`). Talk to
+the Kernel through the plugin-owned client in `plugin/lib/client.js`, which is built
+from the ambient import override:
+
+```js
+const { config } = require('@tetherto/mdk-gateway/plugin')
+const { createMdkClient } = require('@tetherto/mdk-client')
+module.exports = createMdkClient(config)
+```
+
+The app runtime freezes a per-plugin context onto
+`@tetherto/mdk-gateway/plugin` (same pattern as `backend/apps/agent`), so
+`config` already includes `kernelKey` / `kernelBootstrap` plus the `config`
+defaults in `mdk-app.yaml`, overridden by this app's `spec.apps[].config`
+block. Controllers do **not** take `mdkClient` from a `services` parameter.
+
+The return value is sent as JSON (HTTP 200), so return plain data: a `Buffer` would arrive as its JSON form. Throw
+`Error('ERR_...')` to return a 400.
+
+Mark a route that only reads with `"safety": "read-only"`: `mdk run mcp` turns routes into agent tools and
+withholds every other one as a write unless it is started with `--allow-write`. Mark a route that changes
+devices with `"safety": "write"`.
+
+Routes are open by default. Add `"auth": true` to a route to require a caller
+identity: the Gateway then refuses it (401) unless an auth verifier is configured
+and accepts the request.
+
+## Run it
+
+This app is registered in your stack's `mdk.yaml` under `spec.apps` by
+**package name** and resolved from `node_modules` (a `file:` dependency in the project's `package.json` links it):
+
+```yaml
+spec:
+  apps:
+    - name: __PLUGIN_APP__
+      package: __PACKAGE_NAME__
+      config: {}
+```
+
+Then boot the stack:
+
+```bash
+mdk run             # Kernel, workers, this app and the Gateway together
+# or run the app on its own next to `mdk run kernel` and `mdk run gateway`:
+mdk run app __PLUGIN_APP__
+```
+
+Call it: `GET http://localhost:<gatewayPort>/apps/__PLUGIN_APP__/api/__PLUGIN_NAME__/summary`
+(set `mount` on the app entry to serve it under another prefix).

package/templates/app/mdk-app.yaml

@@ -0,0 +1,10 @@
+# The app manifest `mdk run` reads; `plugin/mdk-plugin.json` holds the route table.
+id: com.example.__PLUGIN_APP__
+version: 0.1.0
+displayName: "__PLUGIN_NAME__"
+# What the app asks the operator to approve, e.g.
+#   - resources: [workers, devices]
+#     verbs: [list, read]
+permissions: []
+# Defaults for the app's settings, overridden by its `config` in mdk.yaml.
+config: {}

package/templates/app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "__PLUGIN_NAME__",
+  "version": "0.12.1",
+  "private": true,
+  "description": "MDK app (mdk-app.yaml + plugin/ route manifest and controllers). Run by `mdk run` behind the Gateway — it serves HTTP endpoints that aggregate worker telemetry over the MDK protocol.",
+  "keywords": [
+    "mdk",
+    "mdk-app"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@tetherto/mdk-client": "^0.12.1"
+  }
+}

package/templates/app/plugin/controllers/summary.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const mdkClient = require('../lib/client')
+
+// A read-only aggregation endpoint: it asks the Kernel (through the plugin's
+// ambient MDK client) for the fleet and returns a small summary. Replace this
+// with your own aggregation, grounded in the telemetry channels your workers
+// expose.
+//
+// Contract: `async (req) => result`. The return value is sent as JSON
+// (HTTP 200). Throw `Error('ERR_...')` to return a 400.
+module.exports = async function summary (req) {
+  // createMdkClient fails per request (ERR_MDK_CLIENT_UNAVAILABLE) when the
+  // Gateway has no Kernel key / connection — report that instead of failing
+  // so the route stays callable during boot.
+  let workers
+  try {
+    const resp = await mdkClient.listWorkers()
+    workers = (resp && resp.workers) || []
+  } catch (err) {
+    if (err && err.code === 'ERR_MDK_CLIENT_UNAVAILABLE') {
+      return { ok: true, kernelConnected: false, workerCount: 0, deviceCount: 0, workers: [] }
+    }
+    throw err
+  }
+
+  const deviceCount = workers.reduce((n, w) => n + ((w.deviceIds && w.deviceIds.length) || 0), 0)
+
+  return {
+    ok: true,
+    kernelConnected: true,
+    workerCount: workers.length,
+    deviceCount,
+    workers: workers.map((w) => ({ workerId: w.workerId, devices: (w.deviceIds || []).length }))
+  }
+}

package/templates/app/plugin/lib/client.js

@@ -0,0 +1,11 @@
+'use strict'
+
+// Plugin-owned MDK client, built from the ambient gateway context. The loader
+// overrides `require('@tetherto/mdk-gateway/plugin')` per plugin (same pattern
+// as backend/apps/agent) so `config` carries this plugin's merged settings
+// including kernelKey / kernelBootstrap. Controllers import this module —
+// they never take mdkClient from a services bag.
+const { config } = require('@tetherto/mdk-gateway/plugin')
+const { createMdkClient } = require('@tetherto/mdk-client')
+
+module.exports = createMdkClient(config)

package/templates/app/plugin/mdk-plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "__PLUGIN_NAME__",
+  "version": "0.1.0",
+  "description": "MDK app plugin — HTTP endpoints that aggregate worker telemetry.",
+  "routes": [
+    {
+      "id": "__PLUGIN_NAME__.summary",
+      "handler": "./controllers/summary.js",
+      "safety": "read-only",
+      "http": {
+        "method": "GET",
+        "path": "/api/__PLUGIN_NAME__/summary"
+      }
+    }
+  ]
+}

package/templates/app-ui/tsconfig.json

@@ -0,0 +1,29 @@
+// Editor-only: lets you edit the starter UI in an MDK checkout without errors.
+// `mdk create app` copies only ui-src/, and writes the app's own tsconfig there.
+// The MDK packages resolve to this checkout's built ui/packages (npm run build in ui/).
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "typeRoots": ["../../../../ui/node_modules/@types"],
+    "paths": {
+      "@tetherto/mdk-ui-foundation": ["../../../../ui/packages/ui-foundation/dist/index.d.ts"],
+      "@tetherto/mdk-ui-foundation/app-shared-modules": ["../../../../ui/packages/ui-foundation/dist/apps/shared-modules.d.ts"],
+      "@tetherto/mdk-react-adapter": ["../../../../ui/packages/react-adapter/dist/index.d.ts"],
+      "@tetherto/mdk-react-devkit": ["../../../../ui/packages/react-devkit/dist/index.d.ts"],
+      "react": ["../../../../ui/node_modules/@types/react"],
+      "react/*": ["../../../../ui/node_modules/@types/react/*"],
+      "vite": ["../../../../ui/node_modules/vite"],
+      "@vitejs/plugin-react": ["../../../../ui/node_modules/@vitejs/plugin-react/dist/index.d.ts"]
+    }
+  },
+  "include": ["ui-src"]
+}