@forgeax/engine-ddc 0.1.2

package/src/runtime-scope.ts

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DdcStoreError } from './errors.js';
+
+export interface DdcRuntimeScope {
+  readonly scopeId: string;
+  readonly scopeHash: string;
+  readonly root: string;
+  readonly metadataPath: string;
+}
+
+interface ScopeMetadata {
+  readonly schemaVersion: 'forgeax-ddc-scope/v2';
+  readonly scopeId: string;
+  readonly scopeHash: string;
+}
+
+function scopeHash(scopeId: string): string {
+  return createHash('sha256').update(scopeId, 'utf8').digest('hex');
+}
+
+export function runtimeScopeHash(scopeId: string): string {
+  return scopeHash(scopeId);
+}
+
+export async function createRuntimeScope(root: string, scopeId: string): Promise<DdcRuntimeScope> {
+  if (scopeId.length === 0) {
+    throw new DdcStoreError({
+      code: 'ddc-scope-mismatch',
+      detail: 'runtime scope id must not be empty',
+      expected: 'a non-empty original scope id',
+      actual: scopeId,
+      rootKind: 'project-ddc',
+    });
+  }
+  const hash = scopeHash(scopeId);
+  const scopeRoot = join(root, 'scopes', hash);
+  const metadataPath = join(scopeRoot, 'scope.json');
+  await mkdir(scopeRoot, { recursive: true });
+  const expected: ScopeMetadata = {
+    schemaVersion: 'forgeax-ddc-scope/v2',
+    scopeId,
+    scopeHash: hash,
+  };
+  try {
+    const actual = JSON.parse(await readFile(metadataPath, 'utf8')) as Partial<ScopeMetadata>;
+    if (
+      actual.schemaVersion !== expected.schemaVersion ||
+      actual.scopeId !== expected.scopeId ||
+      actual.scopeHash !== expected.scopeHash
+    ) {
+      throw new DdcStoreError({
+        code: 'ddc-scope-mismatch',
+        detail: 'runtime scope metadata does not match the requested scope',
+        expected,
+        actual,
+        rootKind: 'project-ddc',
+        scope: scopeId,
+      });
+    }
+  } catch (error) {
+    if (error instanceof DdcStoreError) throw error;
+    const temporary = `${metadataPath}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(expected));
+    await rename(temporary, metadataPath);
+  }
+  return { scopeId, scopeHash: hash, root: scopeRoot, metadataPath };
+}
+
+export async function assertRuntimeScope(
+  root: string,
+  scope: Pick<DdcRuntimeScope, 'scopeId' | 'scopeHash'>,
+): Promise<DdcRuntimeScope> {
+  const expectedHash = scopeHash(scope.scopeId);
+  if (scope.scopeHash !== expectedHash) {
+    throw new DdcStoreError({
+      code: 'ddc-scope-mismatch',
+      detail: 'runtime scope hash does not match the original scope id',
+      expected: expectedHash,
+      actual: scope.scopeHash,
+      rootKind: 'project-ddc',
+      scope: scope.scopeId,
+    });
+  }
+  return createRuntimeScope(root, scope.scopeId);
+}

package/src/status.ts

@@ -0,0 +1,58 @@
+import type { DdcErrorRootKind } from './errors.js';
+
+export const DDC_STATUS_SCHEMA = 'forgeax-ddc-status/v2' as const;
+
+export type DdcStatusHealth = 'ready' | 'blocked' | 'missing' | 'stale' | 'failed';
+export type DdcStatusLayerKind = 'build' | 'project' | 'runtime';
+export type DdcStatusRootKind = DdcErrorRootKind;
+
+export interface DdcRecoveryAction {
+  readonly kind: 'inspect' | 'allocate-generation' | 'retry' | 'cold-rebuild' | 'prune';
+  readonly executable: boolean;
+  readonly exactTarget?: string;
+  readonly reason?: string;
+}
+
+export interface DdcStatusLayer {
+  readonly kind: DdcStatusLayerKind;
+  readonly owner: 'engine-ddc' | 'engine-pack' | 'plugin' | 'runtime';
+  readonly rootKind: DdcStatusRootKind;
+  readonly scopeId?: string;
+  readonly current?: number | string;
+  readonly lastKnownGood?: number | string;
+  readonly protection: readonly string[];
+  readonly actions: readonly DdcRecoveryAction[];
+}
+
+export interface DdcStatus {
+  readonly schemaVersion: typeof DDC_STATUS_SCHEMA;
+  readonly health: DdcStatusHealth;
+  readonly layers: readonly DdcStatusLayer[];
+  readonly gameDir?: string;
+  readonly projectDdcRoot?: string;
+}
+
+export type BrowserDdcRecoveryAction = Omit<DdcRecoveryAction, 'exactTarget'>;
+export type BrowserDdcStatusLayer = Omit<DdcStatusLayer, 'actions'> & {
+  readonly actions: readonly BrowserDdcRecoveryAction[];
+};
+export type BrowserDdcStatus = Omit<DdcStatus, 'gameDir' | 'projectDdcRoot' | 'layers'> & {
+  readonly layers: readonly BrowserDdcStatusLayer[];
+};
+
+export function serializeDdcStatus(status: DdcStatus): string {
+  return JSON.stringify(status);
+}
+
+export function projectDdcStatusForBrowser(status: DdcStatus): BrowserDdcStatus {
+  return {
+    schemaVersion: DDC_STATUS_SCHEMA,
+    health: status.health,
+    layers: status.layers.map((layer) => ({
+      ...layer,
+      actions: layer.actions.map(({ exactTarget: _exactTarget, ...action }) => action),
+    })),
+  };
+}
+
+export const toBrowserDdcStatus = projectDdcStatusForBrowser;