@forgeax/engine-pack 0.1.23 → 0.1.25

package/src/{parameterized-pack-node.ts → pack-authoring-node.ts}

@@ -5,26 +5,26 @@ import type { AssetGuid as EngineAssetGuid, Result } from '@forgeax/engine-types
 import { err, ok } from '@forgeax/engine-types';
 import { AssetGuid, isValidAssetGuidString, isValidPackSourceKey, PackageId } from './guid.js';
 import {
-  type AnyParameterizedPackDefinition,
-  createParameterizedPackAuthoringGateway,
+  type AnyScriptablePackDefinition,
+  createPackAuthoringGateway,
   type DirectPackJsonAsset,
   type PackAuthoringError,
   type PackAuthoringErrorCode,
+  type PackAuthoringGatewayPort,
+  type PackAuthoringOperation,
+  type PackAuthoringOperationResult,
+  type PackAuthoringResolutionStatus,
   type PackParameterDefinition,
   type PackParameterInheritanceSubject,
-  type ParameterizedPackGatewayPort,
-  type ParameterizedPackOperation,
-  type ParameterizedPackOperationResult,
-  type ParameterizedPackResolutionStatus,
-  parseParameterizedPackJson,
+  parsePackSourceJson,
   projectDirectPackJson,
   type ResolvedPackParameterInheritance,
   resolvePackParameterInheritance,
   validatePackDefinition,
-} from './parameterized-pack.js';
+} from './pack-authoring.js';
 import { type ScanInventory, scanInventory } from './scanner.js';
 
