@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/external-asset-policy.mjs

@@ -0,0 +1,217 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const ASSET_MANIFEST_SCHEMA = 'aurajs.asset-manifest.v1';
+export const DEFAULT_PUBLISH_ASSET_THRESHOLD_BYTES = 50 * 1024 * 1024;
+export const PUBLISH_ASSET_THRESHOLD_ENV = 'AURA_PUBLISH_ASSET_THRESHOLD_BYTES';
+export const SELF_HOSTED_EXTERNAL_ASSETS_CONFIG = 'aura.external-assets.json';
+
+function formatUnit(value, unit) {
+  const rounded = value >= 10 ? Math.round(value) : Math.round(value * 10) / 10;
+  return `${rounded} ${unit}`;
+}
+
+export function formatBytes(bytes) {
+  const normalized = Number.isFinite(bytes) && bytes >= 0 ? bytes : 0;
+  if (normalized < 1024) return `${normalized} B`;
+  if (normalized < (1024 * 1024)) return formatUnit(normalized / 1024, 'KiB');
+  if (normalized < (1024 * 1024 * 1024)) return formatUnit(normalized / (1024 * 1024), 'MiB');
+  return formatUnit(normalized / (1024 * 1024 * 1024), 'GiB');
+}
+
+export function resolvePublishAssetThresholdBytes(env = process.env) {
+  const raw = String(env?.[PUBLISH_ASSET_THRESHOLD_ENV] || '').trim();
+  if (!raw) {
+    return {
+      bytes: DEFAULT_PUBLISH_ASSET_THRESHOLD_BYTES,
+      source: 'default',
+      raw: null,
+    };
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      bytes: DEFAULT_PUBLISH_ASSET_THRESHOLD_BYTES,
+      source: 'default_invalid_env',
+      raw,
+    };
+  }
+
+  return {
+    bytes: parsed,
+    source: 'env',
+    raw,
+  };
+}
+
+function sumDirectoryBytes(root) {
+  if (!existsSync(root)) {
+    return 0;
+  }
+
+  const stats = statSync(root);
+  if (!stats.isDirectory()) {
+    return stats.size;
+  }
+
+  let total = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of readdirSync(current)) {
+      const fullPath = join(current, entry);
+      const entryStats = statSync(fullPath);
+      if (entryStats.isDirectory()) {
+        stack.push(fullPath);
+      } else {
+        total += entryStats.size;
+      }
+    }
+  }
+  return total;
+}
+
+function parseSelfHostedExternalAssetsConfig(projectRoot) {
+  const configPath = resolve(projectRoot, SELF_HOSTED_EXTERNAL_ASSETS_CONFIG);
+  if (!existsSync(configPath)) {
+    return {
+      present: false,
+      valid: false,
+      path: configPath,
+      schema: null,
+      mode: null,
+      releaseManifestUrl: null,
+    };
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    const releaseManifestUrl = typeof parsed?.releaseManifestUrl === 'string'
+      ? parsed.releaseManifestUrl.trim()
+      : '';
+    return {
+      present: true,
+      valid: parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed),
+      path: configPath,
+      schema: typeof parsed?.schema === 'string' ? parsed.schema : null,
+      mode: typeof parsed?.mode === 'string' ? parsed.mode : null,
+      releaseManifestUrl: releaseManifestUrl || null,
+    };
+  } catch {
+    return {
+      present: true,
+      valid: false,
+      path: configPath,
+      schema: null,
+      mode: null,
+      releaseManifestUrl: null,
+    };
+  }
+}
+
+function resolveBuildAssetBytes(buildRoot, assetsManifestPath, assetsManifest) {
+  if (!assetsManifest || typeof assetsManifest !== 'object') {
+    return {
+      bytes: 0,
+      source: 'assets_manifest_missing',
+    };
+  }
+
+  if (assetsManifest.mode === 'embed') {
+    const packSize = Number.isFinite(assetsManifest?.pack?.sizeBytes)
+      ? assetsManifest.pack.sizeBytes
+      : null;
+    if (packSize !== null) {
+      return {
+        bytes: packSize,
+        source: 'assets_manifest_pack_size',
+      };
+    }
+
+    const packFile = typeof assetsManifest?.pack?.file === 'string' ? assetsManifest.pack.file : null;
+    if (packFile) {
+      const packPath = resolve(buildRoot, packFile);
+      if (existsSync(packPath)) {
+        return {
+          bytes: statSync(packPath).size,
+          source: 'pack_file_stat',
+        };
+      }
+    }
+  }
+
+  if (Array.isArray(assetsManifest.entries)) {
+    const bytes = assetsManifest.entries.reduce((total, entry) => {
+      const size = Number.isFinite(entry?.sizeBytes) ? entry.sizeBytes : 0;
+      return total + size;
+    }, 0);
+    return {
+      bytes,
+      source: 'assets_manifest_entries',
+    };
+  }
+
+  if (existsSync(assetsManifestPath)) {
+    return {
+      bytes: statSync(assetsManifestPath).size,
+      source: 'assets_manifest_file_only',
+    };
+  }
+
+  return {
+    bytes: 0,
+    source: 'assets_manifest_missing',
+  };
+}
+
+export function evaluateExternalAssetPolicy({
+  projectRoot,
+  buildRoot,
+  assetsManifestPath,
+  assetsManifest,
+  assetDir = 'assets',
+  env = process.env,
+} = {}) {
+  const threshold = resolvePublishAssetThresholdBytes(env);
+  const assetRoot = resolve(projectRoot, assetDir || 'assets');
+  const sourceAssetBytes = sumDirectoryBytes(assetRoot);
+  const buildAssetMeasurement = resolveBuildAssetBytes(buildRoot, assetsManifestPath, assetsManifest);
+  const buildAssetBytes = buildAssetMeasurement.bytes;
+  const measuredAssetBytes = buildAssetBytes > 0 ? buildAssetBytes : sourceAssetBytes;
+  const externalConfig = parseSelfHostedExternalAssetsConfig(projectRoot);
+  const overThreshold = measuredAssetBytes > threshold.bytes;
+  const hasSelfHostedConfig = externalConfig.present && externalConfig.valid;
+  const blocked = overThreshold && !hasSelfHostedConfig;
+  const recommendedAction = blocked
+    ? 'self_host_assets_then_generate_config'
+    : (overThreshold
+        ? 'publish_with_self_hosted_external_assets'
+        : 'publish_with_embedded_assets');
+  const recommendedNextStep = blocked
+    ? 'Upload large assets to your own CDN or object storage such as Cloudflare R2 or S3, then generate aura.external-assets.json before publishing.'
+    : (overThreshold
+        ? 'Self-hosted external asset config detected. Keep the package slim and verify packaged runtime hydration before publishing.'
+        : 'Asset payload is within the npm-first threshold. npm-only publish is allowed.');
+
+  return {
+    reasonCode: blocked ? 'publish_asset_threshold_exceeded' : 'publish_asset_threshold_ok',
+    assetRoot,
+    thresholdBytes: threshold.bytes,
+    thresholdSource: threshold.source,
+    thresholdEnvValue: threshold.raw,
+    sourceAssetBytes,
+    buildAssetBytes,
+    buildAssetMeasurementSource: buildAssetMeasurement.source,
+    assetBytes: measuredAssetBytes,
+    measuredAssetBytes,
+    measuredAssetSource: buildAssetBytes > 0 ? 'build' : 'source',
+    overThreshold,
+    blocked,
+    allowed: !blocked,
+    recommendedAction,
+    recommendedNextStep,
+    hasSelfHostedConfig,
+    selfHostedConfig: externalConfig,
+  };
+}

