miaoda-game-devkit 0.7.2 → 0.8.0

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

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  areIndexedPackageSpecs,
+  cleanupIndexedMechanics,
+  resolveIndexedMechanics,
+} from './resolve-game-mechanics-source-index.mjs';
+
+const modulePath = fileURLToPath(import.meta.url);
+const capabilityPath = join(dirname(modulePath), 'game-mechanics-capabilities.json');
+const METADATA_ROOT = '.miaoda';
+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';
+
+function fail(api, field, expected, repair) {
+  throw new Error(`miaoda mechanics source ${api}: ${field} must ${expected}. ${repair}`);
+}
+
+function readJson(path, label = path) {
+  let value;
+  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)}`,
+    );
+  }
+  return value;
+}
+
+function writeJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+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`;
+  return value.replace('./dist/', './src/');
+}
+
+function rewriteExportPaths(value) {
+  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)]));
+  }
+  return 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);
+  return [];
+}
+
+export function createSourceManifest(manifest, resolvedPackages) {
+  const generated = structuredClone(manifest);
+  generated.private = true;
+  delete generated.devDependencies;
+  delete generated.publishConfig;
+  delete generated.files;
+  delete generated.scripts;
+  for (const field of ['main', 'module', 'types']) {
+    if (field in generated) generated[field] = sourcePath(generated[field]);
+  }
+  if (generated.exports) generated.exports = rewriteExportPaths(generated.exports);
+
+  for (const field of ['dependencies', 'optionalDependencies']) {
+    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}`;
+    }
+  }
+  return generated;
+}
+
+export function validateMechanicSelection(projectManifest, resolvedPackages, capabilityDocument) {
+  const config = projectManifest.miaodaGame;
+  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.');
+  }
+  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.');
+  }
+  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.');
+  }
+  if (!Array.isArray(config.blockedPackages)) {
+    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.');
+    }
+    const capability = capabilities[name];
+    if (
+      capability &&
+      capability.engine !== 'neutral' &&
+      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.`);
+    }
+    const uses = config.uses[name];
+    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.');
+    }
+    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.');
+    }
+    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.');
+      }
+      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.');
+      }
+      owners.set(use, name);
+    }
+    if (resolvedPackage.version.length === 0) fail('add', `${name} version`, 'be non-empty', 'Repack the package.');
+  }
+}
+
+function validateSourceEntrypoints(packageDirectory, manifest) {
+  const candidates = [manifest.main, manifest.module, manifest.types, ...stringValues(manifest.exports)];
+  for (const candidate of candidates.filter((value) => typeof value === 'string' && value.startsWith('./src/'))) {
+    if (!existsSync(join(packageDirectory, candidate))) {
+      fail(
+        'add',
+        `${manifest.name} entry ${candidate}`,
+        'exist after dist-to-src conversion',
+        'Add the matching TypeScript source entry or publish an explicit source manifest.',
+      );
+    }
+  }
+}
+
+function listFiles(root, current = root) {
+  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;
+    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()) {
+      fail(
+        'add',
+        `${relative(root, path)} in ${root}`,
+        'be a regular file or directory, not a symbolic link',
+        'Repack the source package without symbolic links.',
+      );
+    }
+  }
+  return files;
+}
+
+function hashTree(root) {
+  const hash = createHash('sha256');
+  for (const path of listFiles(root)) {
+    hash.update(relative(root, path).split(sep).join('/'));
+    hash.update('\0');
+    hash.update(readFileSync(path));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function readState(metadataRoot) {
+  const statePath = join(metadataRoot, STATE_FILENAME);
+  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.`);
+  }
+  return state;
+}
+
+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.`);
+    }
+    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.');
+  }
+  for (const [name, record] of Object.entries(state.packages)) {
+    const directory = join(sourceRoot, name);
+    if (!existsSync(directory)) {
+      statuses[name] = 'missing';
+      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.');
+    }
+    statuses[name] = hashTree(directory) === record.sha256 ? 'clean' : 'modified';
+  }
+  return statuses;
+}
+
+function ensureWorkspacePattern(projectRoot) {
+  const workspacePath = join(projectRoot, 'pnpm-workspace.yaml');
+  const quotedPattern = `'${WORKSPACE_PATTERN}'`;
+  if (!existsSync(workspacePath)) {
+    writeFileSync(workspacePath, `packages:\n  - '.'\n  - ${quotedPattern}\n`);
+    return { path: workspacePath, previous: undefined };
+  }
+  const previous = readFileSync(workspacePath, 'utf8');
+  const lines = previous.split('\n');
+  if (lines.some((line) => /^\s*-\s*['"]?src\/game-mechanics\/\*['"]?\s*(?:#.*)?$/.test(line))) {
+    return { path: workspacePath, previous };
+  }
+  const packagesIndex = lines.findIndex((line) => /^packages:\s*$/.test(line));
+  if (packagesIndex < 0) {
+    if (lines.some((line) => /^packages\s*:/.test(line))) {
+      fail(
+        'add',
+        'pnpm-workspace.yaml packages',
+        'use a block list when the managed pattern is absent',
+        `Add "  - '${WORKSPACE_PATTERN}'" to the existing packages list.`,
+      );
+    }
+    const separator = previous.endsWith('\n') ? '' : '\n';
+    writeFileSync(workspacePath, `${previous}${separator}packages:\n  - ${quotedPattern}\n`);
+    return { path: workspacePath, previous };
+  }
+  let insertAt = packagesIndex + 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);
+}
+
+function updateProjectManifest(projectRoot, roots, resolvedPackages) {
+  const manifestPath = join(projectRoot, 'package.json');
+  const previous = readFileSync(manifestPath, 'utf8');
+  const manifest = readJson(manifestPath);
+  manifest.dependencies ??= {};
+  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.');
+    }
+    manifest.dependencies[name] = `workspace:${resolvedPackage.version}`;
+  }
+  writeJson(manifestPath, manifest);
+  return { path: manifestPath, previous };
+}
+
+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.`);
+  }
+  const version = result.stdout.trim();
+  const major = Number.parseInt(version.split('.')[0], 10);
+  if (major !== 10 && major !== 11) {
+    fail('add', 'pnpm version', `be 10.x or 11.x, but found ${version}`, 'Use a supported project pnpm version.');
+  }
+  return version;
+}
+
+function projectDeclaredPnpmMajor(projectManifest) {
+  const match = /^pnpm@(\d+)(?:\.|$)/.exec(projectManifest.packageManager ?? '');
+  return match ? Number.parseInt(match[1], 10) : undefined;
+}
+
+function runPnpm(pnpmCommand, args, cwd) {
+  const result = spawnSync(pnpmCommand, args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, CI: 'true' },
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const output = result.error?.message || result.stderr || result.stdout || 'pnpm exited without diagnostic output';
+    const detail = output.trim().split('\n').slice(-12).join('\n');
+    throw new Error(`miaoda mechanics source: pnpm ${args.join(' ')} failed in ${cwd}:\n${detail}`);
+  }
+  return result;
+}
+
+function copyResolvedPackage(target, resolvedPackage, resolvedPackages) {
+  cpSync(resolvedPackage.directory, target, {
+    recursive: true,
+    filter: (source) => {
+      const sourceName = basename(source);
+      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;
+      }
+      const packageRelativePath = relative(resolvedPackage.directory, source);
+      return packageRelativePath.includes(sep) || !/^tsconfig(?:\..+)?\.json$/.test(packageRelativePath);
+    },
+  });
+  const sourceManifest = createSourceManifest(resolvedPackage.manifest, resolvedPackages);
+  writeJson(join(target, 'package.json'), sourceManifest);
+  validateSourceEntrypoints(target, sourceManifest);
+  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 generatedReadmeMarker = '<!-- Generated by miaoda mechanics. -->';
+
+function sourceReadme(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}`;
+    })
+    .join('\n');
+  return `${generatedReadmeMarker}
+# Game mechanics
+
+Read this README before implementing gameplay.
+
+Prefer the installed packages below whenever they cover the mechanic you need. Avoid implementing
+overlapping algorithms, simulation rules, or reusable gameplay logic in the game project. Import
+packages by their \`miaoda-game-*\` names; pnpm workspace links connect their internal dependencies.
+
+The source under this directory is editable, but modifying package source is not recommended. First
+use the package's public API, configuration, and composition options. Modify package source only when
+the required game behavior cannot be implemented cleanly through those supported boundaries.
+
+## Available packages
+
+${packages || 'No game mechanic packages are installed.'}
+`;
+}
+
+function ensureSourceGuidance(sourceRoot, resolvedPackages, capabilityDocument) {
+  const readmePath = join(sourceRoot, 'README.md');
+  const existingReadme = existsSync(readmePath) ? readFileSync(readmePath, 'utf8') : undefined;
+  if (
+    existingReadme === undefined ||
+    existingReadme.startsWith(generatedReadmeMarker) ||
+    existingReadme.startsWith('# Game mechanics source\n')
+  ) {
+    writeFileSync(readmePath, sourceReadme(resolvedPackages, capabilityDocument));
+  }
+  const agentsPath = join(sourceRoot, 'AGENTS.md');
+  if (existsSync(agentsPath) && readFileSync(agentsPath, 'utf8') === legacyAgentsSource) {
+    rmSync(agentsPath);
+  }
+}
+
+function materializePackages(
+  stagingSourceRoot,
+  sourceRoot,
+  resolvedPackages,
+  previousState,
+  statuses,
+  capabilityDocument,
+) {
+  mkdirSync(stagingSourceRoot, { recursive: true });
+  if (existsSync(sourceRoot)) {
+    cpSync(sourceRoot, stagingSourceRoot, {
+      recursive: true,
+      filter: (source) => basename(source) !== 'node_modules',
+    });
+  }
+  ensureSourceGuidance(stagingSourceRoot, resolvedPackages, capabilityDocument);
+  const records = {};
+  for (const [name, resolvedPackage] of [...resolvedPackages].sort(([left], [right]) => left.localeCompare(right))) {
+    const target = join(stagingSourceRoot, name);
+    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.`);
+      }
+      records[name] = previous;
+      continue;
+    }
+    if (previous && statuses[name] === 'modified') {
+      fail(
+        '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.`,
+      );
+    }
+    if (existsSync(target)) {
+      if (!previous) {
+        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) };
+  }
+  return records;
+}
+
+function switchManagedDirectory(sourceRoot, stagedSourceRoot, metadataRoot) {
+  const backupRoot = join(metadataRoot, `.game-mechanics-backup-${randomUUID()}`);
+  mkdirSync(dirname(sourceRoot), { recursive: true });
+  if (existsSync(sourceRoot)) renameSync(sourceRoot, backupRoot);
+  try {
+    renameSync(stagedSourceRoot, sourceRoot);
+  } catch (error) {
+    if (existsSync(backupRoot)) renameSync(backupRoot, sourceRoot);
+    throw error;
+  }
+  return { packagesRoot: sourceRoot, backupRoot: existsSync(backupRoot) ? backupRoot : undefined };
+}
+
+function restoreManagedDirectory({ packagesRoot, backupRoot }) {
+  rmSync(packagesRoot, { recursive: true, force: true });
+  if (backupRoot) renameSync(backupRoot, packagesRoot);
+}
+
+function parseArguments(argv) {
+  const command = argv[0];
+  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 specs = argv.slice(1).filter((argument) => !argument.startsWith('--'));
+  return {
+    command,
+    projectRoot: resolve(projectArgument?.slice('--project='.length) || process.cwd()),
+    pnpmCommand: pnpmArgument?.slice('--pnpm='.length) || 'pnpm',
+    sourceIndexUrl:
+      sourceIndexArgument?.slice('--source-index='.length) ||
+      process.env.MIAODA_MECHANICS_INDEX_URL?.trim() ||
+      DEFAULT_SOURCE_INDEX_URL,
+    skipInstall: options.has('--skip-install'),
+    specs,
+  };
+}
+
+const ROOT_HELP = `Usage: miaoda mechanics <command> [options]
+
+Manage editable Miaoda game-mechanic TypeScript source in src/game-mechanics.
+
+Commands:
+  add <package...>  Resolve packages from the source index and add editable source
+  status            Show clean, modified, or missing source packages
+  help              Show this help
+
+Run "miaoda mechanics <command> --help" for command details.`;
+
+const ADD_HELP = `Usage: miaoda mechanics add <miaoda-game-package[@version]...> [options]
+
+Bare package names resolve to the source index's latest version and name@version
+selects an exact indexed version. Transitive miaoda-game-* dependencies are downloaded
+from the same index. Existing source is never overwritten when its recorded version is
+unchanged. An update is refused if that package has local modifications. Source is
+written to src/game-mechanics. npm registry and direct TGZ resolution are intentionally
+not used for game-mechanic source.
+
+Options:
+  --project=<path>  Consumer project root (default: current directory)
+  --pnpm=<command>  Project pnpm executable (default: pnpm)
+  --source-index=<url>
+                    Override the default public stable.json URL:
+                    https://resource-static.bj.bcebos.com/miaoda-game/stable.json
+                    (also configurable with MIAODA_MECHANICS_INDEX_URL)
+  --skip-install    Update source and manifests without the final pnpm install
+  -h, --help        Show this help`;
+
+const STATUS_HELP = `Usage: miaoda mechanics status [--project=<path>]
+
+Compare editable source with its installation checksum. This reads files only.`;
+
+function validateProject(projectRoot) {
+  if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+    fail('add', 'project', `be an existing directory, but received ${projectRoot}`, 'Pass --project=<absolute-path>.');
+  }
+  if (!existsSync(join(projectRoot, 'package.json'))) {
+    fail('add', 'project package.json', 'exist', `Create ${join(projectRoot, 'package.json')} first.`);
+  }
+}
+
+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.`);
+  }
+}
+
+export function mechanicSourceStatus({ projectRoot }) {
+  projectRoot = resolve(projectRoot);
+  validateProject(projectRoot);
+  const metadataRoot = join(projectRoot, METADATA_ROOT);
+  validateMetadataRoot(metadataRoot);
+  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),
+  }));
+}
+
+export async function addMechanicSources({
+  projectRoot,
+  pnpmCommand = 'pnpm',
+  sourceIndexUrl,
+  skipInstall = false,
+  specs,
+}) {
+  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.');
+  }
+  if (!sourceIndexUrl) {
+    fail(
+      'add',
+      'source index',
+      'be configured for package-name resolution',
+      'Pass --source-index=https://.../stable.json or set MIAODA_MECHANICS_INDEX_URL.',
+    );
+  }
+  if (!areIndexedPackageSpecs(specs)) {
+    fail(
+      'add',
+      'package specs',
+      'contain only miaoda-game-* names with optional @version',
+      'Publish source artifacts to the configured storage and request them through stable.json.',
+    );
+  }
+  const projectManifest = readJson(join(projectRoot, 'package.json'));
+  const version = pnpmVersion(pnpmCommand, projectRoot);
+  const declaredMajor = projectDeclaredPnpmMajor(projectManifest);
+  if (declaredMajor && declaredMajor !== Number.parseInt(version.split('.')[0], 10)) {
+    fail(
+      'add',
+      'invoked pnpm major',
+      `match packageManager ${projectManifest.packageManager}, but found ${version}`,
+      'Run the command through the project Corepack/pnpm configuration.',
+    );
+  }
+
+  const metadataRoot = join(projectRoot, METADATA_ROOT);
+  const sourceRoot = join(projectRoot, SOURCE_ROOT);
+  validateMetadataRoot(metadataRoot);
+  mkdirSync(metadataRoot, { recursive: true });
+  const statePath = join(metadataRoot, STATE_FILENAME);
+  const lockfilePath = join(projectRoot, 'pnpm-lock.yaml');
+  const nodeModulesPath = join(projectRoot, 'node_modules');
+  const previousStateText = existsSync(statePath) ? readFileSync(statePath, 'utf8') : undefined;
+  const previousLockfileText = existsSync(lockfilePath) ? readFileSync(lockfilePath, 'utf8') : undefined;
+  const nodeModulesExisted = existsSync(nodeModulesPath);
+  const previousState = readState(metadataRoot);
+  const statuses = inspectExistingPackages(sourceRoot, previousState);
+
+  const stagedPackagesRoot = join(metadataRoot, `.game-mechanics-staging-${randomUUID()}`);
+  let switched;
+  let workspaceChange;
+  let projectManifestChange;
+  let indexedResolution;
+  try {
+    const previousRoots = Object.fromEntries(
+      Object.keys(previousState.roots)
+        .map((name) => [name, previousState.packages[name]?.version])
+        .filter((entry) => typeof entry[1] === 'string' && entry[1].length > 0),
+    );
+    indexedResolution = await resolveIndexedMechanics({
+      indexUrl: sourceIndexUrl,
+      previousRoots,
+      specs,
+    });
+    const roots = indexedResolution.roots;
+    const directNames = Object.keys(roots).sort();
+    const resolvedPackages = indexedResolution.resolvedPackages;
+    const capabilityDocument = readJson(capabilityPath);
+    validateMechanicSelection(projectManifest, resolvedPackages, capabilityDocument);
+    const packageRecords = materializePackages(
+      stagedPackagesRoot,
+      sourceRoot,
+      resolvedPackages,
+      previousState,
+      statuses,
+      capabilityDocument,
+    );
+
+    switched = switchManagedDirectory(sourceRoot, stagedPackagesRoot, metadataRoot);
+    workspaceChange = ensureWorkspacePattern(projectRoot);
+    projectManifestChange = updateProjectManifest(projectRoot, roots, resolvedPackages);
+    writeJson(statePath, {
+      schemaVersion: STATE_SCHEMA_VERSION,
+      pnpmVersion: version,
+      roots,
+      packages: packageRecords,
+      sourceIndexUrl: indexedResolution.sourceIndexUrl,
+    });
+
+    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(),
+      packagesRoot: switched.packagesRoot,
+      pnpmVersion: version,
+    };
+  } catch (error) {
+    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 });
+    throw error;
+  } finally {
+    cleanupIndexedMechanics(indexedResolution);
+    rmSync(stagedPackagesRoot, { recursive: true, force: true });
+  }
+}
+
+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)) {
+    console.log(ROOT_HELP);
+    return;
+  }
+  if (command === 'add') {
+    if (wantsHelp) {
+      console.log(ADD_HELP);
+      return;
+    }
+    const options = parseArguments(mechanicsArguments);
+    const result = await addMechanicSources(options);
+    console.log(formatAddResult(result));
+    return result;
+  }
+  if (command === 'status') {
+    if (wantsHelp) {
+      console.log(STATUS_HELP);
+      return;
+    }
+    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}`);
+    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');
+  return `✓ Added ${result.packageNames.length} editable game-mechanic source packages
+
+Added source:
+${packagePaths}
+
+Next:
+  Read src/game-mechanics/README.md before implementing gameplay.
+  Prefer these packages and avoid reimplementing overlapping algorithms or reusable gameplay logic.
+  Package source is editable, but modification is not recommended unless public APIs, configuration,
+  and composition cannot implement the required behavior.`;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === modulePath) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}