@volter/world-runtime 2.0.0

package/src/catalog.ts

@@ -0,0 +1,156 @@
+// The catalog — where the twins a world can run come from (docs/concepts/worlds.md
+// #the-config-and-the-running-world). Two sources answer one interface: this CHECKOUT (`packages/twin/<vendor>/`, the
+// catalog as the repo holds it) and an INSTALLED catalog (`@volter/twin-<vendor>` packages under
+// `node_modules`, walked up from the world root — hoisting-proof, and independent of the
+// packages' `exports` maps, which do not expose `package.json`). A world born in an app repo
+// names its twins as packages and the runtime resolves them at boot; a world born here names the
+// checkout-relative paths, as before.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+
+export const TWIN_PACKAGE_PREFIX = '@volter/twin-';
+
+/** Packages under the `@volter/twin-` prefix that are NOT twins. */
+
+export function twinPackageName(vendor: string): string { return `${TWIN_PACKAGE_PREFIX}${vendor}`; }
+
+export type CatalogKind = 'checkout' | 'installed';
+
+export type Catalog = {
+  kind: CatalogKind;
+  /** The world root the catalog was resolved for. */
+  root: string;
+  /** Every vendor the catalog can run, sorted — a deterministic input to `init`. */
+  vendors(): string[];
+  /** The pack's directory (holds `src/cli.ts`, `src/index.ts`, `defaults/`, `package.json`), or undefined. */
+  packDir(vendor: string): string | undefined;
+  /** The pack's own version, from its package.json — the value a world's pin carries. */
+  version(vendor: string): string | undefined;
+  /** The birth stamp: the checkout's git sha, or a digest of the installed versions. */
+  sha(): string;
+};
+
+function packageVersion(dir: string): string | undefined {
+  const p = join(dir, 'package.json');
+  if (!existsSync(p)) return undefined;
+  try { const v = (JSON.parse(readFileSync(p, 'utf8')) as { version?: unknown }).version; return typeof v === 'string' ? v : undefined; } catch { return undefined; }
+}
+
+function isPackDir(dir: string): boolean { return packCli(dir) !== undefined; }
+
+type Manifest = { name?: string; exports?: unknown; main?: string; bin?: Record<string, string> | string };
+function manifest(dir: string): Manifest | undefined { const p = join(dir, 'package.json'); if (!existsSync(p)) return undefined; try { return JSON.parse(readFileSync(p, 'utf8')) as Manifest; } catch { return undefined; } }
+
+/** The pack's module entry, FROM ITS MANIFEST (docs/contributing/architecture.md#the-publishing-pipeline): `exports['.']`
+ *  — `src/index.ts` in the checkout, `dist/src/index.js` once published — so the same resolution
+ *  serves both; `main` behind it; the checkout convention last. */
+export function packEntry(dir: string): string {
+  const m = manifest(dir);
+  const dot = m?.exports === undefined ? undefined : typeof m.exports === 'string' ? m.exports : (m.exports as Record<string, unknown>)['.'];
+  const value = typeof dot === 'string' ? dot : dot && typeof dot === 'object' ? ((dot as Record<string, unknown>).default ?? (dot as Record<string, unknown>).import) : undefined;
+  const rel = typeof value === 'string' ? value : typeof m?.main === 'string' ? m.main : 'src/index.ts';
+  return join(dir, rel);
+}
+/** The pack's cli, from its manifest's `bin` (`world-<vendor>` when named, else the first), or undefined when the directory is no pack. */
+export function packCli(dir: string): string | undefined {
+  const m = manifest(dir);
+  const bins = m === undefined ? {} : typeof m.bin === 'string' ? { [m.name ?? 'cli']: m.bin } : m.bin ?? {};
+  const named = Object.entries(bins).find(([n]) => n.startsWith('world-'))?.[1] ?? Object.values(bins)[0];
+  if (named) return join(dir, named);
+  return existsSync(join(dir, 'src', 'cli.ts')) ? join(dir, 'src', 'cli.ts') : undefined;
+}
+
+/** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
+export function findInstalledPackage(from: string, name: string): string | undefined {
+  let dir = resolve(from);
+  for (;;) {
+    const candidate = join(dir, 'node_modules', ...name.split('/'));
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+    const up = dirname(dir);
+    if (up === dir) return undefined;
+    dir = up;
+  }
+}
+
+/** Every installed `@volter/twin-<vendor>` visible from `from`, nearest wins. */
+function installedTwins(from: string): Map<string, string> {
+  const found = new Map<string, string>();
+  let dir = resolve(from);
+  for (;;) {
+    const scope = join(dir, 'node_modules', '@volter');
+    if (existsSync(scope)) {
+      for (const entry of readdirSync(scope, { withFileTypes: true })) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+        const name = `@volter/${entry.name}`;
+        if (!name.startsWith(TWIN_PACKAGE_PREFIX)) continue; // the platform's packages are `@volter/world-*`: outside the prefix by name
+        const vendor = name.slice(TWIN_PACKAGE_PREFIX.length);
+        const packDir = join(scope, entry.name);
+        if (!found.has(vendor) && isPackDir(packDir)) found.set(vendor, packDir);
+      }
+    }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return found;
+}
+
+function fnv1a(text: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) { h ^= text.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h.toString(16).padStart(8, '0');
+}
+
+export function checkoutCatalog(root: string): Catalog {
+  const packsDir = resolve(root, 'packages', 'twin');
+  const vendors = (): string[] => readdirSync(packsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && isPackDir(join(packsDir, entry.name)))
+    .map((entry) => entry.name)
+    .sort();
+  return {
+    kind: 'checkout',
+    root: resolve(root),
+    vendors,
+    packDir: (vendor) => (isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
+    version: (vendor) => packageVersion(join(packsDir, vendor)),
+    sha: () => {
+      const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+      const sha = proc.status === 0 ? proc.stdout.trim() : '';
+      return /^[0-9a-f]{40}$/.test(sha) ? sha : 'unknown';
+    },
+  };
+}
+
+export function installedCatalog(root: string): Catalog {
+  const twins = installedTwins(root);
+  return {
+    kind: 'installed',
+    root: resolve(root),
+    vendors: () => [...twins.keys()].sort(),
+    packDir: (vendor) => twins.get(vendor),
+    version: (vendor) => { const dir = twins.get(vendor); return dir === undefined ? undefined : packageVersion(dir); },
+    sha: () => `installed-${fnv1a([...twins.keys()].sort().map((v) => `${v}@${packageVersion(twins.get(v)!) ?? '?'}`).join(','))}`,
+  };
+}
+
+/** The catalog for a world root: the checkout when `packages/twin` is there, else what is installed. */
+export function resolveCatalog(root: string): Catalog {
+  const resolved = resolve(root);
+  if (existsSync(join(resolved, 'packages', 'twin'))) return checkoutCatalog(resolved);
+  const installed = installedCatalog(resolved);
+  if (installed.vendors().length === 0) {
+    throw new Error(
+      `No twins found for ${resolved}: no \`packages/twin\` catalog here and no \`@volter/twin-<vendor>\` package installed above it. `
+      + `Install the twins your app needs (e.g. \`bun add -d @volter/twin-stripe\`) and run init again.`,
+    );
+  }
+  return installed;
+}
+
+/** The pack directory a service boots from: its `package` resolved from the world root at boot. */
+export function resolveServicePackage(root: string, pkg: string): string {
+  const dir = findInstalledPackage(root, pkg);
+  if (dir === undefined) throw new Error(`Twin package ${pkg} is not installed above ${root} — \`bun add -d ${pkg}\` (or npm/pnpm) and run up again`);
+  return dir;
+}