package/src/external-package-surface.mjs

@@ -0,0 +1,206 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { SELF_HOSTED_EXTERNAL_ASSETS_CONFIG } from './external-asset-policy.mjs';
+
+export const EMBEDDED_PACKAGE_SURFACE_MODE = 'embedded_assets';
+export const SELF_HOSTED_PACKAGE_SURFACE_MODE = 'self_hosted_external_assets';
+
+function normalizeRelativePath(pathLike) {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replace(/[\\/]+/g, '/')
+    .replace(/\/+$/, '');
+}
+
+function pathWithinDirectory(candidatePath, directoryPath) {
+  const normalizedCandidate = normalizeRelativePath(candidatePath);
+  const normalizedDirectory = normalizeRelativePath(directoryPath);
+  if (!normalizedCandidate || !normalizedDirectory) {
+    return false;
+  }
+  return normalizedCandidate === normalizedDirectory || normalizedCandidate.startsWith(`${normalizedDirectory}/`);
+}
+
+function shouldCopyPath(sourcePath, {
+  projectRoot,
+  assetDir,
+  excludeAssetDir = false,
+  excludedFilePaths = [],
+} = {}) {
+  const relativePath = normalizeRelativePath(relative(projectRoot, sourcePath));
+  if (!relativePath) {
+    return true;
+  }
+
+  const topLevel = relativePath.split('/')[0];
+  if (topLevel === '.aura' || topLevel === '.git' || topLevel === 'node_modules') {
+    return false;
+  }
+
+  if (excludedFilePaths.some((entry) => relativePath === entry || relativePath.startsWith(`${entry}/`))) {
+    return false;
+  }
+
+  if (excludeAssetDir && pathWithinDirectory(relativePath, assetDir)) {
+    return false;
+  }
+
+  return true;
+}
+
+function buildSelfHostedFilesList(packageFiles, assetDir) {
+  if (!Array.isArray(packageFiles)) {
+    return null;
+  }
+
+  const filtered = [];
+  let hasExternalAssetsConfig = false;
+
+  for (const entry of packageFiles) {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      continue;
+    }
+
+    const normalizedEntry = normalizeRelativePath(entry);
+    if (normalizedEntry === normalizeRelativePath(SELF_HOSTED_EXTERNAL_ASSETS_CONFIG)) {
+      hasExternalAssetsConfig = true;
+      filtered.push(entry);
+      continue;
+    }
+
+    if (pathWithinDirectory(normalizedEntry, assetDir)) {
+      continue;
+    }
+
+    filtered.push(entry);
+  }
+
+  if (!hasExternalAssetsConfig) {
+    filtered.push(SELF_HOSTED_EXTERNAL_ASSETS_CONFIG);
+  }
+
+  return filtered;
+}
+
+export function inspectPublishPackFiles(
+  packFiles,
+  {
+    assetDir = 'assets',
+    externalAssetsConfigPath = SELF_HOSTED_EXTERNAL_ASSETS_CONFIG,
+  } = {},
+) {
+  const normalizedConfigPath = normalizeRelativePath(externalAssetsConfigPath);
+  return {
+    includesAssetPayload: packFiles.some((entry) => pathWithinDirectory(entry?.path, assetDir)),
+    includesExternalAssetsConfig: packFiles.some(
+      (entry) => normalizeRelativePath(entry?.path) === normalizedConfigPath,
+    ),
+  };
+}
+
+export function preparePublishPackageSurface({
+  projectRoot,
+  projectPackage,
+  assetDir = 'assets',
+  assetPolicy = null,
+  generatedFilePaths = [],
+  generatedFiles = [],
+  excludedFilePaths = [],
+} = {}) {
+  const normalizedAssetDir = normalizeRelativePath(assetDir || 'assets') || 'assets';
+  const normalizedGeneratedFilePaths = [...new Set(
+    (Array.isArray(generatedFilePaths) ? generatedFilePaths : [])
+      .map((entry) => normalizeRelativePath(entry))
+      .filter(Boolean),
+  )];
+  const normalizedGeneratedFiles = (Array.isArray(generatedFiles) ? generatedFiles : [])
+    .map((entry) => {
+      const relativePath = normalizeRelativePath(entry?.path);
+      if (!relativePath) {
+        return null;
+      }
+      return {
+        path: relativePath,
+        contents: String(entry?.contents ?? ''),
+      };
+    })
+    .filter(Boolean);
+  const normalizedExcludedFilePaths = [...new Set(
+    (Array.isArray(excludedFilePaths) ? excludedFilePaths : [])
+      .map((entry) => normalizeRelativePath(entry))
+      .filter(Boolean),
+  )];
+  const allGeneratedFilePaths = [...new Set([
+    ...normalizedGeneratedFilePaths,
+    ...normalizedGeneratedFiles.map((entry) => entry.path),
+  ])];
+  const usingSelfHostedSurface = assetPolicy?.hasSelfHostedConfig === true;
+  const configPath = resolve(projectRoot, SELF_HOSTED_EXTERNAL_ASSETS_CONFIG);
+  const shouldStagePublishSurface = usingSelfHostedSurface
+    || allGeneratedFilePaths.length > 0
+    || normalizedExcludedFilePaths.length > 0;
+
+  if (!shouldStagePublishSurface) {
+    return {
+      mode: EMBEDDED_PACKAGE_SURFACE_MODE,
+      publishRoot: projectRoot,
+      assetDir: normalizedAssetDir,
+      externalAssetsConfigPath: SELF_HOSTED_EXTERNAL_ASSETS_CONFIG,
+      cleanup() {},
+    };
+  }
+
+  if (usingSelfHostedSurface && !existsSync(configPath)) {
+    throw new Error(
+      `Self-hosted asset package surface requires ${SELF_HOSTED_EXTERNAL_ASSETS_CONFIG} in the project root.`,
+    );
+  }
+
+  const publishRoot = mkdtempSync(join(tmpdir(), 'aurajs-publish-surface-'));
+  cpSync(projectRoot, publishRoot, {
+    recursive: true,
+    filter: (sourcePath) => shouldCopyPath(sourcePath, {
+      projectRoot,
+      assetDir: normalizedAssetDir,
+      excludeAssetDir: usingSelfHostedSurface,
+      excludedFilePaths: normalizedExcludedFilePaths,
+    }),
+  });
+
+  const surfacePackagePath = resolve(publishRoot, 'package.json');
+  const surfacePackage = JSON.parse(readFileSync(surfacePackagePath, 'utf8'));
+  const nextFiles = usingSelfHostedSurface
+    ? buildSelfHostedFilesList(
+      Array.isArray(projectPackage?.files) ? projectPackage.files : surfacePackage.files,
+      normalizedAssetDir,
+    )
+    : (Array.isArray(projectPackage?.files) ? [...projectPackage.files] : (Array.isArray(surfacePackage.files) ? [...surfacePackage.files] : null));
+  if (Array.isArray(nextFiles)) {
+    for (const generatedFilePath of allGeneratedFilePaths) {
+      if (!nextFiles.includes(generatedFilePath)) {
+        nextFiles.push(generatedFilePath);
+      }
+    }
+    surfacePackage.files = nextFiles;
+    writeFileSync(surfacePackagePath, `${JSON.stringify(surfacePackage, null, 2)}\n`, 'utf8');
+  }
+
+  for (const generatedFile of normalizedGeneratedFiles) {
+    const outputPath = resolve(publishRoot, generatedFile.path);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, generatedFile.contents, 'utf8');
+  }
+
+  return {
+    mode: usingSelfHostedSurface ? SELF_HOSTED_PACKAGE_SURFACE_MODE : EMBEDDED_PACKAGE_SURFACE_MODE,
+    publishRoot,
+    assetDir: normalizedAssetDir,
+    externalAssetsConfigPath: SELF_HOSTED_EXTERNAL_ASSETS_CONFIG,
+    cleanup() {
+      rmSync(publishRoot, { recursive: true, force: true });
+    },
+  };
+}