miaoda-game-devkit 0.8.0 → 0.8.1

package/mechanics/materialize-game-mechanics-source.mjs

@@ -7,8 +7,8 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
-  readFileSync,
   readdirSync,
+  readFileSync,
   renameSync,
   rmSync,
   statSync,
@@ -29,8 +29,7 @@ const SOURCE_ROOT = 'src/game-mechanics';
 const STATE_FILENAME = 'mechanics-source.json';
 const WORKSPACE_PATTERN = 'src/game-mechanics/*';
 const STATE_SCHEMA_VERSION = 2;
-const DEFAULT_SOURCE_INDEX_URL =
-  'https://resource-static.bj.bcebos.com/miaoda-game/stable.json';
+const DEFAULT_SOURCE_INDEX_URL = 'https://resource-static.bj.bcebos.com/miaoda-game/stable.json';
 
 function fail(api, field, expected, repair) {
   throw new Error(`miaoda mechanics source ${api}: ${field} must ${expected}. ${repair}`);
@@ -41,9 +40,8 @@ function readJson(path, label = path) {
   try {
     value = JSON.parse(readFileSync(path, 'utf8'));
   } catch (error) {
-    throw new Error(
-      `miaoda mechanics source: cannot read ${label} as JSON: ${error instanceof Error ? error.message : String(error)}`,
-    );
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`miaoda mechanics source: cannot read ${label} as JSON: ${detail}`);
   }
   return value;
 }
@@ -53,15 +51,25 @@ function writeJson(path, value) {
 }
 
 function sourcePath(value) {
-  if (typeof value !== 'string' || !value.startsWith('./dist/')) return value;
-  if (value.endsWith('.d.ts')) return `./src/${value.slice('./dist/'.length, -'.d.ts'.length)}.ts`;
-  if (value.endsWith('.js')) return `./src/${value.slice('./dist/'.length, -'.js'.length)}.ts`;
+  if (typeof value !== 'string' || !value.startsWith('./dist/')) {
+    return value;
+  }
+  if (value.endsWith('.d.ts')) {
+    return `./src/${value.slice('./dist/'.length, -'.d.ts'.length)}.ts`;
+  }
+  if (value.endsWith('.js')) {
+    return `./src/${value.slice('./dist/'.length, -'.js'.length)}.ts`;
+  }
   return value.replace('./dist/', './src/');
 }
 
 function rewriteExportPaths(value) {
-  if (typeof value === 'string') return sourcePath(value);
-  if (Array.isArray(value)) return value.map(rewriteExportPaths);
+  if (typeof value === 'string') {
+    return sourcePath(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(rewriteExportPaths);
+  }
   if (value && typeof value === 'object') {
     return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, rewriteExportPaths(child)]));
   }
@@ -69,9 +77,15 @@ function rewriteExportPaths(value) {
 }
 
 function stringValues(value) {
-  if (typeof value === 'string') return [value];
-  if (Array.isArray(value)) return value.flatMap(stringValues);
-  if (value && typeof value === 'object') return Object.values(value).flatMap(stringValues);
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap(stringValues);
+  }
+  if (value && typeof value === 'object') {
+    return Object.values(value).flatMap(stringValues);
+  }
   return [];
 }
 
