miaoda-game-devkit 0.9.0 → 0.10.0

package/README.md

@@ -107,12 +107,19 @@ Devkit 发布统一的 `miaoda` 命令。裸 `miaoda-game-*` 包名默认从公
 
 ```bash
 pnpm exec miaoda mechanics --help
+pnpm exec miaoda mechanics list
+pnpm exec miaoda mechanics list --domain=grid --engine=react
 pnpm exec miaoda mechanics add miaoda-game-beam-core
 pnpm exec miaoda mechanics add miaoda-game-beam-core@1.2.3 \
   --source-index=https://public.example.com/game-mechanics/stable.json
 pnpm exec miaoda mechanics status
 ```
 
+`list` 只列出稳定索引中实际可安装的包，并从 Devkit 自带的 capabilities JSON 动态汇总
+domain 的 `owns` 能力；带筛选时会显示包负责和不负责的边界、使用指引及可测试性。它不会安装
+源码，也不会维护另一份容易过时的文字目录。先选择覆盖需求的最小包集合，再单独运行 `add`，
+成功后阅读生成的 `src/game-mechanics/README.md`。
+
 默认索引是 `https://resource-static.bj.bcebos.com/miaoda-game/stable.json`。只有调试、测试或
 私有镜像场景才需要通过 `--source-index` 或 `MIAODA_MECHANICS_INDEX_URL` 覆盖。
 

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

