@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/lib/status.js

@@ -0,0 +1,245 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { detectEnvironment, NODE_MIN_MAJOR } from './detect.js';
+import { StackSpecError, loadStackSpec, STACK_FILE } from './spec.js';
+import { kernelKeyFile, localDiscovery, mdkDir, resolvePackageDir, trustedKeysDir } from './runtime.js';
+import { appChildPid, isAlive, lockHolder } from './run-lock.js';
+const require = createRequire(import.meta.url);
+function mdkClientModule() {
+    return require('@tetherto/mdk-client');
+}
+const NODE_REQUIRED = `>=${NODE_MIN_MAJOR}`;
+const GATEWAY_TIMEOUT_MS = 1500;
+const KERNEL_TIMEOUT_MS = 3000;
+/** True when `pkg` resolves the way `mdk run` resolves it (subpaths and local paths included). */
+function isResolvable(projectDir, pkg) {
+    try {
+        resolvePackageDir(projectDir, pkg);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probes the Gateway over HTTP.
+ *
+ * A Gateway serves only the routes `mdk.yaml` declares and has no built-in route
+ * (no `/echo`), so no one path is there on every stack. Any answer below 500
+ * from `/`, a 404 included, means the Gateway is serving.
+ */
+async function probeGateway(port) {
+    const url = `http://127.0.0.1:${port}`;
+    try {
+        const res = await fetch(`${url}/`, {
+            signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS),
+        });
+        if (res.status >= 500)
+            return { state: 'down', url, error: `HTTP ${res.status}` };
+        return { state: 'up', url, error: null };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // A refused connection is the normal "not running" case, not a fault.
+        return { state: 'down', url, error: /ECONNREFUSED|fetch failed/i.test(message) ? null : message };
+    }
+}
+/**
+ * Probes the Kernel over HRPC using the published key file, returning its live
+ * worker registry. The client owns its own DHT node, so it is always closed.
+ */
+async function probeKernel(projectDir) {
+    const keyFile = kernelKeyFile(projectDir);
+    if (!existsSync(keyFile)) {
+        return {
+            kernel: { state: 'down', keyFile, key: null, error: null },
+            status: null,
+        };
+    }
+    let key;
+    try {
+        key = readFileSync(keyFile, 'utf8').trim();
+    }
+    catch (error) {
+        return {
+            kernel: {
+                state: 'down',
+                keyFile,
+                key: null,
+                error: error instanceof Error ? error.message : String(error),
+            },
+            status: null,
+        };
+    }
+    let client;
+    try {
+        const discovery = localDiscovery();
+        const kernelKeyPair = discovery.callerKeyPair(join(mdkDir(projectDir), 'cli', 'identity'));
+        discovery.publishTrustedKey(trustedKeysDir(projectDir), 'cli', kernelKeyPair.publicKey);
+        client = mdkClientModule().createMdkClient({ kernelKey: key, kernelKeyPair });
+    }
+    catch (error) {
+        return {
+            kernel: { state: 'down', keyFile, key, error: error instanceof Error ? error.message : String(error) },
+            status: null,
+        };
+    }
+    try {
+        // A newly published key is admitted once the Kernel's trusted-keys watcher sees it.
+        await client.connect({ warmup: true });
+        const status = await client.getStatus({ retries: 1, timeoutMs: KERNEL_TIMEOUT_MS });
+        return { kernel: { state: 'up', keyFile, key, error: null }, status };
+    }
+    catch (error) {
+        return {
+            kernel: {
+                state: 'down',
+                keyFile,
+                key,
+                error: error instanceof Error ? error.message : String(error),
+            },
+            status: null,
+        };
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+/** Merges the workers declared in the spec with the Kernel's live registry. */
+function buildWorkers(spec, status) {
+    const declared = spec ? spec.spec.workers.map((w) => w.name) : [];
+    const registered = new Map((status?.workers ?? []).map((w) => [w.workerId, w]));
+    const items = declared.map((name) => {
+        const live = registered.get(name);
+        return {
+            name,
+            declared: true,
+            registered: live != null,
+            state: live?.state ?? null,
+            health: live?.healthState ?? null,
+            devices: live?.deviceCount ?? live?.deviceIds?.length ?? 0,
+        };
+    });
+    // Workers the Kernel knows about that the spec does not — surfaced rather than
+    // hidden, since they are real processes serving traffic.
+    for (const [workerId, live] of registered) {
+        if (declared.includes(workerId))
+            continue;
+        items.push({
+            name: workerId,
+            declared: false,
+            registered: true,
+            state: live.state ?? null,
+            health: live.healthState ?? null,
+            devices: live.deviceCount ?? live.deviceIds?.length ?? 0,
+        });
+    }
+    return {
+        declared: declared.length,
+        registered: registered.size,
+        totalDevices: status?.totalDevices ?? 0,
+        items,
+    };
+}
+function installedVersion(dir, pkg) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(resolvePackageDir(dir, pkg), 'package.json'), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildApps(dir, spec) {
+    const items = (spec?.spec.apps ?? []).map((a) => {
+        const holder = lockHolder(dir, { kind: 'app', name: a.name });
+        const child = holder === null ? undefined : appChildPid(dir, a.name);
+        const pid = child === undefined ? holder : isAlive(child) ? child : null;
+        return {
+            name: a.name,
+            package: a.package,
+            version: installedVersion(dir, a.package),
+            mount: a.mount ?? `/apps/${a.name}`,
+            running: pid !== null,
+            pid,
+        };
+    });
+    return { declared: items.length, running: items.filter((a) => a.running).length, items };
+}
+/** A worker counts as serving when the Kernel has it READY and not DEAD/SICK. */
+function workerServing(w) {
+    if (!w.registered)
+        return false;
+    if (w.state && w.state !== 'READY')
+        return false;
+    return !(w.health === 'DEAD' || w.health === 'SICK');
+}
+/** Collects the full status report for a project directory. */
+export async function collectStatus(projectDir) {
+    const dir = resolve(projectDir);
+    const env = detectEnvironment(dir);
+    // Spec ------------------------------------------------------------------
+    const specPath = resolve(dir, STACK_FILE);
+    let spec = null;
+    let specError = null;
+    try {
+        spec = loadStackSpec(dir);
+    }
+    catch (error) {
+        if (error instanceof StackSpecError)
+            specError = error.message;
+        else
+            throw error;
+    }
+    // Declared packages must resolve the way the runtime resolves them, or
+    // `mdk run` fails at boot — a precondition worth reporting up front.
+    const packages = spec
+        ? [
+            ...spec.spec.workers.map((w) => w.package),
+            ...spec.spec.apps.map((a) => a.package),
+        ]
+        : [];
+    const missing = packages.filter((p) => !isResolvable(dir, p));
+    const environment = {
+        node: { version: env.nodeVersion, ok: env.nodeOk, required: NODE_REQUIRED },
+        packageManager: env.packageManager,
+        git: env.git,
+        spec: {
+            found: existsSync(specPath),
+            path: specPath,
+            valid: spec != null,
+            error: specError,
+            stack: spec?.metadata.name ?? null,
+        },
+        dependencies: { ok: missing.length === 0, checked: packages.length, missing },
+    };
+    // Stack -----------------------------------------------------------------
+    const [{ kernel, status }, gateway] = await Promise.all([
+        probeKernel(dir),
+        spec
+            ? probeGateway(spec.spec.gateway.port)
+            : Promise.resolve({
+                state: 'down',
+                url: null,
+                error: `no ${STACK_FILE} — gateway port unknown`,
+            }),
+    ]);
+    const workers = buildWorkers(spec, status);
+    const apps = buildApps(dir, spec);
+    const stack = { kernel, gateway, workers, apps };
+    // Aggregate -------------------------------------------------------------
+    const envOk = environment.node.ok && environment.spec.valid && environment.dependencies.ok;
+    let health;
+    if (kernel.state === 'down') {
+        health = 'down';
+    }
+    else if (gateway.state === 'down' || !workers.items.every(workerServing) || apps.running < apps.declared) {
+        health = 'degraded';
+    }
+    else {
+        health = 'healthy';
+    }
+    return { project: dir, environment, stack, health, ok: envOk && health === 'healthy' };
+}
+//# sourceMappingURL=status.js.map

package/dist/lib/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/lib/status.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { detectEnvironment, NODE_MIN_MAJOR } from './detect.js';\nimport { StackSpecError, loadStackSpec, STACK_FILE, type StackSpec } from './spec.js';\nimport { kernelKeyFile, localDiscovery, mdkDir, resolvePackageDir, trustedKeysDir, type CallerKeyPair } from './runtime.js';\nimport { appChildPid, isAlive, lockHolder } from './run-lock.js';\n\nconst require = createRequire(import.meta.url);\n\n/**\n * Read-only state collection for `mdk status`. Nothing here starts, stops or\n * repairs anything: it inspects the environment, validates the spec, and probes\n * the running stack.\n *\n * The one write: the Kernel admits only known callers, so the Kernel probe dials\n * with a persistent CLI identity it publishes to the trusted-keys dir.\n *\n * An app runtime accepts calls from the Gateway's key only, so it cannot be\n * probed from here; an app counts as running while a live process holds its\n * run lock (see run-lock.ts).\n *\n * Liveness is deliberately probe-based, never file-based. Both `.mdk/kernel.key`\n * and `.mdk/keys/*.key` survive a shutdown by design (the keys are stable across\n * restarts), so their presence proves only that a component once ran. The Kernel\n * is therefore probed over HRPC and the Gateway over HTTP.\n */\n\n// --- @tetherto/mdk-client (typeless CommonJS, lazily required) --------------\n\ninterface RegisteredWorker {\n  workerId: string;\n  state?: string;\n  healthState?: string;\n  deviceIds?: string[];\n  deviceCount?: number;\n}\ninterface KernelStatus {\n  workers: RegisteredWorker[];\n  totalDevices: number;\n}\ninterface MdkClient {\n  connect(opts?: Record<string, unknown>): Promise<void>;\n  close(): Promise<void>;\n  getStatus(opts?: Record<string, unknown>): Promise<KernelStatus>;\n}\ninterface MdkClientModule {\n  /** Reads the Kernel key from `config.kernelKey`; without one every call fails with ERR_MDK_CLIENT_UNAVAILABLE. */\n  createMdkClient(config: { kernelKey: string; kernelKeyPair?: CallerKeyPair }): MdkClient;\n}\n\nfunction mdkClientModule(): MdkClientModule {\n  return require('@tetherto/mdk-client') as MdkClientModule;\n}\n\n// --- report shape (the `-o json|yaml` contract) ----------------------------\n\nexport type Health = 'healthy' | 'degraded' | 'down';\nexport type ComponentState = 'up' | 'down';\n\nexport interface EnvironmentReport {\n  node: { version: string; ok: boolean; required: string };\n  packageManager: string;\n  git: boolean;\n  spec: {\n    found: boolean;\n    path: string;\n    valid: boolean;\n    error: string | null;\n    stack: string | null;\n  };\n  dependencies: { ok: boolean; checked: number; missing: string[] };\n}\n\nexport interface WorkerReport {\n  name: string;\n  /** Listed in `spec.workers` (false = registered with the Kernel but not in the spec). */\n  declared: boolean;\n  /** Present in the Kernel's live worker registry. */\n  registered: boolean;\n  state: string | null;\n  health: string | null;\n  devices: number;\n}\n\nexport interface AppReport {\n  name: string;\n  package: string;\n  /** The installed package's version, or null when it is not installed. */\n  version: string | null;\n  /** Where the Gateway serves it. */\n  mount: string;\n  running: boolean;\n  /** The app's runtime process: the child `mdk run` supervises, or the `mdk run app <name>` process. */\n  pid: number | null;\n}\n\nexport interface StackReport {\n  kernel: { state: ComponentState; keyFile: string; key: string | null; error: string | null };\n  gateway: { state: ComponentState; url: string | null; error: string | null };\n  workers: {\n    declared: number;\n    registered: number;\n    totalDevices: number;\n    items: WorkerReport[];\n  };\n  apps: {\n    declared: number;\n    running: number;\n    items: AppReport[];\n  };\n}\n\nexport interface StatusReport {\n  project: string;\n  environment: EnvironmentReport;\n  stack: StackReport;\n  health: Health;\n  ok: boolean;\n}\n\nconst NODE_REQUIRED = `>=${NODE_MIN_MAJOR}`;\nconst GATEWAY_TIMEOUT_MS = 1500;\nconst KERNEL_TIMEOUT_MS = 3000;\n\n/** True when `pkg` resolves the way `mdk run` resolves it (subpaths and local paths included). */\nfunction isResolvable(projectDir: string, pkg: string): boolean {\n  try {\n    resolvePackageDir(projectDir, pkg);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Probes the Gateway over HTTP.\n *\n * A Gateway serves only the routes `mdk.yaml` declares and has no built-in route\n * (no `/echo`), so no one path is there on every stack. Any answer below 500\n * from `/`, a 404 included, means the Gateway is serving.\n */\nasync function probeGateway(port: number): Promise<{ state: ComponentState; url: string; error: string | null }> {\n  const url = `http://127.0.0.1:${port}`;\n  try {\n    const res = await fetch(`${url}/`, {\n      signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS),\n    });\n    if (res.status >= 500) return { state: 'down', url, error: `HTTP ${res.status}` };\n    return { state: 'up', url, error: null };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    // A refused connection is the normal \"not running\" case, not a fault.\n    return { state: 'down', url, error: /ECONNREFUSED|fetch failed/i.test(message) ? null : message };\n  }\n}\n\n/**\n * Probes the Kernel over HRPC using the published key file, returning its live\n * worker registry. The client owns its own DHT node, so it is always closed.\n */\nasync function probeKernel(\n  projectDir: string,\n): Promise<{ kernel: StackReport['kernel']; status: KernelStatus | null }> {\n  const keyFile = kernelKeyFile(projectDir);\n  if (!existsSync(keyFile)) {\n    return {\n      kernel: { state: 'down', keyFile, key: null, error: null },\n      status: null,\n    };\n  }\n\n  let key: string;\n  try {\n    key = readFileSync(keyFile, 'utf8').trim();\n  } catch (error) {\n    return {\n      kernel: {\n        state: 'down',\n        keyFile,\n        key: null,\n        error: error instanceof Error ? error.message : String(error),\n      },\n      status: null,\n    };\n  }\n\n  let client: MdkClient;\n  try {\n    const discovery = localDiscovery();\n    const kernelKeyPair = discovery.callerKeyPair(join(mdkDir(projectDir), 'cli', 'identity'));\n    discovery.publishTrustedKey(trustedKeysDir(projectDir), 'cli', kernelKeyPair.publicKey);\n    client = mdkClientModule().createMdkClient({ kernelKey: key, kernelKeyPair });\n  } catch (error) {\n    return {\n      kernel: { state: 'down', keyFile, key, error: error instanceof Error ? error.message : String(error) },\n      status: null,\n    };\n  }\n  try {\n    // A newly published key is admitted once the Kernel's trusted-keys watcher sees it.\n    await client.connect({ warmup: true });\n    const status = await client.getStatus({ retries: 1, timeoutMs: KERNEL_TIMEOUT_MS });\n    return { kernel: { state: 'up', keyFile, key, error: null }, status };\n  } catch (error) {\n    return {\n      kernel: {\n        state: 'down',\n        keyFile,\n        key,\n        error: error instanceof Error ? error.message : String(error),\n      },\n      status: null,\n    };\n  } finally {\n    await client.close().catch(() => {});\n  }\n}\n\n/** Merges the workers declared in the spec with the Kernel's live registry. */\nfunction buildWorkers(spec: StackSpec | null, status: KernelStatus | null): StackReport['workers'] {\n  const declared = spec ? spec.spec.workers.map((w) => w.name) : [];\n  const registered = new Map((status?.workers ?? []).map((w) => [w.workerId, w]));\n\n  const items: WorkerReport[] = declared.map((name) => {\n    const live = registered.get(name);\n    return {\n      name,\n      declared: true,\n      registered: live != null,\n      state: live?.state ?? null,\n      health: live?.healthState ?? null,\n      devices: live?.deviceCount ?? live?.deviceIds?.length ?? 0,\n    };\n  });\n\n  // Workers the Kernel knows about that the spec does not — surfaced rather than\n  // hidden, since they are real processes serving traffic.\n  for (const [workerId, live] of registered) {\n    if (declared.includes(workerId)) continue;\n    items.push({\n      name: workerId,\n      declared: false,\n      registered: true,\n      state: live.state ?? null,\n      health: live.healthState ?? null,\n      devices: live.deviceCount ?? live.deviceIds?.length ?? 0,\n    });\n  }\n\n  return {\n    declared: declared.length,\n    registered: registered.size,\n    totalDevices: status?.totalDevices ?? 0,\n    items,\n  };\n}\n\nfunction installedVersion(dir: string, pkg: string): string | null {\n  try {\n    const manifest = JSON.parse(readFileSync(join(resolvePackageDir(dir, pkg), 'package.json'), 'utf8')) as {\n      version?: unknown;\n    };\n    return typeof manifest.version === 'string' ? manifest.version : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction buildApps(dir: string, spec: StackSpec | null): StackReport['apps'] {\n  const items = (spec?.spec.apps ?? []).map((a): AppReport => {\n    const holder = lockHolder(dir, { kind: 'app', name: a.name });\n    const child = holder === null ? undefined : appChildPid(dir, a.name);\n    const pid = child === undefined ? holder : isAlive(child) ? child : null;\n    return {\n      name: a.name,\n      package: a.package,\n      version: installedVersion(dir, a.package),\n      mount: a.mount ?? `/apps/${a.name}`,\n      running: pid !== null,\n      pid,\n    };\n  });\n  return { declared: items.length, running: items.filter((a) => a.running).length, items };\n}\n\n/** A worker counts as serving when the Kernel has it READY and not DEAD/SICK. */\nfunction workerServing(w: WorkerReport): boolean {\n  if (!w.registered) return false;\n  if (w.state && w.state !== 'READY') return false;\n  return !(w.health === 'DEAD' || w.health === 'SICK');\n}\n\n/** Collects the full status report for a project directory. */\nexport async function collectStatus(projectDir: string): Promise<StatusReport> {\n  const dir = resolve(projectDir);\n  const env = detectEnvironment(dir);\n\n  // Spec ------------------------------------------------------------------\n  const specPath = resolve(dir, STACK_FILE);\n  let spec: StackSpec | null = null;\n  let specError: string | null = null;\n  try {\n    spec = loadStackSpec(dir);\n  } catch (error) {\n    if (error instanceof StackSpecError) specError = error.message;\n    else throw error;\n  }\n\n  // Declared packages must resolve the way the runtime resolves them, or\n  // `mdk run` fails at boot — a precondition worth reporting up front.\n  const packages = spec\n    ? [\n        ...spec.spec.workers.map((w) => w.package),\n        ...spec.spec.apps.map((a) => a.package),\n      ]\n    : [];\n  const missing = packages.filter((p) => !isResolvable(dir, p));\n\n  const environment: EnvironmentReport = {\n    node: { version: env.nodeVersion, ok: env.nodeOk, required: NODE_REQUIRED },\n    packageManager: env.packageManager,\n    git: env.git,\n    spec: {\n      found: existsSync(specPath),\n      path: specPath,\n      valid: spec != null,\n      error: specError,\n      stack: spec?.metadata.name ?? null,\n    },\n    dependencies: { ok: missing.length === 0, checked: packages.length, missing },\n  };\n\n  // Stack -----------------------------------------------------------------\n  const [{ kernel, status }, gateway] = await Promise.all([\n    probeKernel(dir),\n    spec\n      ? probeGateway(spec.spec.gateway.port)\n      : Promise.resolve({\n          state: 'down' as ComponentState,\n          url: null,\n          error: `no ${STACK_FILE} — gateway port unknown`,\n        }),\n  ]);\n\n  const workers = buildWorkers(spec, status);\n  const apps = buildApps(dir, spec);\n  const stack: StackReport = { kernel, gateway, workers, apps };\n\n  // Aggregate -------------------------------------------------------------\n  const envOk = environment.node.ok && environment.spec.valid && environment.dependencies.ok;\n  let health: Health;\n  if (kernel.state === 'down') {\n    health = 'down';\n  } else if (gateway.state === 'down' || !workers.items.every(workerServing) || apps.running < apps.declared) {\n    health = 'degraded';\n  } else {\n    health = 'healthy';\n  }\n\n  return { project: dir, environment, stack, health, ok: envOk && health === 'healthy' };\n}\n"]}

package/dist/lib/theme.js

@@ -0,0 +1,50 @@
+import pc from 'picocolors';
+// Small palette so the CLI has a consistent, colorful look (OpenClaw-style).
+export const theme = {
+    brand: (s) => pc.cyan(pc.bold(s)),
+    accent: (s) => pc.magenta(s),
+    label: (s) => pc.bold(pc.white(s)),
+    ok: (s) => pc.green(s),
+    warn: (s) => pc.yellow(s),
+    muted: (s) => pc.dim(s),
+    key: (s) => pc.cyan(s),
+    value: (s) => pc.white(s),
+    cmd: (s) => pc.green(s),
+};
+// MDK brand orange (256-color 208), matching the logo. Falls back to plain
+// text when colors are unsupported (e.g. NO_COLOR or a non-TTY pipe).
+const orange = (s) => pc.isColorSupported ? `\x1b[38;5;208m${s}\x1b[39m` : s;
+// A little badge used in intros, e.g. " MDK " on a colored background.
+export function badge(label) {
+    return pc.bgCyan(pc.black(pc.bold(` ${label} `)));
+}
+const MDK_ART = [
+    '███╗   ███╗██████╗ ██╗  ██╗',
+    '████╗ ████║██╔══██╗██║ ██╔╝',
+    '██╔████╔██║██║  ██║█████╔╝ ',
+    '██║╚██╔╝██║██║  ██║██╔═██╗ ',
+    '██║ ╚═╝ ██║██████╔╝██║  ██╗',
+    '╚═╝     ╚═╝╚═════╝ ╚═╝  ╚═╝',
+];
+/** Big orange "MDK" logo with a "tether." tagline, for the onboarding header. */
+export function banner() {
+    const art = MDK_ART.map((line) => orange(pc.bold(line))).join('\n');
+    const tagline = `${' '.repeat(19)}${orange('tether.')}`;
+    return `\n${art}\n${tagline}\n`;
+}
+/** Aligned key/value block (keys padded to a common width, then colored). */
+export function kvBlock(rows) {
+    const width = Math.max(0, ...rows.map(([k]) => k.length));
+    return rows.map(([k, v]) => `${theme.key(k.padEnd(width))}   ${v}`).join('\n');
+}
+/** Aligned command list; a comment (rendered as `# ...`) is optional. */
+export function cmdBlock(rows) {
+    const width = Math.max(0, ...rows.map(([c]) => c.length));
+    return rows
+        .map(([c, comment]) => comment ? `${theme.cmd(c.padEnd(width))}   ${theme.muted(`# ${comment}`)}` : theme.cmd(c))
+        .join('\n');
+}
+export const tick = pc.green('✔');
+export const dot = pc.dim('•');
+export const arrow = pc.dim('→');
+//# sourceMappingURL=theme.js.map

package/dist/lib/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../src/lib/theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,6EAA6E;AAC7E,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACpC,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC1C,EAAE,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,GAAG,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,GAAG,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;CAChC,CAAC;AAEF,2EAA2E;AAC3E,sEAAsE;AACtE,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CACnC,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD,uEAAuE;AACvE,MAAM,UAAU,KAAK,CAAC,KAAa;IACjC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,OAAO,GAAG;IACd,6BAA6B;IAC7B,6BAA6B;IAC7B,6BAA6B;IAC7B,6BAA6B;IAC7B,6BAA6B;IAC7B,6BAA6B;CAC9B,CAAC;AAEF,iFAAiF;AACjF,MAAM,UAAU,MAAM;IACpB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;IACxD,OAAO,KAAK,GAAG,KAAK,OAAO,IAAI,CAAC;AAClC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,IAA6B;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,IAA8B;IACrD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CACpB,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAC1F;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAClC,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC/B,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC","sourcesContent":["import pc from 'picocolors';\n\n// Small palette so the CLI has a consistent, colorful look (OpenClaw-style).\nexport const theme = {\n  brand: (s: string) => pc.cyan(pc.bold(s)),\n  accent: (s: string) => pc.magenta(s),\n  label: (s: string) => pc.bold(pc.white(s)),\n  ok: (s: string) => pc.green(s),\n  warn: (s: string) => pc.yellow(s),\n  muted: (s: string) => pc.dim(s),\n  key: (s: string) => pc.cyan(s),\n  value: (s: string) => pc.white(s),\n  cmd: (s: string) => pc.green(s),\n};\n\n// MDK brand orange (256-color 208), matching the logo. Falls back to plain\n// text when colors are unsupported (e.g. NO_COLOR or a non-TTY pipe).\nconst orange = (s: string): string =>\n  pc.isColorSupported ? `\\x1b[38;5;208m${s}\\x1b[39m` : s;\n\n// A little badge used in intros, e.g. \" MDK \" on a colored background.\nexport function badge(label: string): string {\n  return pc.bgCyan(pc.black(pc.bold(` ${label} `)));\n}\n\nconst MDK_ART = [\n  '███╗   ███╗██████╗ ██╗  ██╗',\n  '████╗ ████║██╔══██╗██║ ██╔╝',\n  '██╔████╔██║██║  ██║█████╔╝ ',\n  '██║╚██╔╝██║██║  ██║██╔═██╗ ',\n  '██║ ╚═╝ ██║██████╔╝██║  ██╗',\n  '╚═╝     ╚═╝╚═════╝ ╚═╝  ╚═╝',\n];\n\n/** Big orange \"MDK\" logo with a \"tether.\" tagline, for the onboarding header. */\nexport function banner(): string {\n  const art = MDK_ART.map((line) => orange(pc.bold(line))).join('\\n');\n  const tagline = `${' '.repeat(19)}${orange('tether.')}`;\n  return `\\n${art}\\n${tagline}\\n`;\n}\n\n/** Aligned key/value block (keys padded to a common width, then colored). */\nexport function kvBlock(rows: Array<[string, string]>): string {\n  const width = Math.max(0, ...rows.map(([k]) => k.length));\n  return rows.map(([k, v]) => `${theme.key(k.padEnd(width))}   ${v}`).join('\\n');\n}\n\n/** Aligned command list; a comment (rendered as `# ...`) is optional. */\nexport function cmdBlock(rows: Array<[string, string?]>): string {\n  const width = Math.max(0, ...rows.map(([c]) => c.length));\n  return rows\n    .map(([c, comment]) =>\n      comment ? `${theme.cmd(c.padEnd(width))}   ${theme.muted(`# ${comment}`)}` : theme.cmd(c),\n    )\n    .join('\\n');\n}\n\nexport const tick = pc.green('✔');\nexport const dot = pc.dim('•');\nexport const arrow = pc.dim('→');\n"]}

package/dist/lib/worker-package.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { isMapping, message, readFile, syntaxError } from './app-package.js';
+const require = createRequire(import.meta.url);
+export const WORKER_CONTRACT = 'mdk-contract.json';
+/**
+ * Checks a worker package before it is run or published: a readable package.json with a
+ * name and version, and a contract-first Worker Plugin — `mdk-contract.json` at the root,
+ * validated against the runtime's mdk-contract.schema.json plus its semantic rules
+ * (unique names, number-param bounds, handler files on disk) and by the Worker runtime's
+ * own loader, with at least one entry, command params as lists, and every handler
+ * compiling. None of them is executed.
+ */
+export function validateWorker(dir) {
+    const errors = [];
+    const result = { errors, telemetry: 0, commands: 0 };
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        errors.push(`${dir}: not a directory`);
+        return result;
+    }
+    const pkg = readFile(dir, 'package.json', JSON.parse, errors);
+    if (isMapping(pkg)) {
+        for (const key of ['name', 'version']) {
+            if (typeof pkg[key] === 'string' && pkg[key])
+                result[key] = pkg[key];
+            else
+                errors.push(`package.json: "${key}" must be a non-empty string`);
+        }
+    }
+    if (!existsSync(join(dir, WORKER_CONTRACT))) {
+        errors.push(`${WORKER_CONTRACT}: not found (a Worker Plugin has its contract at the package root)`);
+        return result;
+    }
+    const loader = require('@tetherto/mdk-worker');
+    // Schema + semantic conformance first: it reports every problem at once
+    // (ERR_CONTRACT_*), where the loader below stops at the first. Unparseable
+    // JSON is left to the loader so it keeps its ERR_CONTRACT_INVALID_JSON shape.
+    let contractJson;
+    try {
+        contractJson = JSON.parse(readFileSync(join(dir, WORKER_CONTRACT), 'utf8'));
+    }
+    catch {
+        contractJson = undefined;
+    }
+    if (contractJson !== undefined) {
+        errors.push(...loader.validateContract(contractJson, { dir }).errors.map((e) => `${WORKER_CONTRACT}: ${e}`));
+    }
+    try {
+        const { contract, entries } = loader.loadContract(dir);
+        result.telemetry = entries.telemetry.size;
+        result.commands = entries.commands.size;
+        if (result.telemetry + result.commands === 0) {
+            errors.push(`${WORKER_CONTRACT}: declares no telemetry and no commands`);
+        }
+        for (const command of contract.capabilities?.commands ?? []) {
+            if (command.params !== undefined && !Array.isArray(command.params)) {
+                errors.push(`${WORKER_CONTRACT}: commands.${command.name}.params must be a list`);
+            }
+        }
+        for (const section of ['telemetry', 'commands']) {
+            for (const [name, file] of entries[section]) {
+                const syntax = syntaxError(file);
+                if (syntax)
+                    errors.push(`${WORKER_CONTRACT}: ${section}.${name} handler does not compile: ${syntax}`);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(`${WORKER_CONTRACT}: ${message(error)}`);
+    }
+    return result;
+}
+//# sourceMappingURL=worker-package.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker-package.js","sourceRoot":"","sources":["../../src/lib/worker-package.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync, statSync } from 'node:fs';\nimport { createRequire } from 'node:module';\nimport { join } from 'node:path';\nimport { isMapping, message, readFile, syntaxError } from './app-package.js';\n\nconst require = createRequire(import.meta.url);\n\nexport const WORKER_CONTRACT = 'mdk-contract.json';\n\nexport interface WorkerValidation {\n  errors: string[];\n  /** The package.json `name` / `version`, when readable. */\n  name?: string;\n  version?: string;\n  telemetry: number;\n  commands: number;\n}\n\ninterface MdkWorkerLoader {\n  loadContract(dir: string): {\n    contract: { capabilities?: { commands?: Array<{ name?: string; params?: unknown }> } };\n    entries: { telemetry: Map<string, string>; commands: Map<string, string> };\n  };\n  validateContract(contract: unknown, opts?: { dir?: string; semantic?: boolean }): { ok: boolean; errors: string[] };\n}\n\n/**\n * Checks a worker package before it is run or published: a readable package.json with a\n * name and version, and a contract-first Worker Plugin — `mdk-contract.json` at the root,\n * validated against the runtime's mdk-contract.schema.json plus its semantic rules\n * (unique names, number-param bounds, handler files on disk) and by the Worker runtime's\n * own loader, with at least one entry, command params as lists, and every handler\n * compiling. None of them is executed.\n */\nexport function validateWorker(dir: string): WorkerValidation {\n  const errors: string[] = [];\n  const result: WorkerValidation = { errors, telemetry: 0, commands: 0 };\n  if (!existsSync(dir) || !statSync(dir).isDirectory()) {\n    errors.push(`${dir}: not a directory`);\n    return result;\n  }\n\n  const pkg = readFile(dir, 'package.json', JSON.parse, errors);\n  if (isMapping(pkg)) {\n    for (const key of ['name', 'version'] as const) {\n      if (typeof pkg[key] === 'string' && pkg[key]) result[key] = pkg[key];\n      else errors.push(`package.json: \"${key}\" must be a non-empty string`);\n    }\n  }\n\n  if (!existsSync(join(dir, WORKER_CONTRACT))) {\n    errors.push(`${WORKER_CONTRACT}: not found (a Worker Plugin has its contract at the package root)`);\n    return result;\n  }\n  const loader = require('@tetherto/mdk-worker') as MdkWorkerLoader;\n\n  // Schema + semantic conformance first: it reports every problem at once\n  // (ERR_CONTRACT_*), where the loader below stops at the first. Unparseable\n  // JSON is left to the loader so it keeps its ERR_CONTRACT_INVALID_JSON shape.\n  let contractJson: unknown;\n  try {\n    contractJson = JSON.parse(readFileSync(join(dir, WORKER_CONTRACT), 'utf8'));\n  } catch {\n    contractJson = undefined;\n  }\n  if (contractJson !== undefined) {\n    errors.push(...loader.validateContract(contractJson, { dir }).errors.map((e) => `${WORKER_CONTRACT}: ${e}`));\n  }\n\n  try {\n    const { contract, entries } = loader.loadContract(dir);\n    result.telemetry = entries.telemetry.size;\n    result.commands = entries.commands.size;\n    if (result.telemetry + result.commands === 0) {\n      errors.push(`${WORKER_CONTRACT}: declares no telemetry and no commands`);\n    }\n    for (const command of contract.capabilities?.commands ?? []) {\n      if (command.params !== undefined && !Array.isArray(command.params)) {\n        errors.push(`${WORKER_CONTRACT}: commands.${command.name}.params must be a list`);\n      }\n    }\n    for (const section of ['telemetry', 'commands'] as const) {\n      for (const [name, file] of entries[section]) {\n        const syntax = syntaxError(file);\n        if (syntax) errors.push(`${WORKER_CONTRACT}: ${section}.${name} handler does not compile: ${syntax}`);\n      }\n    }\n  } catch (error) {\n    errors.push(`${WORKER_CONTRACT}: ${message(error)}`);\n  }\n  return result;\n}\n"]}

package/dist/lib/worker-scaffold.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { installScaffold } from './npm.js';
+import { DIRS } from './project.js';
+import { appendToStackList, copyTemplate, linkIntoProject, updateJson } from './scaffold.js';
+import { deviceId, deviceSerial, MOCK_PORT_BASE } from './spec.js';
+import { NAME_RE, parseOrg } from './names.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Placeholder baked into `templates/worker/**`, replaced at scaffold time. */
+const NAME_TOKEN = '__WORKER_NAME__';
+/**
+ * Absolute path to the bundled worker template (`templates/worker`). Resolves the same from
+ * `dist/lib` (built) and `src/lib` (tsx dev) since both sit one level under the
+ * package root.
+ */
+function templateDir() {
+    return resolve(__dirname, '..', '..', 'templates', 'worker');
+}
+/**
+ * Lowest mock port from `MOCK_PORT_BASE` up that no device in this project's
+ * spec already claims, so scaffolding a second worker cannot collide with the
+ * first. Only covers *this* project — a port taken by another stack on the
+ * machine is resolved at boot (see `resolveMockPorts` in runtime.ts).
+ */
+function nextMockPort(doc) {
+    const spec = doc.toJS();
+    const used = new Set();
+    for (const worker of spec?.spec?.workers ?? []) {
+        for (const device of worker?.config?.devices ?? []) {
+            const port = device?.opts?.port;
+            if (typeof port === 'number')
+                used.add(port);
+        }
+    }
+    let port = MOCK_PORT_BASE;
+    while (used.has(port))
+        port++;
+    return port;
+}
+/**
+ * Appends a worker to `spec.workers` in `<parentDir>/mdk.yaml`. With `mock` (the
+ * default) it seeds a `mock: true` config with one sample device on an unclaimed port
+ * so the entry is runnable immediately; without, the device options are the
+ * operator's to fill in. No-ops (`'exists'`) when this worker is listed already;
+ * `'name-taken'` when the name belongs to a worker running another package.
+ */
+export function addWorkerToStackFile(parentDir, name, relPackage, { mock = true } = {}) {
+    let port = MOCK_PORT_BASE;
+    const update = appendToStackList(parentDir, 'workers', name, (entry) => entry.get('name') === name && entry.get('package') === relPackage, (doc) => {
+        port = nextMockPort(doc);
+        // Flow-style opts to match the compact form the scaffold documents. The
+        // device identity is derived from the (project-unique) worker name: the
+        // Kernel registers device ids globally, so a shared `dev-0` would leave the
+        // second worker silently unregistered.
+        const opts = doc.createNode(mock ? { host: '127.0.0.1', port, serial: deviceSerial(name) } : {});
+        opts.flow = true;
+        const worker = doc.createNode({
+            name,
+            package: relPackage,
+            config: { ...(mock ? { mock: true } : {}), devices: [{ id: deviceId(name) }] },
+        });
+        worker.setIn(['config', 'devices', 0, 'opts'], opts);
+        return worker;
+    });
+    return { update, port };
+}
+/**
+ * Scaffolds a new Worker Plugin package from the bundled worker template
+ * into `<parentDir>/workers/<name>` — the local-path layout `mdk run worker`
+ * expects. Substitutes the name token and sets the package.json `name`.
+ */
+export function createWorker(opts) {
+    const name = opts.name.trim();
+    if (!NAME_RE.test(name)) {
+        return {
+            ok: false,
+            message: `Invalid worker name "${opts.name}". Use lowercase letters, digits, '.', '_' or '-'.`,
+        };
+    }
+    const org = parseOrg(opts.org);
+    if (!org.ok)
+        return { ok: false, message: org.message };
+    const src = templateDir();
+    if (!existsSync(src)) {
+        return { ok: false, message: `Worker template not found at ${src}.` };
+    }
+    const workerPath = resolve(opts.parentDir, DIRS.workers, name);
+    if (existsSync(workerPath) && !opts.force) {
+        return { ok: false, message: `${workerPath} already exists (use --force to overwrite).` };
+    }
+    try {
+        mkdirSync(resolve(opts.parentDir, DIRS.workers), { recursive: true });
+        copyTemplate(src, workerPath, { [NAME_TOKEN]: name });
+        const packageName = org.org ? `@${org.org}/${name}` : name;
+        updateJson(join(workerPath, 'package.json'), { name: packageName });
+        const linkWarning = linkIntoProject(opts.parentDir, packageName, workerPath);
+        const install = installScaffold(opts.parentDir, workerPath, opts.install !== false);
+        const relPackage = `./${DIRS.workers}/${name}`;
+        const stackFile = opts.updateStackFile === false
+            ? undefined
+            : addWorkerToStackFile(opts.parentDir, name, relPackage);
+        return {
+            ok: true,
+            workerPath,
+            relPackage,
+            packageName,
+            installWarning: linkWarning ?? (install.ok ? undefined : install.message),
+            installDir: install.dir,
+            stackFile: stackFile?.update,
+            mockPort: stackFile?.port ?? MOCK_PORT_BASE,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: 'Could not scaffold the worker.',
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=worker-scaffold.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker-scaffold.js","sourceRoot":"","sources":["../../src/lib/worker-scaffold.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, mkdirSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join, resolve } from 'node:path';\nimport type { Document, YAMLMap } from 'yaml';\nimport { installScaffold } from './npm.js';\nimport { DIRS } from './project.js';\nimport { appendToStackList, copyTemplate, linkIntoProject, updateJson, type StackFileUpdate } from './scaffold.js';\nimport { deviceId, deviceSerial, MOCK_PORT_BASE } from './spec.js';\nimport { NAME_RE, parseOrg } from './names.js';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/** Placeholder baked into `templates/worker/**`, replaced at scaffold time. */\nconst NAME_TOKEN = '__WORKER_NAME__';\n\n/**\n * Absolute path to the bundled worker template (`templates/worker`). Resolves the same from\n * `dist/lib` (built) and `src/lib` (tsx dev) since both sit one level under the\n * package root.\n */\nfunction templateDir(): string {\n  return resolve(__dirname, '..', '..', 'templates', 'worker');\n}\n\nexport interface WorkerScaffoldOptions {\n  /** Worker name — used for the folder, the mdk.yaml entry, and the package name. */\n  name: string;\n  /** Project directory; the worker is created under `<parentDir>/workers/<name>`. */\n  parentDir: string;\n  /** npm scope/org for the generated package name (e.g. `demo` → `@demo/<name>`). */\n  org?: string;\n  /** Overwrite the target if it already exists (default: false). */\n  force?: boolean;\n  /** Run `npm install` in the scaffolded worker (default: true). */\n  install?: boolean;\n  /** Add the worker entry to `<parentDir>/mdk.yaml` under `spec.workers` (default: true). */\n  updateStackFile?: boolean;\n}\n\nexport interface WorkerScaffoldResult {\n  ok: boolean;\n  message?: string;\n  detail?: string;\n  /** Absolute path of the scaffolded worker. */\n  workerPath?: string;\n  /** Local path to reference in mdk.yaml (`./workers/<name>`). */\n  relPackage?: string;\n  /** Resolved package.json `name`. */\n  packageName?: string;\n  /** Warning surfaced when `npm install` could not complete (scaffold still ok). */\n  installWarning?: string;\n  /** Directory `npm install` ran in (the workspace root for a linked worker). */\n  installDir?: string;\n  /** How the `mdk.yaml` update went (so the caller can guide the user). */\n  stackFile?: StackFileUpdate;\n  /** Mock port the seed device was given — so a printed snippet matches the file. */\n  mockPort?: number;\n}\n\n/**\n * Lowest mock port from `MOCK_PORT_BASE` up that no device in this project's\n * spec already claims, so scaffolding a second worker cannot collide with the\n * first. Only covers *this* project — a port taken by another stack on the\n * machine is resolved at boot (see `resolveMockPorts` in runtime.ts).\n */\nfunction nextMockPort(doc: Document): number {\n  const spec = doc.toJS() as {\n    spec?: { workers?: Array<{ config?: { devices?: Array<{ opts?: { port?: unknown } }> } }> };\n  };\n\n  const used = new Set<number>();\n  for (const worker of spec?.spec?.workers ?? []) {\n    for (const device of worker?.config?.devices ?? []) {\n      const port = device?.opts?.port;\n      if (typeof port === 'number') used.add(port);\n    }\n  }\n\n  let port = MOCK_PORT_BASE;\n  while (used.has(port)) port++;\n  return port;\n}\n\n/** Outcome of the `mdk.yaml` edit, plus the mock port the entry was given. */\nexport interface StackFileResult {\n  update: StackFileUpdate;\n  port: number;\n}\n\n/**\n * Appends a worker to `spec.workers` in `<parentDir>/mdk.yaml`. With `mock` (the\n * default) it seeds a `mock: true` config with one sample device on an unclaimed port\n * so the entry is runnable immediately; without, the device options are the\n * operator's to fill in. No-ops (`'exists'`) when this worker is listed already;\n * `'name-taken'` when the name belongs to a worker running another package.\n */\nexport function addWorkerToStackFile(\n  parentDir: string,\n  name: string,\n  relPackage: string,\n  { mock = true }: { mock?: boolean } = {},\n): StackFileResult {\n  let port = MOCK_PORT_BASE;\n  const update = appendToStackList(\n    parentDir,\n    'workers',\n    name,\n    (entry) => entry.get('name') === name && entry.get('package') === relPackage,\n    (doc) => {\n      port = nextMockPort(doc);\n      // Flow-style opts to match the compact form the scaffold documents. The\n      // device identity is derived from the (project-unique) worker name: the\n      // Kernel registers device ids globally, so a shared `dev-0` would leave the\n      // second worker silently unregistered.\n      const opts = doc.createNode(mock ? { host: '127.0.0.1', port, serial: deviceSerial(name) } : {});\n      (opts as unknown as { flow: boolean }).flow = true;\n      const worker = doc.createNode({\n        name,\n        package: relPackage,\n        config: { ...(mock ? { mock: true } : {}), devices: [{ id: deviceId(name) }] },\n      }) as YAMLMap;\n      worker.setIn(['config', 'devices', 0, 'opts'], opts);\n      return worker;\n    },\n  );\n  return { update, port };\n}\n\n/**\n * Scaffolds a new Worker Plugin package from the bundled worker template\n * into `<parentDir>/workers/<name>` — the local-path layout `mdk run worker`\n * expects. Substitutes the name token and sets the package.json `name`.\n */\nexport function createWorker(opts: WorkerScaffoldOptions): WorkerScaffoldResult {\n  const name = opts.name.trim();\n  if (!NAME_RE.test(name)) {\n    return {\n      ok: false,\n      message: `Invalid worker name \"${opts.name}\". Use lowercase letters, digits, '.', '_' or '-'.`,\n    };\n  }\n\n  const org = parseOrg(opts.org);\n  if (!org.ok) return { ok: false, message: org.message };\n\n  const src = templateDir();\n  if (!existsSync(src)) {\n    return { ok: false, message: `Worker template not found at ${src}.` };\n  }\n\n  const workerPath = resolve(opts.parentDir, DIRS.workers, name);\n  if (existsSync(workerPath) && !opts.force) {\n    return { ok: false, message: `${workerPath} already exists (use --force to overwrite).` };\n  }\n\n  try {\n    mkdirSync(resolve(opts.parentDir, DIRS.workers), { recursive: true });\n    copyTemplate(src, workerPath, { [NAME_TOKEN]: name });\n\n    const packageName = org.org ? `@${org.org}/${name}` : name;\n    updateJson(join(workerPath, 'package.json'), { name: packageName });\n\n    const linkWarning = linkIntoProject(opts.parentDir, packageName, workerPath);\n    const install = installScaffold(opts.parentDir, workerPath, opts.install !== false);\n\n    const relPackage = `./${DIRS.workers}/${name}`;\n    const stackFile =\n      opts.updateStackFile === false\n        ? undefined\n        : addWorkerToStackFile(opts.parentDir, name, relPackage);\n\n    return {\n      ok: true,\n      workerPath,\n      relPackage,\n      packageName,\n      installWarning: linkWarning ?? (install.ok ? undefined : install.message),\n      installDir: install.dir,\n      stackFile: stackFile?.update,\n      mockPort: stackFile?.port ?? MOCK_PORT_BASE,\n    };\n  } catch (error) {\n    return {\n      ok: false,\n      message: 'Could not scaffold the worker.',\n      detail: error instanceof Error ? error.message : String(error),\n    };\n  }\n}\n"]}