@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/self-hosted-assets.mjs

@@ -0,0 +1,604 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const SELF_HOSTED_RELEASE_SCHEMA = 'aurajs.external-assets-release.v1';
+export const SELF_HOSTED_ASSETS_SCHEMA = 'aurajs.external-assets-manifest.v1';
+export const SELF_HOSTED_PLAN_SCHEMA = 'aurajs.external-assets-plan.v1';
+export const SELF_HOSTED_CONFIG_SCHEMA = 'aurajs.external-assets-config.v1';
+
+export class SelfHostedAssetsError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'SelfHostedAssetsError';
+    this.reasonCode = typeof reasonCode === 'string' && reasonCode
+      ? reasonCode
+      : 'external_assets_failed';
+    this.details = details && typeof details === 'object' ? details : {};
+  }
+}
+
+function currentPlatformTarget() {
+  if (process.platform === 'win32') return 'windows';
+  if (process.platform === 'darwin') return 'mac';
+  return 'linux';
+}
+
+function readJsonFile(path, label) {
+  if (!existsSync(path)) {
+    throw new SelfHostedAssetsError(
+      'external_assets_file_missing',
+      `${label} not found: ${path}`,
+      { path, label },
+    );
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new SelfHostedAssetsError(
+      'external_assets_json_parse_failed',
+      `Unable to parse ${label} at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { path, label },
+    );
+  }
+}
+
+function normalizeSlug(value, label) {
+  const normalized = String(value || '').trim().toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!normalized) {
+    throw new SelfHostedAssetsError(
+      'external_assets_invalid_input',
+      `${label} must resolve to a non-empty slug.`,
+      { label, value },
+    );
+  }
+  return normalized;
+}
+
+function normalizeRelease(value, fallback = '0.1.0') {
+  const normalized = String(value || fallback).trim();
+  if (!normalized) {
+    throw new SelfHostedAssetsError(
+      'external_assets_invalid_input',
+      'release must be a non-empty string.',
+      { value },
+    );
+  }
+  return normalized;
+}
+
+function normalizeChannel(value) {
+  const normalized = String(value || 'latest').trim();
+  if (!normalized) {
+    throw new SelfHostedAssetsError(
+      'external_assets_invalid_input',
+      'channel must be a non-empty string.',
+      { value },
+    );
+  }
+  return normalized;
+}
+
+function normalizePublicBaseUrl(value) {
+  const normalized = String(value || '').trim().replace(/\/+$/g, '');
+  if (!normalized) {
+    throw new SelfHostedAssetsError(
+      'external_assets_public_base_url_missing',
+      'external-assets generate requires --public-base-url <url>.',
+    );
+  }
+  let url;
+  try {
+    url = new URL(normalized);
+  } catch (error) {
+    throw new SelfHostedAssetsError(
+      'external_assets_public_base_url_invalid',
+      `Invalid --public-base-url: ${error instanceof Error ? error.message : String(error)}`,
+      { value: normalized },
+    );
+  }
+  if (url.protocol !== 'https:') {
+    throw new SelfHostedAssetsError(
+      'external_assets_public_base_url_invalid',
+      '--public-base-url must use https:// for the self-hosted public lane.',
+      { value: normalized },
+    );
+  }
+  return normalized;
+}
+
+function resolveBuildDir(projectRoot, buildDir) {
+  if (buildDir) return resolve(projectRoot, buildDir);
+  return resolve(projectRoot, 'build', currentPlatformTarget());
+}
+
+function sha256File(path) {
+  const hash = createHash('sha256');
+  hash.update(readFileSync(path));
+  return hash.digest('hex');
+}
+
+function toPosix(pathLike) {
+  return String(pathLike || '').replace(/\\/g, '/');
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function ensureBuildManifest(buildManifestPath) {
+  const manifest = readJsonFile(buildManifestPath, 'AuraJS build manifest');
+  if (manifest?.schema !== 'aurajs.build-manifest.v1') {
+    throw new SelfHostedAssetsError(
+      'external_assets_build_manifest_unsupported',
+      `Expected aurajs.build-manifest.v1 at ${buildManifestPath}. Run "aura build" for a native target first.`,
+      { buildManifestPath },
+    );
+  }
+  return manifest;
+}
+
+function ensureAssetsManifest(assetsManifestPath) {
+  const manifest = readJsonFile(assetsManifestPath, 'AuraJS assets manifest');
+  if (manifest?.schema !== 'aurajs.asset-manifest.v1') {
+    throw new SelfHostedAssetsError(
+      'external_assets_assets_manifest_unsupported',
+      `Expected aurajs.asset-manifest.v1 at ${assetsManifestPath}.`,
+      { assetsManifestPath },
+    );
+  }
+  return manifest;
+}
+
+function copyBlobIntoStage({ sourcePath, payloadRoot, sha256 }) {
+  const blobKey = `blobs/sha256/${sha256.slice(0, 2)}/${sha256}`;
+  const destPath = resolve(payloadRoot, ...blobKey.split('/'));
+  if (!existsSync(destPath)) {
+    mkdirSync(dirname(destPath), { recursive: true });
+    copyFileSync(sourcePath, destPath);
+  }
+  return { blobKey, destPath };
+}
+
+function createUploadRecord({ kind, sourcePath, key, url, sizeBytes, sha256 = null }) {
+  return {
+    kind,
+    sourcePath,
+    key,
+    url,
+    sizeBytes,
+    sha256,
+  };
+}
+
+function parseLongOptions(args) {
+  const options = { _: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index] || '');
+    if (!token.startsWith('--')) {
+      options._.push(token);
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token.includes('=')) {
+      const [rawKey, ...rest] = token.slice(2).split('=');
+      options[rawKey] = rest.join('=');
+      continue;
+    }
+    const key = token.slice(2);
+    const value = String(args[index + 1] || '').trim();
+    if (!value) {
+      throw new SelfHostedAssetsError(
+        'external_assets_invalid_args',
+        `${token} requires a value.`,
+      );
+    }
+    options[key] = value;
+    index += 1;
+  }
+  return options;
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function printHelp() {
+  console.log(`
+  aura external-assets generate --public-base-url <url> [options]
+
+  Generate provider-neutral self-hosted asset metadata for a built AuraJS game.
+
+  Generate options:
+    --public-base-url <url>    Public HTTPS base URL where manifests + blobs will live
+    --build-dir <path>         Build output directory (default: build/<current-platform>)
+    --project <slug>           Project slug (default: build-manifest identity.executableBaseName)
+    --release <version>        Release version (default: build-manifest identity.version)
+    --channel <name>           Release channel (default: latest)
+    --stage-dir <path>         Override local staging directory
+    --config-path <path>       Override generated aura.external-assets.json path
+    --json                     Emit machine-readable command output
+  `.trimStart());
+}
+
+function printGenerateSummary(plan) {
+  console.log('\n  aura external-assets: staged self-hosted asset metadata.');
+  console.log(`  Project: ${plan.project}`);
+  console.log(`  Release: ${plan.release}`);
+  console.log(`  Channel: ${plan.channel}`);
+  console.log(`  Build dir: ${plan.buildDir}`);
+  console.log(`  Stage dir: ${plan.stageDir}`);
+  console.log(`  Public base URL: ${plan.publicBaseUrl}`);
+  console.log(`  Provider: ${plan.provider}`);
+  console.log(`  Unique blobs: ${plan.uniqueBlobCount}`);
+  console.log(`  Blob bytes: ${plan.totalBlobBytes}`);
+  console.log(`  Upload records: ${plan.uploads.length}`);
+  console.log(`  Plan: ${plan.publishPlanPath}`);
+  console.log(`  Config: ${plan.configPath}`);
+  console.log('');
+  console.log('  Staged manifests:');
+  console.log(`    build:   ${plan.manifests.buildManifestPath}`);
+  console.log(`    assets:  ${plan.manifests.assetsManifestPath}`);
+  console.log(`    release: ${plan.manifests.releaseManifestPath}`);
+  console.log('');
+}
+
+export function stageSelfHostedAssets(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const buildDir = resolveBuildDir(projectRoot, options.buildDir);
+  const buildManifestPath = resolve(buildDir, 'build-manifest.json');
+  const buildManifest = ensureBuildManifest(buildManifestPath);
+  const assetsManifestPath = resolve(buildDir, buildManifest.assetsManifest);
+  const assetsManifest = ensureAssetsManifest(assetsManifestPath);
+  const publicBaseUrl = normalizePublicBaseUrl(options.publicBaseUrl);
+
+  const project = normalizeSlug(
+    options.project
+      || buildManifest?.identity?.executableBaseName
+      || basename(projectRoot),
+    'project',
+  );
+  const release = normalizeRelease(
+    options.release || buildManifest?.identity?.version || '0.1.0',
+  );
+  const channel = normalizeChannel(options.channel);
+  const stageNamespace = options.stageNamespace || 'external-assets';
+  const stageDir = resolve(options.stageDir || join(projectRoot, '.aura', stageNamespace, project, release));
+  const payloadRoot = resolve(stageDir, 'payload');
+  const releasePrefix = `releases/${project}/${release}`;
+  const releaseRoot = resolve(payloadRoot, ...releasePrefix.split('/'));
+  const createdAt = new Date().toISOString();
+  const provider = String(options.provider || 'self-hosted').trim() || 'self-hosted';
+  const schemas = {
+    release: options.schemas?.release || SELF_HOSTED_RELEASE_SCHEMA,
+    assets: options.schemas?.assets || SELF_HOSTED_ASSETS_SCHEMA,
+    plan: options.schemas?.plan || SELF_HOSTED_PLAN_SCHEMA,
+    config: options.schemas?.config || SELF_HOSTED_CONFIG_SCHEMA,
+  };
+  const storage = {
+    publicBaseUrl,
+    releasePrefix,
+    blobPrefix: 'blobs/sha256',
+    ...(options.storageExtra && typeof options.storageExtra === 'object' ? options.storageExtra : {}),
+  };
+
+  const blobUploads = [];
+  const uniqueBlobs = new Map();
+  const createBlobDescriptor = (sourcePath) => {
+    const stats = statSync(sourcePath);
+    const sha256 = sha256File(sourcePath);
+    const cached = uniqueBlobs.get(sha256);
+    if (cached) {
+      return cached;
+    }
+    const copied = copyBlobIntoStage({ sourcePath, payloadRoot, sha256 });
+    const descriptor = {
+      sha256,
+      sizeBytes: stats.size,
+      blobKey: copied.blobKey,
+      blobUrl: `${publicBaseUrl}/${copied.blobKey}`,
+      stagedPath: copied.destPath,
+      sourcePath,
+    };
+    uniqueBlobs.set(sha256, descriptor);
+    blobUploads.push(createUploadRecord({
+      kind: 'blob',
+      sourcePath: copied.destPath,
+      key: copied.blobKey,
+      url: descriptor.blobUrl,
+      sizeBytes: descriptor.sizeBytes,
+      sha256,
+    }));
+    return descriptor;
+  };
+
+  let publicAssetsManifest;
+  if (assetsManifest.mode === 'embed') {
+    const packFile = assetsManifest?.pack?.file;
+    if (!packFile) {
+      throw new SelfHostedAssetsError(
+        'external_assets_pack_missing',
+        `Embedded assets manifest at ${assetsManifestPath} is missing pack.file`,
+        { assetsManifestPath },
+      );
+    }
+    const packSourcePath = resolve(buildDir, packFile);
+    const packBlob = createBlobDescriptor(packSourcePath);
+    publicAssetsManifest = {
+      schema: schemas.assets,
+      createdAt,
+      provider,
+      project,
+      release,
+      channel,
+      sourceSchema: assetsManifest.schema,
+      sourceManifestHash: assetsManifest.manifestHash || null,
+      assetMode: assetsManifest.mode,
+      runtimeResolver: assetsManifest.runtimeResolver || buildManifest.runtimeResolver || null,
+      storage,
+      pack: {
+        ...assetsManifest.pack,
+        sha256: packBlob.sha256,
+        blobKey: packBlob.blobKey,
+        blobUrl: packBlob.blobUrl,
+      },
+      entries: Array.isArray(assetsManifest.entries)
+        ? assetsManifest.entries.map((entry) => ({
+          ...entry,
+          packBlobKey: packBlob.blobKey,
+          packBlobUrl: packBlob.blobUrl,
+        }))
+        : [],
+    };
+  } else if (assetsManifest.mode === 'sibling') {
+    publicAssetsManifest = {
+      schema: schemas.assets,
+      createdAt,
+      provider,
+      project,
+      release,
+      channel,
+      sourceSchema: assetsManifest.schema,
+      sourceManifestHash: assetsManifest.manifestHash || null,
+      assetMode: assetsManifest.mode,
+      runtimeResolver: assetsManifest.runtimeResolver || buildManifest.runtimeResolver || null,
+      storage,
+      entries: Array.isArray(assetsManifest.entries)
+        ? assetsManifest.entries.map((entry) => {
+          const sourceFile = entry.file || `assets/${entry.path}`;
+          const sourcePath = resolve(buildDir, sourceFile);
+          const blob = createBlobDescriptor(sourcePath);
+          return {
+            path: entry.path,
+            kind: entry.kind,
+            sizeBytes: entry.sizeBytes,
+            sha1: entry.sha1 || null,
+            sha256: blob.sha256,
+            sourceFile: toPosix(sourceFile),
+            blobKey: blob.blobKey,
+            blobUrl: blob.blobUrl,
+          };
+        })
+        : [],
+    };
+  } else {
+    throw new SelfHostedAssetsError(
+      'external_assets_asset_mode_unsupported',
+      `Unsupported asset mode "${assetsManifest.mode}". Expected "embed" or "sibling".`,
+      { mode: assetsManifest.mode },
+    );
+  }
+
+  const publicAssetsManifestPath = resolve(releaseRoot, 'assets-manifest.json');
+  writeJson(publicAssetsManifestPath, publicAssetsManifest);
+
+  const releaseManifestUrl = `${publicBaseUrl}/${releasePrefix}/release.json`;
+  const assetsManifestUrl = `${publicBaseUrl}/${releasePrefix}/assets-manifest.json`;
+  const publicBuildManifest = {
+    ...buildManifest,
+    distribution: {
+      mode: options.distributionMode || 'npm+self-hosted-assets',
+      provider,
+      project,
+      release,
+      channel,
+      releaseManifestUrl,
+      assetsManifestUrl,
+      ...(options.buildManifestDistributionExtra && typeof options.buildManifestDistributionExtra === 'object'
+        ? options.buildManifestDistributionExtra
+        : {}),
+    },
+  };
+  const publicBuildManifestPath = resolve(releaseRoot, 'build-manifest.json');
+  writeJson(publicBuildManifestPath, publicBuildManifest);
+
+  const releaseManifest = {
+    schema: schemas.release,
+    createdAt,
+    mode: options.planMode || 'stage-only-self-hosted',
+    provider,
+    project,
+    release,
+    channel,
+    buildDir,
+    storage,
+    manifests: {
+      build: {
+        key: `${releasePrefix}/build-manifest.json`,
+        url: `${publicBaseUrl}/${releasePrefix}/build-manifest.json`,
+      },
+      assets: {
+        key: `${releasePrefix}/assets-manifest.json`,
+        url: assetsManifestUrl,
+      },
+    },
+    blobSummary: {
+      uniqueBlobCount: uniqueBlobs.size,
+      totalBlobBytes: [...uniqueBlobs.values()].reduce((sum, entry) => sum + entry.sizeBytes, 0),
+      assetMode: assetsManifest.mode,
+    },
+    notes: Array.isArray(options.releaseNotes) ? options.releaseNotes : [],
+  };
+  const releaseManifestPath = resolve(releaseRoot, 'release.json');
+  writeJson(releaseManifestPath, releaseManifest);
+
+  const manifestUploads = [
+    createUploadRecord({
+      kind: 'manifest',
+      sourcePath: publicBuildManifestPath,
+      key: `${releasePrefix}/build-manifest.json`,
+      url: `${publicBaseUrl}/${releasePrefix}/build-manifest.json`,
+      sizeBytes: statSync(publicBuildManifestPath).size,
+    }),
+    createUploadRecord({
+      kind: 'manifest',
+      sourcePath: publicAssetsManifestPath,
+      key: `${releasePrefix}/assets-manifest.json`,
+      url: assetsManifestUrl,
+      sizeBytes: statSync(publicAssetsManifestPath).size,
+    }),
+    createUploadRecord({
+      kind: 'manifest',
+      sourcePath: releaseManifestPath,
+      key: `${releasePrefix}/release.json`,
+      url: releaseManifestUrl,
+      sizeBytes: statSync(releaseManifestPath).size,
+    }),
+  ];
+
+  const configPath = resolve(options.configPath || join(projectRoot, options.configFilename || 'aura.external-assets.json'));
+  const config = {
+    schema: schemas.config,
+    mode: options.configMode || 'self-hosted',
+    project,
+    release,
+    channel,
+    provider,
+    releaseManifestUrl,
+    assetsManifestUrl,
+    generatedAt: createdAt,
+    ...(options.configExtra && typeof options.configExtra === 'object' ? options.configExtra : {}),
+  };
+  writeJson(configPath, config);
+
+  const publishPlan = {
+    schema: schemas.plan,
+    createdAt,
+    provider,
+    mode: options.planMode || 'stage-only-self-hosted',
+    project,
+    release,
+    channel,
+    projectRoot,
+    buildDir,
+    stageDir,
+    configPath,
+    summary: {
+      assetMode: assetsManifest.mode,
+      uniqueBlobCount: uniqueBlobs.size,
+      manifestCount: manifestUploads.length,
+      totalUploadBytes: [...blobUploads, ...manifestUploads].reduce((sum, entry) => sum + entry.sizeBytes, 0),
+    },
+    uploads: [...manifestUploads, ...blobUploads],
+    nextSteps: Array.isArray(options.planNextSteps) && options.planNextSteps.length > 0
+      ? options.planNextSteps
+      : [
+        'Verify the staged release metadata under the stageDir.',
+        'Upload manifests to releases/<project>/<release>/ at the public base URL origin.',
+        'Upload all referenced blob keys under blobs/sha256/<prefix>/<sha256>.',
+        'Publish the slim npm package only after the generated aura.external-assets.json is present.',
+      ],
+    ...(options.planExtra && typeof options.planExtra === 'object' ? options.planExtra : {}),
+  };
+  const publishPlanPath = resolve(stageDir, 'publish-plan.json');
+  writeJson(publishPlanPath, publishPlan);
+
+  return {
+    publishPlanPath,
+    stageDir,
+    buildDir,
+    project,
+    release,
+    channel,
+    publicBaseUrl,
+    provider,
+    uniqueBlobCount: uniqueBlobs.size,
+    totalBlobBytes: releaseManifest.blobSummary.totalBlobBytes,
+    uploads: publishPlan.uploads,
+    manifests: {
+      buildManifestPath: publicBuildManifestPath,
+      assetsManifestPath: publicAssetsManifestPath,
+      releaseManifestPath,
+    },
+    configPath,
+  };
+}
+
+function runGenerate(options) {
+  const plan = stageSelfHostedAssets({
+    projectRoot: process.cwd(),
+    buildDir: options['build-dir'] || null,
+    project: options.project || null,
+    release: options.release || null,
+    channel: options.channel || null,
+    stageDir: options['stage-dir'] || null,
+    publicBaseUrl: options['public-base-url'] || null,
+    configPath: options['config-path'] || null,
+  });
+
+  if (options.json) {
+    printJson({
+      ok: true,
+      reasonCode: 'external_assets_generate_staged',
+      publishPlanPath: plan.publishPlanPath,
+      stageDir: plan.stageDir,
+      project: plan.project,
+      release: plan.release,
+      channel: plan.channel,
+      publicBaseUrl: plan.publicBaseUrl,
+      provider: plan.provider,
+      uniqueBlobCount: plan.uniqueBlobCount,
+      totalBlobBytes: plan.totalBlobBytes,
+      uploadCount: plan.uploads.length,
+      manifests: plan.manifests,
+      configPath: plan.configPath,
+    });
+    return;
+  }
+
+  printGenerateSummary(plan);
+}
+
+export async function runExternalAssetsCommand(args = []) {
+  const [firstArg, ...restArgs] = args;
+  if (!firstArg || firstArg === 'generate') {
+    runGenerate(parseLongOptions(firstArg ? restArgs : args));
+    return;
+  }
+  if (firstArg === '--help' || firstArg === '-h' || firstArg === 'help') {
+    printHelp();
+    return;
+  }
+  if (firstArg.startsWith('--')) {
+    runGenerate(parseLongOptions(args));
+    return;
+  }
+  throw new SelfHostedAssetsError(
+    'external_assets_invalid_args',
+    `Unknown external-assets subcommand "${firstArg}". Supported subcommands: generate.`,
+  );
+}