@leeoohoo/ui-apps-devkit 0.1.1 → 0.1.3

package/src/commands/validate.js

@@ -1,113 +1,113 @@
-import fs from 'fs';
-import path from 'path';
-
-import { isFile } from '../lib/fs.js';
-import { loadDevkitConfig } from '../lib/config.js';
-import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
-import { resolveInsideDir } from '../lib/path-boundary.js';
-
-function assert(cond, message) {
-  if (!cond) throw new Error(message);
-}
-
-function statSizeSafe(filePath) {
-  try {
-    return fs.statSync(filePath).size;
-  } catch {
-    return 0;
-  }
-}
-
-export async function cmdValidate({ flags }) {
-  const { config } = loadDevkitConfig(process.cwd());
-  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
-
-  const { manifestPath, manifest } = loadPluginManifest(pluginDir);
-
-  const manifestSize = statSizeSafe(manifestPath);
-  assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
-
-  assert(Number(manifest?.manifestVersion || 1) === 1, 'manifestVersion must be 1');
-  assert(typeof manifest?.id === 'string' && manifest.id.trim(), 'plugin.id is required');
-  assert(typeof manifest?.name === 'string' && manifest.name.trim(), 'plugin.name is required');
-
-  if (manifest?.backend?.entry) {
-    const backendAbs = resolveInsideDir(pluginDir, manifest.backend.entry);
-    assert(isFile(backendAbs), `backend.entry must be a file: ${manifest.backend.entry}`);
-  }
-
-  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
-  assert(apps.length > 0, 'plugin.apps[] is required (>=1)');
-  const ids = new Set();
-  for (const app of apps) {
-    const appId = typeof app?.id === 'string' ? app.id.trim() : '';
-    assert(appId, 'apps[i].id is required');
-    assert(!ids.has(appId), `duplicate app.id: ${appId}`);
-    ids.add(appId);
-
-    assert(typeof app?.name === 'string' && app.name.trim(), `apps[${appId}].name is required`);
-    assert(app?.entry?.type === 'module', `apps[${appId}].entry.type must be "module"`);
-    const entryPath = typeof app?.entry?.path === 'string' ? app.entry.path.trim() : '';
-    assert(entryPath, `apps[${appId}].entry.path is required`);
-    const entryAbs = resolveInsideDir(pluginDir, entryPath);
-    assert(isFile(entryAbs), `apps[${appId}].entry.path must be a file: ${entryPath}`);
-
-    const compactType = app?.entry?.compact?.type;
-    if (compactType && compactType !== 'module') {
-      assert(false, `apps[${appId}].entry.compact.type must be "module"`);
-    }
-    const compactPath = typeof app?.entry?.compact?.path === 'string' ? app.entry.compact.path.trim() : '';
-    if (compactPath) {
-      const compactAbs = resolveInsideDir(pluginDir, compactPath);
-      assert(isFile(compactAbs), `apps[${appId}].entry.compact.path must be a file: ${compactPath}`);
-    }
-
-    // Basic ai path boundary checks (full schema is defined in docs; this validates the security boundary).
-    const ai = app?.ai;
-    const aiObj =
-      typeof ai === 'string'
-        ? { config: ai }
-        : ai && typeof ai === 'object'
-          ? ai
-          : null;
-
-    if (aiObj?.config) {
-      const abs = resolveInsideDir(pluginDir, aiObj.config);
-      assert(isFile(abs), `apps[${appId}].ai.config must be a file: ${aiObj.config}`);
-      const size = statSizeSafe(abs);
-      assert(size <= 128 * 1024, `ai.config too large (>128KiB): ${aiObj.config}`);
-    }
-
-    if (aiObj?.mcp?.entry) {
-      const abs = resolveInsideDir(pluginDir, aiObj.mcp.entry);
-      assert(isFile(abs), `apps[${appId}].ai.mcp.entry must be a file: ${aiObj.mcp.entry}`);
-    }
-
-    const mcpPrompt = aiObj?.mcpPrompt;
-    const collectPromptPaths = () => {
-      if (!mcpPrompt) return [];
-      if (typeof mcpPrompt === 'string') return [mcpPrompt];
-      if (typeof mcpPrompt !== 'object') return [];
-      const zh = mcpPrompt.zh;
-      const en = mcpPrompt.en;
-      const out = [];
-      const pushSource = (src) => {
-        if (!src) return;
-        if (typeof src === 'string') out.push(src);
-        else if (typeof src === 'object' && typeof src.path === 'string') out.push(src.path);
-      };
-      pushSource(zh);
-      pushSource(en);
-      return out;
-    };
-    for (const rel of collectPromptPaths()) {
-      const abs = resolveInsideDir(pluginDir, rel);
-      assert(isFile(abs), `apps[${appId}].ai.mcpPrompt path must be a file: ${rel}`);
-      const size = statSizeSafe(abs);
-      assert(size <= 128 * 1024, `mcpPrompt too large (>128KiB): ${rel}`);
-    }
-  }
-
-  // eslint-disable-next-line no-console
-  console.log(`OK: ${path.relative(process.cwd(), pluginDir)} (apps=${apps.length})`);
-}
+import fs from 'fs';
+import path from 'path';
+
+import { isFile } from '../lib/fs.js';
+import { loadDevkitConfig } from '../lib/config.js';
+import { findPluginDir, loadPluginManifest } from '../lib/plugin.js';
+import { resolveInsideDir } from '../lib/path-boundary.js';
+
+function assert(cond, message) {
+  if (!cond) throw new Error(message);
+}
+
+function statSizeSafe(filePath) {
+  try {
+    return fs.statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+export async function cmdValidate({ flags }) {
+  const { config } = loadDevkitConfig(process.cwd());
+  const pluginDir = findPluginDir(process.cwd(), flags['plugin-dir'] || flags.pluginDir || config?.pluginDir);
+
+  const { manifestPath, manifest } = loadPluginManifest(pluginDir);
+
+  const manifestSize = statSizeSafe(manifestPath);
+  assert(manifestSize <= 256 * 1024, `plugin.json too large (>256KiB): ${manifestSize} bytes`);
+
+  assert(Number(manifest?.manifestVersion || 1) === 1, 'manifestVersion must be 1');
+  assert(typeof manifest?.id === 'string' && manifest.id.trim(), 'plugin.id is required');
+  assert(typeof manifest?.name === 'string' && manifest.name.trim(), 'plugin.name is required');
+
+  if (manifest?.backend?.entry) {
+    const backendAbs = resolveInsideDir(pluginDir, manifest.backend.entry);
+    assert(isFile(backendAbs), `backend.entry must be a file: ${manifest.backend.entry}`);
+  }
+
+  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
+  assert(apps.length > 0, 'plugin.apps[] is required (>=1)');
+  const ids = new Set();
+  for (const app of apps) {
+    const appId = typeof app?.id === 'string' ? app.id.trim() : '';
+    assert(appId, 'apps[i].id is required');
+    assert(!ids.has(appId), `duplicate app.id: ${appId}`);
+    ids.add(appId);
+
+    assert(typeof app?.name === 'string' && app.name.trim(), `apps[${appId}].name is required`);
+    assert(app?.entry?.type === 'module', `apps[${appId}].entry.type must be "module"`);
+    const entryPath = typeof app?.entry?.path === 'string' ? app.entry.path.trim() : '';
+    assert(entryPath, `apps[${appId}].entry.path is required`);
+    const entryAbs = resolveInsideDir(pluginDir, entryPath);
+    assert(isFile(entryAbs), `apps[${appId}].entry.path must be a file: ${entryPath}`);
+
+    const compactType = app?.entry?.compact?.type;
+    if (compactType && compactType !== 'module') {
+      assert(false, `apps[${appId}].entry.compact.type must be "module"`);
+    }
+    const compactPath = typeof app?.entry?.compact?.path === 'string' ? app.entry.compact.path.trim() : '';
+    if (compactPath) {
+      const compactAbs = resolveInsideDir(pluginDir, compactPath);
+      assert(isFile(compactAbs), `apps[${appId}].entry.compact.path must be a file: ${compactPath}`);
+    }
+
+    // Basic ai path boundary checks (full schema is defined in docs; this validates the security boundary).
+    const ai = app?.ai;
+    const aiObj =
+      typeof ai === 'string'
+        ? { config: ai }
+        : ai && typeof ai === 'object'
+          ? ai
+          : null;
+
+    if (aiObj?.config) {
+      const abs = resolveInsideDir(pluginDir, aiObj.config);
+      assert(isFile(abs), `apps[${appId}].ai.config must be a file: ${aiObj.config}`);
+      const size = statSizeSafe(abs);
+      assert(size <= 128 * 1024, `ai.config too large (>128KiB): ${aiObj.config}`);
+    }
+
+    if (aiObj?.mcp?.entry) {
+      const abs = resolveInsideDir(pluginDir, aiObj.mcp.entry);
+      assert(isFile(abs), `apps[${appId}].ai.mcp.entry must be a file: ${aiObj.mcp.entry}`);
+    }
+
+    const mcpPrompt = aiObj?.mcpPrompt;
+    const collectPromptPaths = () => {
+      if (!mcpPrompt) return [];
+      if (typeof mcpPrompt === 'string') return [mcpPrompt];
+      if (typeof mcpPrompt !== 'object') return [];
+      const zh = mcpPrompt.zh;
+      const en = mcpPrompt.en;
+      const out = [];
+      const pushSource = (src) => {
+        if (!src) return;
+        if (typeof src === 'string') out.push(src);
+        else if (typeof src === 'object' && typeof src.path === 'string') out.push(src.path);
+      };
+      pushSource(zh);
+      pushSource(en);
+      return out;
+    };
+    for (const rel of collectPromptPaths()) {
+      const abs = resolveInsideDir(pluginDir, rel);
+      assert(isFile(abs), `apps[${appId}].ai.mcpPrompt path must be a file: ${rel}`);
+      const size = statSizeSafe(abs);
+      assert(size <= 128 * 1024, `mcpPrompt too large (>128KiB): ${rel}`);
+    }
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`OK: ${path.relative(process.cwd(), pluginDir)} (apps=${apps.length})`);
+}

package/src/lib/args.js

@@ -1,49 +1,49 @@
-export function parseArgs(argv) {
-  const raw = Array.isArray(argv) ? argv.slice(2) : [];
-  const flags = {};
-  const positionals = [];
-
-  for (let i = 0; i < raw.length; i += 1) {
-    const token = raw[i];
-    if (!token) continue;
-
-    if (token === '--') {
-      positionals.push(...raw.slice(i + 1));
-      break;
-    }
-
-    if (token.startsWith('--')) {
-      const eq = token.indexOf('=');
-      const key = (eq >= 0 ? token.slice(2, eq) : token.slice(2)).trim();
-      const value = eq >= 0 ? token.slice(eq + 1) : raw[i + 1];
-      if (!key) continue;
-
-      if (eq < 0 && value && !value.startsWith('-')) {
-        flags[key] = value;
-        i += 1;
-      } else if (eq >= 0) {
-        flags[key] = value;
-      } else {
-        flags[key] = true;
-      }
-      continue;
-    }
-
-    if (token.startsWith('-') && token.length > 1) {
-      const key = token.slice(1).trim();
-      const value = raw[i + 1];
-      if (value && !value.startsWith('-')) {
-        flags[key] = value;
-        i += 1;
-      } else {
-        flags[key] = true;
-      }
-      continue;
-    }
-
-    positionals.push(token);
-  }
-
-  return { positionals, flags };
-}
-
+export function parseArgs(argv) {
+  const raw = Array.isArray(argv) ? argv.slice(2) : [];
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < raw.length; i += 1) {
+    const token = raw[i];
+    if (!token) continue;
+
+    if (token === '--') {
+      positionals.push(...raw.slice(i + 1));
+      break;
+    }
+
+    if (token.startsWith('--')) {
+      const eq = token.indexOf('=');
+      const key = (eq >= 0 ? token.slice(2, eq) : token.slice(2)).trim();
+      const value = eq >= 0 ? token.slice(eq + 1) : raw[i + 1];
+      if (!key) continue;
+
+      if (eq < 0 && value && !value.startsWith('-')) {
+        flags[key] = value;
+        i += 1;
+      } else if (eq >= 0) {
+        flags[key] = value;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+
+    if (token.startsWith('-') && token.length > 1) {
+      const key = token.slice(1).trim();
+      const value = raw[i + 1];
+      if (value && !value.startsWith('-')) {
+        flags[key] = value;
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return { positionals, flags };
+}
+

package/src/lib/config.js

@@ -1,29 +1,29 @@
-import fs from 'fs';
-import path from 'path';
-
-import { isFile, readJson } from './fs.js';
-
-export function loadDevkitConfig(cwd) {
-  const root = typeof cwd === 'string' ? cwd : process.cwd();
-  const cfgPath = path.join(root, 'chatos.config.json');
-  if (!isFile(cfgPath)) return { path: cfgPath, config: null };
-  try {
-    const cfg = readJson(cfgPath);
-    return { path: cfgPath, config: cfg };
-  } catch {
-    return { path: cfgPath, config: null };
-  }
-}
-
-export function readOptionalJson(filePath) {
-  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
-  if (!normalized) return null;
-  if (!fs.existsSync(normalized)) return null;
-  try {
-    const raw = fs.readFileSync(normalized, 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
+import fs from 'fs';
+import path from 'path';
+
+import { isFile, readJson } from './fs.js';
+
+export function loadDevkitConfig(cwd) {
+  const root = typeof cwd === 'string' ? cwd : process.cwd();
+  const cfgPath = path.join(root, 'chatos.config.json');
+  if (!isFile(cfgPath)) return { path: cfgPath, config: null };
+  try {
+    const cfg = readJson(cfgPath);
+    return { path: cfgPath, config: cfg };
+  } catch {
+    return { path: cfgPath, config: null };
+  }
+}
+
+export function readOptionalJson(filePath) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) return null;
+  if (!fs.existsSync(normalized)) return null;
+  try {
+    const raw = fs.readFileSync(normalized, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+

package/src/lib/fs.js

@@ -1,78 +1,78 @@
-import fs from 'fs';
-import path from 'path';
-
-export function isFile(filePath) {
-  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
-  if (!normalized) return false;
-  try {
-    return fs.existsSync(normalized) && fs.statSync(normalized).isFile();
-  } catch {
-    return false;
-  }
-}
-
-export function isDirectory(dirPath) {
-  const normalized = typeof dirPath === 'string' ? dirPath.trim() : '';
-  if (!normalized) return false;
-  try {
-    return fs.existsSync(normalized) && fs.statSync(normalized).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-export function ensureDir(dirPath) {
-  const normalized = typeof dirPath === 'string' ? dirPath.trim() : '';
-  if (!normalized) return;
-  fs.mkdirSync(normalized, { recursive: true });
-}
-
-export function readText(filePath) {
-  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
-  if (!normalized) throw new Error('readText: filePath is required');
-  return fs.readFileSync(normalized, 'utf8');
-}
-
-export function writeText(filePath, content) {
-  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
-  if (!normalized) throw new Error('writeText: filePath is required');
-  ensureDir(path.dirname(normalized));
-  fs.writeFileSync(normalized, content, 'utf8');
-}
-
-export function readJson(filePath) {
-  const raw = readText(filePath);
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== 'object') throw new Error(`Invalid JSON object: ${filePath}`);
-  return parsed;
-}
-
-export function writeJson(filePath, obj) {
-  writeText(filePath, `${JSON.stringify(obj, null, 2)}\n`);
-}
-
-export function rmForce(targetPath) {
-  const normalized = typeof targetPath === 'string' ? targetPath.trim() : '';
-  if (!normalized) return;
-  try {
-    fs.rmSync(normalized, { recursive: true, force: true });
-  } catch {
-    // ignore
-  }
-}
-
-export function copyDir(srcDir, destDir, { filter } = {}) {
-  fs.cpSync(srcDir, destDir, {
-    recursive: true,
-    force: true,
-    dereference: false,
-    filter: (src) => (typeof filter === 'function' ? filter(src) : true),
-  });
-}
-
-export function sanitizeDirComponent(value) {
-  const raw = typeof value === 'string' ? value.trim() : '';
-  if (!raw) return '';
-  return raw.replace(/[^a-zA-Z0-9._-]+/g, '-');
-}
-
+import fs from 'fs';
+import path from 'path';
+
+export function isFile(filePath) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) return false;
+  try {
+    return fs.existsSync(normalized) && fs.statSync(normalized).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function isDirectory(dirPath) {
+  const normalized = typeof dirPath === 'string' ? dirPath.trim() : '';
+  if (!normalized) return false;
+  try {
+    return fs.existsSync(normalized) && fs.statSync(normalized).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function ensureDir(dirPath) {
+  const normalized = typeof dirPath === 'string' ? dirPath.trim() : '';
+  if (!normalized) return;
+  fs.mkdirSync(normalized, { recursive: true });
+}
+
+export function readText(filePath) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) throw new Error('readText: filePath is required');
+  return fs.readFileSync(normalized, 'utf8');
+}
+
+export function writeText(filePath, content) {
+  const normalized = typeof filePath === 'string' ? filePath.trim() : '';
+  if (!normalized) throw new Error('writeText: filePath is required');
+  ensureDir(path.dirname(normalized));
+  fs.writeFileSync(normalized, content, 'utf8');
+}
+
+export function readJson(filePath) {
+  const raw = readText(filePath);
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object') throw new Error(`Invalid JSON object: ${filePath}`);
+  return parsed;
+}
+
+export function writeJson(filePath, obj) {
+  writeText(filePath, `${JSON.stringify(obj, null, 2)}\n`);
+}
+
+export function rmForce(targetPath) {
+  const normalized = typeof targetPath === 'string' ? targetPath.trim() : '';
+  if (!normalized) return;
+  try {
+    fs.rmSync(normalized, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+export function copyDir(srcDir, destDir, { filter } = {}) {
+  fs.cpSync(srcDir, destDir, {
+    recursive: true,
+    force: true,
+    dereference: false,
+    filter: (src) => (typeof filter === 'function' ? filter(src) : true),
+  });
+}
+
+export function sanitizeDirComponent(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (!raw) return '';
+  return raw.replace(/[^a-zA-Z0-9._-]+/g, '-');
+}
+

package/src/lib/path-boundary.js

@@ -1,16 +1,16 @@
-import path from 'path';
-
-export function resolveInsideDir(rootDir, relativePath) {
-  const root = typeof rootDir === 'string' ? rootDir.trim() : '';
-  const rel = typeof relativePath === 'string' ? relativePath.trim() : '';
-  if (!root) throw new Error('rootDir is required');
-  if (!rel) throw new Error('relativePath is required');
-  const resolved = path.resolve(root, rel);
-  const normalizedRoot = path.resolve(root);
-  const isInside = resolved === normalizedRoot || resolved.startsWith(normalizedRoot + path.sep);
-  if (!isInside) {
-    throw new Error(`Path escapes plugin dir: ${relativePath}`);
-  }
-  return resolved;
-}
-
+import path from 'path';
+
+export function resolveInsideDir(rootDir, relativePath) {
+  const root = typeof rootDir === 'string' ? rootDir.trim() : '';
+  const rel = typeof relativePath === 'string' ? relativePath.trim() : '';
+  if (!root) throw new Error('rootDir is required');
+  if (!rel) throw new Error('relativePath is required');
+  const resolved = path.resolve(root, rel);
+  const normalizedRoot = path.resolve(root);
+  const isInside = resolved === normalizedRoot || resolved.startsWith(normalizedRoot + path.sep);
+  if (!isInside) {
+    throw new Error(`Path escapes plugin dir: ${relativePath}`);
+  }
+  return resolved;
+}
+

package/src/lib/plugin.js

@@ -1,45 +1,45 @@
-import path from 'path';
-
-import { isFile, readJson } from './fs.js';
-
-export function findPluginDir(cwd, explicitPluginDir) {
-  const root = typeof cwd === 'string' ? cwd : process.cwd();
-  if (explicitPluginDir) {
-    const abs = path.resolve(root, explicitPluginDir);
-    if (!isFile(path.join(abs, 'plugin.json'))) {
-      throw new Error(`plugin.json not found in --plugin-dir: ${abs}`);
-    }
-    return abs;
-  }
-
-  const direct = path.join(root, 'plugin.json');
-  if (isFile(direct)) return root;
-
-  const nested = path.join(root, 'plugin', 'plugin.json');
-  if (isFile(nested)) return path.join(root, 'plugin');
-
-  throw new Error('Cannot find plugin.json (expected ./plugin.json or ./plugin/plugin.json)');
-}
-
-export function loadPluginManifest(pluginDir) {
-  const manifestPath = path.join(pluginDir, 'plugin.json');
-  const manifest = readJson(manifestPath);
-  const pluginId = typeof manifest?.id === 'string' ? manifest.id.trim() : '';
-  const name = typeof manifest?.name === 'string' ? manifest.name.trim() : '';
-  const version = typeof manifest?.version === 'string' ? manifest.version.trim() : '0.0.0';
-  if (!pluginId) throw new Error(`plugin.json missing "id": ${manifestPath}`);
-  if (!name) throw new Error(`plugin.json missing "name": ${manifestPath}`);
-  return { manifestPath, manifest, pluginId, name, version };
-}
-
-export function pickAppFromManifest(manifest, preferredAppId) {
-  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
-  if (apps.length === 0) throw new Error('plugin.json apps[] is empty');
-  if (preferredAppId) {
-    const hit = apps.find((a) => String(a?.id || '') === String(preferredAppId));
-    if (!hit) throw new Error(`app not found in plugin.json: ${preferredAppId}`);
-    return hit;
-  }
-  return apps[0];
-}
-
+import path from 'path';
+
+import { isFile, readJson } from './fs.js';
+
+export function findPluginDir(cwd, explicitPluginDir) {
+  const root = typeof cwd === 'string' ? cwd : process.cwd();
+  if (explicitPluginDir) {
+    const abs = path.resolve(root, explicitPluginDir);
+    if (!isFile(path.join(abs, 'plugin.json'))) {
+      throw new Error(`plugin.json not found in --plugin-dir: ${abs}`);
+    }
+    return abs;
+  }
+
+  const direct = path.join(root, 'plugin.json');
+  if (isFile(direct)) return root;
+
+  const nested = path.join(root, 'plugin', 'plugin.json');
+  if (isFile(nested)) return path.join(root, 'plugin');
+
+  throw new Error('Cannot find plugin.json (expected ./plugin.json or ./plugin/plugin.json)');
+}
+
+export function loadPluginManifest(pluginDir) {
+  const manifestPath = path.join(pluginDir, 'plugin.json');
+  const manifest = readJson(manifestPath);
+  const pluginId = typeof manifest?.id === 'string' ? manifest.id.trim() : '';
+  const name = typeof manifest?.name === 'string' ? manifest.name.trim() : '';
+  const version = typeof manifest?.version === 'string' ? manifest.version.trim() : '0.0.0';
+  if (!pluginId) throw new Error(`plugin.json missing "id": ${manifestPath}`);
+  if (!name) throw new Error(`plugin.json missing "name": ${manifestPath}`);
+  return { manifestPath, manifest, pluginId, name, version };
+}
+
+export function pickAppFromManifest(manifest, preferredAppId) {
+  const apps = Array.isArray(manifest?.apps) ? manifest.apps : [];
+  if (apps.length === 0) throw new Error('plugin.json apps[] is empty');
+  if (preferredAppId) {
+    const hit = apps.find((a) => String(a?.id || '') === String(preferredAppId));
+    if (!hit) throw new Error(`app not found in plugin.json: ${preferredAppId}`);
+    return hit;
+  }
+  return apps[0];
+}
+