@tetherto/mdk-cli 0.0.0 → 0.12.1

package/dist/lib/app-ui-check.js

@@ -0,0 +1,178 @@
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * The bare imports a dashboard lends to the app UIs it loads (import map), so
+ * the only ones an app's built `ui/` may leave unresolved. A copy of
+ * `MDK_APP_SHARED_MODULES` in `@tetherto/mdk-ui-foundation` — the CLI does not
+ * depend on the UI packages; a test fails if the two drift.
+ */
+export const APP_UI_SHARED_MODULES = [
+    'react',
+    'react/jsx-runtime',
+    'react-dom',
+    'react-router',
+    '@tanstack/react-query',
+    '@tetherto/mdk-ui-foundation',
+    '@tetherto/mdk-react-adapter',
+    '@tetherto/mdk-react-devkit',
+];
+const SHARED = new Set(APP_UI_SHARED_MODULES);
+// Static `import … from '…'`, `import '…'` and `export … from '…'`, at the
+// start of a statement, and dynamic `import('…')`. Built ES modules (what
+// `ui/` holds) write them this plainly; syntax is checked by Node separately.
+const STATIC_IMPORT = /(?:^|[;\n}])\s*(import|export)\s*(?:([\w$\s{},*]*?)\s*from\s*)?(['"])([^'"\n]+)\3/g;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*(['"])([^'"\n]+)\1\s*\)/g;
+// React 19 keeps its internals under this key in every build of `react` and
+// `react-dom`: finding it in ui/ means a copy of React was bundled in.
+const REACT_INTERNALS = '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';
+// Edits within this window of the build are taken as part of it: a fresh clone
+// or copy writes ui/ and ui-src/ moments apart, in any order.
+const STALE_TOLERANCE_MS = 2_000;
+// How long the contract check may run the app's top-level code before giving up.
+const CONTRACT_TIMEOUT_MS = 15_000;
+const isBare = (specifier) => !specifier.startsWith('.') && !specifier.startsWith('/') && !/^[a-z][a-z0-9+.-]*:/i.test(specifier);
+/** The names a statement's clause imports: `{ a, b as c }` → a, b; `x` → default. */
+function importedNames(kind, clause) {
+    if (!clause)
+        return [];
+    const names = [];
+    const braces = clause.match(/\{([^}]*)\}/);
+    if (braces) {
+        for (const part of braces[1].split(',')) {
+            const name = part.trim().split(/\s+as\s+/)[0].trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    // `import x from`, `import x, { … } from` — a default import; `* as ns` is not.
+    const head = clause.replace(/\{[^}]*\}/, '').replace(/,/g, ' ').trim();
+    if (kind === 'import' && head && !head.startsWith('*'))
+        names.push('default');
+    return names;
+}
+/** Every bare import in `source`, with the names imported from each. */
+export function scanImports(source) {
+    const found = new Map();
+    const add = (specifier, names) => {
+        if (!isBare(specifier))
+            return;
+        found.set(specifier, [...(found.get(specifier) ?? []), ...names]);
+    };
+    for (const m of source.matchAll(STATIC_IMPORT))
+        add(m[4], importedNames(m[1], m[2]));
+    for (const m of source.matchAll(DYNAMIC_IMPORT))
+        add(m[2], []);
+    return found;
+}
+/** Files under `dir`, skipping `node_modules`. */
+function listFiles(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        if (entry.name === 'node_modules')
+            return [];
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            return listFiles(full);
+        return entry.isFile() ? [full] : [];
+    });
+}
+/** Node's own parser, without running the code: `node --check` on a `.mjs` copy. */
+function syntaxError(file, label) {
+    const work = mkdtempSync(join(tmpdir(), 'mdk-ui-check-'));
+    try {
+        const copy = join(work, 'module.mjs');
+        copyFileSync(file, copy);
+        const res = spawnSync(process.execPath, ['--check', copy], { encoding: 'utf8' });
+        if (res.status === 0)
+            return undefined;
+        const detail = (res.stderr || '').split('\n').find((line) => /Error/.test(line))?.trim();
+        return `${label} is not a valid JavaScript module${detail ? `: ${detail}` : ''}`;
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+function runnerPath() {
+    const js = join(__dirname, 'app-ui-runner.js');
+    return existsSync(js) ? js : join(__dirname, 'app-ui-runner.ts');
+}
+/**
+ * Checks an app's built UI (`<dir>/ui/`) the way the dashboard will use it:
+ *
+ * - every `.js` file parses as an ES module;
+ * - it does not bundle its own React;
+ * - its bare imports are only the modules the dashboard provides
+ *   ({@link APP_UI_SHARED_MODULES}) — anything else fails to resolve in the
+ *   browser, and a missing `react` import usually means React was bundled in;
+ * - with `runContract`, `ui/index.js` is loaded in a child Node process with
+ *   those imports stubbed, and its default export checked against the app UI
+ *   contract (id matching `mdk-app.yaml`, displayName, routes, panels). This
+ *   runs the app's top-level code, so it is for the author's own package
+ *   (`mdk validate app`), not for installing someone else's;
+ * - `ui-src/` edited after the last build is a warning.
+ */
+export function checkAppUi(dir, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    const uiDir = join(dir, 'ui');
+    const entry = join(uiDir, 'index.js');
+    if (!existsSync(entry))
+        return { errors: ['ui/index.js: not found'], warnings };
+    const imports = new Map();
+    for (const file of listFiles(uiDir).filter((f) => f.endsWith('.js') || f.endsWith('.mjs'))) {
+        const label = relative(dir, file).split(sep).join('/');
+        const bad = syntaxError(file, label);
+        if (bad) {
+            errors.push(bad);
+            continue;
+        }
+        const source = readFileSync(file, 'utf8');
+        if (source.includes(REACT_INTERNALS)) {
+            errors.push(`${label} bundles its own copy of React — leave the shared modules external in the UI build ` +
+                '(rollupOptions.external: MDK_APP_SHARED_MODULES), or hooks break inside the dashboard');
+        }
+        for (const [specifier, names] of scanImports(source)) {
+            if (!SHARED.has(specifier)) {
+                errors.push(`${label} imports "${specifier}", which the dashboard does not provide — bundle it, ` +
+                    `or import only: ${APP_UI_SHARED_MODULES.join(', ')}`);
+            }
+            imports.set(specifier, [...(imports.get(specifier) ?? []), ...names]);
+        }
+    }
+    // A ui-src/ newer than the build means the published UI would be stale.
+    const src = join(dir, 'ui-src');
+    if (existsSync(src)) {
+        const built = statSync(entry).mtimeMs;
+        const newer = listFiles(src).find((file) => statSync(file).mtimeMs > built + STALE_TOLERANCE_MS);
+        if (newer) {
+            warnings.push(`${relative(dir, newer).split(sep).join('/')} changed after ui/ was built — run \`npm run build:ui\``);
+        }
+    }
+    if (opts.runContract && opts.id && !errors.length) {
+        const res = spawnSync(process.execPath, [runnerPath()], {
+            encoding: 'utf8',
+            timeout: CONTRACT_TIMEOUT_MS,
+            env: {
+                ...process.env,
+                MDK_UI_ENTRY: entry,
+                MDK_UI_ID: opts.id,
+                MDK_UI_IMPORTS: JSON.stringify(Object.fromEntries(imports)),
+            },
+        });
+        const line = (res.stdout || '').trim().split('\n').at(-1);
+        try {
+            const result = JSON.parse(line ?? '');
+            errors.push(...result.errors);
+            warnings.push(...result.warnings);
+        }
+        catch {
+            const reason = res.error?.message ?? ((res.stderr || '').trim().split('\n')[0] || `exit code ${res.status}`);
+            warnings.push(`could not check the UI contract (${reason}); the dashboard checks it when it loads the app`);
+        }
+    }
+    return { errors, warnings };
+}
+//# sourceMappingURL=app-ui-check.js.map

package/dist/lib/app-ui-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-ui-check.js","sourceRoot":"","sources":["../../src/lib/app-ui-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawnSync } from 'node:child_process';\nimport { copyFileSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';\nimport { tmpdir } from 'node:os';\nimport { dirname, join, relative, sep } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/**\n * The bare imports a dashboard lends to the app UIs it loads (import map), so\n * the only ones an app's built `ui/` may leave unresolved. A copy of\n * `MDK_APP_SHARED_MODULES` in `@tetherto/mdk-ui-foundation` — the CLI does not\n * depend on the UI packages; a test fails if the two drift.\n */\nexport const APP_UI_SHARED_MODULES = [\n  'react',\n  'react/jsx-runtime',\n  'react-dom',\n  'react-router',\n  '@tanstack/react-query',\n  '@tetherto/mdk-ui-foundation',\n  '@tetherto/mdk-react-adapter',\n  '@tetherto/mdk-react-devkit',\n] as const;\n\nconst SHARED = new Set<string>(APP_UI_SHARED_MODULES);\n\nexport interface AppUiCheck {\n  errors: string[];\n  warnings: string[];\n}\n\n// Static `import … from '…'`, `import '…'` and `export … from '…'`, at the\n// start of a statement, and dynamic `import('…')`. Built ES modules (what\n// `ui/` holds) write them this plainly; syntax is checked by Node separately.\nconst STATIC_IMPORT = /(?:^|[;\\n}])\\s*(import|export)\\s*(?:([\\w$\\s{},*]*?)\\s*from\\s*)?(['\"])([^'\"\\n]+)\\3/g;\nconst DYNAMIC_IMPORT = /\\bimport\\s*\\(\\s*(['\"])([^'\"\\n]+)\\1\\s*\\)/g;\n\n// React 19 keeps its internals under this key in every build of `react` and\n// `react-dom`: finding it in ui/ means a copy of React was bundled in.\nconst REACT_INTERNALS = '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE';\n\n// Edits within this window of the build are taken as part of it: a fresh clone\n// or copy writes ui/ and ui-src/ moments apart, in any order.\nconst STALE_TOLERANCE_MS = 2_000;\n\n// How long the contract check may run the app's top-level code before giving up.\nconst CONTRACT_TIMEOUT_MS = 15_000;\n\nconst isBare = (specifier: string): boolean =>\n  !specifier.startsWith('.') && !specifier.startsWith('/') && !/^[a-z][a-z0-9+.-]*:/i.test(specifier);\n\n/** The names a statement's clause imports: `{ a, b as c }` → a, b; `x` → default. */\nfunction importedNames(kind: string, clause: string | undefined): string[] {\n  if (!clause) return [];\n  const names: string[] = [];\n  const braces = clause.match(/\\{([^}]*)\\}/);\n  if (braces) {\n    for (const part of braces[1]!.split(',')) {\n      const name = part.trim().split(/\\s+as\\s+/)[0]!.trim();\n      if (name) names.push(name);\n    }\n  }\n  // `import x from`, `import x, { … } from` — a default import; `* as ns` is not.\n  const head = clause.replace(/\\{[^}]*\\}/, '').replace(/,/g, ' ').trim();\n  if (kind === 'import' && head && !head.startsWith('*')) names.push('default');\n  return names;\n}\n\n/** Every bare import in `source`, with the names imported from each. */\nexport function scanImports(source: string): Map<string, string[]> {\n  const found = new Map<string, string[]>();\n  const add = (specifier: string, names: string[]): void => {\n    if (!isBare(specifier)) return;\n    found.set(specifier, [...(found.get(specifier) ?? []), ...names]);\n  };\n  for (const m of source.matchAll(STATIC_IMPORT)) add(m[4]!, importedNames(m[1]!, m[2]));\n  for (const m of source.matchAll(DYNAMIC_IMPORT)) add(m[2]!, []);\n  return found;\n}\n\n/** Files under `dir`, skipping `node_modules`. */\nfunction listFiles(dir: string): string[] {\n  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {\n    if (entry.name === 'node_modules') return [];\n    const full = join(dir, entry.name);\n    if (entry.isDirectory()) return listFiles(full);\n    return entry.isFile() ? [full] : [];\n  });\n}\n\n/** Node's own parser, without running the code: `node --check` on a `.mjs` copy. */\nfunction syntaxError(file: string, label: string): string | undefined {\n  const work = mkdtempSync(join(tmpdir(), 'mdk-ui-check-'));\n  try {\n    const copy = join(work, 'module.mjs');\n    copyFileSync(file, copy);\n    const res = spawnSync(process.execPath, ['--check', copy], { encoding: 'utf8' });\n    if (res.status === 0) return undefined;\n    const detail = (res.stderr || '').split('\\n').find((line) => /Error/.test(line))?.trim();\n    return `${label} is not a valid JavaScript module${detail ? `: ${detail}` : ''}`;\n  } finally {\n    rmSync(work, { recursive: true, force: true });\n  }\n}\n\nfunction runnerPath(): string {\n  const js = join(__dirname, 'app-ui-runner.js');\n  return existsSync(js) ? js : join(__dirname, 'app-ui-runner.ts');\n}\n\n/**\n * Checks an app's built UI (`<dir>/ui/`) the way the dashboard will use it:\n *\n * - every `.js` file parses as an ES module;\n * - it does not bundle its own React;\n * - its bare imports are only the modules the dashboard provides\n *   ({@link APP_UI_SHARED_MODULES}) — anything else fails to resolve in the\n *   browser, and a missing `react` import usually means React was bundled in;\n * - with `runContract`, `ui/index.js` is loaded in a child Node process with\n *   those imports stubbed, and its default export checked against the app UI\n *   contract (id matching `mdk-app.yaml`, displayName, routes, panels). This\n *   runs the app's top-level code, so it is for the author's own package\n *   (`mdk validate app`), not for installing someone else's;\n * - `ui-src/` edited after the last build is a warning.\n */\nexport function checkAppUi(dir: string, opts: { id?: string; runContract?: boolean } = {}): AppUiCheck {\n  const errors: string[] = [];\n  const warnings: string[] = [];\n  const uiDir = join(dir, 'ui');\n  const entry = join(uiDir, 'index.js');\n  if (!existsSync(entry)) return { errors: ['ui/index.js: not found'], warnings };\n\n  const imports = new Map<string, string[]>();\n  for (const file of listFiles(uiDir).filter((f) => f.endsWith('.js') || f.endsWith('.mjs'))) {\n    const label = relative(dir, file).split(sep).join('/');\n    const bad = syntaxError(file, label);\n    if (bad) {\n      errors.push(bad);\n      continue;\n    }\n    const source = readFileSync(file, 'utf8');\n    if (source.includes(REACT_INTERNALS)) {\n      errors.push(\n        `${label} bundles its own copy of React — leave the shared modules external in the UI build ` +\n          '(rollupOptions.external: MDK_APP_SHARED_MODULES), or hooks break inside the dashboard',\n      );\n    }\n    for (const [specifier, names] of scanImports(source)) {\n      if (!SHARED.has(specifier)) {\n        errors.push(\n          `${label} imports \"${specifier}\", which the dashboard does not provide — bundle it, ` +\n            `or import only: ${APP_UI_SHARED_MODULES.join(', ')}`,\n        );\n      }\n      imports.set(specifier, [...(imports.get(specifier) ?? []), ...names]);\n    }\n  }\n\n  // A ui-src/ newer than the build means the published UI would be stale.\n  const src = join(dir, 'ui-src');\n  if (existsSync(src)) {\n    const built = statSync(entry).mtimeMs;\n    const newer = listFiles(src).find((file) => statSync(file).mtimeMs > built + STALE_TOLERANCE_MS);\n    if (newer) {\n      warnings.push(`${relative(dir, newer).split(sep).join('/')} changed after ui/ was built — run \\`npm run build:ui\\``);\n    }\n  }\n\n  if (opts.runContract && opts.id && !errors.length) {\n    const res = spawnSync(process.execPath, [runnerPath()], {\n      encoding: 'utf8',\n      timeout: CONTRACT_TIMEOUT_MS,\n      env: {\n        ...process.env,\n        MDK_UI_ENTRY: entry,\n        MDK_UI_ID: opts.id,\n        MDK_UI_IMPORTS: JSON.stringify(Object.fromEntries(imports)),\n      },\n    });\n    const line = (res.stdout || '').trim().split('\\n').at(-1);\n    try {\n      const result = JSON.parse(line ?? '') as AppUiCheck;\n      errors.push(...result.errors);\n      warnings.push(...result.warnings);\n    } catch {\n      const reason = res.error?.message ?? ((res.stderr || '').trim().split('\\n')[0] || `exit code ${res.status}`);\n      warnings.push(`could not check the UI contract (${reason}); the dashboard checks it when it loads the app`);\n    }\n  }\n\n  return { errors, warnings };\n}\n"]}

package/dist/lib/app-ui-runner.js

@@ -0,0 +1,122 @@
+/**
+ * Child process for `checkAppUi`'s contract check: imports an app's built
+ * `ui/index.js` with every bare import replaced by a stub, then checks its
+ * default export against the app UI contract the dashboard enforces
+ * (`checkAppUiModule` in @tetherto/mdk-react-adapter).
+ *
+ * Runs in its own process so the app's top-level code never touches the CLI's
+ * module graph. It has no imports of its own beyond `node:`, so it also runs
+ * as `.ts` (tests) under Node's type stripping.
+ *
+ * Input (env): MDK_UI_ENTRY (absolute path), MDK_UI_ID (expected id),
+ * MDK_UI_IMPORTS (JSON: specifier → the names imported from it).
+ * Output (stdout, one JSON line): { errors: string[], warnings: string[] }.
+ */
+import { registerHooks } from 'node:module';
+import { pathToFileURL } from 'node:url';
+const STUB_PREFIX = 'mdk-ui-stub:';
+// Exports whose real value an app's default export is built from, so a stub
+// would fail the contract check: kept as they are in @tetherto/mdk-react-adapter
+// (a test runs the same modules through both checkers).
+const REAL_EXPORTS = {
+    defineMdkApp: 'export const defineMdkApp = (ui) => ui;',
+    MDK_APP_PANEL_SLOT: "export const MDK_APP_PANEL_SLOT = Object.freeze({ HOME: 'home' });",
+};
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+const entry = process.env.MDK_UI_ENTRY ?? '';
+const expectedId = process.env.MDK_UI_ID ?? '';
+const imports = JSON.parse(process.env.MDK_UI_IMPORTS ?? '{}');
+const isBare = (specifier) => !specifier.startsWith('.') && !specifier.startsWith('/') && !/^[a-z][a-z0-9+.-]*:/i.test(specifier);
+// A value that survives anything top-level code does with an import it got from
+// the dashboard: call it, construct it, read any property of it.
+const stubSource = (specifier) => {
+    const names = imports[specifier] ?? [];
+    const lines = [
+        'const stub = new Proxy(function () {}, {',
+        '  get: (_t, key) => (key === Symbol.toPrimitive ? () => "" : stub),',
+        '  apply: () => stub,',
+        '  construct: () => stub,',
+        '});',
+        'export default stub;',
+    ];
+    for (const name of new Set(names)) {
+        if (name === 'default' || !IDENTIFIER.test(name))
+            continue;
+        lines.push(REAL_EXPORTS[name] ?? `export const ${name} = stub;`);
+    }
+    return lines.join('\n');
+};
+registerHooks({
+    resolve(specifier, context, nextResolve) {
+        if (isBare(specifier))
+            return { url: `${STUB_PREFIX}${specifier}`, shortCircuit: true };
+        return nextResolve(specifier, context);
+    },
+    load(url, context, nextLoad) {
+        if (url.startsWith(STUB_PREFIX)) {
+            return { format: 'module', source: stubSource(url.slice(STUB_PREFIX.length)), shortCircuit: true };
+        }
+        return nextLoad(url, context);
+    },
+});
+const isRecord = (value) => value !== null && typeof value === 'object';
+const isComponent = (value) => typeof value === 'function' || (isRecord(value) && '$$typeof' in value);
+const errors = [];
+const warnings = [];
+function checkContract(ui) {
+    if (!isRecord(ui)) {
+        errors.push('ui/index.js must default-export the app UI object (defineMdkApp({ ... }))');
+        return;
+    }
+    if (ui.id !== expectedId) {
+        errors.push(`ui/index.js declares id "${String(ui.id)}", but mdk-app.yaml says "${expectedId}" — the dashboard refuses a mismatch`);
+    }
+    if (typeof ui.displayName !== 'string' || !ui.displayName)
+        errors.push('ui/index.js must export a non-empty `displayName`');
+    if (!Array.isArray(ui.routes))
+        errors.push('ui/index.js must export `routes` as an array');
+    else {
+        ui.routes.forEach((route, i) => {
+            if (!isRecord(route) || typeof route.path !== 'string')
+                errors.push(`ui/index.js routes[${i}] needs a string \`path\``);
+            else if (!isComponent(route.component))
+                errors.push(`ui/index.js routes[${i}] ("${route.path}") needs a React \`component\``);
+        });
+    }
+    // Valid, but invisible: no sidebar entry and nothing on Home — usually the
+    // placeholder `mdk create app` writes before the UI is built.
+    if (Array.isArray(ui.routes) && Array.isArray(ui.panels) && !ui.routes.length && !ui.panels.length) {
+        warnings.push('ui/index.js exports no pages and no panels, so the app will not show in the dashboard — build the UI with `npm run build:ui`');
+    }
+    if (!Array.isArray(ui.panels))
+        errors.push('ui/index.js must export `panels` as an array');
+    else {
+        const ids = new Set();
+        ui.panels.forEach((panel, i) => {
+            if (!isRecord(panel) || typeof panel.id !== 'string' || !panel.id) {
+                errors.push(`ui/index.js panels[${i}] needs a string \`id\``);
+                return;
+            }
+            if (ids.has(panel.id))
+                errors.push(`ui/index.js has two panels with id "${panel.id}"`);
+            ids.add(panel.id);
+            if (typeof panel.slot !== 'string' || !panel.slot)
+                errors.push(`ui/index.js panel "${panel.id}" needs a string \`slot\``);
+            if (!isComponent(panel.component))
+                errors.push(`ui/index.js panel "${panel.id}" needs a React \`component\``);
+        });
+    }
+}
+try {
+    const mod = (await import(pathToFileURL(entry).href));
+    checkContract(mod.default);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Syntax is checked before this runs; anything thrown here is the app's
+    // top-level code meeting a stub or a browser-only global. The dashboard still
+    // checks the contract when it loads the app, so this is not fatal.
+    warnings.push(`could not check the UI contract in Node (${message.split('\n')[0]}); the dashboard checks it when it loads the app`);
+}
+process.stdout.write(`${JSON.stringify({ errors, warnings })}\n`);
+//# sourceMappingURL=app-ui-runner.js.map

package/dist/lib/app-ui-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-ui-runner.js","sourceRoot":"","sources":["../../src/lib/app-ui-runner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Child process for `checkAppUi`'s contract check: imports an app's built\n * `ui/index.js` with every bare import replaced by a stub, then checks its\n * default export against the app UI contract the dashboard enforces\n * (`checkAppUiModule` in @tetherto/mdk-react-adapter).\n *\n * Runs in its own process so the app's top-level code never touches the CLI's\n * module graph. It has no imports of its own beyond `node:`, so it also runs\n * as `.ts` (tests) under Node's type stripping.\n *\n * Input (env): MDK_UI_ENTRY (absolute path), MDK_UI_ID (expected id),\n * MDK_UI_IMPORTS (JSON: specifier → the names imported from it).\n * Output (stdout, one JSON line): { errors: string[], warnings: string[] }.\n */\nimport { registerHooks } from 'node:module';\nimport { pathToFileURL } from 'node:url';\n\nconst STUB_PREFIX = 'mdk-ui-stub:';\n\n// Exports whose real value an app's default export is built from, so a stub\n// would fail the contract check: kept as they are in @tetherto/mdk-react-adapter\n// (a test runs the same modules through both checkers).\nconst REAL_EXPORTS: Record<string, string> = {\n  defineMdkApp: 'export const defineMdkApp = (ui) => ui;',\n  MDK_APP_PANEL_SLOT: \"export const MDK_APP_PANEL_SLOT = Object.freeze({ HOME: 'home' });\",\n};\nconst IDENTIFIER = /^[A-Za-z_$][\\w$]*$/;\n\nconst entry = process.env.MDK_UI_ENTRY ?? '';\nconst expectedId = process.env.MDK_UI_ID ?? '';\nconst imports = JSON.parse(process.env.MDK_UI_IMPORTS ?? '{}') as Record<string, string[]>;\n\nconst isBare = (specifier: string): boolean =>\n  !specifier.startsWith('.') && !specifier.startsWith('/') && !/^[a-z][a-z0-9+.-]*:/i.test(specifier);\n\n// A value that survives anything top-level code does with an import it got from\n// the dashboard: call it, construct it, read any property of it.\nconst stubSource = (specifier: string): string => {\n  const names = imports[specifier] ?? [];\n  const lines = [\n    'const stub = new Proxy(function () {}, {',\n    '  get: (_t, key) => (key === Symbol.toPrimitive ? () => \"\" : stub),',\n    '  apply: () => stub,',\n    '  construct: () => stub,',\n    '});',\n    'export default stub;',\n  ];\n  for (const name of new Set(names)) {\n    if (name === 'default' || !IDENTIFIER.test(name)) continue;\n    lines.push(REAL_EXPORTS[name] ?? `export const ${name} = stub;`);\n  }\n  return lines.join('\\n');\n};\n\nregisterHooks({\n  resolve(specifier, context, nextResolve) {\n    if (isBare(specifier)) return { url: `${STUB_PREFIX}${specifier}`, shortCircuit: true };\n    return nextResolve(specifier, context);\n  },\n  load(url, context, nextLoad) {\n    if (url.startsWith(STUB_PREFIX)) {\n      return { format: 'module', source: stubSource(url.slice(STUB_PREFIX.length)), shortCircuit: true };\n    }\n    return nextLoad(url, context);\n  },\n});\n\nconst isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object';\nconst isComponent = (value: unknown): boolean => typeof value === 'function' || (isRecord(value) && '$$typeof' in value);\n\nconst errors: string[] = [];\nconst warnings: string[] = [];\n\nfunction checkContract(ui: unknown): void {\n  if (!isRecord(ui)) {\n    errors.push('ui/index.js must default-export the app UI object (defineMdkApp({ ... }))');\n    return;\n  }\n  if (ui.id !== expectedId) {\n    errors.push(`ui/index.js declares id \"${String(ui.id)}\", but mdk-app.yaml says \"${expectedId}\" — the dashboard refuses a mismatch`);\n  }\n  if (typeof ui.displayName !== 'string' || !ui.displayName) errors.push('ui/index.js must export a non-empty `displayName`');\n\n  if (!Array.isArray(ui.routes)) errors.push('ui/index.js must export `routes` as an array');\n  else {\n    ui.routes.forEach((route: unknown, i) => {\n      if (!isRecord(route) || typeof route.path !== 'string') errors.push(`ui/index.js routes[${i}] needs a string \\`path\\``);\n      else if (!isComponent(route.component)) errors.push(`ui/index.js routes[${i}] (\"${route.path}\") needs a React \\`component\\``);\n    });\n  }\n\n  // Valid, but invisible: no sidebar entry and nothing on Home — usually the\n  // placeholder `mdk create app` writes before the UI is built.\n  if (Array.isArray(ui.routes) && Array.isArray(ui.panels) && !ui.routes.length && !ui.panels.length) {\n    warnings.push('ui/index.js exports no pages and no panels, so the app will not show in the dashboard — build the UI with `npm run build:ui`');\n  }\n\n  if (!Array.isArray(ui.panels)) errors.push('ui/index.js must export `panels` as an array');\n  else {\n    const ids = new Set<string>();\n    ui.panels.forEach((panel: unknown, i) => {\n      if (!isRecord(panel) || typeof panel.id !== 'string' || !panel.id) {\n        errors.push(`ui/index.js panels[${i}] needs a string \\`id\\``);\n        return;\n      }\n      if (ids.has(panel.id)) errors.push(`ui/index.js has two panels with id \"${panel.id}\"`);\n      ids.add(panel.id);\n      if (typeof panel.slot !== 'string' || !panel.slot) errors.push(`ui/index.js panel \"${panel.id}\" needs a string \\`slot\\``);\n      if (!isComponent(panel.component)) errors.push(`ui/index.js panel \"${panel.id}\" needs a React \\`component\\``);\n    });\n  }\n}\n\ntry {\n  const mod = (await import(pathToFileURL(entry).href)) as { default?: unknown };\n  checkContract(mod.default);\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  // Syntax is checked before this runs; anything thrown here is the app's\n  // top-level code meeting a stub or a browser-only global. The dashboard still\n  // checks the contract when it loads the app, so this is not fatal.\n  warnings.push(`could not check the UI contract in Node (${message.split('\\n')[0]}); the dashboard checks it when it loads the app`);\n}\n\nprocess.stdout.write(`${JSON.stringify({ errors, warnings })}\\n`);\n"]}

package/dist/lib/catalog.js

@@ -0,0 +1,69 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { checkoutRoot } from './checkout.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Package root of the CLI itself — the anchor for finding the MDK checkout. */
+const CLI_ROOT = resolve(__dirname, '..', '..');
+/**
+ * Worker plugins offered by `mdk onboard`. Empty today — the bundled demo
+ * worker was removed from the monorepo. When an entry is added, a `repoPath`
+ * makes it a checkout-linked package; without one it is installed from the
+ * registry (and its device config would need to be filled in by hand).
+ */
+export const WORKER_CATALOG = [];
+/**
+ * Apps offered by `mdk onboard`. Every entry today has a `repoPath`
+ * and is real/runnable from the MDK checkout — the field stays optional for a
+ * future entry that isn't (selecting one without a `repoPath` would still
+ * write a valid spec entry, but its install would 404).
+ */
+export const APP_CATALOG = [
+    {
+        value: '@tetherto/mdk-app-agent',
+        label: 'mdk-app-agent',
+        hint: 'auth-gated operator agent chat (sessions, SSE, approvals) — bundled',
+        repoPath: join('backend', 'apps', 'agent'),
+        // The UI's agent transport (ui/packages/ui-agent) calls /agent/... at the Gateway root.
+        mount: '/',
+    },
+    {
+        value: '@tetherto/mdk-app-demo',
+        label: 'mdk-app-demo',
+        hint: 'fleet summary + history across your hashrate_rt miners — bundled',
+        repoPath: join('backend', 'apps', 'demo'),
+    },
+];
+export function findCatalogWorker(pkg) {
+    return WORKER_CATALOG.find((entry) => entry.value === pkg);
+}
+export function findCatalogApp(pkg) {
+    return APP_CATALOG.find((entry) => entry.value === pkg);
+}
+/**
+ * Absolute path to `repoPath` in the MDK checkout the CLI runs from (only the
+ * `<root>/packages/cli` layout counts, see `checkoutRoot`). Returns null when
+ * the CLI is installed standalone from npm, where there is no checkout to point at.
+ */
+function findInCheckout(repoPath) {
+    const root = checkoutRoot(CLI_ROOT);
+    if (!root)
+        return null;
+    const candidate = join(root, repoPath);
+    return existsSync(join(candidate, 'package.json')) ? candidate : null;
+}
+/**
+ * Decides how a selected catalog entry (worker or app) should be
+ * installed. A bundled package is path-backed with a relative `file:` dep to
+ * its checkout directory; everything else is installed from the registry.
+ */
+export function resolveCatalogPackage(entry) {
+    const packageName = entry.value;
+    if (!entry.repoPath)
+        return { packageName, bundled: false };
+    const dir = findInCheckout(entry.repoPath);
+    if (dir)
+        return { packageName, bundled: true, checkoutDir: dir };
+    return { packageName, bundled: false, unavailable: true };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/lib/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/lib/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,gFAAgF;AAChF,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AA8ChD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB,EAAE,CAAC;AAElD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAiB;IACvC;QACE,KAAK,EAAE,yBAAyB;QAChC,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,qEAAqE;QAC3E,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC;QAC1C,wFAAwF;QACxF,KAAK,EAAE,GAAG;KACX;IACD;QACE,KAAK,EAAE,wBAAwB;QAC/B,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,kEAAkE;QACxE,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;KAC1C;CACF,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvC,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAmB;IACvD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,QAAQ;QAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAE5D,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,GAAG;QAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC;IACjE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC5D,CAAC","sourcesContent":["import { existsSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join, resolve } from 'node:path';\nimport { checkoutRoot } from './checkout.js';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\n/** Package root of the CLI itself — the anchor for finding the MDK checkout. */\nconst CLI_ROOT = resolve(__dirname, '..', '..');\n\nexport interface CatalogEntry {\n  /** npm package name — what `mdk.yaml` references when it resolves from the registry. */\n  value: string;\n  label: string;\n  hint: string;\n  /**\n   * Location inside the MDK checkout, for a package that ships with MDK but is\n   * not on npm yet. When the CLI runs from the checkout, the project depends on\n   * it via `addFileDependency`: a relative `file:` link to the checkout\n   * path (whether that path sits inside the project folder or elsewhere in the\n   * monorepo) — never by appending the path to `workspaces`, and never via bare\n   * `*` (npm would treat that as a registry range outside a parent workspace).\n   * `npm install` links it into `node_modules/<package>`, exactly as it would a\n   * published package. No project folder is created for it: `workers/*` and\n   * `apps/*` are reserved for packages the user actually owns\n   * (`mdk create ...`).\n   *\n   * Linking (rather than copying) also keeps in-checkout relative resolution\n   * working: Node resolves a symlinked package from its real location, so a\n   * device mock finds its shared framework and an app finds the deps\n   * in its own node_modules.\n   */\n  repoPath?: string;\n}\n\nexport interface CatalogApp extends CatalogEntry {\n  /** `spec.apps[].mount` to write, when the app's clients call it somewhere other than `/apps/<name>`. */\n  mount?: string;\n}\n\nexport interface CatalogWorker extends CatalogEntry {\n  /** Worker-level config the plugin reads, beyond its device list. */\n  config?: Record<string, unknown>;\n  /**\n   * Per-device opts beyond the `host`/`port`/`serial` every seed device gets.\n   *\n   * One object is handed to both the plugin's `connect()` and the device mock,\n   * so it has to satisfy both at once.\n   */\n  deviceOpts?: Record<string, unknown>;\n  /** Boot a device simulator from `<pkg>/mock/server.js`, so no hardware is needed. */\n  mock?: boolean;\n}\n\n/**\n * Worker plugins offered by `mdk onboard`. Empty today — the bundled demo\n * worker was removed from the monorepo. When an entry is added, a `repoPath`\n * makes it a checkout-linked package; without one it is installed from the\n * registry (and its device config would need to be filled in by hand).\n */\nexport const WORKER_CATALOG: CatalogWorker[] = [];\n\n/**\n * Apps offered by `mdk onboard`. Every entry today has a `repoPath`\n * and is real/runnable from the MDK checkout — the field stays optional for a\n * future entry that isn't (selecting one without a `repoPath` would still\n * write a valid spec entry, but its install would 404).\n */\nexport const APP_CATALOG: CatalogApp[] = [\n  {\n    value: '@tetherto/mdk-app-agent',\n    label: 'mdk-app-agent',\n    hint: 'auth-gated operator agent chat (sessions, SSE, approvals) — bundled',\n    repoPath: join('backend', 'apps', 'agent'),\n    // The UI's agent transport (ui/packages/ui-agent) calls /agent/... at the Gateway root.\n    mount: '/',\n  },\n  {\n    value: '@tetherto/mdk-app-demo',\n    label: 'mdk-app-demo',\n    hint: 'fleet summary + history across your hashrate_rt miners — bundled',\n    repoPath: join('backend', 'apps', 'demo'),\n  },\n];\n\nexport function findCatalogWorker(pkg: string): CatalogWorker | undefined {\n  return WORKER_CATALOG.find((entry) => entry.value === pkg);\n}\n\nexport function findCatalogApp(pkg: string): CatalogApp | undefined {\n  return APP_CATALOG.find((entry) => entry.value === pkg);\n}\n\n/**\n * Absolute path to `repoPath` in the MDK checkout the CLI runs from (only the\n * `<root>/packages/cli` layout counts, see `checkoutRoot`). Returns null when\n * the CLI is installed standalone from npm, where there is no checkout to point at.\n */\nfunction findInCheckout(repoPath: string): string | null {\n  const root = checkoutRoot(CLI_ROOT);\n  if (!root) return null;\n  const candidate = join(root, repoPath);\n  return existsSync(join(candidate, 'package.json')) ? candidate : null;\n}\n\nexport interface ResolvedCatalogPackage {\n  /** npm package name — what `mdk.yaml` references and what lands in node_modules. */\n  packageName: string;\n  /** True when the package is linked from the checkout rather than the registry. */\n  bundled: boolean;\n  /** Set when the entry wanted the checkout but the CLI is running standalone. */\n  unavailable?: boolean;\n  /** Absolute checkout path — present when bundled and resolvable. */\n  checkoutDir?: string;\n}\n\n/**\n * Decides how a selected catalog entry (worker or app) should be\n * installed. A bundled package is path-backed with a relative `file:` dep to\n * its checkout directory; everything else is installed from the registry.\n */\nexport function resolveCatalogPackage(entry: CatalogEntry): ResolvedCatalogPackage {\n  const packageName = entry.value;\n  if (!entry.repoPath) return { packageName, bundled: false };\n\n  const dir = findInCheckout(entry.repoPath);\n  if (dir) return { packageName, bundled: true, checkoutDir: dir };\n  return { packageName, bundled: false, unavailable: true };\n}\n"]}

package/dist/lib/checkout.js

@@ -0,0 +1,14 @@
+import { basename, dirname } from 'node:path';
+/**
+ * Root of the MDK monorepo checkout the CLI runs from, or null for a published
+ * install. Only the known `<root>/packages/cli` layout is accepted — never a walk
+ * up the tree, which would let any ancestor directory (a shared `/tmp`, a home
+ * directory) plant the templates or packages the CLI then copies and installs.
+ */
+export function checkoutRoot(cliRoot) {
+    const packagesDir = dirname(cliRoot);
+    if (basename(cliRoot) !== 'cli' || basename(packagesDir) !== 'packages')
+        return null;
+    return dirname(packagesDir);
+}
+//# sourceMappingURL=checkout.js.map

package/dist/lib/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../src/lib/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,KAAK,IAAI,QAAQ,CAAC,WAAW,CAAC,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACrF,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;AAC9B,CAAC","sourcesContent":["import { basename, dirname } from 'node:path';\n\n/**\n * Root of the MDK monorepo checkout the CLI runs from, or null for a published\n * install. Only the known `<root>/packages/cli` layout is accepted — never a walk\n * up the tree, which would let any ancestor directory (a shared `/tmp`, a home\n * directory) plant the templates or packages the CLI then copies and installs.\n */\nexport function checkoutRoot(cliRoot: string): string | null {\n  const packagesDir = dirname(cliRoot);\n  if (basename(cliRoot) !== 'cli' || basename(packagesDir) !== 'packages') return null;\n  return dirname(packagesDir);\n}\n"]}

package/dist/lib/dashboard-apps.js

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { APP_MANIFEST } from './app-package.js';
+import { resolvePackageDir } from './runtime.js';
+/**
+ * Environment variable `mdk run dashboard` hands the installed apps to the
+ * dashboard's dev server in: a JSON array of {@link DashboardApp}. The
+ * dashboard serves each app's built `ui/` and lists the apps to the browser
+ * itself, so finding them needs no Gateway.
+ */
+export const DASHBOARD_APPS_ENV = 'MDK_DASHBOARD_APPS';
+/**
+ * Where the Gateway serves an app's own routes: its `mount`, or `/apps/<name>`
+ * (startGateway's default). `mount: /` puts them at the root, so the prefix is
+ * empty.
+ */
+export function appApiBase(app) {
+    const mount = app.mount ?? `/apps/${app.name}`;
+    return mount === '/' ? '' : mount.replace(/\/+$/, '');
+}
+/**
+ * Resolves each `spec.apps[]` package to its directory, as `mdk run` does
+ * (`resolvePackageDir`); it must hold an `mdk-app.yaml`, or it is not an app.
+ */
+export function resolveAppDirs(projectDir, apps) {
+    return apps.map((app) => {
+        let dir;
+        try {
+            dir = resolvePackageDir(projectDir, app.package);
+        }
+        catch (error) {
+            throw new Error(`App "${app.name}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!existsSync(join(dir, APP_MANIFEST))) {
+            throw new Error(`App "${app.name}": ${dir} has no ${APP_MANIFEST} — "${app.package}" is not an MDK app package.`);
+        }
+        return { name: app.name, dir };
+    });
+}
+/**
+ * The installed apps of a stack, read from `mdk.yaml` and each app's
+ * `mdk-app.yaml`, for the dashboard to load. Throws naming the app when a
+ * package is missing or its manifest lacks what the dashboard shows.
+ */
+export function describeDashboardApps(projectDir, apps) {
+    return resolveAppDirs(projectDir, apps).map(({ name, dir }, i) => {
+        let manifest;
+        try {
+            manifest = parseYaml(readFileSync(join(dir, APP_MANIFEST), 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`App "${name}": ${APP_MANIFEST}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const fields = (manifest ?? {});
+        for (const field of ['id', 'version', 'displayName']) {
+            if (typeof fields[field] !== 'string' || !fields[field]) {
+                throw new Error(`App "${name}": ${APP_MANIFEST} is missing "${field}" — check it with \`mdk validate app ${name}\`.`);
+            }
+        }
+        return {
+            name,
+            id: fields.id,
+            version: fields.version,
+            displayName: fields.displayName,
+            apiBase: appApiBase(apps[i]),
+            dir,
+        };
+    });
+}
+//# sourceMappingURL=dashboard-apps.js.map

package/dist/lib/dashboard-apps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-apps.js","sourceRoot":"","sources":["../../src/lib/dashboard-apps.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\nimport { APP_MANIFEST } from './app-package.js';\nimport { resolvePackageDir } from './runtime.js';\nimport type { StackSpec } from './spec.js';\n\n/**\n * Environment variable `mdk run dashboard` hands the installed apps to the\n * dashboard's dev server in: a JSON array of {@link DashboardApp}. The\n * dashboard serves each app's built `ui/` and lists the apps to the browser\n * itself, so finding them needs no Gateway.\n */\nexport const DASHBOARD_APPS_ENV = 'MDK_DASHBOARD_APPS';\n\n/** One installed app, as the dashboard needs it to load the app's UI. */\nexport interface DashboardApp {\n  /** Installed name (`spec.apps[].name`). */\n  name: string;\n  /** Reverse-DNS id from the app's `mdk-app.yaml`. */\n  id: string;\n  version: string;\n  displayName: string;\n  /** Where the app's own routes are reached through the Gateway: its `mount`, default `/apps/<name>`. */\n  apiBase: string;\n  /** The app package's directory; its built UI is `<dir>/ui/`. */\n  dir: string;\n}\n\ntype AppEntry = NonNullable<StackSpec['spec']['apps']>[number];\n\n/**\n * Where the Gateway serves an app's own routes: its `mount`, or `/apps/<name>`\n * (startGateway's default). `mount: /` puts them at the root, so the prefix is\n * empty.\n */\nexport function appApiBase(app: Pick<AppEntry, 'name' | 'mount'>): string {\n  const mount = app.mount ?? `/apps/${app.name}`;\n  return mount === '/' ? '' : mount.replace(/\\/+$/, '');\n}\n\n/**\n * Resolves each `spec.apps[]` package to its directory, as `mdk run` does\n * (`resolvePackageDir`); it must hold an `mdk-app.yaml`, or it is not an app.\n */\nexport function resolveAppDirs(projectDir: string, apps: AppEntry[]): Array<{ name: string; dir: string }> {\n  return apps.map((app) => {\n    let dir: string;\n    try {\n      dir = resolvePackageDir(projectDir, app.package);\n    } catch (error) {\n      throw new Error(`App \"${app.name}\": ${error instanceof Error ? error.message : String(error)}`);\n    }\n    if (!existsSync(join(dir, APP_MANIFEST))) {\n      throw new Error(`App \"${app.name}\": ${dir} has no ${APP_MANIFEST} — \"${app.package}\" is not an MDK app package.`);\n    }\n    return { name: app.name, dir };\n  });\n}\n\n/**\n * The installed apps of a stack, read from `mdk.yaml` and each app's\n * `mdk-app.yaml`, for the dashboard to load. Throws naming the app when a\n * package is missing or its manifest lacks what the dashboard shows.\n */\nexport function describeDashboardApps(projectDir: string, apps: AppEntry[]): DashboardApp[] {\n  return resolveAppDirs(projectDir, apps).map(({ name, dir }, i) => {\n    let manifest: unknown;\n    try {\n      manifest = parseYaml(readFileSync(join(dir, APP_MANIFEST), 'utf8'));\n    } catch (error) {\n      throw new Error(`App \"${name}\": ${APP_MANIFEST}: ${error instanceof Error ? error.message : String(error)}`);\n    }\n    const fields = (manifest ?? {}) as Record<string, unknown>;\n    for (const field of ['id', 'version', 'displayName']) {\n      if (typeof fields[field] !== 'string' || !fields[field]) {\n        throw new Error(`App \"${name}\": ${APP_MANIFEST} is missing \"${field}\" — check it with \\`mdk validate app ${name}\\`.`);\n      }\n    }\n    return {\n      name,\n      id: fields.id as string,\n      version: fields.version as string,\n      displayName: fields.displayName as string,\n      apiBase: appApiBase(apps[i]!),\n      dir,\n    };\n  });\n}\n"]}