Harden community MiniApp package checks

Assisted-by: codex reason:community-contract-validator

Author: dazhi

docs/package-contract.md

@@ -96,10 +96,11 @@ No other keys are allowed inside `mcode`. Other top-level keys (`name`, `type`,
   inside one of `artifacts.node`. `runtime.lifecycle` is `on-demand` or omitted.
 - `surface.path` is the route the Node entry serves the page on. It is relative to the Host and
   must not contain an origin, query, fragment, or backslash. A missing leading `/` is added.
-- `mcpEndpoints` is an array of `{ "server": string, "path": string }`. `server` matches
-  `^[a-zA-Z0-9_-]{1,128}$` and must name a server declared through `plugin.json.mcpServers`; MiniMax
-  Code checks that reference at install time. `server` and `path` are each unique. Use `[]` when
-  there are none.
+- `mcpEndpoints` is an array of `{ "server": string, "path": string }`; include `[]` when there
+  are none. `server` matches `^[a-zA-Z0-9_-]{1,128}$` and must name a server declared inside one
+  of the `plugin.json.mcpServers` descriptor files. `npm run check` reads those descriptor files
+  and checks the reference when they are valid JSON; MiniMax Code repeats the check at install time.
+  `server` and `path` are each unique.
 - `hostConnectorAccess` is optional: `{ "providers": string[] }`, each matching
   `^[a-z0-9_-]{1,64}$` and unique. Declared providers are granted by the Host at install time; this
   repository does not document their use.

plugins/amszuidas/mcode-token-usage-board/README.md

@@ -22,19 +22,23 @@ Include the hidden `.minimax-plugin` directory. Restart a version of MiniMax Cod
 
 Choose today, the past 7 days, the past 30 days, or all time, and optionally filter by model or session. Click “刷新” (Refresh) to update the data; the page also refreshes every 60 seconds. No API key or additional dependency installation is required.
 
-## Data access and counting
+## Data & access
 
 The service searches upward from the Host-provided `context.dataDir` for `v2/sessions`. If none is found, it falls back to `.minimax/v2/sessions` in your home directory. It reads `manifest.json` and `messages.jsonl` from session directories to extract usage, model names, session IDs, and titles derived from the first meaningful user text.
 
 Usage is grouped by day in your local time zone. The total adds input, output, cache-read, and cache-write Tokens; it is not an official billable Token count or invoice. The app depends on the client's session file format. Missing usage fields or format changes may result in incomplete statistics.
 
 The runtime does not write local files or upload data to external services. It has no telemetry or credential configuration, and its cache stays in process memory. The page displays actual session titles, so take care when sharing screenshots or your screen.
 
+## Tested environment
+
+The contribution was checked with synthetic sessions and a browser preview. Installation in the actual MiniMax Code desktop app, the minimum supported client version, and compatibility across operating systems have not been verified.
+
 ## Source and verification
 
 The page is in `miniapp/client/index.html`, and the Node service is in `miniapp/node/server.mjs`. No build step is required.
 
-Checks performed when adding this app covered usage aggregation, data refresh, error handling, and service shutdown with synthetic sessions, plus a browser preview. Installation in the actual MiniMax Code desktop app has not been verified as part of this contribution. The minimum supported client version and compatibility across operating systems remain unconfirmed.
+Checks performed when adding this app covered usage aggregation, data refresh, error handling, and service shutdown with synthetic sessions, plus a browser preview.
 
 ## License
 

plugins/yanhy2000/mcode-usage-monitor/README.md

@@ -24,7 +24,7 @@ The page opens on the last 24 hours. You can switch between 1 hour, 24 hours, 7
 
 This app requires **Python 3.8+** on the local machine to read the local database. It uses only the standard library, so no `pip install` is needed. No API key or other configuration is required.
 
-## Data access and counting
+## Data & access
 
 The app reads two local sources:
 
@@ -40,11 +40,15 @@ This is a local, near-real-time view. The in-product usage page (Settings → Us
 
 The runtime sends nothing to external services and has no telemetry. It writes a single preferences file (`prefs.json`) into the Host-provided plugin data directory. The page shows real session titles, so take care when sharing screenshots or your screen.
 
+## Tested environment
+
+Verified environment: MiniMax Code desktop `3.0.73.166` on Windows (10.0.26200, x64). macOS and Linux are unverified.
+
 ## Source and verification
 
 The page is in `miniapp/client/index.html` (ECharts is bundled locally), the Node entry is `miniapp/node/server.mjs`, and the data backend is `miniapp/node/api.py`. No build step is required.
 
-Verified environment: MiniMax Code desktop `3.0.73.166` on Windows (10.0.26200, x64). Verified during development: plugin install and open, aggregation and de-duplication, model/session filtering, preference persistence, auto refresh, theme switching, and chart and table rendering. macOS and Linux are unverified.
+Verified during development: plugin install and open, aggregation and de-duplication, model/session filtering, preference persistence, auto refresh, theme switching, and chart and table rendering.
 
 Third-party components: [ECharts](https://echarts.apache.org/) (Apache License 2.0), bundled locally for offline use.
 

scripts/lib/contract.mjs

@@ -103,5 +103,6 @@ export const REQUIRED_FILES = [
 export const README_HEADINGS = ['## Tested environment', '## Data & access'];
 
 export const STDOUT_CALL = /\b(?:console\.(?:log|info|debug|dir|table)|process\.stdout\.write)\s*\(/u;
-export const START_EXPORT =
-  /^\s*export\s+(?:async\s+function\s+start\b|function\s+start\b|const\s+start\b|let\s+start\b|\{[^}]*\bstart\b[^}]*\})/mu;
+export const START_EXPORT_DECLARATION =
+  /^\s*export\s+(?:(?:async\s+)?function\s+start\b|(?:const|let|var)\s+start\b)/mu;
+export const START_EXPORT_LIST = /^\s*export\s*\{([^}]*)\}/gmu;

scripts/lib/package.mjs

@@ -13,12 +13,14 @@ import { checkReadme } from './rules/readme.mjs';
 export async function validatePackage(packageDir, { requireLowercaseAuthor = true } = {}) {
   const dir = path.resolve(packageDir);
   const report = createReport();
+  let mcpServerNames = [];
 
   await checkLayout(report, { packageDir: dir, requireLowercaseAuthor });
 
   const manifest = await readJson(report, dir, '.minimax-plugin/plugin.json', 'MANIFEST_UNREADABLE');
   if (manifest.present) {
     const identity = await checkManifest(report, { packageDir: dir, manifest: manifest.value });
+    mcpServerNames = identity.mcpServerNames ?? [];
     await checkNameMatchesDirectory(report, { packageDir: dir, name: identity.name });
     if (identity.icon) await checkImageFile(report, { packageDir: dir, relativePath: identity.icon, label: 'icon' });
     if (identity.darkIcon) await checkImageFile(report, { packageDir: dir, relativePath: identity.darkIcon, label: 'darkIcon' });
@@ -29,7 +31,7 @@ export async function validatePackage(packageDir, { requireLowercaseAuthor = tru
 
   const miniapp = await readJson(report, dir, 'miniapp/miniapp.json', 'MINIAPP_UNREADABLE');
   let resolved = { nodeRoots: [], clientRoots: [] };
-  if (miniapp.present) resolved = await checkMiniApp(report, { packageDir: dir, manifest: miniapp.value });
+  if (miniapp.present) resolved = await checkMiniApp(report, { packageDir: dir, manifest: miniapp.value, mcpServerNames });
 
   await checkFiles(report, { packageDir: dir });
   await checkReadme(report, { packageDir: dir });

scripts/lib/paths.mjs

@@ -14,6 +14,12 @@ export function normalizePluginPath(value) {
   return { ok: true, value: normalized };
 }
 
+export function resolvePackagePath(packageDir, relativePath) {
+  const root = path.resolve(packageDir);
+  const absolute = path.resolve(root, ...relativePath.split('/'));
+  return absolute === root || absolute.startsWith(`${root}${path.sep}`) ? absolute : undefined;
+}
+
 export function portablePathIssue(relativePath) {
   if (!relativePath) return 'path is empty';
   if (!/^[\x00-\x7f]*$/u.test(relativePath)) return 'is not ASCII';

scripts/lib/rules/layout.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { REQUIRED_FILES } from '../contract.mjs';
 import { pathExists } from '../fs.mjs';
+import { resolvePackagePath } from '../paths.mjs';
 
 export async function checkLayout(report, { packageDir, requireLowercaseAuthor }) {
   if (requireLowercaseAuthor) {
@@ -36,7 +37,11 @@ const SIGNATURES = [
 ];
 
 export async function checkImageFile(report, { packageDir, relativePath, label }) {
-  const absolute = path.join(packageDir, ...relativePath.split('/'));
+  const absolute = resolvePackagePath(packageDir, relativePath);
+  if (absolute === undefined) {
+    report.error('LAYOUT_IMAGE_INVALID', `${label} path must stay inside the package`, relativePath);
+    return;
+  }
   if (!(await pathExists(absolute, 'file'))) {
     report.error('LAYOUT_IMAGE_INVALID', `${label} file does not exist`, relativePath);
     return;

scripts/lib/rules/manifest.mjs

@@ -1,5 +1,3 @@
-import path from 'node:path';
-
 import {
   APP_PATH,
   CATEGORIES,
@@ -15,7 +13,8 @@ import {
   SKILL_PATH,
   VERSION_MAX_LENGTH,
 } from '../contract.mjs';
-import { isRecord, pathExists } from '../fs.mjs';
+import { isRecord, pathExists, readJsonFile } from '../fs.mjs';
+import { portablePathIssue, resolvePackagePath } from '../paths.mjs';
 
 const FILE = '.minimax-plugin/plugin.json';
 
@@ -63,7 +62,8 @@ export async function checkManifest(report, { packageDir, manifest }) {
   if (apps && apps.length > 0) {
     report.warning('MANIFEST_APPS_IGNORED', 'apps entries are ignored for locally installed packages', FILE);
   }
-  await references(report, packageDir, manifest.mcpServers, 'mcpServers', MCP_PATH, { required: true, mustExist: true });
+  const mcpServers = await references(report, packageDir, manifest.mcpServers, 'mcpServers', MCP_PATH, { required: true, mustExist: true });
+  const mcpServerNames = await readMcpServerNames(packageDir, mcpServers);
   await references(report, packageDir, manifest.skills, 'skills', SKILL_PATH, { required: true, mustExist: true });
   await references(report, packageDir, manifest.hooks, 'hooks', HOOK_PATH, { required: false, mustExist: true });
   await references(report, packageDir, manifest.hostBindings, 'hostBindings', HOST_BINDING_PATH, { required: false, mustExist: true });
@@ -72,6 +72,7 @@ export async function checkManifest(report, { packageDir, manifest }) {
   if (name !== undefined) identity.name = name;
   if (icon !== undefined) identity.icon = icon;
   if (darkIcon !== undefined) identity.darkIcon = darkIcon;
+  identity.mcpServerNames = mcpServerNames;
   return identity;
 }
 
@@ -103,7 +104,7 @@ function imagePath(report, value, label, required) {
     return undefined;
   }
   const trimmed = value.trim();
-  if (trimmed.length > REFERENCE_MAX_LENGTH || !ICON_PATH.test(trimmed)) {
+  if (trimmed.length > REFERENCE_MAX_LENGTH || portablePathIssue(trimmed) || !ICON_PATH.test(trimmed)) {
     report.error('MANIFEST_FIELD_INVALID', `${label} must be a plugin-relative .png, .jpg, .jpeg, or .webp path`, FILE);
     return undefined;
   }
@@ -130,13 +131,32 @@ async function references(report, packageDir, value, label, pattern, { required,
     return items;
   }
   for (const item of items) {
-    if (item.length > REFERENCE_MAX_LENGTH || !pattern.test(item)) {
+    const issue = portablePathIssue(item);
+    if (item.length > REFERENCE_MAX_LENGTH || issue || !pattern.test(item)) {
       report.error('MANIFEST_REFERENCE_INVALID', `${label} entry "${item}" must match ${pattern.source}`, FILE);
       continue;
     }
-    if (mustExist && !(await pathExists(path.join(packageDir, ...item.split('/')), 'file'))) {
+    const absolute = resolvePackagePath(packageDir, item);
+    if (absolute === undefined) {
+      report.error('MANIFEST_REFERENCE_INVALID', `${label} entry "${item}" must stay inside the package`, FILE);
+      continue;
+    }
+    if (mustExist && !(await pathExists(absolute, 'file'))) {
       report.error('MANIFEST_REFERENCE_MISSING', `${label} entry "${item}" does not exist`, item);
     }
   }
   return items;
 }
+
+async function readMcpServerNames(packageDir, references) {
+  if (!references) return [];
+  const names = new Set();
+  for (const relativePath of references) {
+    const absolute = resolvePackagePath(packageDir, relativePath);
+    if (absolute === undefined) continue;
+    const result = await readJsonFile(absolute);
+    if (!result.ok || !isRecord(result.value) || !isRecord(result.value.mcpServers)) continue;
+    for (const name of Object.keys(result.value.mcpServers)) names.add(name);
+  }
+  return [...names];
+}

scripts/lib/rules/miniapp.mjs

@@ -18,7 +18,7 @@ import { isCoveredBy, normalizePluginPath, normalizeRoutePath } from '../paths.m
 
 const FILE = 'miniapp/miniapp.json';
 
-export async function checkMiniApp(report, { packageDir, manifest }) {
+export async function checkMiniApp(report, { packageDir, manifest, mcpServerNames = [] }) {
   const resolved = { nodeRoots: [], clientRoots: [] };
   if (!isRecord(manifest)) {
     report.error('MINIAPP_NOT_OBJECT', 'miniapp.json must be a JSON object', FILE);
@@ -35,7 +35,7 @@ export async function checkMiniApp(report, { packageDir, manifest }) {
   const entry = await checkRuntime(report, packageDir, manifest.runtime, artifacts.node);
   if (entry) resolved.entry = entry;
   checkSurface(report, manifest.surface);
-  checkMcpEndpoints(report, manifest.mcpEndpoints);
+  checkMcpEndpoints(report, manifest.mcpEndpoints, mcpServerNames);
   checkHostConnectorAccess(report, manifest.hostConnectorAccess);
   return resolved;
 }
@@ -120,12 +120,16 @@ function checkSurface(report, value) {
   if (!route.ok) report.error('MINIAPP_SURFACE_INVALID', `surface.path ${route.reason}`, FILE);
 }
 
-function checkMcpEndpoints(report, value) {
-  if (value === undefined) return;
+function checkMcpEndpoints(report, value, mcpServerNames) {
+  if (value === undefined) {
+    report.error('MINIAPP_MCP_ENDPOINT_INVALID', 'mcpEndpoints must be an array (use [] when empty)', FILE);
+    return;
+  }
   if (!Array.isArray(value)) {
     report.error('MINIAPP_MCP_ENDPOINT_INVALID', 'mcpEndpoints must be an array (use [] when empty)', FILE);
     return;
   }
+  const knownServers = new Set(mcpServerNames);
   const servers = new Set();
   const paths = new Set();
   for (const item of value) {
@@ -137,6 +141,10 @@ function checkMcpEndpoints(report, value) {
       report.error('MINIAPP_MCP_ENDPOINT_INVALID', `MCP endpoint server must match ${MCP_SERVER_NAME.source}`, FILE);
       continue;
     }
+    if (!knownServers.has(item.server)) {
+      report.error('MINIAPP_MCP_ENDPOINT_INVALID', `MCP server "${item.server}" is not declared by plugin.json.mcpServers`, FILE);
+      continue;
+    }
     const route = normalizeRoutePath(item.path);
     if (!route.ok) {
       report.error('MINIAPP_MCP_ENDPOINT_INVALID', `MCP endpoint path ${route.reason}`, FILE);

scripts/lib/rules/node.mjs

@@ -3,7 +3,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 
-import { START_EXPORT, STDOUT_CALL } from '../contract.mjs';
+import { START_EXPORT_DECLARATION, START_EXPORT_LIST, STDOUT_CALL } from '../contract.mjs';
 import { pathExists } from '../fs.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -25,26 +25,34 @@ export async function checkNode(report, { packageDir, entry, nodeRoots }) {
     const absolute = path.join(packageDir, ...relativePath.split('/'));
     if (!(await pathExists(absolute, 'file'))) continue;
     const isEntry = relativePath === entry;
-    if (path.extname(relativePath) !== '.js') {
-      try {
-        await execFileAsync(process.execPath, ['--check', absolute], { windowsHide: true });
-      } catch (error) {
-        report.error('ENTRY_SYNTAX', firstLine(error.stderr) || 'syntax check failed', relativePath);
-        continue;
-      }
+    try {
+      await execFileAsync(process.execPath, ['--check', absolute], { windowsHide: true });
+    } catch (error) {
+      report.error('ENTRY_SYNTAX', firstLine(error.stderr) || 'syntax check failed', relativePath);
+      continue;
     }
     const source = await readFile(absolute, 'utf8');
     if (STDOUT_CALL.test(source)) {
       const message = 'writes to stdout, which belongs to the Host; log through context.logger instead';
       if (isEntry) report.error('ENTRY_STDOUT', message, relativePath);
       else report.warning('ENTRY_STDOUT', message, relativePath);
     }
-    if (isEntry && !START_EXPORT.test(source)) {
+    if (isEntry && !hasNamedStartExport(source)) {
       report.error('ENTRY_START_EXPORT_MISSING', 'the Node entry must export a named start function using ESM syntax', relativePath);
     }
   }
 }
 
+function hasNamedStartExport(source) {
+  if (START_EXPORT_DECLARATION.test(source)) return true;
+  START_EXPORT_LIST.lastIndex = 0;
+  for (const match of source.matchAll(START_EXPORT_LIST)) {
+    const specifiers = match[1].split(',').map((specifier) => specifier.trim());
+    if (specifiers.some((specifier) => /^(?:start|[A-Za-z_$][\w$]*\s+as\s+start|default\s+as\s+start)$/u.test(specifier))) return true;
+  }
+  return false;
+}
+
 async function collectScripts(absoluteDir, relativeDir) {
   const files = [];
   for (const dirent of await readdir(absoluteDir, { withFileTypes: true })) {