@@ -83,15 +97,23 @@ export function createSourceManifest(manifest, resolvedPackages) {
   delete generated.files;
   delete generated.scripts;
   for (const field of ['main', 'module', 'types']) {
-    if (field in generated) generated[field] = sourcePath(generated[field]);
+    if (field in generated) {
+      generated[field] = sourcePath(generated[field]);
+    }
+  }
+  if (generated.exports) {
+    generated.exports = rewriteExportPaths(generated.exports);
   }
-  if (generated.exports) generated.exports = rewriteExportPaths(generated.exports);
 
   for (const field of ['dependencies', 'optionalDependencies']) {
-    if (!generated[field]) continue;
+    if (!generated[field]) {
+      continue;
+    }
     for (const dependencyName of Object.keys(generated[field])) {
       const dependency = resolvedPackages.get(dependencyName);
-      if (dependency) generated[field][dependencyName] = `workspace:${dependency.version}`;
+      if (dependency) {
+        generated[field][dependencyName] = `workspace:${dependency.version}`;
+      }
     }
   }
   return generated;
@@ -99,25 +121,52 @@ export function createSourceManifest(manifest, resolvedPackages) {
 
 export function validateMechanicSelection(projectManifest, resolvedPackages, capabilityDocument) {
   const config = projectManifest.miaodaGame;
-  if (config === undefined) return;
+  if (config === undefined) {
+    return;
+  }
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
-    fail('add', 'package.json miaodaGame', 'be an object when defined', 'Remove it or declare schemaVersion, engine, uses, and blockedPackages.');
+    fail(
+      'add',
+      'package.json miaodaGame',
+      'be an object when defined',
+      'Remove it or declare schemaVersion, engine, uses, and blockedPackages.',
+    );
   }
   const engines = new Set(['neutral', 'react', 'phaser', 'cocos']);
   if (config.schemaVersion !== 1 || !engines.has(config.engine)) {
-    fail('add', 'package.json miaodaGame', 'use schemaVersion 1 and a neutral, react, phaser, or cocos engine', 'Correct the project mechanic selection metadata.');
+    fail(
+      'add',
+      'package.json miaodaGame',
+      'use schemaVersion 1 and a neutral, react, phaser, or cocos engine',
+      'Correct the project mechanic selection metadata.',
+    );
   }
   if (!config.uses || typeof config.uses !== 'object' || Array.isArray(config.uses)) {
-    fail('add', 'package.json miaodaGame.uses', 'be an object', 'Map selected package names to their intended owned capabilities.');
+    fail(
+      'add',
+      'package.json miaodaGame.uses',
+      'be an object',
+      'Map selected package names to their intended owned capabilities.',
+    );
   }
   if (!Array.isArray(config.blockedPackages)) {
-    fail('add', 'package.json miaodaGame.blockedPackages', 'be an array', 'Use an empty array when no package is blocked.');
+    fail(
+      'add',
+      'package.json miaodaGame.blockedPackages',
+      'be an array',
+      'Use an empty array when no package is blocked.',
+    );
   }
   const capabilities = capabilityDocument?.packages ?? {};
   const owners = new Map();
   for (const [name, resolvedPackage] of resolvedPackages) {
     if (config.blockedPackages.includes(name)) {
-      fail('add', name, 'not be listed in miaodaGame.blockedPackages', 'Remove the package request or unblock it explicitly.');
+      fail(
+        'add',
+        name,
+        'not be listed in miaodaGame.blockedPackages',
+        'Remove the package request or unblock it explicitly.',
+      );
     }
     const capability = capabilities[name];
     if (
@@ -126,27 +175,56 @@ export function validateMechanicSelection(projectManifest, resolvedPackages, cap
       config.engine !== 'neutral' &&
       capability.engine !== config.engine
     ) {
-      fail('add', `${name} engine`, `match project engine ${config.engine}`, `Choose a ${config.engine} adapter or an engine-neutral core package.`);
+      fail(
+        'add',
+        `${name} engine`,
+        `match project engine ${config.engine}`,
+        `Choose a ${config.engine} adapter or an engine-neutral core package.`,
+      );
     }
     const uses = config.uses[name];
-    if (uses === undefined) continue;
+    if (uses === undefined) {
+      continue;
+    }
     if (!capability) {
-      fail('add', `${name} capability metadata`, 'exist before declaring miaodaGame.uses', 'Update the Devkit capability snapshot or remove the declaration.');
+      fail(
+        'add',
+        `${name} capability metadata`,
+        'exist before declaring miaodaGame.uses',
+        'Update the Devkit capability snapshot or remove the declaration.',
+      );
     }
     if (!Array.isArray(uses) || uses.length === 0 || new Set(uses).size !== uses.length) {
-      fail('add', `miaodaGame.uses.${name}`, 'be a non-empty array without duplicates', 'Declare each intended owned capability once.');
+      fail(
+        'add',
+        `miaodaGame.uses.${name}`,
+        'be a non-empty array without duplicates',
+        'Declare each intended owned capability once.',
+      );
     }
     for (const use of uses) {
       if (!capability.owns.includes(use)) {
-        fail('add', `${name} use ${use}`, `be one of its owned capabilities: ${capability.owns.join(', ')}`, 'Select the correct package or capability name.');
+        fail(
+          'add',
+          `${name} use ${use}`,
+          `be one of its owned capabilities: ${capability.owns.join(', ')}`,
+          'Select the correct package or capability name.',
+        );
       }
       const existing = owners.get(use);
       if (existing && existing !== name) {
-        fail('add', `capability ${use}`, `have one owner, but both ${existing} and ${name} are selected`, 'Remove the duplicate ownership assignment.');
+        fail(
+          'add',
+          `capability ${use}`,
+          `have one owner, but both ${existing} and ${name} are selected`,
+          'Remove the duplicate ownership assignment.',
+        );
       }
       owners.set(use, name);
     }
-    if (resolvedPackage.version.length === 0) fail('add', `${name} version`, 'be non-empty', 'Repack the package.');
+    if (resolvedPackage.version.length === 0) {
+      fail('add', `${name} version`, 'be non-empty', 'Repack the package.');
+    }
   }
 }
 
@@ -165,14 +243,20 @@ function validateSourceEntrypoints(packageDirectory, manifest) {
 }
 
 function listFiles(root, current = root) {
-  const entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+  const entries = readdirSync(current, { withFileTypes: true }).sort((left, right) =>
+    left.name.localeCompare(right.name),
+  );
   const files = [];
   for (const entry of entries) {
-    if (entry.name === 'node_modules') continue;
+    if (entry.name === 'node_modules') {
+      continue;
+    }
     const path = join(current, entry.name);
-    if (entry.isDirectory()) files.push(...listFiles(root, path));
-    else if (entry.isFile()) files.push(path);
-    else if (entry.isSymbolicLink()) {
+    if (entry.isDirectory()) {
+      files.push(...listFiles(root, path));
+    } else if (entry.isFile()) {
+      files.push(path);
+    } else if (entry.isSymbolicLink()) {
       fail(
         'add',
         `${relative(root, path)} in ${root}`,
@@ -197,10 +281,17 @@ function hashTree(root) {
 
 function readState(metadataRoot) {
   const statePath = join(metadataRoot, STATE_FILENAME);
-  if (!existsSync(statePath)) return { schemaVersion: STATE_SCHEMA_VERSION, roots: {}, packages: {} };
+  if (!existsSync(statePath)) {
+    return { schemaVersion: STATE_SCHEMA_VERSION, roots: {}, packages: {} };
+  }
   const state = readJson(statePath, STATE_FILENAME);
   if (state.schemaVersion !== STATE_SCHEMA_VERSION || !state.roots || !state.packages) {
-    fail('add', STATE_FILENAME, `use schemaVersion ${STATE_SCHEMA_VERSION}`, `Preserve src/game-mechanics, then remove ${STATE_FILENAME} to adopt it again.`);
+    fail(
+      'add',
+      STATE_FILENAME,
+      `use schemaVersion ${STATE_SCHEMA_VERSION}`,
+      `Preserve src/game-mechanics, then remove ${STATE_FILENAME} to adopt it again.`,
+    );
   }
   return state;
 }
@@ -209,12 +300,22 @@ function inspectExistingPackages(sourceRoot, state) {
   const statuses = {};
   if (!existsSync(sourceRoot)) {
     if (Object.keys(state.packages).length > 0) {
-      fail('add', sourceRoot, 'exist for the recorded state', `Restore it or preserve intentional changes and remove ${STATE_FILENAME} to reinstall.`);
+      fail(
+        'add',
+        sourceRoot,
+        'exist for the recorded state',
+        `Restore it or preserve intentional changes and remove ${STATE_FILENAME} to reinstall.`,
+      );
     }
     return statuses;
   }
   if (lstatSync(sourceRoot).isSymbolicLink()) {
-    fail('add', sourceRoot, 'be a real project directory, not a symbolic link', 'Replace the link after preserving its contents.');
+    fail(
+      'add',
+      sourceRoot,
+      'be a real project directory, not a symbolic link',
+      'Replace the link after preserving its contents.',
+    );
   }
   for (const [name, record] of Object.entries(state.packages)) {
     const directory = join(sourceRoot, name);
@@ -223,7 +324,12 @@ function inspectExistingPackages(sourceRoot, state) {
       continue;
     }
     if (lstatSync(directory).isSymbolicLink()) {
-      fail('add', `${name} source`, 'be a real directory, not a symbolic link', 'Replace the link with the editable source directory.');
+      fail(
+        'add',
+        `${name} source`,
+        'be a real directory, not a symbolic link',
+        'Replace the link with the editable source directory.',
+      );
     }
     statuses[name] = hashTree(directory) === record.sha256 ? 'clean' : 'modified';
   }
@@ -257,15 +363,20 @@ function ensureWorkspacePattern(projectRoot) {
     return { path: workspacePath, previous };
   }
   let insertAt = packagesIndex + 1;
-  while (insertAt < lines.length && (lines[insertAt].trim() === '' || /^\s+/.test(lines[insertAt]))) insertAt += 1;
+  while (insertAt < lines.length && (lines[insertAt].trim() === '' || /^\s+/.test(lines[insertAt]))) {
+    insertAt += 1;
+  }
   lines.splice(insertAt, 0, `  - ${quotedPattern}`);
   writeFileSync(workspacePath, lines.join('\n'));
   return { path: workspacePath, previous };
 }
 
 function restoreFile(path, previous) {
-  if (previous === undefined) rmSync(path, { force: true });
-  else writeFileSync(path, previous);
+  if (previous === undefined) {
+    rmSync(path, { force: true });
+  } else {
+    writeFileSync(path, previous);
+  }
 }
 
 function updateProjectManifest(projectRoot, roots, resolvedPackages) {
@@ -276,7 +387,12 @@ function updateProjectManifest(projectRoot, roots, resolvedPackages) {
   for (const name of Object.keys(roots).sort()) {
     const resolvedPackage = resolvedPackages.get(name);
     if (!resolvedPackage) {
-      fail('add', `direct package ${name}`, 'be present in the resolved Miaoda graph', 'Check the source package name and registry metadata.');
+      fail(
+        'add',
+        `direct package ${name}`,
+        'be present in the resolved Miaoda graph',
+        'Check the source package name and registry metadata.',
+      );
     }
     manifest.dependencies[name] = `workspace:${resolvedPackage.version}`;
   }
@@ -288,7 +404,12 @@ function pnpmVersion(pnpmCommand, cwd) {
   const result = spawnSync(pnpmCommand, ['--version'], { cwd, encoding: 'utf8' });
   if (result.status !== 0) {
     const detail = result.error?.message || result.stderr?.trim() || result.stdout?.trim();
-    fail('add', 'pnpm command', 'run successfully', detail || `Install pnpm 10 or 11 and ensure ${pnpmCommand} is on PATH.`);
+    fail(
+      'add',
+      'pnpm command',
+      'run successfully',
+      detail || `Install pnpm 10 or 11 and ensure ${pnpmCommand} is on PATH.`,
+    );
   }
   const version = result.stdout.trim();
   const major = Number.parseInt(version.split('.')[0], 10);
@@ -323,7 +444,9 @@ function copyResolvedPackage(target, resolvedPackage, resolvedPackages) {
     recursive: true,
     filter: (source) => {
       const sourceName = basename(source);
-      if (['node_modules', 'dist', 'coverage', '.nx', '__tests__'].includes(sourceName)) return false;
+      if (['node_modules', 'dist', 'coverage', '.nx', '__tests__'].includes(sourceName)) {
+        return false;
+      }
       if (/\.(?:spec|test)\.[cm]?[jt]sx?$/.test(sourceName) || /^vitest\.config\.[cm]?[jt]s$/.test(sourceName)) {
         return false;
       }
@@ -337,19 +460,56 @@ function copyResolvedPackage(target, resolvedPackage, resolvedPackages) {
   return hashTree(target);
 }
 
-const legacyAgentsSource = '# Editable game mechanics\n\n- This directory contains editable TypeScript source, not generated build output.\n- Preserve package boundaries and import packages by their `miaoda-game-*` names.\n- Modify each package under `<package>/src/`; do not edit `node_modules`.\n- Run `pnpm exec miaoda mechanics status` before updating a locally modified package.\n';
+const legacyAgentsSource = [
+  '# Editable game mechanics',
+  '',
+  '- This directory contains editable TypeScript source, not generated build output.',
+  '- Preserve package boundaries and import packages by their `miaoda-game-*` names.',
+  '- Modify each package under `<package>/src/`; do not edit `node_modules`.',
+  '- Run `pnpm exec miaoda mechanics status` before updating a locally modified package.',
+  '',
+].join('\n');
 const generatedReadmeMarker = '<!-- Generated by miaoda mechanics. -->';
 
-function sourceReadme(resolvedPackages, capabilityDocument) {
+function readmeDetail(label, value, separator = ', ') {
+  if (Array.isArray(value)) {
+    return value.length > 0 ? [`- ${label}: ${value.join(separator)}`] : [];
+  }
+  return typeof value === 'string' && value.length > 0 ? [`- ${label}: ${value}`] : [];
+}
+
+function capabilityReadme(capability) {
+  if (!capability) {
+    return ['- Capability metadata: unavailable; read the package README and source before assigning ownership.'];
+  }
+  return [
+    ...readmeDetail('Engine', capability.engine),
+    ...readmeDetail('Domains', capability.domains),
+    ...readmeDetail('Owns', capability.owns),
+    ...readmeDetail('Keep outside', capability.doesNotOwn),
+    ...readmeDetail('Compatible with', capability.compatibleWith),
+    ...readmeDetail('Use for', capability.guidance?.useFor, ' '),
+    ...readmeDetail('Boundary guidance', capability.guidance?.keepOutside, ' '),
+    ...readmeDetail('Rules', capability.guidance?.rules, ' '),
+    ...(capability.useInsteadWhen ?? []).map(
+      ({ package: packageName, condition }) => `- Use ${packageName} instead when: ${condition}`,
+    ),
+    ...readmeDetail('Persistence', capability.persistence),
+    ...readmeDetail('Observe', capability.testability?.methods?.observe),
+    ...readmeDetail('Advance', capability.testability?.methods?.advance),
+  ];
+}
+
+export function createSourceReadme(resolvedPackages, capabilityDocument) {
   const packages = [...resolvedPackages]
     .sort(([left], [right]) => left.localeCompare(right))
     .map(([name, resolvedPackage]) => {
       const capability = capabilityDocument?.packages?.[name];
       const description = resolvedPackage.manifest.description || 'Miaoda game mechanic package.';
-      const owns = capability?.owns?.length ? `\n  - Provides: ${capability.owns.join(', ')}` : '';
-      return `- \`${name}@${resolvedPackage.version}\` — ${description}${owns}`;
+      const details = [`- Source: \`./${name}/\``, ...capabilityReadme(capability)].join('\n');
+      return `### \`${name}@${resolvedPackage.version}\`\n\n${description}\n\n${details}`;
     })
-    .join('\n');
+    .join('\n\n');
   return `${generatedReadmeMarker}
 # Game mechanics
 
@@ -377,7 +537,7 @@ function ensureSourceGuidance(sourceRoot, resolvedPackages, capabilityDocument)
     existingReadme.startsWith(generatedReadmeMarker) ||
     existingReadme.startsWith('# Game mechanics source\n')
   ) {
-    writeFileSync(readmePath, sourceReadme(resolvedPackages, capabilityDocument));
+    writeFileSync(readmePath, createSourceReadme(resolvedPackages, capabilityDocument));
   }
   const agentsPath = join(sourceRoot, 'AGENTS.md');
   if (existsSync(agentsPath) && readFileSync(agentsPath, 'utf8') === legacyAgentsSource) {
@@ -407,7 +567,12 @@ function materializePackages(
     const previous = previousState.packages[name];
     if (previous && previous.version === resolvedPackage.version) {
       if (statuses[name] === 'missing') {
-        fail('add', `${name} source`, 'still exist', `Restore ${join(sourceRoot, name)} or remove its state entry before reinstalling.`);
+        fail(
+          'add',
+          `${name} source`,
+          'still exist',
+          `Restore ${join(sourceRoot, name)} or remove its state entry before reinstalling.`,
+        );
       }
       records[name] = previous;
       continue;
@@ -417,16 +582,25 @@ function materializePackages(
         'add',
         `${name} ${previous.version} source`,
         `be clean before updating to ${resolvedPackage.version}`,
-        `Preserve or commit ${join(sourceRoot, name)}, then explicitly restore it before retrying the update. Nothing was overwritten.`,
+        `Preserve or commit ${join(sourceRoot, name)}, then explicitly restore it before retrying ` +
+          'the update. Nothing was overwritten.',
       );
     }
     if (existsSync(target)) {
       if (!previous) {
-        fail('add', `${name} destination`, 'not contain an unmanaged package', `Move ${join(sourceRoot, name)} elsewhere or adopt it explicitly.`);
+        fail(
+          'add',
+          `${name} destination`,
+          'not contain an unmanaged package',
+          `Move ${join(sourceRoot, name)} elsewhere or adopt it explicitly.`,
+        );
       }
       rmSync(target, { recursive: true, force: true });
     }
-    records[name] = { version: resolvedPackage.version, sha256: copyResolvedPackage(target, resolvedPackage, resolvedPackages) };
+    records[name] = {
+      version: resolvedPackage.version,
+      sha256: copyResolvedPackage(target, resolvedPackage, resolvedPackages),
+    };
   }
   return records;
 }
@@ -434,11 +608,15 @@ function materializePackages(
 function switchManagedDirectory(sourceRoot, stagedSourceRoot, metadataRoot) {
   const backupRoot = join(metadataRoot, `.game-mechanics-backup-${randomUUID()}`);
   mkdirSync(dirname(sourceRoot), { recursive: true });
-  if (existsSync(sourceRoot)) renameSync(sourceRoot, backupRoot);
+  if (existsSync(sourceRoot)) {
+    renameSync(sourceRoot, backupRoot);
+  }
   try {
     renameSync(stagedSourceRoot, sourceRoot);
   } catch (error) {
-    if (existsSync(backupRoot)) renameSync(backupRoot, sourceRoot);
+    if (existsSync(backupRoot)) {
+      renameSync(backupRoot, sourceRoot);
+    }
     throw error;
   }
   return { packagesRoot: sourceRoot, backupRoot: existsSync(backupRoot) ? backupRoot : undefined };
@@ -446,7 +624,9 @@ function switchManagedDirectory(sourceRoot, stagedSourceRoot, metadataRoot) {
 
 function restoreManagedDirectory({ packagesRoot, backupRoot }) {
   rmSync(packagesRoot, { recursive: true, force: true });
-  if (backupRoot) renameSync(backupRoot, packagesRoot);
+  if (backupRoot) {
+    renameSync(backupRoot, packagesRoot);
+  }
 }
 
 function parseArguments(argv) {
@@ -454,7 +634,9 @@ function parseArguments(argv) {
   const projectArgument = argv.find((argument) => argument.startsWith('--project='));
   const pnpmArgument = argv.find((argument) => argument.startsWith('--pnpm='));
   const sourceIndexArgument = argv.find((argument) => argument.startsWith('--source-index='));
-  const options = new Set(argv.filter((argument) => argument.startsWith('--')).map((argument) => argument.split('=')[0]));
+  const options = new Set(
+    argv.filter((argument) => argument.startsWith('--')).map((argument) => argument.split('=')[0]),
+  );
   const specs = argv.slice(1).filter((argument) => !argument.startsWith('--'));
   return {
     command,
@@ -514,7 +696,12 @@ function validateProject(projectRoot) {
 
 function validateMetadataRoot(metadataRoot) {
   if (existsSync(metadataRoot) && lstatSync(metadataRoot).isSymbolicLink()) {
-    fail('add', metadataRoot, 'be a real directory, not a symbolic link', `Replace ${METADATA_ROOT} with a project-local directory.`);
+    fail(
+      'add',
+      metadataRoot,
+      'be a real directory, not a symbolic link',
+      `Replace ${METADATA_ROOT} with a project-local directory.`,
+    );
   }
 }
 
@@ -526,12 +713,14 @@ export function mechanicSourceStatus({ projectRoot }) {
   const state = readState(metadataRoot);
   const sourceRoot = join(projectRoot, SOURCE_ROOT);
   const statuses = inspectExistingPackages(sourceRoot, state);
-  return Object.keys(state.packages).sort().map((name) => ({
-    name,
-    version: state.packages[name].version,
-    status: statuses[name],
-    path: join(sourceRoot, name),
-  }));
+  return Object.keys(state.packages)
+    .sort()
+    .map((name) => ({
+      name,
+      version: state.packages[name].version,
+      status: statuses[name],
+      path: join(sourceRoot, name),
+    }));
 }
 
 export async function addMechanicSources({
@@ -544,7 +733,12 @@ export async function addMechanicSources({
   projectRoot = resolve(projectRoot);
   validateProject(projectRoot);
   if (!Array.isArray(specs) || specs.length === 0) {
-    fail('add', 'package specs', 'contain at least one miaoda-game-* package', 'Pass a package name with an optional @version.');
+    fail(
+      'add',
+      'package specs',
+      'contain at least one miaoda-game-* package',
+      'Pass a package name with an optional @version.',
+    );
   }
   if (!sourceIndexUrl) {
     fail(
@@ -628,8 +822,12 @@ export async function addMechanicSources({
       sourceIndexUrl: indexedResolution.sourceIndexUrl,
     });
 
-    if (!skipInstall) runPnpm(pnpmCommand, ['install', '--ignore-scripts', '--no-frozen-lockfile'], projectRoot);
-    if (switched.backupRoot) rmSync(switched.backupRoot, { recursive: true, force: true });
+    if (!skipInstall) {
+      runPnpm(pnpmCommand, ['install', '--ignore-scripts', '--no-frozen-lockfile'], projectRoot);
+    }
+    if (switched.backupRoot) {
+      rmSync(switched.backupRoot, { recursive: true, force: true });
+    }
     return {
       directPackages: directNames,
       packageNames: [...resolvedPackages.keys()].sort(),
@@ -637,12 +835,20 @@ export async function addMechanicSources({
       pnpmVersion: version,
     };
   } catch (error) {
-    if (projectManifestChange) restoreFile(projectManifestChange.path, projectManifestChange.previous);
-    if (workspaceChange) restoreFile(workspaceChange.path, workspaceChange.previous);
-    if (switched) restoreManagedDirectory(switched);
+    if (projectManifestChange) {
+      restoreFile(projectManifestChange.path, projectManifestChange.previous);
+    }
+    if (workspaceChange) {
+      restoreFile(workspaceChange.path, workspaceChange.previous);
+    }
+    if (switched) {
+      restoreManagedDirectory(switched);
+    }
     restoreFile(statePath, previousStateText);
     restoreFile(lockfilePath, previousLockfileText);
-    if (!nodeModulesExisted) rmSync(nodeModulesPath, { recursive: true, force: true });
+    if (!nodeModulesExisted) {
+      rmSync(nodeModulesPath, { recursive: true, force: true });
+    }
     throw error;
   } finally {
     cleanupIndexedMechanics(indexedResolution);
@@ -654,7 +860,7 @@ export async function main(argv = process.argv.slice(2)) {
   const mechanicsArguments = argv[0] === 'mechanics' ? argv.slice(1) : argv;
   const command = mechanicsArguments[0];
   const wantsHelp = mechanicsArguments.includes('--help') || mechanicsArguments.includes('-h');
-  if (!command || command === 'help' || wantsHelp && !['add', 'status'].includes(command)) {
+  if (!command || command === 'help' || (wantsHelp && !['add', 'status'].includes(command))) {
     console.log(ROOT_HELP);
     return;
   }
@@ -675,17 +881,20 @@ export async function main(argv = process.argv.slice(2)) {
     }
     const options = parseArguments(mechanicsArguments);
     const statuses = mechanicSourceStatus(options);
-    if (statuses.length === 0) console.log('No Miaoda game-mechanic source packages are installed.');
-    else for (const entry of statuses) console.log(`${entry.name}@${entry.version}  ${entry.status}  ${entry.path}`);
+    if (statuses.length === 0) {
+      console.log('No Miaoda game-mechanic source packages are installed.');
+    } else {
+      for (const entry of statuses) {
+        console.log(`${entry.name}@${entry.version}  ${entry.status}  ${entry.path}`);
+      }
+    }
     return statuses;
   }
   throw new Error(`Unknown miaoda mechanics command: ${command}\n\n${ROOT_HELP}`);
 }
 
 export function formatAddResult(result) {
-  const packagePaths = result.packageNames
-    .map((name) => `  - src/game-mechanics/${name}/`)
-    .join('\n');
+  const packagePaths = result.packageNames.map((name) => `  - src/game-mechanics/${name}/`).join('\n');
   return `✓ Added ${result.packageNames.length} editable game-mechanic source packages
 
 Added source:

package/mechanics/resolve-game-mechanics-source-index.mjs

@@ -1,10 +1,9 @@
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, relative } from 'node:path';
 import { x as extractTarball } from 'tar';
 
-const MECHANIC_PREFIX = 'miaoda-game-';
 const INDEX_SCHEMA_VERSION = 1;
 const MAX_INDEX_BYTES = 5 * 1024 * 1024;
 const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
@@ -18,9 +17,13 @@ function isMechanicName(value) {
 }
 
 function parsePackageSpec(spec) {
-  if (typeof spec !== 'string') return undefined;
+  if (typeof spec !== 'string') {
+    return undefined;
+  }
   const match = /^(miaoda-game-[a-z0-9][a-z0-9._-]*?)(?:@([^/]+))?$/.exec(spec);
-  if (!match) return undefined;
+  if (!match) {
+    return undefined;
+  }
   return { name: match[1], version: match[2] };
 }
 
@@ -30,13 +33,19 @@ export function areIndexedPackageSpecs(specs) {
 
 async function readResponse(response, limit, label) {
   if (!response.ok) {
-    fail(label, `download successfully, but received HTTP ${response.status}`, 'Check the public source URL and object permissions.');
+    fail(
+      label,
+      `download successfully, but received HTTP ${response.status}`,
+      'Check the public source URL and object permissions.',
+    );
   }
   const declaredLength = Number(response.headers.get('content-length'));
   if (Number.isFinite(declaredLength) && declaredLength > limit) {
     fail(label, `be at most ${limit} bytes`, 'Publish a smaller source artifact.');
   }
-  if (!response.body) fail(label, 'contain a response body', 'Upload the source object again.');
+  if (!response.body) {
+    fail(label, 'contain a response body', 'Upload the source object again.');
+  }
   const chunks = [];
   let total = 0;
   for await (const chunk of response.body) {
@@ -76,7 +85,11 @@ function validateVersionRecord(name, version, record, indexUrl) {
     fail(`${name}@${version} url`, 'use HTTP or HTTPS', 'Upload the source archive to the configured public storage.');
   }
   if (typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(record.sha256)) {
-    fail(`${name}@${version} sha256`, 'contain 64 hexadecimal characters', 'Regenerate the source index after packing.');
+    fail(
+      `${name}@${version} sha256`,
+      'contain 64 hexadecimal characters',
+      'Regenerate the source index after packing.',
+    );
   }
   const dependencies = record.dependencies ?? {};
   if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) {
@@ -113,11 +126,19 @@ function selectVersion(index, name, requestedVersion, indexUrl) {
 function resolveGraph(index, indexUrl, previousRoots, specs) {
   const roots = new Map();
   for (const [name, version] of Object.entries(previousRoots ?? {})) {
-    if (isMechanicName(name) && typeof version === 'string' && version.length > 0) roots.set(name, version);
+    if (isMechanicName(name) && typeof version === 'string' && version.length > 0) {
+      roots.set(name, version);
+    }
   }
   for (const spec of specs) {
     const parsed = parsePackageSpec(spec);
-    if (!parsed) fail(`package spec ${spec}`, 'be a miaoda-game-* name with an optional @version', 'Pass TGZ URLs without --source-index.');
+    if (!parsed) {
+      fail(
+        `package spec ${spec}`,
+        'be a miaoda-game-* name with an optional @version',
+        'Pass TGZ URLs without --source-index.',
+      );
+    }
     const selected = selectVersion(index, parsed.name, parsed.version, indexUrl);
     roots.set(parsed.name, selected.version);
   }
@@ -140,7 +161,11 @@ function resolveGraph(index, indexUrl, previousRoots, specs) {
     const selected = selectVersion(index, request.name, request.version, indexUrl);
     selectedPackages.set(request.name, selected);
     for (const [dependencyName, dependencyVersion] of Object.entries(selected.dependencies).sort()) {
-      queue.push({ name: dependencyName, version: dependencyVersion, requestedBy: `${selected.name}@${selected.version}` });
+      queue.push({
+        name: dependencyName,
+        version: dependencyVersion,
+        requestedBy: `${selected.name}@${selected.version}`,
+      });
     }
   }
   return { roots: Object.fromEntries([...roots].sort()), selectedPackages };
@@ -164,7 +189,11 @@ async function readIndex(indexUrl) {
     fail('stable.json', 'contain valid JSON', error instanceof Error ? error.message : String(error));
   }
   if (index?.schemaVersion !== INDEX_SCHEMA_VERSION || !index.packages || typeof index.packages !== 'object') {
-    fail('stable.json', `use schemaVersion ${INDEX_SCHEMA_VERSION} and a packages object`, 'Regenerate the source index.');
+    fail(
+      'stable.json',
+      `use schemaVersion ${INDEX_SCHEMA_VERSION} and a packages object`,
+      'Regenerate the source index.',
+    );
   }
   return { index, indexUrl: normalizedUrl };
 }
@@ -175,9 +204,15 @@ function assertExtractedTree(root, name) {
     const current = stack.pop();
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       if (entry.isSymbolicLink()) {
-        fail(`${name} ${relative(root, join(current, entry.name))}`, 'not be a symbolic link', 'Repack the source archive without links.');
+        fail(
+          `${name} ${relative(root, join(current, entry.name))}`,
+          'not be a symbolic link',
+          'Repack the source archive without links.',
+        );
+      }
+      if (entry.isDirectory()) {
+        stack.push(join(current, entry.name));
       }
-      if (entry.isDirectory()) stack.push(join(current, entry.name));
     }
   }
 }
@@ -202,16 +237,24 @@ async function extractPackage(targetRoot, selected, bytes) {
     strict: true,
     preservePaths: false,
     filter(path, entry) {
-      if (!path.startsWith('package/')) return false;
+      if (!path.startsWith('package/')) {
+        return false;
+      }
       if (entry.type === 'SymbolicLink' || entry.type === 'Link') {
-        fail(`${selected.name}@${selected.version} archive`, 'not contain links', 'Repack the source archive with regular files only.');
+        fail(
+          `${selected.name}@${selected.version} archive`,
+          'not contain links',
+          'Repack the source archive with regular files only.',
+        );
       }
       return true;
     },
   });
   assertExtractedTree(packageDirectory, selected.name);
   const manifestPath = join(packageDirectory, 'package.json');
-  if (!existsSync(manifestPath)) fail(`${selected.name} package.json`, 'exist in the TGZ', 'Repack the source package.');
+  if (!existsSync(manifestPath)) {
+    fail(`${selected.name} package.json`, 'exist in the TGZ', 'Repack the source package.');
+  }
   let manifest;
   try {
     manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
@@ -230,9 +273,19 @@ async function extractPackage(targetRoot, selected, bytes) {
     );
   }
   if (!existsSync(join(packageDirectory, 'src'))) {
-    fail(`${selected.name}@${selected.version} src`, 'exist in the TGZ', 'Pack production TypeScript source before uploading.');
+    fail(
+      `${selected.name}@${selected.version} src`,
+      'exist in the TGZ',
+      'Pack production TypeScript source before uploading.',
+    );
   }
-  return { directory: packageDirectory, manifest, version: selected.version, sourceUrl: selected.url, artifactSha256: actualHash };
+  return {
+    directory: packageDirectory,
+    manifest,
+    version: selected.version,
+    sourceUrl: selected.url,
+    artifactSha256: actualHash,
+  };
 }
 
 export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, specs }) {
@@ -241,7 +294,9 @@ export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, sp
   const temporaryRoot = mkdtempSync(join(tmpdir(), 'miaoda-mechanics-source-index-'));
   const resolvedPackages = new Map();
   try {
-    for (const selected of [...graph.selectedPackages.values()].sort((left, right) => left.name.localeCompare(right.name))) {
+    for (const selected of [...graph.selectedPackages.values()].sort((left, right) =>
+      left.name.localeCompare(right.name),
+    )) {
       const bytes = await download(selected.url, MAX_TARBALL_BYTES, `${selected.name}@${selected.version}`);
       resolvedPackages.set(selected.name, await extractPackage(temporaryRoot, selected, bytes));
     }
@@ -258,5 +313,7 @@ export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, sp
 }
 
 export function cleanupIndexedMechanics(resolution) {
-  if (resolution?.temporaryRoot) rmSync(resolution.temporaryRoot, { recursive: true, force: true });
+  if (resolution?.temporaryRoot) {
+    rmSync(resolution.temporaryRoot, { recursive: true, force: true });
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",