miaoda-game-devkit 0.7.2 → 0.8.0

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

@@ -0,0 +1,262 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, 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;
+
+function fail(field, expected, repair) {
+  throw new Error(`miaoda mechanics source index: ${field} must ${expected}. ${repair}`);
+}
+
+function isMechanicName(value) {
+  return typeof value === 'string' && /^miaoda-game-[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+
+function parsePackageSpec(spec) {
+  if (typeof spec !== 'string') return undefined;
+  const match = /^(miaoda-game-[a-z0-9][a-z0-9._-]*?)(?:@([^/]+))?$/.exec(spec);
+  if (!match) return undefined;
+  return { name: match[1], version: match[2] };
+}
+
+export function areIndexedPackageSpecs(specs) {
+  return Array.isArray(specs) && specs.length > 0 && specs.every((spec) => parsePackageSpec(spec));
+}
+
+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.');
+  }
+  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.');
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of response.body) {
+    total += chunk.byteLength;
+    if (total > limit) {
+      fail(label, `be at most ${limit} bytes`, 'Publish a smaller source artifact.');
+    }
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+async function download(url, limit, label) {
+  let response;
+  try {
+    response = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30_000) });
+  } catch (error) {
+    fail(label, `be reachable at ${url}`, error instanceof Error ? error.message : String(error));
+  }
+  return readResponse(response, limit, label);
+}
+
+function validateVersionRecord(name, version, record, indexUrl) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    fail(`${name}@${version}`, 'be an object in the source index', 'Regenerate the source index.');
+  }
+  if (typeof record.url !== 'string' || record.url.length === 0) {
+    fail(`${name}@${version} url`, 'be a non-empty URL', 'Regenerate the source index.');
+  }
+  let url;
+  try {
+    url = new URL(record.url, indexUrl).href;
+  } catch {
+    fail(`${name}@${version} url`, 'be an absolute or index-relative HTTP(S) URL', 'Correct the source object URL.');
+  }
+  if (!/^https?:/.test(url)) {
+    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.');
+  }
+  const dependencies = record.dependencies ?? {};
+  if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) {
+    fail(`${name}@${version} dependencies`, 'be an object', 'Regenerate the source index.');
+  }
+  for (const [dependencyName, dependencyVersion] of Object.entries(dependencies)) {
+    if (!isMechanicName(dependencyName) || typeof dependencyVersion !== 'string' || dependencyVersion.length === 0) {
+      fail(
+        `${name}@${version} dependency ${dependencyName}`,
+        'map a miaoda-game-* name to an exact non-empty version',
+        'Regenerate the source index from workspace manifests.',
+      );
+    }
+  }
+  return { url, sha256: record.sha256.toLowerCase(), dependencies };
+}
+
+function selectVersion(index, name, requestedVersion, indexUrl) {
+  const packageRecord = index.packages[name];
+  if (!packageRecord) {
+    fail(name, 'exist in the source index', 'Upload the package and regenerate stable.json.');
+  }
+  const version = requestedVersion || packageRecord.latest;
+  if (typeof version !== 'string' || version.length === 0) {
+    fail(`${name} latest`, 'be a non-empty version', 'Regenerate stable.json with a latest pointer.');
+  }
+  const versionRecord = packageRecord.versions?.[version];
+  if (!versionRecord) {
+    fail(`${name}@${version}`, 'exist in the source index', 'Upload that version or request an indexed version.');
+  }
+  return { name, version, ...validateVersionRecord(name, version, versionRecord, 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);
+  }
+  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.');
+    const selected = selectVersion(index, parsed.name, parsed.version, indexUrl);
+    roots.set(parsed.name, selected.version);
+  }
+
+  const selectedPackages = new Map();
+  const queue = [...roots].map(([name, version]) => ({ name, version, requestedBy: 'root selection' }));
+  while (queue.length > 0) {
+    const request = queue.shift();
+    const existing = selectedPackages.get(request.name);
+    if (existing) {
+      if (existing.version !== request.version) {
+        fail(
+          `resolved versions for ${request.name}`,
+          `contain one version, but found ${existing.version} and ${request.version}`,
+          `Align ${request.requestedBy} with the existing source dependency graph.`,
+        );
+      }
+      continue;
+    }
+    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}` });
+    }
+  }
+  return { roots: Object.fromEntries([...roots].sort()), selectedPackages };
+}
+
+async function readIndex(indexUrl) {
+  let normalizedUrl;
+  try {
+    normalizedUrl = new URL(indexUrl).href;
+  } catch {
+    fail('index URL', 'be an absolute HTTP(S) URL', 'Pass --source-index=https://.../stable.json.');
+  }
+  if (!/^https?:/.test(normalizedUrl)) {
+    fail('index URL', 'use HTTP or HTTPS', 'Host stable.json on publicly readable storage.');
+  }
+  const bytes = await download(normalizedUrl, MAX_INDEX_BYTES, 'stable.json');
+  let index;
+  try {
+    index = JSON.parse(new TextDecoder().decode(bytes));
+  } catch (error) {
+    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.');
+  }
+  return { index, indexUrl: normalizedUrl };
+}
+
+function assertExtractedTree(root, name) {
+  const stack = [root];
+  while (stack.length > 0) {
+    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.');
+      }
+      if (entry.isDirectory()) stack.push(join(current, entry.name));
+    }
+  }
+}
+
+async function extractPackage(targetRoot, selected, bytes) {
+  const actualHash = createHash('sha256').update(bytes).digest('hex');
+  if (actualHash !== selected.sha256) {
+    fail(
+      `${selected.name}@${selected.version} sha256`,
+      `match stable.json (${selected.sha256}), but downloaded ${actualHash}`,
+      'Upload the correct immutable TGZ or regenerate stable.json.',
+    );
+  }
+  const tarballPath = join(targetRoot, `${selected.name}-${selected.version}.tgz`);
+  const packageDirectory = join(targetRoot, selected.name);
+  writeFileSync(tarballPath, bytes);
+  mkdirSync(packageDirectory, { recursive: true });
+  await extractTarball({
+    cwd: packageDirectory,
+    file: tarballPath,
+    strip: 1,
+    strict: true,
+    preservePaths: false,
+    filter(path, entry) {
+      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.');
+      }
+      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.');
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    fail(
+      `${selected.name}@${selected.version} package.json`,
+      'contain valid JSON',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  if (manifest.name !== selected.name || manifest.version !== selected.version) {
+    fail(
+      `${selected.name}@${selected.version} manifest identity`,
+      `match the index, but found ${manifest.name}@${manifest.version}`,
+      'Regenerate stable.json from the exact uploaded TGZ.',
+    );
+  }
+  if (!existsSync(join(packageDirectory, 'src'))) {
+    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 };
+}
+
+export async function resolveIndexedMechanics({ indexUrl, previousRoots = {}, specs }) {
+  const loaded = await readIndex(indexUrl);
+  const graph = resolveGraph(loaded.index, loaded.indexUrl, previousRoots, specs);
+  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))) {
+      const bytes = await download(selected.url, MAX_TARBALL_BYTES, `${selected.name}@${selected.version}`);
+      resolvedPackages.set(selected.name, await extractPackage(temporaryRoot, selected, bytes));
+    }
+    return {
+      roots: graph.roots,
+      resolvedPackages,
+      temporaryRoot,
+      sourceIndexUrl: loaded.indexUrl,
+    };
+  } catch (error) {
+    rmSync(temporaryRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function cleanupIndexedMechanics(resolution) {
+  if (resolution?.temporaryRoot) rmSync(resolution.temporaryRoot, { recursive: true, force: true });
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "bin": {
+    "miaoda": "bin/miaoda.js",
     "miaoda-phaser-game-lint": "bin/miaoda-phaser-game-lint.js",
     "miaoda-react-game-lint": "bin/miaoda-react-game-lint.js"
   },
@@ -73,7 +74,6 @@
       }
     },
     "./react/vitest-setup": "./dist/react/vitest-setup.mjs",
-    "./pnpmfile": "./mechanics/pnpmfile.cjs",
     "./biome": "./biome-config.json",
     "./tsconfig-base": "./tsconfig-base.json"
   },
@@ -87,7 +87,8 @@
     "!dist/**/*.map",
     "!dist/lint/*.contract.mjs",
     "!dist/lint/contracts.config.mjs",
-    "!dist/lint/**/*.test.*"
+    "!dist/lint/**/*.test.*",
+    "!mechanics/*.test.mjs"
   ],
   "nx": {
     "tags": [
@@ -110,7 +111,7 @@
           "build"
         ],
         "options": {
-          "command": "pnpm run test:contracts && pnpm run test:published",
+          "command": "pnpm run test:contracts && pnpm run test:mechanics && pnpm run test:published",
           "cwd": "packages/game-devkit"
         }
       }
@@ -120,10 +121,11 @@
     "@biomejs/biome": "2.5.6",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "jsdom": "29.1.1",
-    "oxc-resolver": "11.24.2",
     "oxc-parser": "0.144.0",
+    "oxc-resolver": "11.24.2",
     "oxlint": "1.76.0",
     "tailwindcss": "3.4.19",
+    "tar": "7.5.22",
     "vitest": "4.1.10"
   },
   "peerDependencies": {

package/tsconfig-base.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/tsconfig",
   "compilerOptions": {
     "target": "ES2020",
-    "useDefineForClassFields": true,
+    "useDefineForClassFields": false,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "ESNext",
     "moduleResolution": "bundler",