miaoda-game-devkit 0.7.1 → 0.7.2

package/mechanics/game-mechanics-capabilities.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://miaoda.dev/schemas/game-mechanics-capabilities.schema.json",
+  "title": "Miaoda game-mechanics capability boundaries",
+  "description": "Repository-owned routing metadata used to help tools and AI select packages without assigning duplicate runtime ownership.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "requiredPackages", "packages"],
+  "properties": {
+    "$schema": {
+      "const": "./game-mechanics-capabilities.schema.json",
+      "description": "Local schema reference for editor validation and field documentation."
+    },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Version of this machine-readable capability document."
+    },
+    "requiredPackages": {
+      "description": "Public packages that must have capability metadata; repository validation rejects missing entries.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/packageName" }
+    },
+    "packages": {
+      "description": "Capability metadata keyed by full published package name.",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "$ref": "#/$defs/packageName" },
+      "additionalProperties": { "$ref": "#/$defs/capability" }
+    }
+  },
+  "$defs": {
+    "packageName": {
+      "type": "string",
+      "pattern": "^miaoda-game-[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "tokenList": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+      }
+    },
+    "packageList": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/packageName" }
+    },
+    "alternative": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package", "condition"],
+      "properties": {
+        "package": {
+          "$ref": "#/$defs/packageName",
+          "description": "Package that should be selected instead when the condition applies."
+        },
+        "condition": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable decision condition for AI and maintainers; it is not executable game logic."
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "engine",
+        "domains",
+        "owns",
+        "doesNotOwn",
+        "compatibleWith",
+        "useInsteadWhen",
+        "persistence"
+      ],
+      "properties": {
+        "engine": {
+          "enum": ["neutral", "react", "phaser", "cocos"],
+          "description": "Runtime boundary: neutral logic or a specific host integration."
+        },
+        "domains": {
+          "$ref": "#/$defs/tokenList",
+          "description": "Broad routing tags used to discover relevant packages."
+        },
+        "owns": {
+          "$ref": "#/$defs/tokenList",
+          "description": "Responsibilities for which this package is authoritative."
+        },
+        "doesNotOwn": {
+          "$ref": "#/$defs/tokenList",
+          "description": "Common adjacent responsibilities that must remain elsewhere."
+        },
+        "compatibleWith": {
+          "$ref": "#/$defs/packageList",
+          "description": "Public packages that form an intentional non-overlapping composition."
+        },
+        "useInsteadWhen": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/alternative" },
+          "description": "Explicit alternatives that prevent plausible but incorrect package selection."
+        },
+        "persistence": {
+          "enum": ["none", "snapshot", "envelope", "delegated"],
+          "description": "Persistence responsibility: none, package snapshot, versioned envelope, or delegated to another owner."
+        },
+        "testability": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["observation", "advance", "methods"],
+          "description": "Optional deterministic headless boundary for consumers and AI-authored playthroughs.",
+          "properties": {
+            "observation": {
+              "enum": [
+                "return-value",
+                "command-result",
+                "snapshot",
+                "step-result",
+                "snapshot-and-result",
+                "snapshot-and-step-result",
+                "axis-and-actions"
+              ],
+              "description": "Smallest stable readback shape exposed by the package."
+            },
+            "advance": {
+              "enum": ["none", "command", "update", "step", "scheduler", "manual"],
+              "description": "How a consumer explicitly advances or samples the package."
+            },
+            "methods": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["observe", "advance"],
+              "properties": {
+                "observe": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Public observation method or expression."
+                },
+                "advance": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Public advancement or sampling method."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/mechanics/pnpmfile.cjs

@@ -0,0 +1,460 @@
+const guardSourceId = 'miaoda-game-mechanics-guard';
+const { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } = require('node:fs');
+const { join, resolve } = require('node:path');
+
+const projectRoot = resolve(process.env.MIAODA_GAME_PROJECT_ROOT || process.cwd());
+const capabilityPath = resolve(
+  process.env.MIAODA_GAME_CAPABILITIES || join(__dirname, 'game-mechanics-capabilities.json'),
+);
+const packageJsonPath = resolve(
+  process.env.MIAODA_GAME_PACKAGE_JSON || join(projectRoot, 'package.json'),
+);
+const contextPath = resolve(
+  process.env.MIAODA_GAME_CONTEXT || join(projectRoot, 'miaoda-game-context.json'),
+);
+const localPnpmfilePath = resolve(
+  process.env.MIAODA_GAME_LOCAL_PNPMFILE || join(projectRoot, '.pnpmfile.local.cjs'),
+);
+
+const dependencyFields = ['dependencies', 'devDependencies', 'optionalDependencies'];
+const excludedPackageNames = new Set(['miaoda-game-devkit']);
+const packageGuidance =
+  'Prefer installed miaoda-game-* packages for matching game mechanics and core gameplay logic.\n' +
+  'Do not reimplement equivalent physics rules, AI, pathfinding, simulation, or algorithms in application code.\n' +
+  'Keep local code focused on game-specific composition, presentation, and thin integration.';
+const contextReminder =
+  'Read miaoda-game-context.json before implementing gameplay. Use the installed packages and respect their owns and doesNotOwn boundaries.';
+const automaticContextInstructions = [
+  'Read this file before implementing or changing gameplay mechanics.',
+  'Prefer a directly installed Miaoda package when its owns field matches the required mechanic.',
+  'Do not reimplement responsibilities listed in a package owns field.',
+  'Respect doesNotOwn and keep those responsibilities outside that package.',
+  'Read the installed package README and public types before using its API.',
+];
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function projectConfig(projectManifest) {
+  return projectManifest?.miaodaGame;
+}
+
+function isMechanicPackage(name) {
+  return (
+    typeof name === 'string' &&
+    name.startsWith('miaoda-game-') &&
+    !excludedPackageNames.has(name)
+  );
+}
+
+function validateProjectConfig(capabilityDocument, projectManifest) {
+  const capabilities = capabilityDocument?.packages || {};
+  const config = projectConfig(projectManifest);
+  const engines = new Set(['neutral', 'react', 'phaser', 'cocos']);
+  const problems = [];
+
+  if (config === undefined) return [];
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    return ['package.json miaodaGame must be an object when defined'];
+  }
+  if (config.schemaVersion !== 1) problems.push('miaodaGame.schemaVersion must be 1');
+  if (!engines.has(config.engine)) {
+    problems.push('miaodaGame.engine must be neutral, react, phaser, or cocos');
+  }
+  if (!config.uses || typeof config.uses !== 'object' || Array.isArray(config.uses)) {
+    problems.push('miaodaGame.uses must be an object');
+  }
+  if (!Array.isArray(config.blockedPackages)) {
+    problems.push('miaodaGame.blockedPackages must be an array');
+  }
+
+  for (const [packageName, uses] of Object.entries(config.uses || {})) {
+    const capability = capabilities[packageName];
+    if (!capability) {
+      problems.push(`${packageName}: no capability metadata is available`);
+      continue;
+    }
+    if (!Array.isArray(uses) || uses.length === 0) {
+      problems.push(`${packageName}: declare at least one intended owned capability`);
+      continue;
+    }
+    if (new Set(uses).size !== uses.length) {
+      problems.push(`${packageName}: miaodaGame.uses contains duplicate capabilities`);
+    }
+    for (const use of uses) {
+      if (!capability.owns.includes(use)) {
+        problems.push(
+          `${packageName}: '${use}' is not owned by this package; owned capabilities: ${capability.owns.join(', ')}`,
+        );
+      }
+    }
+    if (
+      capability.engine !== 'neutral' &&
+      config.engine !== 'neutral' &&
+      capability.engine !== config.engine
+    ) {
+      problems.push(
+        `${packageName}: ${capability.engine} package is incompatible with ${config.engine} project`,
+      );
+    }
+  }
+
+  return problems;
+}
+
+function createGuard(capabilityDocument, projectManifest, observedPackages = new Map()) {
+  const capabilities = capabilityDocument?.packages || {};
+  const config = projectConfig(projectManifest);
+  const problems = validateProjectConfig(capabilityDocument, projectManifest);
+  if (problems.length) {
+    throw new Error(`Invalid package.json miaodaGame configuration:\n- ${problems.join('\n- ')}`);
+  }
+
+  const blockedPackages = new Set(config?.blockedPackages || []);
+  let guidanceLogged = false;
+  const loggedPackages = new Set();
+
+  return function readPackage(pkg, context) {
+    if (!isMechanicPackage(pkg?.name)) return pkg;
+    observedPackages.set(pkg.name, {
+      version: pkg.version,
+      description: pkg.description,
+      types: pkg.types,
+    });
+    if (blockedPackages.has(pkg.name)) {
+      throw new Error(`Restricted by package.json miaodaGame.blockedPackages: ${pkg.name}`);
+    }
+
+    if (!guidanceLogged) {
+      context.log(packageGuidance);
+      guidanceLogged = true;
+    }
+
+    const capability = capabilities[pkg.name];
+    if (!capability) return pkg;
+    if (
+      config &&
+      capability.engine !== 'neutral' &&
+      config.engine !== 'neutral' &&
+      capability.engine !== config.engine
+    ) {
+      throw new Error(
+        `Restricted: ${pkg.name} targets ${capability.engine}, but this project targets ${config.engine}.`,
+      );
+    }
+
+    const uses = config?.uses?.[pkg.name];
+    if (uses && !loggedPackages.has(pkg.name)) {
+      context.log(
+        `[miaoda-game] ${pkg.name}: approved for ${uses.join(', ')}; does not own ${capability.doesNotOwn.join(', ')}`,
+      );
+      loggedPackages.add(pkg.name);
+    }
+    return pkg;
+  };
+}
+
+function directDependencies(lockfile, projectManifest) {
+  const importer = lockfile?.importers?.['.'];
+  const result = new Map();
+  for (const field of dependencyFields) {
+    const resolved = importer?.[field] || {};
+    const declared = projectManifest?.[field] || {};
+    for (const name of new Set([...Object.keys(declared), ...Object.keys(resolved)])) {
+      if (!isMechanicPackage(name)) continue;
+      result.set(name, { dependencyType: field, resolution: resolved[name] || declared[name] });
+    }
+  }
+  return result;
+}
+
+function resolvedVersion(resolution, observed) {
+  if (typeof observed?.version === 'string') return observed.version;
+  const value = typeof resolution === 'string' ? resolution : resolution?.version;
+  if (typeof value !== 'string') return 'unknown';
+  if (value.startsWith('link:') || value.startsWith('workspace:')) return value;
+  return value.split('(')[0];
+}
+
+function createContext(
+  capabilityDocument,
+  projectManifest,
+  lockfile,
+  observedPackages = new Map(),
+) {
+  const config = projectConfig(projectManifest);
+  const direct = directDependencies(lockfile, projectManifest);
+  const directNames = new Set(direct.keys());
+  const configuredUses = config?.uses || {};
+  const blockedPackages = config?.blockedPackages || [];
+  const packages = {};
+  const assignments = {};
+  const problems = [];
+
+  for (const name of [...direct.keys()].sort()) {
+    const { dependencyType, resolution } = direct.get(name);
+    const capability = capabilityDocument.packages[name];
+    const observed = observedPackages.get(name);
+    const entry = {
+      version: resolvedVersion(resolution, observed),
+      dependencyType,
+      ...(observed?.description ? { description: observed.description } : {}),
+    };
+    if (capability) {
+      Object.assign(entry, {
+        engine: capability.engine,
+        domains: capability.domains,
+        owns: capability.owns,
+        doesNotOwn: capability.doesNotOwn,
+        compatibleWith: capability.compatibleWith,
+        installedCompanions: capability.compatibleWith.filter((item) => directNames.has(item)),
+        useInsteadWhen: capability.useInsteadWhen,
+        persistence: capability.persistence,
+        ...(capability.testability ? { testability: capability.testability } : {}),
+      });
+    } else {
+      entry.capabilityStatus = 'missing';
+      problems.push({
+        code: 'CAPABILITY_METADATA_MISSING',
+        package: name,
+        message: `${name} is installed directly but has no capability metadata. Read its README and public types before assigning ownership.`,
+      });
+    }
+    entry.references = {
+      packageJson: `node_modules/${name}/package.json`,
+      readme: `node_modules/${name}/README.md`,
+      ...(observed?.types ? { types: `node_modules/${name}/${observed.types}` } : {}),
+      importFrom: name,
+    };
+    packages[name] = entry;
+
+    if (!config) continue;
+    const uses = configuredUses[name];
+    if (!uses) {
+      problems.push({
+        code: 'INTENDED_USE_MISSING',
+        package: name,
+        message: `${name} is installed directly but package.json miaodaGame.uses does not assign its project responsibilities.`,
+      });
+      continue;
+    }
+    for (const capabilityName of [...uses].sort()) {
+      const existing = assignments[capabilityName];
+      if (existing && existing.owner !== name) {
+        problems.push({
+          code: 'DUPLICATE_OWNER',
+          capability: capabilityName,
+          packages: [existing.owner, name].sort(),
+          message: `${capabilityName} is assigned to more than one directly installed package.`,
+        });
+      } else {
+        assignments[capabilityName] = { owner: name, required: true };
+      }
+    }
+  }
+
+  for (const name of Object.keys(configuredUses).sort()) {
+    if (!directNames.has(name)) {
+      problems.push({
+        code: 'SELECTED_PACKAGE_NOT_INSTALLED',
+        package: name,
+        message: `${name} is configured in package.json miaodaGame.uses but is not a direct dependency.`,
+      });
+    }
+  }
+  for (const name of [...blockedPackages].sort()) {
+    if (directNames.has(name)) {
+      problems.push({
+        code: 'BLOCKED_PACKAGE_INSTALLED',
+        package: name,
+        message: `${name} is both directly installed and blocked by package.json miaodaGame.blockedPackages.`,
+      });
+    }
+  }
+
+  return {
+    schemaVersion: 1,
+    generated: true,
+    instructions: config
+      ? [
+          automaticContextInstructions[0],
+          'Use the assigned Miaoda package for every responsibility in assignments.',
+          ...automaticContextInstructions.slice(2),
+        ]
+      : automaticContextInstructions,
+    project: config
+      ? { selectionMode: 'declared', engine: config.engine }
+      : { selectionMode: 'installed-direct-dependencies' },
+    packages,
+    assignments: Object.fromEntries(
+      Object.entries(assignments).sort(([left], [right]) => left.localeCompare(right)),
+    ),
+    problems,
+  };
+}
+
+function writeContext(path, context) {
+  const source = `${JSON.stringify(context, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === source) return false;
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporaryPath, source);
+    renameSync(temporaryPath, path);
+  } finally {
+    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
+  }
+  return true;
+}
+
+function rootImporterLockfile(path) {
+  if (!existsSync(path)) return undefined;
+  const importer = {};
+  let inRootImporter = false;
+  let dependencyField;
+  let packageName;
+  for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+    if (line === '  .:') {
+      inRootImporter = true;
+      continue;
+    }
+    if (!inRootImporter) continue;
+    if (/^  \S/.test(line)) break;
+    const fieldMatch = line.match(/^    (dependencies|devDependencies|optionalDependencies):$/);
+    if (fieldMatch) {
+      dependencyField = fieldMatch[1];
+      importer[dependencyField] = {};
+      packageName = undefined;
+      continue;
+    }
+    const packageMatch = dependencyField && line.match(/^      (miaoda-game-[a-z0-9-]+):$/);
+    if (packageMatch) {
+      packageName = packageMatch[1];
+      continue;
+    }
+    const versionMatch = packageName && line.match(/^        version:\s+(.+)$/);
+    if (versionMatch) {
+      importer[dependencyField][packageName] = {
+        version: versionMatch[1].replace(/^['"]|['"]$/g, ''),
+      };
+      packageName = undefined;
+    }
+  }
+  return { importers: { '.': importer } };
+}
+
+function installedDirectPackages(projectManifest) {
+  const observed = new Map();
+  for (const name of directDependencies(undefined, projectManifest).keys()) {
+    const declared = dependencyFields
+      .map((field) => projectManifest?.[field]?.[name])
+      .find((value) => typeof value === 'string');
+    const localPath = declared?.startsWith('file:')
+      ? resolve(projectRoot, declared.slice('file:'.length), 'package.json')
+      : undefined;
+    const installedManifestPath = existsSync(join(projectRoot, 'node_modules', name, 'package.json'))
+      ? join(projectRoot, 'node_modules', name, 'package.json')
+      : localPath;
+    if (!installedManifestPath || !existsSync(installedManifestPath)) continue;
+    const installedManifest = readJson(installedManifestPath);
+    observed.set(name, {
+      version: installedManifest.version,
+      description: installedManifest.description,
+      types: installedManifest.types,
+    });
+  }
+  return observed;
+}
+
+function refreshInstalledContext(capabilityDocument, projectManifest, path) {
+  const observed = installedDirectPackages(projectManifest);
+  const lockfile = rootImporterLockfile(join(projectRoot, 'pnpm-lock.yaml'));
+  const direct = directDependencies(lockfile, projectManifest);
+  if (
+    [...direct.keys()].some(
+      (name) => resolvedVersion(direct.get(name).resolution, observed.get(name)) === 'unknown',
+    )
+  ) {
+    return false;
+  }
+  return writeContext(path, createContext(capabilityDocument, projectManifest, lockfile, observed));
+}
+
+if (!existsSync(packageJsonPath)) {
+  throw new Error(
+    `Missing ${packageJsonPath}. The pnpm guard must be installed beside package.json.`,
+  );
+}
+
+const capabilityDocument = readJson(capabilityPath);
+const projectManifest = readJson(packageJsonPath);
+const observedPackages = new Map();
+const guardReadPackage = createGuard(capabilityDocument, projectManifest, observedPackages);
+const localPnpmfile = existsSync(localPnpmfilePath) ? require(localPnpmfilePath) : {};
+let contextReminderLogged = false;
+
+if (process.env.MIAODA_GAME_CONTEXT_DISABLED !== '1') {
+  refreshInstalledContext(capabilityDocument, projectManifest, contextPath);
+  const installedLockfile = rootImporterLockfile(join(projectRoot, 'pnpm-lock.yaml'));
+  if (existsSync(contextPath) && directDependencies(installedLockfile, projectManifest).size > 0) {
+    console.log(contextReminder);
+    contextReminderLogged = true;
+  }
+}
+
+function logContextReminder(context) {
+  if (contextReminderLogged) return;
+  if (typeof context?.log === 'function') context.log(contextReminder);
+  else console.log(contextReminder);
+  contextReminderLogged = true;
+}
+
+function readPackage(pkg, context) {
+  const guarded = guardReadPackage(pkg, context);
+  const directNames = directDependencies(undefined, projectManifest);
+  if (
+    directNames.has(pkg?.name) &&
+    [...directNames.keys()].every((name) => observedPackages.has(name))
+  ) {
+    writeContext(
+      contextPath,
+      createContext(capabilityDocument, projectManifest, undefined, observedPackages),
+    );
+    logContextReminder(context);
+  }
+  const localReadPackage = localPnpmfile.hooks?.readPackage;
+  return typeof localReadPackage === 'function' ? localReadPackage(guarded, context) : guarded;
+}
+
+async function afterAllResolved(lockfile, context) {
+  const localAfterAllResolved = localPnpmfile.hooks?.afterAllResolved;
+  const resolved =
+    typeof localAfterAllResolved === 'function'
+      ? (await localAfterAllResolved(lockfile, context)) || lockfile
+      : lockfile;
+  const generated = createContext(capabilityDocument, projectManifest, resolved, observedPackages);
+  const changed = writeContext(contextPath, generated);
+  if (changed && typeof context?.log === 'function') {
+    context.log(`[miaoda-game] Generated ${contextPath}.`);
+  }
+  if (directDependencies(resolved, projectManifest).size > 0) logContextReminder(context);
+  return resolved;
+}
+
+module.exports = {
+  ...localPnpmfile,
+  guardSourceId,
+  hooks: {
+    ...localPnpmfile.hooks,
+    readPackage,
+    afterAllResolved,
+  },
+  createContext,
+  createGuard,
+  directDependencies,
+  isMechanicPackage,
+  refreshInstalledContext,
+  rootImporterLockfile,
+  validateProjectConfig,
+  writeContext,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -73,12 +73,14 @@
       }
     },
     "./react/vitest-setup": "./dist/react/vitest-setup.mjs",
+    "./pnpmfile": "./mechanics/pnpmfile.cjs",
     "./biome": "./biome-config.json",
     "./tsconfig-base": "./tsconfig-base.json"
   },
   "files": [
     "dist",
     "bin",
+    "mechanics",
     "biome-config.json",
     "oxlint-config.json",
     "tsconfig-base.json",