@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/publish-command.mjs

@@ -1,17 +1,22 @@
 import { spawn } from 'node:child_process';
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 
 import { preparePublishPackageSurface } from './external-package-surface.mjs';
 import {
   PACKAGE_INTEGRITY_PUBLISH_FILES,
   writeSignedPackageIntegrityArtifacts,
 } from './package-integrity.mjs';
+import { canPromptInteractively, promptInput, promptSelect } from './terminal-ui.mjs';
 import { resolvePublishEnvExampleSurface } from './publish-env-example.mjs';
 import { validatePublishProject } from './publish-validation.mjs';
 import { formatBytes } from './external-asset-policy.mjs';
 
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z-.]+)?$/;
+const SCOPED_PACKAGE_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+const UNSCOPED_PACKAGE_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
 export function isNpmPublishLifecycleInvocation(env = process.env) {
   return env.npm_lifecycle_event === 'publish' && env.npm_command === 'publish';
 }
@@ -36,6 +41,126 @@ function stripOption(commandArgs, optionName) {
   return nextArgs;
 }
 
+function sanitizePackageSlug(value) {
+  const compact = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@[^/]+\//, '')
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9._-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-._]+|[-._]+$/g, '');
+  if (!compact) {
+    throw new Error(`Cannot derive package slug from "${value}".`);
+  }
+  return compact;
+}
+
+function buildDefaultPackageName(projectRoot) {
+  return `@aurajs/${sanitizePackageSlug(basename(projectRoot))}`;
+}
+
+function ensureScopedPackageName(value) {
+  const trimmed = String(value || '').trim();
+  if (!trimmed) {
+    throw new Error('Package name cannot be empty.');
+  }
+  if (/^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(trimmed)) {
+    return `@${trimmed}`;
+  }
+  return trimmed;
+}
+
+function isValidPackageName(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) {
+    return false;
+  }
+  try {
+    const candidate = ensureScopedPackageName(normalized);
+    return SCOPED_PACKAGE_RE.test(candidate) || UNSCOPED_PACKAGE_RE.test(candidate);
+  } catch {
+    return false;
+  }
+}
+
+function validatePackageName(value) {
+  const normalized = ensureScopedPackageName(value);
+  if (!SCOPED_PACKAGE_RE.test(normalized) && !UNSCOPED_PACKAGE_RE.test(normalized)) {
+    throw new Error(`Invalid npm package name "${value}".`);
+  }
+}
+
+function normalizeVersion(value) {
+  return String(value || '').trim().replace(/^v/i, '');
+}
+
+function isValidVersion(value) {
+  return SEMVER_RE.test(String(value || '').trim());
+}
+
+function validateVersion(value) {
+  if (!isValidVersion(value)) {
+    throw new Error(`Invalid version "${value}". Expected semver like 1.2.3 or 1.2.3-beta.1.`);
+  }
+}
+
+function bumpVersion(currentVersion, bumpKind) {
+  const match = normalizeVersion(currentVersion).match(SEMVER_RE);
+  if (!match) {
+    throw new Error(`Current version "${currentVersion}" is not valid semver.`);
+  }
+  const major = Number.parseInt(match[1], 10);
+  const minor = Number.parseInt(match[2], 10);
+  const patch = Number.parseInt(match[3], 10);
+  const prerelease = match[4] || '';
+
+  if (bumpKind === 'major') return `${major + 1}.0.0${prerelease}`;
+  if (bumpKind === 'minor') return `${major}.${minor + 1}.0${prerelease}`;
+  return `${major}.${minor}.${patch + 1}${prerelease}`;
+}
+
+function extractInternalPublishOptions(commandArgs) {
+  const sanitizedArgs = [];
+  let explicitName = null;
+  let explicitVersion = null;
+  let yes = false;
+
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const current = commandArgs[index];
+    if (current === '--yes' || current === '-y') {
+      yes = true;
+      continue;
+    }
+    if (current === '--name') {
+      explicitName = commandArgs[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (current.startsWith('--name=')) {
+      explicitName = current.slice('--name='.length);
+      continue;
+    }
+    if (current === '--version') {
+      explicitVersion = commandArgs[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (current.startsWith('--version=')) {
+      explicitVersion = current.slice('--version='.length);
+      continue;
+    }
+    sanitizedArgs.push(current);
+  }
+
+  return {
+    sanitizedArgs,
+    explicitName,
+    explicitVersion,
+    yes,
+  };
+}
+
 export function extractPublishToken(commandArgs, env = process.env) {
   let explicitToken = null;
 
@@ -130,7 +255,7 @@ function createPublishTokenEnv(token, env = process.env) {
   };
 }
 
-export function readProjectPackage(projectRoot = process.cwd()) {
+function readProjectPackageManifest(projectRoot = process.cwd()) {
   const packagePath = resolve(projectRoot, 'package.json');
   if (!existsSync(packagePath)) {
     throw new Error('aura publish requires a package.json in the current project root.');
@@ -146,9 +271,6 @@ export function readProjectPackage(projectRoot = process.cwd()) {
   const packageName = typeof projectPackage?.name === 'string' && projectPackage.name.trim().length > 0
     ? projectPackage.name.trim()
     : null;
-  if (!packageName) {
-    throw new Error('aura publish requires package.json -> name to be set.');
-  }
 
   return {
     packagePath,
@@ -157,6 +279,158 @@ export function readProjectPackage(projectRoot = process.cwd()) {
   };
 }
 
+export function readProjectPackage(projectRoot = process.cwd()) {
+  const projectPackage = readProjectPackageManifest(projectRoot);
+  if (!projectPackage.packageName) {
+    throw new Error('aura publish requires package.json -> name to be set.');
+  }
+  return projectPackage;
+}
+
+async function resolvePublishPackageName(
+  commandArgs,
+  {
+    projectRoot = process.cwd(),
+    canPromptInteractivelyImpl = canPromptInteractively,
+    promptInputImpl = promptInput,
+  } = {},
+) {
+  const { packagePath, projectPackage, packageName: currentPackageName } = readProjectPackageManifest(projectRoot);
+  const { sanitizedArgs, explicitName, yes } = extractInternalPublishOptions(commandArgs);
+  const defaultPackageName = buildDefaultPackageName(projectRoot);
+  const currentValidPackageName = currentPackageName && isValidPackageName(currentPackageName)
+    ? ensureScopedPackageName(currentPackageName)
+    : null;
+
+  let targetPackageName = currentPackageName;
+
+  if (explicitName !== null) {
+    targetPackageName = ensureScopedPackageName(explicitName);
+    validatePackageName(targetPackageName);
+  } else if (yes) {
+    targetPackageName = currentPackageName || defaultPackageName;
+    validatePackageName(targetPackageName);
+  } else if (canPromptInteractivelyImpl()) {
+    const fallbackPackageName = currentValidPackageName || defaultPackageName;
+    const fallbackDisplay = fallbackPackageName.startsWith('@')
+      ? fallbackPackageName.slice(1)
+      : fallbackPackageName;
+    const input = await promptInputImpl(`  Package name (default: ${fallbackDisplay})`);
+    targetPackageName = ensureScopedPackageName(input || fallbackPackageName);
+    validatePackageName(targetPackageName);
+  }
+
+  if (targetPackageName && projectPackage.name !== targetPackageName) {
+    projectPackage.name = targetPackageName;
+    writeFileSync(packagePath, `${JSON.stringify(projectPackage, null, 2)}\n`, 'utf8');
+  }
+
+  return {
+    publishArgs: sanitizedArgs,
+    packageName: targetPackageName,
+  };
+}
+
+async function resolvePublishVersion(
+  commandArgs,
+  {
+    projectRoot = process.cwd(),
+    canPromptInteractivelyImpl = canPromptInteractively,
+    promptSelectImpl = promptSelect,
+    promptInputImpl = promptInput,
+  } = {},
+) {
+  const { packagePath, projectPackage } = readProjectPackage(projectRoot);
+  const { sanitizedArgs, explicitVersion, yes } = extractInternalPublishOptions(commandArgs);
+  const packageVersion = typeof projectPackage?.version === 'string' && projectPackage.version.trim().length > 0
+    ? normalizeVersion(projectPackage.version)
+    : null;
+  const currentVersion = isValidVersion(packageVersion || '') ? packageVersion : null;
+
+  let targetVersion = packageVersion;
+
+  if (explicitVersion !== null) {
+    const normalized = normalizeVersion(explicitVersion);
+    validateVersion(normalized);
+    targetVersion = normalized;
+  } else if (yes) {
+    if (packageVersion) {
+      validateVersion(packageVersion);
+      targetVersion = packageVersion;
+    } else {
+      targetVersion = '0.1.0';
+    }
+  } else if (canPromptInteractivelyImpl()) {
+    if (currentVersion) {
+      const choice = await promptSelectImpl(
+        '  Version selection',
+        [
+          { value: 'current', label: `Current (${currentVersion})`, aliases: ['c', 'keep'] },
+          { value: 'bump', label: 'Bump version', aliases: ['b'] },
+          { value: 'custom', label: 'Custom version', aliases: ['x'] },
+        ],
+        'current',
+      );
+
+      if (choice === 'bump') {
+        const bumpKind = await promptSelectImpl(
+          '  Bump type',
+          [
+            { value: 'patch', label: `Patch (${bumpVersion(currentVersion, 'patch')})`, aliases: ['p'] },
+            { value: 'minor', label: `Minor (${bumpVersion(currentVersion, 'minor')})`, aliases: ['m'] },
+            { value: 'major', label: `Major (${bumpVersion(currentVersion, 'major')})`, aliases: ['M'] },
+          ],
+          'patch',
+        );
+        targetVersion = bumpVersion(currentVersion, bumpKind);
+      } else if (choice === 'custom') {
+        while (true) {
+          const input = normalizeVersion(await promptInputImpl('  Custom version (semver)'));
+          if (!input) {
+            console.error('  Version is required.');
+            continue;
+          }
+          if (!isValidVersion(input)) {
+            console.error('  Invalid version format. Use semver like 1.2.3 or 1.2.3-beta.1');
+            continue;
+          }
+          targetVersion = input;
+          break;
+        }
+      }
+    } else {
+      const defaultVersion = packageVersion ? '' : '0.1.0';
+      const promptLabel = defaultVersion
+        ? `  Package version (semver, default: ${defaultVersion})`
+        : '  Package version (semver)';
+      while (true) {
+        const input = normalizeVersion(await promptInputImpl(promptLabel));
+        const candidate = input || defaultVersion;
+        if (!candidate) {
+          console.error('  Version is required.');
+          continue;
+        }
+        if (!isValidVersion(candidate)) {
+          console.error('  Invalid version format. Use semver like 1.2.3 or 1.2.3-beta.1');
+          continue;
+        }
+        targetVersion = candidate;
+        break;
+      }
+    }
+  }
+
+  if (targetVersion && projectPackage.version !== targetVersion) {
+    projectPackage.version = targetVersion;
+    writeFileSync(packagePath, `${JSON.stringify(projectPackage, null, 2)}\n`, 'utf8');
+  }
+
+  return {
+    publishArgs: sanitizedArgs,
+    packageVersion: targetVersion,
+  };
+}
+
 export function buildPublishArgs(commandArgs, { packageName } = {}) {
   const sanitizedArgs = stripOption(commandArgs, '--token');
   const publishArgs = ['publish', ...sanitizedArgs];
@@ -217,6 +491,9 @@ export async function runPublishCommand(
     stdout = process.stdout,
     stderr = process.stderr,
     validateProject = validatePublishProject,
+    canPromptInteractivelyImpl = canPromptInteractively,
+    promptSelectImpl = promptSelect,
+    promptInputImpl = promptInput,
   } = {},
 ) {
   if (isNpmPublishLifecycleInvocation(env)) {
@@ -231,6 +508,19 @@ export async function runPublishCommand(
     };
   }
 
+  await resolvePublishPackageName(commandArgs, {
+    projectRoot,
+    canPromptInteractivelyImpl,
+    promptInputImpl,
+  });
+
+  const publishVersionResolution = await resolvePublishVersion(commandArgs, {
+    projectRoot,
+    canPromptInteractivelyImpl,
+    promptSelectImpl,
+    promptInputImpl,
+  });
+
   let validation;
   try {
     validation = await validateProject({
@@ -260,7 +550,10 @@ export async function runPublishCommand(
 
   const packageName = validation.packageName;
   const { projectPackage } = readProjectPackage(projectRoot);
-  const { publishArgs: sanitizedCommandArgs, publishEnv, publishToken } = extractPublishToken(commandArgs, env);
+  const { publishArgs: sanitizedCommandArgs, publishEnv, publishToken } = extractPublishToken(
+    publishVersionResolution.publishArgs,
+    env,
+  );
   const publishArgs = buildPublishArgs(sanitizedCommandArgs, { packageName });
   const publishTokenEnv = createPublishTokenEnv(publishToken, publishEnv);
   const dryRun = hasOption(sanitizedCommandArgs, '--dry-run');
@@ -284,6 +577,9 @@ export async function runPublishCommand(
   });
   stdout?.write(`\n  aura publish: ${dryRun ? 'dry-run' : 'npm-first publish'}\n`);
   stdout?.write(`  Package: ${packageName}\n`);
+  if (publishVersionResolution.packageVersion) {
+    stdout?.write(`  Version: ${publishVersionResolution.packageVersion}\n`);
+  }
   stdout?.write(`  Validation report: ${validation.reportPath}\n`);
   if (Number.isFinite(validation?.report?.validation?.assets?.assetBytes)) {
     const assets = validation.report.validation.assets;
@@ -309,6 +605,7 @@ export async function runPublishCommand(
     skipped: false,
     reasonCode: dryRun ? 'publish_dry_run_ok' : 'publish_ok',
     packageName,
+    packageVersion: publishVersionResolution.packageVersion || validation.packageVersion || null,
     reportPath: validation.reportPath,
     publishArgs,
   };

package/src/replay-runtime.mjs

@@ -0,0 +1,257 @@
+import { resolve } from 'node:path';
+
+import { executeFrame } from './headless-test.mjs';
+import {
+  applySessionState,
+  bootSessionRuntime,
+  exportSessionState,
+} from './session-runtime.mjs';
+
+export const GAME_REPLAY_SCHEMA_VERSION = 'aurajs.game-replay.v1';
+export const GAME_REPLAY_REPORT_SCHEMA_VERSION = 'aurajs.game-replay-report.v1';
+
+export class ReplayError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'ReplayError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+function parseReplayFrames(value, fallback = 1) {
+  if (value == null) return fallback;
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1) {
+    throw new ReplayError('invalid_replay_frames', 'Replay step frames must be a positive integer.');
+  }
+  return numeric;
+}
+
+function normalizeReplayPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new ReplayError('invalid_replay_payload', 'Replay payload must be an object.');
+  }
+  if (payload.schemaVersion !== GAME_REPLAY_SCHEMA_VERSION) {
+    throw new ReplayError(
+      'schema_version_mismatch',
+      `Unsupported replay schema "${payload.schemaVersion}". Expected "${GAME_REPLAY_SCHEMA_VERSION}".`,
+    );
+  }
+  if (!Array.isArray(payload.steps) || payload.steps.length === 0) {
+    throw new ReplayError('invalid_replay_payload', 'Replay payload requires a non-empty steps array.');
+  }
+
+  return {
+    schemaVersion: GAME_REPLAY_SCHEMA_VERSION,
+    seed: payload.seed == null ? null : String(payload.seed),
+    stopOnDivergence: payload.stopOnDivergence !== false,
+    initialState: payload.initialState ?? null,
+    steps: payload.steps.map((step, index) => {
+      if (!step || typeof step !== 'object' || Array.isArray(step)) {
+        throw new ReplayError('invalid_replay_step', `Replay step at index ${index} must be an object.`);
+      }
+      return {
+        label: typeof step.label === 'string' && step.label.trim().length > 0 ? step.label.trim() : null,
+        checkpointId: typeof step.checkpointId === 'string' && step.checkpointId.trim().length > 0 ? step.checkpointId.trim() : null,
+        expectFingerprint: typeof step.expectFingerprint === 'string' && step.expectFingerprint.trim().length > 0
+          ? step.expectFingerprint.trim()
+          : null,
+        frames: parseReplayFrames(step.frames, 1),
+        input: step.input && typeof step.input === 'object' && !Array.isArray(step.input)
+          ? step.input
+          : null,
+      };
+    }),
+  };
+}
+
+function hashReplaySeed(seed) {
+  const text = String(seed || '');
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function createSeededMath(seed) {
+  if (seed == null) return Math;
+  let state = hashReplaySeed(seed);
+  if (state === 0) state = 0x6d2b79f5;
+  const nextRandom = () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const math = Object.create(Math);
+  math.random = nextRandom;
+  return math;
+}
+
+function captureStateOrThrow(runtime, seed, capturedAt = null) {
+  const result = exportSessionState(runtime, {
+    mode: 'headless',
+    seed,
+    capturedAt,
+  });
+  if (!result || typeof result !== 'object' || result.ok !== true || !result.payload) {
+    throw new ReplayError(
+      typeof result?.reasonCode === 'string' ? result.reasonCode : 'replay_state_export_failed',
+      result?.detail
+        ? `Replay state export failed: ${result.detail}`
+        : 'Replay state export failed.',
+      { stateResult: result || null },
+    );
+  }
+  return result.payload;
+}
+
+function buildCheckpoint({ step, stepIndex, runtime, payload, matchedExpectation }) {
+  return {
+    checkpointId: step.checkpointId || null,
+    label: step.label || null,
+    stepIndex,
+    frameIndex: runtime.frameIndex,
+    elapsedSeconds: runtime.elapsedSeconds,
+    fingerprint: payload.export?.fingerprint || null,
+    matchedExpectation,
+  };
+}
+
+export async function runHeadlessReplay(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const replay = normalizeReplayPayload(options.payload);
+  const runtime = await bootSessionRuntime({
+    projectRoot,
+    file: options.file,
+    width: options.width,
+    height: options.height,
+    math: createSeededMath(replay.seed),
+  });
+
+  const inputController = runtime.aura?.input?.__headless;
+  if (!inputController || typeof inputController.applyFrame !== 'function' || typeof inputController.clearFrameTransitions !== 'function') {
+    throw new ReplayError(
+      'replay_input_unavailable',
+      'Headless replay requires the headless input controller.',
+    );
+  }
+
+  let initialStateApplied = false;
+  if (replay.initialState) {
+    const applyResult = applySessionState(runtime, replay.initialState);
+    if (!applyResult || typeof applyResult !== 'object' || applyResult.ok !== true) {
+      throw new ReplayError(
+        typeof applyResult?.reasonCode === 'string' ? applyResult.reasonCode : 'replay_initial_state_apply_failed',
+        applyResult?.detail
+          ? `Replay initial state apply failed: ${applyResult.detail}`
+          : 'Replay initial state apply failed.',
+        { applyResult: applyResult || null },
+      );
+    }
+    initialStateApplied = true;
+  }
+
+  const checkpoints = [];
+  let divergence = null;
+
+  for (let index = 0; index < replay.steps.length; index += 1) {
+    const step = replay.steps[index];
+    if (step.input) {
+      inputController.applyFrame(step.input);
+    } else {
+      inputController.clearFrameTransitions();
+    }
+
+    for (let frame = 0; frame < step.frames; frame += 1) {
+      await executeFrame(runtime.aura, 1 / 60);
+      runtime.frameIndex += 1;
+      runtime.elapsedSeconds += 1 / 60;
+      if (frame < step.frames - 1) {
+        inputController.clearFrameTransitions();
+      }
+    }
+
+    const needsCheckpoint = step.checkpointId || step.expectFingerprint;
+    if (!needsCheckpoint) {
+      inputController.clearFrameTransitions();
+      continue;
+    }
+
+    const payload = captureStateOrThrow(runtime, replay.seed, null);
+    const actualFingerprint = payload.export?.fingerprint || null;
+    const matchedExpectation = step.expectFingerprint == null || step.expectFingerprint === actualFingerprint;
+    checkpoints.push(buildCheckpoint({
+      step,
+      stepIndex: index,
+      runtime,
+      payload,
+      matchedExpectation,
+    }));
+
+    if (!matchedExpectation) {
+      divergence = {
+        stepIndex: index,
+        label: step.label || null,
+        checkpointId: step.checkpointId || null,
+        expectedFingerprint: step.expectFingerprint,
+        actualFingerprint,
+        frameIndex: runtime.frameIndex,
+        elapsedSeconds: runtime.elapsedSeconds,
+      };
+      if (replay.stopOnDivergence) {
+        break;
+      }
+    }
+
+    inputController.clearFrameTransitions();
+  }
+
+  const finalState = captureStateOrThrow(runtime, replay.seed, null);
+  const completed = divergence == null;
+  const report = {
+    schemaVersion: GAME_REPLAY_REPORT_SCHEMA_VERSION,
+    ok: completed,
+    reasonCode: completed ? 'replay_ok' : 'replay_diverged',
+    replaySchemaVersion: GAME_REPLAY_SCHEMA_VERSION,
+    mode: 'headless',
+    projectRoot,
+    entryFile: runtime.entryFile,
+    seed: replay.seed,
+    initialStateApplied,
+    totalSteps: replay.steps.length,
+    executedFrames: runtime.frameIndex,
+    elapsedSeconds: runtime.elapsedSeconds,
+    finalFingerprint: finalState.export?.fingerprint || null,
+    checkpoints,
+    divergence,
+  };
+
+  return {
+    replay,
+    report,
+    finalState,
+    runtime,
+    runtimeSummary: {
+      width: runtime.width,
+      height: runtime.height,
+      framesExecuted: runtime.frameIndex,
+      elapsedSeconds: runtime.elapsedSeconds,
+      bundleOutFile: runtime.bundle.outFile,
+      moduleCount: runtime.bundle.moduleCount,
+      assertionsPassed: runtime.testState.passes,
+      drawCalls: runtime.testState.drawCalls,
+      audioCalls: runtime.testState.audioCalls,
+    },
+  };
+}
+
+export function serializeReplayReport(payload, compact = false) {
+  return compact
+    ? `${JSON.stringify(payload)}\n`
+    : `${JSON.stringify(payload, null, 2)}\n`;
+}

package/src/scaffold/config.mjs

@@ -4,9 +4,11 @@ import { fileURLToPath } from 'node:url';
 const SCAFFOLD_DIR = dirname(fileURLToPath(import.meta.url));
 const CLI_SRC_DIR = resolve(SCAFFOLD_DIR, '..');
 const CLI_PACKAGE = JSON.parse(readFileSync(resolve(CLI_SRC_DIR, '../package.json'), 'utf8'));
+export const CLI_PACKAGE_NAME = CLI_PACKAGE.name;
 const CLI_PACKAGE_VERSION = CLI_PACKAGE.version;
 
 export const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter');
+export const PACKAGED_STARTER_UTILS_DIR = resolve(CLI_SRC_DIR, './helpers/starter-utils');
 
 export const CREATE_TEMPLATE_DIRS = {
   '2d-adventure': resolve(CLI_SRC_DIR, '../templates/create/2d-adventure'),

package/src/scaffold/fs.mjs

@@ -1,3 +1,4 @@
+import { isUtf8 } from 'node:buffer';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
@@ -33,7 +34,13 @@ export function copyTree(src, dest, replacements) {
       continue;
     }
 
-    let content = readFileSync(srcPath, 'utf8');
+    const sourceBytes = readFileSync(srcPath);
+    if (!isUtf8(sourceBytes)) {
+      writeFileSync(destPath, sourceBytes);
+      continue;
+    }
+
+    let content = sourceBytes.toString('utf8');
     for (const [key, value] of Object.entries(replacements)) {
       content = content.replaceAll(`{{${key}}}`, value);
     }