@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/commands/add.js

@@ -0,0 +1,61 @@
+import { addPackage } from '../lib/add-package.js';
+import { examples } from '../lib/help.js';
+import { theme, tick, arrow } from '../lib/theme.js';
+function report(kind, result) {
+    if (!result.ok) {
+        process.stderr.write(`${theme.warn('error')}: ${result.message}\n`);
+        for (const error of result.errors ?? [])
+            process.stderr.write(`  ${error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const section = kind === 'app' ? 'spec.apps' : 'spec.workers';
+    const stack = result.stackFile === 'added'
+        ? `added under ${theme.key(section)}`
+        : result.stackFile === 'exists'
+            ? 'already listed (left as is)'
+            : `could not be updated; add it under ${theme.key(section)} yourself`;
+    let out = `${tick} ${result.stackFile === 'exists' ? 'Updated' : 'Added'} ${kind} ${theme.label(result.instanceName)} ${arrow} ${theme.value(result.reference)}\n` +
+        (result.installed
+            ? `  ${theme.muted('package.json')} dependency ${theme.value(result.packageName)}\n`
+            : `  ${theme.muted('package.json')} not changed (--no-install)\n`) +
+        `  ${theme.muted('mdk.yaml')} ${stack}\n`;
+    if (result.needsDeviceOpts) {
+        out += `  ${theme.warn('note')}: this worker has no mock; fill in ${theme.key('config.devices[].opts')} for your hardware.\n`;
+    }
+    out += `\n${theme.label('Next steps')}\n  ${theme.muted('1.')} Run it: ${theme.cmd('mdk run')} ${theme.muted(`(or \`mdk run ${kind} ${result.instanceName}\`)`)}\n`;
+    process.stdout.write(out);
+}
+const SOURCE_HELP = 'An npm package (@scope/pkg, pkg@1.2.3, @scope/pkg/<subdir>) or GitHub repo ' +
+    '(github:owner/repo#ref, owner/repo, https://github.com/owner/repo).';
+const EXAMPLES = {
+    app: ['mdk add app @your-org/mdk-app-ops-center', 'mdk add app github:me/my-app#v0.2.0 --name ops'],
+    worker: ['mdk add worker @your-org/mdk-worker-rig@^1', 'mdk add worker https://github.com/me/rig-worker'],
+};
+function register(add, kind) {
+    const section = kind === 'app' ? 'spec.apps' : 'spec.workers';
+    add
+        .command(kind)
+        .argument('<source>', SOURCE_HELP)
+        .summary(`Install ${kind === 'app' ? 'an app' : 'a worker'} from npm or GitHub`)
+        .description(`Install ${kind === 'app' ? 'an app' : 'a worker'} from npm or GitHub (npm records it in package.json), ` +
+        `check it with the same rules as \`mdk validate ${kind}\`, then add it to mdk.yaml under ${section}. ` +
+        'Install scripts do not run, and the exact version is recorded. A refused package leaves mdk.yaml and package.json unchanged.')
+        .option('--dir <path>', 'Project directory (the one holding mdk.yaml)', '.')
+        .option('--name <name>', `Name for the ${kind} in mdk.yaml (default: derived from the package name)`)
+        .option('--no-install', 'Skip `npm install`: the npm package must already be installed (not for GitHub sources)')
+        .addHelpText('after', examples(...EXAMPLES[kind]))
+        .action((source, opts) => report(kind, addPackage({ kind, source, dir: opts.dir, name: opts.name, install: opts.install })));
+}
+// Group B — Add
+export function registerAdd(program) {
+    const add = program
+        .command('add')
+        .usage('<command> [options]')
+        .summary('Install an app or worker from npm or GitHub')
+        .description('Install an app or worker from npm or GitHub and add it to package.json and mdk.yaml.')
+        .addHelpText('after', examples(...EXAMPLES.app.slice(0, 1), ...EXAMPLES.worker.slice(0, 1)));
+    register(add, 'app');
+    register(add, 'worker');
+}
+//# sourceMappingURL=add.js.map

package/dist/commands/add.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.js","sourceRoot":"","sources":["../../src/commands/add.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from 'commander';\nimport { addPackage, type AddPackageResult, type PackageKind } from '../lib/add-package.js';\nimport { examples } from '../lib/help.js';\nimport { theme, tick, arrow } from '../lib/theme.js';\n\ninterface AddOpts {\n  dir: string;\n  name?: string;\n  install: boolean;\n}\n\nfunction report(kind: PackageKind, result: AddPackageResult): void {\n  if (!result.ok) {\n    process.stderr.write(`${theme.warn('error')}: ${result.message}\\n`);\n    for (const error of result.errors ?? []) process.stderr.write(`  ${error}\\n`);\n    process.exitCode = 1;\n    return;\n  }\n\n  const section = kind === 'app' ? 'spec.apps' : 'spec.workers';\n  const stack =\n    result.stackFile === 'added'\n      ? `added under ${theme.key(section)}`\n      : result.stackFile === 'exists'\n        ? 'already listed (left as is)'\n        : `could not be updated; add it under ${theme.key(section)} yourself`;\n\n  let out =\n    `${tick} ${result.stackFile === 'exists' ? 'Updated' : 'Added'} ${kind} ${theme.label(result.instanceName!)} ${arrow} ${theme.value(result.reference!)}\\n` +\n    (result.installed\n      ? `  ${theme.muted('package.json')} dependency ${theme.value(result.packageName!)}\\n`\n      : `  ${theme.muted('package.json')} not changed (--no-install)\\n`) +\n    `  ${theme.muted('mdk.yaml')} ${stack}\\n`;\n  if (result.needsDeviceOpts) {\n    out += `  ${theme.warn('note')}: this worker has no mock; fill in ${theme.key('config.devices[].opts')} for your hardware.\\n`;\n  }\n  out += `\\n${theme.label('Next steps')}\\n  ${theme.muted('1.')} Run it: ${theme.cmd('mdk run')} ${theme.muted(`(or \\`mdk run ${kind} ${result.instanceName}\\`)`)}\\n`;\n  process.stdout.write(out);\n}\n\nconst SOURCE_HELP =\n  'An npm package (@scope/pkg, pkg@1.2.3, @scope/pkg/<subdir>) or GitHub repo ' +\n  '(github:owner/repo#ref, owner/repo, https://github.com/owner/repo).';\n\nconst EXAMPLES: Record<PackageKind, string[]> = {\n  app: ['mdk add app @your-org/mdk-app-ops-center', 'mdk add app github:me/my-app#v0.2.0 --name ops'],\n  worker: ['mdk add worker @your-org/mdk-worker-rig@^1', 'mdk add worker https://github.com/me/rig-worker'],\n};\n\nfunction register(add: Command, kind: PackageKind): void {\n  const section = kind === 'app' ? 'spec.apps' : 'spec.workers';\n  add\n    .command(kind)\n    .argument('<source>', SOURCE_HELP)\n    .summary(`Install ${kind === 'app' ? 'an app' : 'a worker'} from npm or GitHub`)\n    .description(\n      `Install ${kind === 'app' ? 'an app' : 'a worker'} from npm or GitHub (npm records it in package.json), ` +\n        `check it with the same rules as \\`mdk validate ${kind}\\`, then add it to mdk.yaml under ${section}. ` +\n        'Install scripts do not run, and the exact version is recorded. A refused package leaves mdk.yaml and package.json unchanged.',\n    )\n    .option('--dir <path>', 'Project directory (the one holding mdk.yaml)', '.')\n    .option('--name <name>', `Name for the ${kind} in mdk.yaml (default: derived from the package name)`)\n    .option('--no-install', 'Skip `npm install`: the npm package must already be installed (not for GitHub sources)')\n    .addHelpText('after', examples(...EXAMPLES[kind]))\n    .action((source: string, opts: AddOpts) =>\n      report(kind, addPackage({ kind, source, dir: opts.dir, name: opts.name, install: opts.install })),\n    );\n}\n\n// Group B — Add\nexport function registerAdd(program: Command): void {\n  const add = program\n    .command('add')\n    .usage('<command> [options]')\n    .summary('Install an app or worker from npm or GitHub')\n    .description('Install an app or worker from npm or GitHub and add it to package.json and mdk.yaml.')\n    .addHelpText('after', examples(...EXAMPLES.app.slice(0, 1), ...EXAMPLES.worker.slice(0, 1)));\n  register(add, 'app');\n  register(add, 'worker');\n}\n"]}

package/dist/commands/agent.js

@@ -0,0 +1,42 @@
+import { examples } from '../lib/help.js';
+import { resolve } from 'node:path';
+import { installSkill } from '../lib/skill.js';
+const SKILL_CLIENTS = new Set(['cursor', 'claude', 'all']);
+// Group F — Agent enablement
+export function registerSkill(program) {
+    const skill = program
+        .command('skill')
+        .usage('<command> [options]')
+        .summary('Install the MDK coding-agent skills')
+        .description('Manage the MDK Developer Skill suite for coding agents (Cursor, Claude).');
+    skill
+        .command('add')
+        .description('Install the MDK Developer Skill suite into the project, for Cursor, Claude or both.')
+        .option('--client <client>', 'Target client: cursor | claude | all', 'all')
+        .option('--dir <path>', 'Project directory', '.')
+        .addHelpText('after', examples('mdk skill add', 'mdk skill add --client cursor'))
+        .action((opts) => {
+        const client = opts.client;
+        if (!SKILL_CLIENTS.has(client)) {
+            process.stderr.write(`mdk skill add: unknown client '${opts.client}' — use cursor | claude | all\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = installSkill(client, resolve(opts.dir));
+        if (!result.ok) {
+            process.stderr.write(`mdk skill add: ${result.message}\n`);
+            if (result.detail)
+                process.stderr.write(`${result.detail}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (result.message)
+            process.stdout.write(`${result.message}\n`);
+        if (result.detail)
+            process.stdout.write(`${result.detail}\n`);
+        if (result.warning)
+            process.stderr.write(`warning: ${result.warning}\n`);
+        process.stderr.write('MDK Developer Skill installed.\n');
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/commands/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAoB,MAAM,iBAAiB,CAAC;AAEjE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAExE,6BAA6B;AAC7B,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,KAAK,GAAG,OAAO;SAClB,OAAO,CAAC,OAAO,CAAC;SAChB,KAAK,CAAC,qBAAqB,CAAC;SAC5B,OAAO,CAAC,qCAAqC,CAAC;SAC9C,WAAW,CAAC,0EAA0E,CAAC,CAAC;IAE3F,KAAK;SACF,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,qFAAqF,CAAC;SAClG,MAAM,CAAC,mBAAmB,EAAE,sCAAsC,EAAE,KAAK,CAAC;SAC1E,MAAM,CAAC,cAAc,EAAE,mBAAmB,EAAE,GAAG,CAAC;SAChD,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,eAAe,EAAE,+BAA+B,CAAC,CAAC;SAChF,MAAM,CAAC,CAAC,IAAqC,EAAE,EAAE;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAqB,CAAC;QAC1C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,IAAI,CAAC,MAAM,iCAAiC,CAAC,CAAC;YACrG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YAC3D,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YAC9D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QAChE,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAC9D,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QACzE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["import type { Command } from 'commander';\nimport { examples } from '../lib/help.js';\nimport { resolve } from 'node:path';\nimport { installSkill, type SkillClient } from '../lib/skill.js';\n\nconst SKILL_CLIENTS = new Set<SkillClient>(['cursor', 'claude', 'all']);\n\n// Group F — Agent enablement\nexport function registerSkill(program: Command): void {\n  const skill = program\n    .command('skill')\n    .usage('<command> [options]')\n    .summary('Install the MDK coding-agent skills')\n    .description('Manage the MDK Developer Skill suite for coding agents (Cursor, Claude).');\n\n  skill\n    .command('add')\n    .description('Install the MDK Developer Skill suite into the project, for Cursor, Claude or both.')\n    .option('--client <client>', 'Target client: cursor | claude | all', 'all')\n    .option('--dir <path>', 'Project directory', '.')\n    .addHelpText('after', examples('mdk skill add', 'mdk skill add --client cursor'))\n    .action((opts: { client: string; dir: string }) => {\n      const client = opts.client as SkillClient;\n      if (!SKILL_CLIENTS.has(client)) {\n        process.stderr.write(`mdk skill add: unknown client '${opts.client}' — use cursor | claude | all\\n`);\n        process.exitCode = 1;\n        return;\n      }\n      const result = installSkill(client, resolve(opts.dir));\n      if (!result.ok) {\n        process.stderr.write(`mdk skill add: ${result.message}\\n`);\n        if (result.detail) process.stderr.write(`${result.detail}\\n`);\n        process.exitCode = 1;\n        return;\n      }\n      if (result.message) process.stdout.write(`${result.message}\\n`);\n      if (result.detail) process.stdout.write(`${result.detail}\\n`);\n      if (result.warning) process.stderr.write(`warning: ${result.warning}\\n`);\n      process.stderr.write('MDK Developer Skill installed.\\n');\n    });\n}\n"]}

package/dist/commands/create.js

@@ -0,0 +1,261 @@
+import { examples } from '../lib/help.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { createDashboard, dashboardNameFromStack, defaultTemplateRef } from '../lib/dashboard.js';
+import { NAME_RE } from '../lib/names.js';
+import { createWorker } from '../lib/worker-scaffold.js';
+import { deviceId, deviceSerial } from '../lib/spec.js';
+import { createApp } from '../lib/app-scaffold.js';
+import { DIRS } from '../lib/project.js';
+import { theme, tick, arrow } from '../lib/theme.js';
+/**
+ * Resolves the dashboard's package name and its location.
+ *
+ * With no name the app takes the canonical `apps/dashboard` path and a
+ * `<stack>-dashboard` package name read from mdk.yaml — so the path never churns
+ * when the stack is renamed. An explicit name gets its own `apps/<name>` slot,
+ * which is how a project ends up with more than one dashboard.
+ */
+function resolveDashboard(explicit, parentDir) {
+    if (explicit) {
+        const name = explicit.trim();
+        if (!NAME_RE.test(name)) {
+            return { error: `invalid dashboard name "${explicit}". Use lowercase letters, digits, '.', '_' or '-'.` };
+        }
+        return { name, subdir: join(DIRS.apps, name) };
+    }
+    const specPath = resolve(parentDir, 'mdk.yaml');
+    if (!existsSync(specPath))
+        return null;
+    let stack;
+    try {
+        const doc = parseYaml(readFileSync(specPath, 'utf8'));
+        stack = typeof doc.metadata?.name === 'string' ? doc.metadata.name.trim() : undefined;
+    }
+    catch {
+        return null;
+    }
+    if (!stack)
+        return null;
+    const name = dashboardNameFromStack(stack);
+    if (!NAME_RE.test(name)) {
+        return {
+            error: `mdk.yaml metadata.name "${stack}" is not a valid name. Use lowercase letters, digits, '.', '_' or '-', or pass a dashboard name.`,
+        };
+    }
+    return { name, subdir: DIRS.dashboard };
+}
+// Group B — Scaffold
+export function registerCreate(program) {
+    const create = program
+        .command('create')
+        .usage('<command> [options]')
+        .summary('Scaffold a worker, app or dashboard')
+        .description('Scaffold a new worker, app or dashboard from the bundled templates and register it in mdk.yaml.')
+        .addHelpText('after', examples('mdk create worker rig', 'mdk create app ops-center --org your-org', 'mdk create dashboard'));
+    create
+        .command('worker')
+        .argument('<name>', "Worker name: lowercase letters, digits, '.', '_' or '-'")
+        .summary('Scaffold a Worker Plugin into workers/<name>')
+        .description('Scaffold a Worker Plugin (mdk-contract.json, handlers and a mock device) into <dir>/workers/<name>, ' +
+        'link it into package.json and add it to mdk.yaml under spec.workers with a mock device.')
+        .option('--org <scope>', 'npm scope for the package name, e.g. your-org -> @your-org/<name>')
+        .option('--dir <path>', 'Project directory', '.')
+        .option('--force', 'Overwrite the target if it already exists', false)
+        .option('--no-install', 'Skip `npm install`')
+        .option('--no-stack-entry', 'Do not add the worker to mdk.yaml')
+        .addHelpText('after', examples('mdk create worker rig', 'mdk create worker rig --org your-org --no-install'))
+        .action((name, opts) => {
+        const result = createWorker({
+            name,
+            parentDir: opts.dir,
+            org: opts.org,
+            force: opts.force,
+            install: opts.install,
+            updateStackFile: opts.stackEntry,
+        });
+        if (!result.ok) {
+            process.stderr.write(`${theme.warn('error')}: ${result.message}\n`);
+            if (result.detail)
+                process.stderr.write(`${result.detail}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (result.installWarning) {
+            process.stderr.write(`${theme.warn('warning')}: ${result.installWarning} ` +
+                `${theme.muted(`(run \`npm install\` in ${result.installDir})`)}\n`);
+        }
+        let out = `${tick} Scaffolded worker ${theme.label(name)} ${arrow} ${theme.value(result.workerPath)}\n` +
+            `  ${theme.muted('package')} ${theme.value(result.packageName)}\n`;
+        // Report how mdk.yaml was touched, and fall back to the manual snippet
+        // when it could not be updated automatically.
+        const manualSnippet = `${theme.cmd(`    - name: ${name}\n` +
+            `      package: ${result.relPackage}\n` +
+            `      config:\n` +
+            `        mock: true\n` +
+            `        devices:\n` +
+            `          - id: ${deviceId(name)}\n` +
+            `            opts: { host: 127.0.0.1, port: ${result.mockPort}, serial: ${deviceSerial(name)} }`)}\n`;
+        switch (result.stackFile) {
+            case 'added':
+                out += `  ${tick} Added to ${theme.value('mdk.yaml')} under ${theme.key('spec.workers')}\n`;
+                break;
+            case 'exists':
+                out += `  ${theme.muted(`spec.workers already has "${name}" in mdk.yaml — left unchanged`)}\n`;
+                break;
+            case 'name-taken':
+                out += `  ${theme.warn('!')} spec.workers already has a worker named "${name}" with another package; mdk.yaml was not changed\n`;
+                process.exitCode = 1;
+                break;
+            case 'no-file':
+                out +=
+                    `\n${theme.warn('No mdk.yaml found')} in ${theme.value(opts.dir)}. Start a project with ${theme.cmd('mdk onboard')}, ` +
+                        `or add this under ${theme.key('spec.workers')} of an existing one:\n\n` +
+                        manualSnippet;
+                break;
+            case 'error':
+                out +=
+                    `\n${theme.warn('Could not update mdk.yaml automatically')}. Add this under ${theme.key('spec.workers')}:\n\n` +
+                        manualSnippet;
+                break;
+            default:
+                // --no-stack-entry
+                out +=
+                    `\n${theme.muted('Add this to')} ${theme.value('mdk.yaml')} under ${theme.key('spec.workers')}:\n\n` +
+                        manualSnippet;
+        }
+        out +=
+            `\n${theme.label('Next steps')}\n` +
+                `  ${theme.muted('1.')} Customize ${theme.value('mdk-contract.json')}, ${theme.value('src/')} + ${theme.value('mock/server.js')} for your device.\n` +
+                `  ${theme.muted('2.')} Run it: ${theme.cmd(`mdk run worker ${name}`)}\n`;
+        process.stdout.write(out);
+    });
+    create
+        .command('app')
+        .argument('<name>', "App name: lowercase letters, digits, '.', '_' or '-'")
+        .summary(`Scaffold an app into ${DIRS.apps}/<name>`)
+        .description(`Scaffold an app (mdk-app.yaml, plugin/ route table and controllers, and a starter UI built into ui/) ` +
+        `into <dir>/${DIRS.apps}/<name>, link it into package.json and add it to mdk.yaml under spec.apps.`)
+        .option('--org <scope>', 'npm scope for the package name, e.g. your-org -> @your-org/<name>')
+        .option('--dir <path>', 'Project directory', '.')
+        .option('--force', 'Overwrite the target if it already exists', false)
+        .option('--no-install', 'Skip `npm install` and building the starter UI')
+        .option('--no-stack-entry', 'Do not add the app to mdk.yaml')
+        .addHelpText('after', examples('mdk create app ops-center', 'mdk create app ops-center --org your-org'))
+        .action((name, opts) => {
+        const result = createApp({
+            name,
+            parentDir: opts.dir,
+            org: opts.org,
+            force: opts.force,
+            install: opts.install,
+            updateStackFile: opts.stackEntry,
+        });
+        if (!result.ok) {
+            process.stderr.write(`${theme.warn('error')}: ${result.message}\n`);
+            if (result.detail)
+                process.stderr.write(`${result.detail}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (result.installWarning) {
+            process.stderr.write(`${theme.warn('warning')}: ${result.installWarning} ` +
+                `${theme.muted(`(run \`npm install\` in ${result.installDir})`)}\n`);
+        }
+        let out = `${tick} Scaffolded app ${theme.label(name)} ${arrow} ${theme.value(result.appPath)}\n` +
+            `  ${theme.muted('package')} ${theme.value(result.packageName)}\n` +
+            (result.uiBuilt
+                ? `  ${tick} Built the starter UI ${arrow} ${theme.value('ui/index.js')} ${theme.muted('(source in ui-src/)')}\n`
+                : `  ${theme.warn('!')} Starter UI not built: ${result.uiWarning}\n` +
+                    `    ${theme.muted('Build it yourself:')} ${theme.cmd(`cd ${result.appPath} && npm --prefix ui-src install && npm run build:ui`)}\n`);
+        // Apps are referenced by package name (resolved via the `file:` link),
+        // so the manual snippet uses the package name too.
+        const manualSnippet = `${theme.cmd(`    - name: ${result.appName}\n      package: ${result.packageName}\n      config: {}`)}\n`;
+        switch (result.stackFile) {
+            case 'added':
+                out += `  ${tick} Added to ${theme.value('mdk.yaml')} under ${theme.key('spec.apps')}\n`;
+                break;
+            case 'exists':
+                out += `  ${theme.muted(`spec.apps already lists "${result.packageName}" — left unchanged`)}\n`;
+                break;
+            case 'name-taken':
+                out += `  ${theme.warn('!')} spec.apps already has an app named "${result.appName}" with another package; mdk.yaml was not changed\n`;
+                process.exitCode = 1;
+                break;
+            case 'no-file':
+                out +=
+                    `\n${theme.warn('No mdk.yaml found')} in ${theme.value(opts.dir)}. Start a project with ${theme.cmd('mdk onboard')}, ` +
+                        `or add this under ${theme.key('spec.apps')} of an existing one:\n\n` +
+                        manualSnippet;
+                break;
+            case 'error':
+                out +=
+                    `\n${theme.warn('Could not update mdk.yaml automatically')}. Add this under ${theme.key('spec.apps')}:\n\n` +
+                        manualSnippet;
+                break;
+            default:
+                // --no-stack-entry
+                out +=
+                    `\n${theme.muted('Add this to')} ${theme.value('mdk.yaml')} under ${theme.key('spec.apps')}:\n\n` +
+                        manualSnippet;
+        }
+        out +=
+            `\n${theme.label('Next steps')}\n` +
+                `  ${theme.muted('1.')} Add routes in ${theme.value('plugin/mdk-plugin.json')} + ${theme.value('plugin/controllers/')}.\n` +
+                `  ${theme.muted('2.')} Set ${theme.key('id')} and ${theme.key('permissions')} in ${theme.value('mdk-app.yaml')}, then check it: ${theme.cmd(`mdk validate app ${result.appName}`)}\n` +
+                `  ${theme.muted('3.')} Run it: ${theme.cmd('mdk run')} ${theme.muted(`(or \`mdk run app ${result.appName}\` + \`mdk run gateway\`)`)}, then ${theme.cmd('mdk run dashboard')} to see its UI\n` +
+                `  ${theme.muted('4.')} Edit the UI in ${theme.value('ui-src/')}; rebuild with ${theme.cmd('npm run build:ui')} (or ${theme.cmd('npm run dev:ui')} to rebuild on save).\n`;
+        process.stdout.write(out);
+    });
+    create
+        .command('dashboard')
+        .argument('[name]', `Dashboard name (default: <stack>-dashboard in ${DIRS.dashboard})`)
+        .summary(`Scaffold the UI dashboard into ${DIRS.dashboard}`)
+        .description(`Scaffold the MDK UI shell into <dir>/${DIRS.dashboard}, named <stack>-dashboard from mdk.yaml. ` +
+        `With a name it goes to <dir>/${DIRS.apps}/<name> instead.`)
+        .option('--dir <path>', 'Project directory', '.')
+        .option('--ref <git-ref>', 'Branch, tag or SHA to fetch the UI shell from', defaultTemplateRef())
+        .option('--force', 'Overwrite the target if it already exists', false)
+        .option('--no-install', 'Skip `npm install`')
+        .addHelpText('after', examples('mdk create dashboard', 'mdk create dashboard ops-ui --ref v0.10.0'))
+        .action(async (name, opts) => {
+        const app = resolveDashboard(name, opts.dir);
+        if (!app) {
+            process.stderr.write('mdk create dashboard: pass a name, or run from a directory with mdk.yaml (uses <stack>-dashboard).\n');
+            process.exitCode = 1;
+            return;
+        }
+        if ('error' in app) {
+            process.stderr.write(`mdk create dashboard: ${app.error}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const result = await createDashboard({
+            name: app.name,
+            subdir: app.subdir,
+            parentDir: opts.dir,
+            ref: opts.ref,
+            force: opts.force,
+            install: opts.install,
+        });
+        if (result.ok) {
+            if (result.installWarning) {
+                process.stderr.write(`${theme.warn('warning')}: ${result.installWarning} ` +
+                    `${theme.muted(`(run \`npm install\` in ${result.appPath})`)}\n`);
+            }
+            const from = result.source === 'monorepo' ? 'local monorepo template' : 'GitHub template';
+            const out = `Scaffolded ${result.appPath} ${theme.muted(`(${from})`)}\n` +
+                `\n${theme.label('Next steps')}\n` +
+                `  ${theme.muted('1.')} Edit ${theme.value(`${result.appPath}/.env`)} if you need a different Gateway/OAuth URL.\n` +
+                `  ${theme.muted('2.')} Run it: ${theme.cmd(`mdk run dashboard --dir ${opts.dir}`)}\n`;
+            process.stdout.write(out);
+            return;
+        }
+        process.stderr.write(`mdk create dashboard: ${result.message}\n`);
+        if (result.detail)
+            process.stderr.write(`${result.detail}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=create.js.map

package/dist/commands/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAClG,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;GAOG;AACH,SAAS,gBAAgB,CACvB,QAA4B,EAC5B,SAAiB;IAEjB,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,EAAE,KAAK,EAAE,2BAA2B,QAAQ,oDAAoD,EAAE,CAAC;QAC5G,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAChD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,KAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAsC,CAAC;QAC3F,KAAK,GAAG,OAAO,GAAG,CAAC,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,IAAI,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,2BAA2B,KAAK,kGAAkG;SAC1I,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;AAC1C,CAAC;AAED,qBAAqB;AACrB,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,MAAM,MAAM,GAAG,OAAO;SACnB,OAAO,CAAC,QAAQ,CAAC;SACjB,KAAK,CAAC,qBAAqB,CAAC;SAC5B,OAAO,CAAC,qCAAqC,CAAC;SAC9C,WAAW,CAAC,iGAAiG,CAAC;SAC9G,WAAW,CACV,OAAO,EACP,QAAQ,CAAC,uBAAuB,EAAE,0CAA0C,EAAE,sBAAsB,CAAC,CACtG,CAAC;IAEJ,MAAM;SACH,OAAO,CAAC,QAAQ,CAAC;SACjB,QAAQ,CAAC,QAAQ,EAAE,yDAAyD,CAAC;SAC7E,OAAO,CAAC,8CAA8C,CAAC;SACvD,WAAW,CACV,sGAAsG;QACpG,yFAAyF,CAC5F;SACA,MAAM,CAAC,eAAe,EAAE,mEAAmE,CAAC;SAC5F,MAAM,CAAC,cAAc,EAAE,mBAAmB,EAAE,GAAG,CAAC;SAChD,MAAM,CAAC,SAAS,EAAE,2CAA2C,EAAE,KAAK,CAAC;SACrE,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAAC;SAC5C,MAAM,CAAC,kBAAkB,EAAE,mCAAmC,CAAC;SAC/D,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,uBAAuB,EAAE,mDAAmD,CAAC,CAAC;SAC5G,MAAM,CACL,CACE,IAAY,EACZ,IAA0F,EAC1F,EAAE;QACF,MAAM,MAAM,GAAG,YAAY,CAAC;YAC1B,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,UAAU;SACjC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YACpE,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YAC9D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC,cAAc,GAAG;gBACnD,GAAG,KAAK,CAAC,KAAK,CAAC,2BAA2B,MAAM,CAAC,UAAU,GAAG,CAAC,IAAI,CACtE,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,GACL,GAAG,IAAI,sBAAsB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,UAAW,CAAC,IAAI;YAC9F,KAAK,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,WAAY,CAAC,IAAI,CAAC;QAEtE,uEAAuE;QACvE,8CAA8C;QAC9C,MAAM,aAAa,GACjB,GAAG,KAAK,CAAC,GAAG,CACV,eAAe,IAAI,IAAI;YACrB,kBAAkB,MAAM,CAAC,UAAU,IAAI;YACvC,iBAAiB;YACjB,sBAAsB;YACtB,oBAAoB;YACpB,mBAAmB,QAAQ,CAAC,IAAI,CAAC,IAAI;YACrC,8CAA8C,MAAM,CAAC,QAAQ,aAAa,YAAY,CAAC,IAAI,CAAC,IAAI,CACnG,IAAI,CAAC;QAER,QAAQ,MAAM,CAAC,SAAS,EAAE,CAAC;YACzB,KAAK,OAAO;gBACV,GAAG,IAAI,KAAK,IAAI,aAAa,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC;gBAC5F,MAAM;YACR,KAAK,QAAQ;gBACX,GAAG,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,6BAA6B,IAAI,gCAAgC,CAAC,IAAI,CAAC;gBAC/F,MAAM;YACR,KAAK,YAAY;gBACf,GAAG,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,6CAA6C,IAAI,oDAAoD,CAAC;gBACjI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;gBACrB,MAAM;YACR,KAAK,SAAS;gBACZ,GAAG;oBACD,KAAK,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,0BAA0B,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI;wBACtH,qBAAqB,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,0BAA0B;wBACxE,aAAa,CAAC;gBAChB,MAAM;YACR,KAAK,OAAO;gBACV,GAAG;oBACD,KAAK,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,oBAAoB,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO;wBAC9G,aAAa,CAAC;gBAChB,MAAM;YACR;gBACE,mBAAmB;gBACnB,GAAG;oBACD,KAAK,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,OAAO;wBACpG,aAAa,CAAC;QACpB,CAAC;QAED,GAAG;YACD,KAAK,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI;gBAClC,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,qBAAqB;gBACpJ,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,IAAI,CAAC;QAE5E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC,CACF,CAAC;IAEJ,MAAM;SACH,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,QAAQ,EAAE,sDAAsD,CAAC;SAC1E,OAAO,CAAC,wBAAwB,IAAI,CAAC,IAAI,SAAS,CAAC;SACnD,WAAW,CACV,uGAAuG;QACrG,cAAc,IAAI,CAAC,IAAI,4EAA4E,CACtG;SACA,MAAM,CAAC,eAAe,EAAE,mEAAmE,CAAC;SAC5F,MAAM,CAAC,cAAc,EAAE,mBAAmB,EAAE,GAAG,CAAC;SAChD,MAAM,CAAC,SAAS,EAAE,2CAA2C,EAAE,KAAK,CAAC;SACrE,MAAM,CAAC,cAAc,EAAE,gDAAgD,CAAC;SACxE,MAAM,CAAC,kBAAkB,EAAE,gCAAgC,CAAC;SAC5D,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,2BAA2B,EAAE,0CAA0C,CAAC,CAAC;SACvG,MAAM,CACL,CACE,IAAY,EACZ,IAA0F,EAC1F,EAAE;QACF,MAAM,MAAM,GAAG,SAAS,CAAC;YACvB,IAAI;YACJ,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,UAAU;SACjC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YACpE,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YAC9D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC,cAAc,GAAG;gBACnD,GAAG,KAAK,CAAC,KAAK,CAAC,2BAA2B,MAAM,CAAC,UAAU,GAAG,CAAC,IAAI,CACtE,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,GACL,GAAG,IAAI,mBAAmB,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,OAAQ,CAAC,IAAI;YACxF,KAAK,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,WAAY,CAAC,IAAI;YACnE,CAAC,MAAM,CAAC,OAAO;gBACb,CAAC,CAAC,KAAK,IAAI,yBAAyB,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAC,IAAI;gBACjH,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,0BAA0B,MAAM,CAAC,SAAS,IAAI;oBAClE,OAAO,KAAK,CAAC,KAAK,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,qDAAqD,CAAC,IAAI,CAAC,CAAC;QAE5I,uEAAuE;QACvE,mDAAmD;QACnD,MAAM,aAAa,GACjB,GAAG,KAAK,CAAC,GAAG,CAAC,eAAe,MAAM,CAAC,OAAO,oBAAoB,MAAM,CAAC,WAAW,oBAAoB,CAAC,IAAI,CAAC;QAE5G,QAAQ,MAAM,CAAC,SAAS,EAAE,CAAC;YACzB,KAAK,OAAO;gBACV,GAAG,IAAI,KAAK,IAAI,aAAa,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC;gBACzF,MAAM;YACR,KAAK,QAAQ;gBACX,GAAG,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,4BAA4B,MAAM,CAAC,WAAW,oBAAoB,CAAC,IAAI,CAAC;gBAChG,MAAM;YACR,KAAK,YAAY;gBACf,GAAG,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,wCAAwC,MAAM,CAAC,OAAO,oDAAoD,CAAC;gBACtI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;gBACrB,MAAM;YACR,KAAK,SAAS;gBACZ,GAAG;oBACD,KAAK,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,0BAA0B,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI;wBACtH,qBAAqB,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,0BAA0B;wBACrE,aAAa,CAAC;gBAChB,MAAM;YACR,KAAK,OAAO;gBACV,GAAG;oBACD,KAAK,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,oBAAoB,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO;wBAC3G,aAAa,CAAC;gBAChB,MAAM;YACR;gBACE,mBAAmB;gBACnB,GAAG;oBACD,KAAK,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO;wBACjG,aAAa,CAAC;QACpB,CAAC;QAED,GAAG;YACD,KAAK,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI;gBAClC,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,KAAK,CAAC,wBAAwB,CAAC,MAAM,KAAK,CAAC,KAAK,CAAC,qBAAqB,CAAC,KAAK;gBAC1H,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,oBAAoB,KAAK,CAAC,GAAG,CAAC,oBAAoB,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI;gBACtL,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,qBAAqB,MAAM,CAAC,OAAO,2BAA2B,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,kBAAkB;gBAC/L,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,kBAAkB,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,QAAQ,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,yBAAyB,CAAC;QAE7K,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC,CACF,CAAC;IAEJ,MAAM;SACH,OAAO,CAAC,WAAW,CAAC;SACpB,QAAQ,CAAC,QAAQ,EAAE,iDAAiD,IAAI,CAAC,SAAS,GAAG,CAAC;SACtF,OAAO,CAAC,kCAAkC,IAAI,CAAC,SAAS,EAAE,CAAC;SAC3D,WAAW,CACV,wCAAwC,IAAI,CAAC,SAAS,2CAA2C;QAC/F,gCAAgC,IAAI,CAAC,IAAI,kBAAkB,CAC9D;SACA,MAAM,CAAC,cAAc,EAAE,mBAAmB,EAAE,GAAG,CAAC;SAChD,MAAM,CAAC,iBAAiB,EAAE,+CAA+C,EAAE,kBAAkB,EAAE,CAAC;SAChG,MAAM,CAAC,SAAS,EAAE,2CAA2C,EAAE,KAAK,CAAC;SACrE,MAAM,CAAC,cAAc,EAAE,oBAAoB,CAAC;SAC5C,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,sBAAsB,EAAE,2CAA2C,CAAC,CAAC;SACnG,MAAM,CACL,KAAK,EACH,IAAwB,EACxB,IAAoE,EACpE,EAAE;QACF,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,sGAAsG,CACvG,CAAC;YACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC;YAC7D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC;YACnC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG;YACnB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;gBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,CAAC,cAAc,GAAG;oBACnD,GAAG,KAAK,CAAC,KAAK,CAAC,2BAA2B,MAAM,CAAC,OAAO,GAAG,CAAC,IAAI,CACnE,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GACR,MAAM,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,iBAAiB,CAAC;YAC/E,MAAM,GAAG,GACP,cAAc,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI;gBAC5D,KAAK,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI;gBAClC,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,OAAO,CAAC,+CAA+C;gBACnH,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,GAAG,CAAC,2BAA2B,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;YACzF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;QAClE,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;QAC9D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CACF,CAAC;AACN,CAAC","sourcesContent":["import type { Command } from 'commander';\nimport { examples } from '../lib/help.js';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\nimport { createDashboard, dashboardNameFromStack, defaultTemplateRef } from '../lib/dashboard.js';\nimport { NAME_RE } from '../lib/names.js';\nimport { createWorker } from '../lib/worker-scaffold.js';\nimport { deviceId, deviceSerial } from '../lib/spec.js';\nimport { createApp } from '../lib/app-scaffold.js';\nimport { DIRS } from '../lib/project.js';\nimport { theme, tick, arrow } from '../lib/theme.js';\n\n/**\n * Resolves the dashboard's package name and its location.\n *\n * With no name the app takes the canonical `apps/dashboard` path and a\n * `<stack>-dashboard` package name read from mdk.yaml — so the path never churns\n * when the stack is renamed. An explicit name gets its own `apps/<name>` slot,\n * which is how a project ends up with more than one dashboard.\n */\nfunction resolveDashboard(\n  explicit: string | undefined,\n  parentDir: string,\n): { name: string; subdir: string } | { error: string } | null {\n  if (explicit) {\n    const name = explicit.trim();\n    if (!NAME_RE.test(name)) {\n      return { error: `invalid dashboard name \"${explicit}\". Use lowercase letters, digits, '.', '_' or '-'.` };\n    }\n    return { name, subdir: join(DIRS.apps, name) };\n  }\n\n  const specPath = resolve(parentDir, 'mdk.yaml');\n  if (!existsSync(specPath)) return null;\n  let stack: string | undefined;\n  try {\n    const doc = parseYaml(readFileSync(specPath, 'utf8')) as { metadata?: { name?: unknown } };\n    stack = typeof doc.metadata?.name === 'string' ? doc.metadata.name.trim() : undefined;\n  } catch {\n    return null;\n  }\n  if (!stack) return null;\n  const name = dashboardNameFromStack(stack);\n  if (!NAME_RE.test(name)) {\n    return {\n      error: `mdk.yaml metadata.name \"${stack}\" is not a valid name. Use lowercase letters, digits, '.', '_' or '-', or pass a dashboard name.`,\n    };\n  }\n  return { name, subdir: DIRS.dashboard };\n}\n\n// Group B — Scaffold\nexport function registerCreate(program: Command): void {\n  const create = program\n    .command('create')\n    .usage('<command> [options]')\n    .summary('Scaffold a worker, app or dashboard')\n    .description('Scaffold a new worker, app or dashboard from the bundled templates and register it in mdk.yaml.')\n    .addHelpText(\n      'after',\n      examples('mdk create worker rig', 'mdk create app ops-center --org your-org', 'mdk create dashboard'),\n    );\n\n  create\n    .command('worker')\n    .argument('<name>', \"Worker name: lowercase letters, digits, '.', '_' or '-'\")\n    .summary('Scaffold a Worker Plugin into workers/<name>')\n    .description(\n      'Scaffold a Worker Plugin (mdk-contract.json, handlers and a mock device) into <dir>/workers/<name>, ' +\n        'link it into package.json and add it to mdk.yaml under spec.workers with a mock device.',\n    )\n    .option('--org <scope>', 'npm scope for the package name, e.g. your-org -> @your-org/<name>')\n    .option('--dir <path>', 'Project directory', '.')\n    .option('--force', 'Overwrite the target if it already exists', false)\n    .option('--no-install', 'Skip `npm install`')\n    .option('--no-stack-entry', 'Do not add the worker to mdk.yaml')\n    .addHelpText('after', examples('mdk create worker rig', 'mdk create worker rig --org your-org --no-install'))\n    .action(\n      (\n        name: string,\n        opts: { org?: string; dir: string; force: boolean; install: boolean; stackEntry: boolean },\n      ) => {\n        const result = createWorker({\n          name,\n          parentDir: opts.dir,\n          org: opts.org,\n          force: opts.force,\n          install: opts.install,\n          updateStackFile: opts.stackEntry,\n        });\n        if (!result.ok) {\n          process.stderr.write(`${theme.warn('error')}: ${result.message}\\n`);\n          if (result.detail) process.stderr.write(`${result.detail}\\n`);\n          process.exitCode = 1;\n          return;\n        }\n\n        if (result.installWarning) {\n          process.stderr.write(\n            `${theme.warn('warning')}: ${result.installWarning} ` +\n              `${theme.muted(`(run \\`npm install\\` in ${result.installDir})`)}\\n`,\n          );\n        }\n\n        let out =\n          `${tick} Scaffolded worker ${theme.label(name)} ${arrow} ${theme.value(result.workerPath!)}\\n` +\n          `  ${theme.muted('package')} ${theme.value(result.packageName!)}\\n`;\n\n        // Report how mdk.yaml was touched, and fall back to the manual snippet\n        // when it could not be updated automatically.\n        const manualSnippet =\n          `${theme.cmd(\n            `    - name: ${name}\\n` +\n              `      package: ${result.relPackage}\\n` +\n              `      config:\\n` +\n              `        mock: true\\n` +\n              `        devices:\\n` +\n              `          - id: ${deviceId(name)}\\n` +\n              `            opts: { host: 127.0.0.1, port: ${result.mockPort}, serial: ${deviceSerial(name)} }`,\n          )}\\n`;\n\n        switch (result.stackFile) {\n          case 'added':\n            out += `  ${tick} Added to ${theme.value('mdk.yaml')} under ${theme.key('spec.workers')}\\n`;\n            break;\n          case 'exists':\n            out += `  ${theme.muted(`spec.workers already has \"${name}\" in mdk.yaml — left unchanged`)}\\n`;\n            break;\n          case 'name-taken':\n            out += `  ${theme.warn('!')} spec.workers already has a worker named \"${name}\" with another package; mdk.yaml was not changed\\n`;\n            process.exitCode = 1;\n            break;\n          case 'no-file':\n            out +=\n              `\\n${theme.warn('No mdk.yaml found')} in ${theme.value(opts.dir)}. Start a project with ${theme.cmd('mdk onboard')}, ` +\n              `or add this under ${theme.key('spec.workers')} of an existing one:\\n\\n` +\n              manualSnippet;\n            break;\n          case 'error':\n            out +=\n              `\\n${theme.warn('Could not update mdk.yaml automatically')}. Add this under ${theme.key('spec.workers')}:\\n\\n` +\n              manualSnippet;\n            break;\n          default:\n            // --no-stack-entry\n            out +=\n              `\\n${theme.muted('Add this to')} ${theme.value('mdk.yaml')} under ${theme.key('spec.workers')}:\\n\\n` +\n              manualSnippet;\n        }\n\n        out +=\n          `\\n${theme.label('Next steps')}\\n` +\n          `  ${theme.muted('1.')} Customize ${theme.value('mdk-contract.json')}, ${theme.value('src/')} + ${theme.value('mock/server.js')} for your device.\\n` +\n          `  ${theme.muted('2.')} Run it: ${theme.cmd(`mdk run worker ${name}`)}\\n`;\n\n        process.stdout.write(out);\n      },\n    );\n\n  create\n    .command('app')\n    .argument('<name>', \"App name: lowercase letters, digits, '.', '_' or '-'\")\n    .summary(`Scaffold an app into ${DIRS.apps}/<name>`)\n    .description(\n      `Scaffold an app (mdk-app.yaml, plugin/ route table and controllers, and a starter UI built into ui/) ` +\n        `into <dir>/${DIRS.apps}/<name>, link it into package.json and add it to mdk.yaml under spec.apps.`,\n    )\n    .option('--org <scope>', 'npm scope for the package name, e.g. your-org -> @your-org/<name>')\n    .option('--dir <path>', 'Project directory', '.')\n    .option('--force', 'Overwrite the target if it already exists', false)\n    .option('--no-install', 'Skip `npm install` and building the starter UI')\n    .option('--no-stack-entry', 'Do not add the app to mdk.yaml')\n    .addHelpText('after', examples('mdk create app ops-center', 'mdk create app ops-center --org your-org'))\n    .action(\n      (\n        name: string,\n        opts: { org?: string; dir: string; force: boolean; install: boolean; stackEntry: boolean },\n      ) => {\n        const result = createApp({\n          name,\n          parentDir: opts.dir,\n          org: opts.org,\n          force: opts.force,\n          install: opts.install,\n          updateStackFile: opts.stackEntry,\n        });\n        if (!result.ok) {\n          process.stderr.write(`${theme.warn('error')}: ${result.message}\\n`);\n          if (result.detail) process.stderr.write(`${result.detail}\\n`);\n          process.exitCode = 1;\n          return;\n        }\n\n        if (result.installWarning) {\n          process.stderr.write(\n            `${theme.warn('warning')}: ${result.installWarning} ` +\n              `${theme.muted(`(run \\`npm install\\` in ${result.installDir})`)}\\n`,\n          );\n        }\n\n        let out =\n          `${tick} Scaffolded app ${theme.label(name)} ${arrow} ${theme.value(result.appPath!)}\\n` +\n          `  ${theme.muted('package')} ${theme.value(result.packageName!)}\\n` +\n          (result.uiBuilt\n            ? `  ${tick} Built the starter UI ${arrow} ${theme.value('ui/index.js')} ${theme.muted('(source in ui-src/)')}\\n`\n            : `  ${theme.warn('!')} Starter UI not built: ${result.uiWarning}\\n` +\n              `    ${theme.muted('Build it yourself:')} ${theme.cmd(`cd ${result.appPath} && npm --prefix ui-src install && npm run build:ui`)}\\n`);\n\n        // Apps are referenced by package name (resolved via the `file:` link),\n        // so the manual snippet uses the package name too.\n        const manualSnippet =\n          `${theme.cmd(`    - name: ${result.appName}\\n      package: ${result.packageName}\\n      config: {}`)}\\n`;\n\n        switch (result.stackFile) {\n          case 'added':\n            out += `  ${tick} Added to ${theme.value('mdk.yaml')} under ${theme.key('spec.apps')}\\n`;\n            break;\n          case 'exists':\n            out += `  ${theme.muted(`spec.apps already lists \"${result.packageName}\" — left unchanged`)}\\n`;\n            break;\n          case 'name-taken':\n            out += `  ${theme.warn('!')} spec.apps already has an app named \"${result.appName}\" with another package; mdk.yaml was not changed\\n`;\n            process.exitCode = 1;\n            break;\n          case 'no-file':\n            out +=\n              `\\n${theme.warn('No mdk.yaml found')} in ${theme.value(opts.dir)}. Start a project with ${theme.cmd('mdk onboard')}, ` +\n              `or add this under ${theme.key('spec.apps')} of an existing one:\\n\\n` +\n              manualSnippet;\n            break;\n          case 'error':\n            out +=\n              `\\n${theme.warn('Could not update mdk.yaml automatically')}. Add this under ${theme.key('spec.apps')}:\\n\\n` +\n              manualSnippet;\n            break;\n          default:\n            // --no-stack-entry\n            out +=\n              `\\n${theme.muted('Add this to')} ${theme.value('mdk.yaml')} under ${theme.key('spec.apps')}:\\n\\n` +\n              manualSnippet;\n        }\n\n        out +=\n          `\\n${theme.label('Next steps')}\\n` +\n          `  ${theme.muted('1.')} Add routes in ${theme.value('plugin/mdk-plugin.json')} + ${theme.value('plugin/controllers/')}.\\n` +\n          `  ${theme.muted('2.')} Set ${theme.key('id')} and ${theme.key('permissions')} in ${theme.value('mdk-app.yaml')}, then check it: ${theme.cmd(`mdk validate app ${result.appName}`)}\\n` +\n          `  ${theme.muted('3.')} Run it: ${theme.cmd('mdk run')} ${theme.muted(`(or \\`mdk run app ${result.appName}\\` + \\`mdk run gateway\\`)`)}, then ${theme.cmd('mdk run dashboard')} to see its UI\\n` +\n          `  ${theme.muted('4.')} Edit the UI in ${theme.value('ui-src/')}; rebuild with ${theme.cmd('npm run build:ui')} (or ${theme.cmd('npm run dev:ui')} to rebuild on save).\\n`;\n\n        process.stdout.write(out);\n      },\n    );\n\n  create\n    .command('dashboard')\n    .argument('[name]', `Dashboard name (default: <stack>-dashboard in ${DIRS.dashboard})`)\n    .summary(`Scaffold the UI dashboard into ${DIRS.dashboard}`)\n    .description(\n      `Scaffold the MDK UI shell into <dir>/${DIRS.dashboard}, named <stack>-dashboard from mdk.yaml. ` +\n        `With a name it goes to <dir>/${DIRS.apps}/<name> instead.`,\n    )\n    .option('--dir <path>', 'Project directory', '.')\n    .option('--ref <git-ref>', 'Branch, tag or SHA to fetch the UI shell from', defaultTemplateRef())\n    .option('--force', 'Overwrite the target if it already exists', false)\n    .option('--no-install', 'Skip `npm install`')\n    .addHelpText('after', examples('mdk create dashboard', 'mdk create dashboard ops-ui --ref v0.10.0'))\n    .action(\n      async (\n        name: string | undefined,\n        opts: { dir: string; ref: string; force: boolean; install: boolean },\n      ) => {\n        const app = resolveDashboard(name, opts.dir);\n        if (!app) {\n          process.stderr.write(\n            'mdk create dashboard: pass a name, or run from a directory with mdk.yaml (uses <stack>-dashboard).\\n',\n          );\n          process.exitCode = 1;\n          return;\n        }\n        if ('error' in app) {\n          process.stderr.write(`mdk create dashboard: ${app.error}\\n`);\n          process.exitCode = 1;\n          return;\n        }\n        const result = await createDashboard({\n          name: app.name,\n          subdir: app.subdir,\n          parentDir: opts.dir,\n          ref: opts.ref,\n          force: opts.force,\n          install: opts.install,\n        });\n        if (result.ok) {\n          if (result.installWarning) {\n            process.stderr.write(\n              `${theme.warn('warning')}: ${result.installWarning} ` +\n                `${theme.muted(`(run \\`npm install\\` in ${result.appPath})`)}\\n`,\n            );\n          }\n          const from =\n            result.source === 'monorepo' ? 'local monorepo template' : 'GitHub template';\n          const out =\n            `Scaffolded ${result.appPath} ${theme.muted(`(${from})`)}\\n` +\n            `\\n${theme.label('Next steps')}\\n` +\n            `  ${theme.muted('1.')} Edit ${theme.value(`${result.appPath}/.env`)} if you need a different Gateway/OAuth URL.\\n` +\n            `  ${theme.muted('2.')} Run it: ${theme.cmd(`mdk run dashboard --dir ${opts.dir}`)}\\n`;\n          process.stdout.write(out);\n          return;\n        }\n        process.stderr.write(`mdk create dashboard: ${result.message}\\n`);\n        if (result.detail) process.stderr.write(`${result.detail}\\n`);\n        process.exitCode = 1;\n      },\n    );\n}\n"]}

package/dist/commands/inspect.js

@@ -0,0 +1,171 @@
+import { examples } from '../lib/help.js';
+import { stringify as toYaml } from 'yaml';
+import { collectStatus } from '../lib/status.js';
+import { STACK_FILE } from '../lib/spec.js';
+import { theme, tick } from '../lib/theme.js';
+// Group C — Run & manage (read-only inspection commands)
+const OUTPUT_FORMATS = ['table', 'json', 'yaml'];
+/** Green when healthy, yellow otherwise — the same convention across sections. */
+function flag(ok, label) {
+    return ok ? theme.ok(label) : theme.warn(label);
+}
+/**
+ * Renders a probe failure for humans. Bare error codes (`ERR_MDK_STATUS_TIMEOUT`,
+ * `CHANNEL_CLOSED: channel closed`) mean nothing on their own, so they get a
+ * plain-English lead-in; anything already written as prose is shown as-is. The
+ * untouched value stays in `-o json` for scripts.
+ */
+function humanError(error) {
+    if (!error)
+        return null;
+    const first = error.split('\n')[0] ?? '';
+    const code = (first.split(':')[0] ?? '').trim();
+    return /^[A-Z][A-Z0-9_]*$/.test(code) ? `unreachable (${code})` : first;
+}
+/**
+ * Left-aligned columns padded to the widest cell, with an optional header row.
+ * Padding counts raw string length, so only the last column may carry color.
+ */
+function columns(headers, rows) {
+    const count = Math.max(headers?.length ?? 0, ...rows.map((r) => r.length));
+    const widths = Array.from({ length: count }, (_, i) => Math.max(headers?.[i]?.length ?? 0, ...rows.map((r) => (r[i] ?? '').length)));
+    const line = (cells) => cells
+        .map((c, i) => (i === count - 1 ? c : c.padEnd(widths[i] ?? 0)))
+        .join('  ')
+        .trimEnd();
+    const body = rows.map((r) => `  ${line(r)}`);
+    return headers ? [`  ${theme.muted(line(headers))}`, ...body].join('\n') : body.join('\n');
+}
+function workerRows(items) {
+    return items.map((w) => [
+        w.name,
+        w.registered ? 'yes' : 'no',
+        w.state ?? '-',
+        w.health ?? '-',
+        String(w.devices),
+        w.declared ? '' : 'not in spec',
+    ]);
+}
+function appRows(items) {
+    return items.map((a) => [
+        a.name,
+        a.running ? 'yes' : 'no',
+        a.pid === null ? '-' : String(a.pid),
+        a.version ?? '-',
+        a.mount,
+        a.package,
+    ]);
+}
+/** Human-readable report: environment first, then the running stack. */
+function renderTable(report) {
+    const { environment: env, stack } = report;
+    const out = [];
+    const title = [
+        theme.brand('MDK status'),
+        env.spec.stack ? theme.value(env.spec.stack) : theme.muted('(no stack)'),
+    ]
+        .filter(Boolean)
+        .join('  ');
+    // The project path goes on its own line so it cannot stretch the table below.
+    out.push('', title, theme.muted(report.project), '');
+    out.push(theme.label('Environment'));
+    out.push(columns(null, [
+        [
+            'Node',
+            `v${env.node.version}`,
+            flag(env.node.ok, env.node.ok ? 'ok' : `need ${env.node.required}`),
+        ],
+        ['Package manager', env.packageManager, ''],
+        [
+            'Spec',
+            STACK_FILE,
+            env.spec.valid ? theme.ok('ok') : theme.warn(env.spec.found ? 'invalid' : 'missing'),
+        ],
+        [
+            'Dependencies',
+            `${env.dependencies.checked} declared`,
+            flag(env.dependencies.ok, env.dependencies.ok ? 'ok' : `${env.dependencies.missing.length} not installed`),
+        ],
+    ]));
+    if (env.spec.error) {
+        for (const line of env.spec.error.split('\n'))
+            out.push(theme.muted(`    ${line}`));
+    }
+    for (const pkg of env.dependencies.missing) {
+        out.push(theme.muted(`    not installed: ${pkg}`));
+    }
+    // Only the trailing cell is colored, so the columns stay aligned.
+    const detail = (component, upDetail) => {
+        const note = component.state === 'up' ? upDetail : humanError(component.error) ?? 'not running';
+        return `${flag(component.state === 'up', component.state.padEnd(4))}  ${theme.muted(note)}`;
+    };
+    out.push('', theme.label('Stack'));
+    out.push(columns(null, [
+        ['Kernel', detail(stack.kernel, stack.kernel.key?.slice(0, 16) ?? '')],
+        ['Gateway', detail(stack.gateway, stack.gateway.url ?? '')],
+        [
+            'Workers',
+            `${stack.workers.registered}/${stack.workers.declared} registered  ` +
+                theme.muted(`${stack.workers.totalDevices} device${stack.workers.totalDevices === 1 ? '' : 's'}`),
+        ],
+        ['Apps', `${stack.apps.running}/${stack.apps.declared} running`],
+    ]));
+    if (stack.workers.items.length) {
+        out.push('', columns(['WORKER', 'REGISTERED', 'STATE', 'HEALTH', 'DEVICES', ''], workerRows(stack.workers.items)));
+    }
+    if (stack.apps.items.length) {
+        out.push('', columns(['APP', 'RUNNING', 'PID', 'VERSION', 'MOUNT', 'PACKAGE'], appRows(stack.apps.items)));
+    }
+    const health = report.health === 'healthy'
+        ? theme.ok('healthy')
+        : report.health === 'degraded'
+            ? theme.warn('degraded')
+            : theme.warn('down');
+    out.push('', `${report.ok ? tick : theme.warn('!')} Health: ${health}`, '');
+    return out.join('\n');
+}
+/**
+ * Exit codes are part of the CLI contract (see the HLD §3.3):
+ *   4 — precondition not met (old Node, missing/invalid spec, packages not installed)
+ *   5 — stack not fully up (Kernel/Gateway unreachable, a declared worker is
+ *       not registered/serving, or a declared app is not running)
+ */
+function exitCodeFor(report) {
+    const env = report.environment;
+    if (!env.node.ok || !env.spec.valid || !env.dependencies.ok)
+        return 4;
+    return report.health === 'healthy' ? 0 : 5;
+}
+export function registerStatus(program) {
+    program
+        .command('status')
+        .summary('Check the environment and every component')
+        .description('One-shot check of the environment and every component (Kernel, Gateway, workers and their device ' +
+        'counts, apps). Starts, stops and repairs nothing; its only write is the CLI key it publishes to ' +
+        '.mdk/trusted-keys so the Kernel answers it. Use the global -o json | yaml for machine-readable output.')
+        .addHelpText('after', examples('mdk status', 'mdk status -o json'))
+        .option('-d, --dir <path>', 'Project directory containing mdk.yaml', '.')
+        .action(async (options, cmd) => {
+        const output = String(cmd.optsWithGlobals().output ?? 'table');
+        if (!OUTPUT_FORMATS.includes(output)) {
+            process.stderr.write(`${theme.warn('error')}: unknown --output "${output}". Use one of: ${OUTPUT_FORMATS.join(' | ')}.\n`);
+            process.exit(2);
+        }
+        let report;
+        try {
+            report = await collectStatus(options.dir);
+        }
+        catch (error) {
+            process.stderr.write(`${theme.warn('error')}: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+        if (output === 'json')
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        else if (output === 'yaml')
+            process.stdout.write(toYaml(report));
+        else
+            process.stdout.write(`${renderTable(report)}\n`);
+        process.exitCode = exitCodeFor(report);
+    });
+}
+//# sourceMappingURL=inspect.js.map