-export interface ParameterizedPackMaterializedAsset {
+export interface PackAuthoringMaterializedAsset {
   readonly packageId: string;
   readonly sourceKey: string;
   readonly guid: string;
@@ -35,13 +35,13 @@ export interface ParameterizedPackMaterializedAsset {
   readonly artifactsReady?: boolean;
 }
 
-export interface FileSystemParameterizedPackAuthoringOptions {
+export interface FileSystemPackAuthoringOptions {
   readonly gameRoot: string;
   readonly scanRoots?: readonly string[];
   /** Current-generation rows only; this callback is never called by mutations. */
   readonly materialized?: () =>
-    | readonly ParameterizedPackMaterializedAsset[]
-    | Promise<readonly ParameterizedPackMaterializedAsset[]>;
+    | readonly PackAuthoringMaterializedAsset[]
+    | Promise<readonly PackAuthoringMaterializedAsset[]>;
   /** Build owner callback; the gateway itself does not own DDC or Catalog state. */
   readonly rebuild?: (
     sourcePath: string,
@@ -69,7 +69,7 @@ interface SubjectBase {
 
 interface SourceSubject extends SubjectBase {
   readonly format: 'source';
-  readonly definition: AnyParameterizedPackDefinition;
+  readonly definition: AnyScriptablePackDefinition;
 }
 
 interface DirectSubject extends SubjectBase {
@@ -145,7 +145,7 @@ function pathError(
     | 'pack-source-not-found'
     | 'pack-source-write-failed'
     | 'pack-source-revision-conflict',
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
   expected: string,
   hint: string,
   detail: Readonly<Record<string, unknown>> = {},
@@ -157,7 +157,7 @@ function pathError(
 function confinedPath(
   gameRoot: string,
   candidate: unknown,
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
 ): Result<ConfinedPath, PackAuthoringError> {
   if (typeof candidate !== 'string' || candidate.length === 0 || isAbsolute(candidate)) {
     return err(
@@ -217,7 +217,7 @@ function parsePackageId(value: unknown): PackageId | undefined {
 }
 
 function serializedParameters(
-  definition: AnyParameterizedPackDefinition,
+  definition: AnyScriptablePackDefinition,
 ): readonly Readonly<Record<string, unknown>>[] | undefined {
   if (!('parameters' in definition)) return undefined;
   return definition.parameters.map((parameter) => ({
@@ -233,8 +233,8 @@ function serializedParameters(
 
 function sourceResult(
   subject: Subject,
-  operation: ParameterizedPackOperation,
-): ParameterizedPackOperationResult {
+  operation: PackAuthoringOperation,
+): PackAuthoringOperationResult {
   const base = {
     operation: operation.operation,
     requestId: operation.requestId,
@@ -277,7 +277,7 @@ function sourceResult(
   };
 }
 
-function scanFailure(operation: ParameterizedPackOperation, cause: unknown): PackAuthoringError {
+function scanFailure(operation: PackAuthoringOperation, cause: unknown): PackAuthoringError {
   const value =
     cause !== null && typeof cause === 'object' ? (cause as Record<string, unknown>) : {};
   const detail = value.detail !== null && typeof value.detail === 'object' ? value.detail : {};
@@ -285,7 +285,7 @@ function scanFailure(operation: ParameterizedPackOperation, cause: unknown): Pac
   const code: PackAuthoringErrorCode =
     reason === 'pack-parent-not-found' ||
     reason === 'pack-parent-cycle' ||
-    reason === 'pack-parent-not-parameterized'
+    reason === 'pack-parent-has-no-parameters'
       ? reason
       : value.code === 'pack-guid-collision'
         ? 'pack-guid-collision'
@@ -300,15 +300,15 @@ function scanFailure(operation: ParameterizedPackOperation, cause: unknown): Pac
   );
 }
 
-function scanRoots(options: FileSystemParameterizedPackAuthoringOptions): readonly string[] {
+function scanRoots(options: FileSystemPackAuthoringOptions): readonly string[] {
   return options.scanRoots === undefined || options.scanRoots.length === 0
     ? [resolve(options.gameRoot)]
     : options.scanRoots.map((root) => resolve(options.gameRoot, root));
 }
 
 async function readMaterialized(
-  options: FileSystemParameterizedPackAuthoringOptions,
-  operation: ParameterizedPackOperation,
+  options: FileSystemPackAuthoringOptions,
+  operation: PackAuthoringOperation,
 ): Promise<Result<readonly MaterializedAsset[], PackAuthoringError>> {
   let rawRows: unknown;
   try {
@@ -350,7 +350,7 @@ async function readMaterialized(
         ),
       );
     }
-    const row = rawRow as unknown as ParameterizedPackMaterializedAsset;
+    const row = rawRow as unknown as PackAuthoringMaterializedAsset;
     const parsedPackageId = parsePackageId(row.packageId);
     if (parsedPackageId === undefined) {
       return err(
@@ -474,8 +474,8 @@ async function readMaterialized(
 }
 
 async function createSnapshot(
-  options: FileSystemParameterizedPackAuthoringOptions,
-  operation: ParameterizedPackOperation,
+  options: FileSystemPackAuthoringOptions,
+  operation: PackAuthoringOperation,
 ): Promise<Result<GatewaySnapshot, PackAuthoringError>> {
   const scanned =
     options.inventory === undefined
@@ -486,7 +486,7 @@ async function createSnapshot(
   const directAssets: DirectAuthorAsset[] = [];
   for (const [sourcePath, declaration] of scanned.value.declarations) {
     const relativePath = relative(resolve(options.gameRoot), sourcePath).split(sep).join('/');
-    if (declaration.format === 'pack.ts-parameterized') {
+    if (declaration.format === 'pack.ts') {
       subjects.set(packageKey(declaration.definition.packageId), {
         format: 'source',
         packageId: declaration.definition.packageId,
@@ -497,7 +497,7 @@ async function createSnapshot(
       continue;
     }
     if (declaration.format !== 'pack.json' || declaration.value.schemaVersion !== '3.0.0') continue;
-    const parsed = parseParameterizedPackJson(declaration.value);
+    const parsed = parsePackSourceJson(declaration.value);
     if (!parsed.ok) return err(parsed.error);
     if (parsed.value.format === 'direct') {
       const projected = projectDirectPackJson(parsed.value);
@@ -637,7 +637,7 @@ async function resolveInstance(
 function subjectFor(
   gameRoot: string,
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
 ): Result<Subject, PackAuthoringError> {
   if (operation.sourcePath !== undefined) {
     const confined = confinedPath(gameRoot, operation.sourcePath, operation);
@@ -748,8 +748,8 @@ function subjectFor(
 async function inspectAsset(
   gameRoot: string,
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
-): Promise<Result<ParameterizedPackOperationResult, PackAuthoringError>> {
+  operation: PackAuthoringOperation,
+): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
   const selected = subjectFor(gameRoot, snapshot, operation);
   if (!selected.ok) return selected;
   const subject = selected.value;
@@ -852,8 +852,8 @@ async function inspectAsset(
 
 function listAssets(
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
-): ParameterizedPackOperationResult {
+  operation: PackAuthoringOperation,
+): PackAuthoringOperationResult {
   const assets = snapshotAssets(snapshot)
     .map((asset) => ({
       packageId: asset.packageId,
@@ -936,8 +936,8 @@ function assetForPair(
 async function resolveAsset(
   gameRoot: string,
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
-): Promise<Result<ParameterizedPackOperationResult, PackAuthoringError>> {
+  operation: PackAuthoringOperation,
+): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
   if (
     operation.require !== undefined &&
     operation.require !== 'identity' &&
@@ -1125,7 +1125,7 @@ async function resolveAsset(
     (candidate) =>
       candidate.packageId === packageKey(packageId) && candidate.sourceKey === sourceKey,
   );
-  const requirement: ParameterizedPackResolutionStatus = operation.require ?? 'identity';
+  const requirement: PackAuthoringResolutionStatus = operation.require ?? 'identity';
   if (requirement === 'present' && materialized === undefined) {
     return err(
       makeError(
@@ -1174,8 +1174,8 @@ async function resolveAsset(
 
 async function verify(
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
-): Promise<Result<ParameterizedPackOperationResult, PackAuthoringError>> {
+  operation: PackAuthoringOperation,
+): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
   for (const subject of snapshot.subjects.values()) {
     if (subject.format === 'instance') {
       const resolved = await resolveInstance(snapshot, subject);
@@ -1232,7 +1232,7 @@ async function verify(
 
 function packageIdFromOperation(
   snapshot: GatewaySnapshot,
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
 ): Result<PackageId, PackAuthoringError> {
   const value =
     operation.packageId === undefined
@@ -1264,8 +1264,8 @@ function packageIdFromOperation(
 }
 
 async function readConfined(
-  options: FileSystemParameterizedPackAuthoringOptions,
-  operation: ParameterizedPackOperation,
+  options: FileSystemPackAuthoringOptions,
+  operation: PackAuthoringOperation,
   sourcePath: unknown,
 ): Promise<
   Result<ConfinedPath & { readonly source: string; readonly revision: string }, PackAuthoringError>
@@ -1297,7 +1297,7 @@ async function readConfined(
 }
 
 function revisionConflict(
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
   path: string,
   actual: string,
 ): PackAuthoringError {
@@ -1322,7 +1322,7 @@ function directJson(
   return { schemaVersion: '3.0.0', packageId: PackageId.format(packageId), assets };
 }
 
-function parameterizedScaffold(
+function packSourceScaffold(
   packageId: PackageId,
   parameters: readonly PackParameterDefinition[] | undefined,
 ): string {
@@ -1359,12 +1359,12 @@ function replacePackageIdLiteral(source: string, packageId: string): string | un
 }
 
 async function inspectAfterWrite(
-  operation: ParameterizedPackOperation,
+  operation: PackAuthoringOperation,
   path: ConfinedPath,
   source: string,
   packageId: PackageId,
-  extra: Partial<ParameterizedPackOperationResult> = {},
-): Promise<Result<ParameterizedPackOperationResult, PackAuthoringError>> {
+  extra: Partial<PackAuthoringOperationResult> = {},
+): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
   return ok({
     operation: operation.operation,
     requestId: operation.requestId,
@@ -1377,9 +1377,9 @@ async function inspectAfterWrite(
 }
 
 async function executeRaw(
-  options: FileSystemParameterizedPackAuthoringOptions,
-  operation: ParameterizedPackOperation,
-): Promise<Result<ParameterizedPackOperationResult, PackAuthoringError>> {
+  options: FileSystemPackAuthoringOptions,
+  operation: PackAuthoringOperation,
+): Promise<Result<PackAuthoringOperationResult, PackAuthoringError>> {
   if (operation.operation === 'asset.list' || operation.operation === 'asset.inspect') {
     const snapshot = await createSnapshot(options, operation);
     if (!snapshot.ok) return snapshot;
@@ -1443,7 +1443,7 @@ async function executeRaw(
       );
     }
     let source: string;
-    let extra: Partial<ParameterizedPackOperationResult> = { format };
+    let extra: Partial<PackAuthoringOperationResult> = { format };
     if (format === 'pack.json') {
       if (
         operation.parameters !== undefined ||
@@ -1455,13 +1455,13 @@ async function executeRaw(
           makeError(
             'pack-parameter-invalid',
             'direct create to contain assets only',
-            'use pack.ts for a parameterized source or create-instance for parent+values',
+            'use pack.ts for a ScriptablePack source or create-instance for parent+values',
             { requestId: operation.requestId },
           ),
         );
       }
       const assets = operation.initialAssets ?? {};
-      const parsed = parseParameterizedPackJson(directJson(identity.value, assets));
+      const parsed = parsePackSourceJson(directJson(identity.value, assets));
       if (!parsed.ok) return err(parsed.error);
       if (parsed.value.format !== 'direct') {
         return err(
@@ -1523,7 +1523,7 @@ async function executeRaw(
         }
         parameters = validated.value.parameters;
       }
-      source = parameterizedScaffold(identity.value, parameters);
+      source = packSourceScaffold(identity.value, parameters);
       const serialized =
         parameters === undefined
           ? undefined
@@ -1532,7 +1532,7 @@ async function executeRaw(
               packageId: identity.value,
               parameters,
               build: () => ok({}),
-            } as AnyParameterizedPackDefinition);
+            } as AnyScriptablePackDefinition);
       extra = {
         format,
         ...(serialized === undefined ? {} : { parameters: serialized }),
@@ -1626,7 +1626,7 @@ async function executeRaw(
           ),
         );
       }
-      const parsed = parseParameterizedPackJson(parsedValue);
+      const parsed = parsePackSourceJson(parsedValue);
       if (!parsed.ok) return err(parsed.error);
       source = `${JSON.stringify(
         parsed.value.format === 'direct'
@@ -1688,7 +1688,7 @@ async function executeRaw(
         makeError(
           'pack-parent-not-found',
           'a parent packageId for the new instance',
-          'pass parentPackageId or parent and point it at a parameterized source',
+          'pass parentPackageId or parent and point it at a ScriptablePack source with parameters',
           { requestId: operation.requestId },
         ),
       );
@@ -1711,7 +1711,7 @@ async function executeRaw(
         makeError(
           'pack-parent-not-found',
           'the parent packageId to exist in the current Source Index',
-          'inspect the Source Index and choose a parameterized parent',
+          'inspect the Source Index and choose a ScriptablePack parent with parameters',
           { requestId: operation.requestId, parent: parentText },
         ),
       );
@@ -1719,8 +1719,8 @@ async function executeRaw(
     if (parent.format === 'source' && !('parameters' in parent.definition)) {
       return err(
         makeError(
-          'pack-parent-not-parameterized',
-          'a non-empty parameterized Pack source as the parent',
+          'pack-parent-has-no-parameters',
+          'a ScriptablePack source with a non-empty parameter list as the parent',
           'use asset-source.clone for a zero-parameter Pack',
           { requestId: operation.requestId, parent: parentText },
         ),
@@ -1729,8 +1729,8 @@ async function executeRaw(
     if (parent.format === 'direct') {
       return err(
         makeError(
-          'pack-parent-not-parameterized',
-          'a parameterized Pack source or instance as the parent',
+          'pack-parent-has-no-parameters',
+          'a ScriptablePack source or instance with parameters as the parent',
           'direct Packs cannot be instance parents',
           { requestId: operation.requestId, parent: parentText },
         ),
@@ -1836,7 +1836,7 @@ async function executeRaw(
         ),
       );
     }
-    const parsed = parseParameterizedPackJson(json);
+    const parsed = parsePackSourceJson(json);
     if (!parsed.ok) return err(parsed.error);
     if (parsed.value.format !== 'instance') {
       return err(
@@ -1946,23 +1946,21 @@ async function executeRaw(
   return err(
     makeError(
       'pack-parameter-invalid',
-      'a supported parameterized Pack operation',
-      'use one of PARAMETERIZED_PACK_OPERATION_IDS',
+      'a supported Pack authoring operation',
+      'use one of PACK_AUTHORING_OPERATION_IDS',
       { requestId: operation.requestId, operation: operation.operation },
     ),
   );
 }
 
-export function createFileSystemParameterizedPackAuthoringPort(
-  options: FileSystemParameterizedPackAuthoringOptions,
-): ParameterizedPackGatewayPort<ParameterizedPackOperationResult> {
+export function createFileSystemPackAuthoringPort(
+  options: FileSystemPackAuthoringOptions,
+): PackAuthoringGatewayPort<PackAuthoringOperationResult> {
   return { execute: (operation) => executeRaw(options, operation) };
 }
 
-export function createFileSystemParameterizedPackAuthoringGateway(
-  options: FileSystemParameterizedPackAuthoringOptions,
-): ParameterizedPackGatewayPort<ParameterizedPackOperationResult> {
-  return createParameterizedPackAuthoringGateway(
-    createFileSystemParameterizedPackAuthoringPort(options),
-  );
+export function createFileSystemPackAuthoringGateway(
+  options: FileSystemPackAuthoringOptions,
+): PackAuthoringGatewayPort<PackAuthoringOperationResult> {
+  return createPackAuthoringGateway(createFileSystemPackAuthoringPort(options));
 }