@@ -0,0 +1,254 @@
+import { readFileSync } from 'node:fs';
+import { listIndexedMechanics } from './resolve-game-mechanics-source-index.mjs';
+
+const ENGINES = new Set(['neutral', 'react', 'phaser', 'cocos']);
+const FILTER_NAMES = ['domain', 'engine', 'owns'];
+
+function readCapabilityDocument(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`miaoda mechanics list: cannot read capabilities JSON: ${detail}`);
+  }
+}
+
+function optionValue(argv, name) {
+  const prefix = `--${name}=`;
+  const argument = argv.find((value) => value.startsWith(prefix));
+  return argument?.slice(prefix.length).trim();
+}
+
+export function parseMechanicListArguments(argv, defaultSourceIndexUrl) {
+  const allowed = new Set(['--json', '--help', '-h']);
+  for (const argument of argv.slice(1)) {
+    if (allowed.has(argument)) {
+      continue;
+    }
+    if (['--domain=', '--engine=', '--owns=', '--source-index='].some((prefix) => argument.startsWith(prefix))) {
+      continue;
+    }
+    throw new Error(
+      `miaoda mechanics list: unsupported argument ${JSON.stringify(argument)}. ` +
+        'Use --domain=<domain>, --engine=<engine>, --owns=<capability>, or --json.',
+    );
+  }
+  const filters = Object.fromEntries(
+    FILTER_NAMES.map((name) => [name, optionValue(argv, name)]).filter(([, value]) => Boolean(value)),
+  );
+  if (filters.engine && !ENGINES.has(filters.engine)) {
+    throw new Error(
+      `miaoda mechanics list: engine must be neutral, react, phaser, or cocos; received ${filters.engine}.`,
+    );
+  }
+  return {
+    filters,
+    json: argv.includes('--json'),
+    sourceIndexUrl: optionValue(argv, 'source-index') || defaultSourceIndexUrl,
+  };
+}
+
+function packageMatches(entry, filters) {
+  if (!entry.annotated) {
+    return Object.keys(filters).length === 0;
+  }
+  if (filters.domain && !entry.domains.includes(filters.domain)) {
+    return false;
+  }
+  if (filters.owns && !entry.provides.includes(filters.owns)) {
+    return false;
+  }
+  if (filters.engine) {
+    const compatible =
+      filters.engine === 'neutral'
+        ? entry.engine === 'neutral'
+        : entry.engine === 'neutral' || entry.engine === filters.engine;
+    if (!compatible) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function packageEntry(name, version, capability, installableNames) {
+  if (!capability) {
+    return { name, version, annotated: false };
+  }
+  return {
+    name,
+    version,
+    annotated: true,
+    engine: capability.engine,
+    domains: capability.domains,
+    provides: capability.owns,
+    leavesOutside: capability.doesNotOwn,
+    compatibleWith: capability.compatibleWith.filter((candidate) => installableNames.has(candidate)),
+    useFor: capability.guidance?.useFor ?? [],
+    keepOutside: capability.guidance?.keepOutside ?? [],
+    rules: capability.guidance?.rules ?? [],
+    useInsteadWhen: capability.useInsteadWhen,
+    testability: capability.testability,
+    persistence: capability.persistence,
+  };
+}
+
+function summarizeDomains(packages) {
+  const domains = new Map();
+  for (const entry of packages) {
+    if (!entry.annotated) {
+      continue;
+    }
+    for (const domain of entry.domains) {
+      const summary = domains.get(domain) ?? { name: domain, packageNames: new Set(), provides: new Set() };
+      summary.packageNames.add(entry.name);
+      for (const capability of entry.provides) {
+        summary.provides.add(capability);
+      }
+      domains.set(domain, summary);
+    }
+  }
+  return [...domains.values()]
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((summary) => ({
+      name: summary.name,
+      packageCount: summary.packageNames.size,
+      provides: [...summary.provides].sort(),
+    }));
+}
+
+export function createMechanicCatalog(indexedPackages, capabilityDocument, filters = {}, sourceIndexUrl) {
+  const installableNames = new Set(indexedPackages.map((entry) => entry.name));
+  const allPackages = indexedPackages
+    .map(({ name, version }) =>
+      packageEntry(name, version, capabilityDocument.packages?.[name], installableNames),
+    )
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const matchedPackages = allPackages.filter((entry) => packageMatches(entry, filters));
+  const matchedNames = new Set(matchedPackages.map((entry) => entry.name));
+  const packages = matchedPackages.map((entry) => {
+    if (!entry.annotated) {
+      return entry;
+    }
+    return {
+      ...entry,
+      compatibleWith: entry.compatibleWith.filter((candidate) => matchedNames.has(candidate)),
+    };
+  });
+  const filtersActive = Object.keys(filters).length > 0;
+  return {
+    schemaVersion: 1,
+    sourceIndexUrl,
+    filters,
+    installablePackageCount: allPackages.length,
+    unannotatedPackageCount: allPackages.filter((entry) => !entry.annotated).length,
+    domains: summarizeDomains(filtersActive ? packages : allPackages),
+    packages,
+  };
+}
+
+export async function listMechanics({ sourceIndexUrl, capabilityPath, filters }) {
+  const indexed = await listIndexedMechanics(sourceIndexUrl);
+  const capabilityDocument = readCapabilityDocument(capabilityPath);
+  return createMechanicCatalog(indexed.packages, capabilityDocument, filters, indexed.sourceIndexUrl);
+}
+
+function formatList(values) {
+  return values.length > 0 ? values.join(', ') : 'none declared';
+}
+
+function formatTestability(testability) {
+  if (!testability) {
+    return undefined;
+  }
+  return `observation=${testability.observation}; advance=${testability.advance}; ` +
+    `observe: ${testability.methods.observe}; exercise: ${testability.methods.advance}`;
+}
+
+function formatPackage(entry) {
+  if (!entry.annotated) {
+    return `${entry.name}@${entry.version}\n  Capability metadata: unavailable; inspect its README after add.`;
+  }
+  const lines = [
+    `${entry.name}@${entry.version} [${entry.engine}]`,
+    `  Provides: ${formatList(entry.provides)}`,
+    `  Leaves outside: ${formatList(entry.leavesOutside)}`,
+  ];
+  if (entry.useFor.length > 0) {
+    lines.push(`  Use for: ${entry.useFor.join(' ')}`);
+  }
+  if (entry.keepOutside.length > 0) {
+    lines.push(`  Keep outside: ${entry.keepOutside.join(' ')}`);
+  }
+  if (entry.rules.length > 0) {
+    lines.push(`  Rules: ${entry.rules.join(' ')}`);
+  }
+  if (entry.compatibleWith.length > 0) {
+    lines.push(`  Works with: ${entry.compatibleWith.join(', ')}`);
+  }
+  for (const alternative of entry.useInsteadWhen) {
+    lines.push(`  Use ${alternative.package} instead when: ${alternative.condition}`);
+  }
+  const testability = formatTestability(entry.testability);
+  if (testability) {
+    lines.push(`  Testability: ${testability}`);
+  }
+  return lines.join('\n');
+}
+
+function formatFilters(filters) {
+  const values = Object.entries(filters).map(([name, value]) => `${name}=${value}`);
+  return values.length > 0 ? values.join(', ') : 'none';
+}
+
+export function formatMechanicList(catalog, { json = false } = {}) {
+  if (json) {
+    return JSON.stringify(catalog, null, 2);
+  }
+  const filtersActive = Object.keys(catalog.filters).length > 0;
+  if (!filtersActive) {
+    const domainLines = catalog.domains.map((domain) => {
+      const preview = domain.provides.slice(0, 3).join(', ');
+      const remaining = Math.max(0, domain.provides.length - 3);
+      const suffix = remaining > 0 ? `, +${remaining} more` : '';
+      return `  ${domain.name} (${domain.packageCount}) — can provide: ${preview}${suffix}`;
+    });
+    const annotationNote =
+      catalog.unannotatedPackageCount > 0
+        ? `\n${catalog.unannotatedPackageCount} installable packages lack capability annotations.`
+        : '';
+    return `Installable Miaoda mechanic domains (${catalog.domains.length} domains, ` +
+      `${catalog.installablePackageCount} packages):\n${domainLines.join('\n')}${annotationNote}\n\n` +
+      'Next:\n' +
+      '  Rerun with --domain=<domain>, --engine=<react|phaser|cocos|neutral>, or --owns=<capability>.\n' +
+      '  Use --json for complete machine-readable facts. Do not install every match.';
+  }
+  if (catalog.packages.length === 0) {
+    return `No installable mechanics matched ${formatFilters(catalog.filters)}.\n` +
+      'Run "pnpm exec miaoda mechanics list" to inspect available domains and exact capability names.';
+  }
+  return `Matched ${catalog.packages.length} installable mechanic packages (${formatFilters(catalog.filters)}):\n\n` +
+    `${catalog.packages.map(formatPackage).join('\n\n')}\n\n` +
+    'Next:\n' +
+    '  Select the smallest set whose Provides entries own required mechanics, then run:\n' +
+    '  pnpm exec miaoda mechanics add <full miaoda-game-* names>\n' +
+    '  Run add by itself, then read src/game-mechanics/README.md before gameplay edits.';
+}
+
+export const LIST_HELP = `Usage: miaoda mechanics list [filters]
+
+Discover packages that are currently installable through the source index. Package
+meaning comes from the bundled capabilities JSON: owns becomes Provides, doesNotOwn
+becomes Leaves outside, and guidance/testability are shown when annotated. This command
+is read-only and never installs source.
+
+Without filters, list prints domain summaries with real owned-capability previews.
+With filters, it prints package versions and ownership boundaries. An engine filter
+includes engine-neutral cores plus adapters for that engine.
+
+Filters:
+  --domain=<domain>       Match one exact domain from the summary
+  --engine=<engine>       neutral, react, phaser, or cocos
+  --owns=<capability>     Match one exact owned-capability token
+  --json                  Emit complete machine-readable JSON
+  --source-index=<url>    Override the public stable.json URL
+  -h, --help              Show this help`;

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

@@ -16,6 +16,12 @@ import {
 } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  formatMechanicList,
+  LIST_HELP,
+  listMechanics,
+  parseMechanicListArguments,
+} from './list-game-mechanics-source.mjs';
 import {
   areIndexedPackageSpecs,
   cleanupIndexedMechanics,
@@ -657,6 +663,7 @@ Manage editable Miaoda game-mechanic TypeScript source in src/game-mechanics.
 
 Commands:
   add <package...>  Resolve packages from the source index and add editable source
+  list              Discover installable packages and their ownership boundaries
   status            Show clean, modified, or missing source packages
   help              Show this help
 
@@ -860,10 +867,24 @@ 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', 'list', 'status'].includes(command))) {
     console.log(ROOT_HELP);
     return;
   }
+  if (command === 'list') {
+    if (wantsHelp) {
+      console.log(LIST_HELP);
+      return;
+    }
+    const options = parseMechanicListArguments(mechanicsArguments, DEFAULT_SOURCE_INDEX_URL);
+    const catalog = await listMechanics({
+      sourceIndexUrl: options.sourceIndexUrl,
+      capabilityPath,
+      filters: options.filters,
+    });
+    console.log(formatMechanicList(catalog, { json: options.json }));
+    return catalog;
+  }
   if (command === 'add') {
     if (wantsHelp) {
       console.log(ADD_HELP);

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

@@ -312,6 +312,20 @@ export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, sp
   }
 }
 
+export async function listIndexedMechanics(indexUrl) {
+  const loaded = await readIndex(indexUrl);
+  const packages = Object.keys(loaded.index.packages)
+    .sort()
+    .map((name) => {
+      const selected = selectVersion(loaded.index, name, undefined, loaded.indexUrl);
+      return { name: selected.name, version: selected.version };
+    });
+  return {
+    sourceIndexUrl: loaded.indexUrl,
+    packages,
+  };
+}
+
 export function cleanupIndexedMechanics(resolution) {
   if (resolution?.temporaryRoot) {
     rmSync(resolution.temporaryRoot, { recursive: true, force: true });

package/package.json

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