@auraindustry/aurajs 0.0.7 → 0.1.1

package/src/publish-validation.mjs

@@ -0,0 +1,708 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { assertProjectBinIntegrity, DEFAULT_AURAJS_PACKAGE_ROOT } from './bin-integrity.mjs';
+import { BUILD_MANIFEST_SCHEMA } from './build-contract.mjs';
+import { loadConfig } from './config.mjs';
+import {
+  ASSET_MANIFEST_SCHEMA,
+  evaluateExternalAssetPolicy,
+} from './external-asset-policy.mjs';
+import {
+  inspectPublishPackFiles,
+  preparePublishPackageSurface,
+  SELF_HOSTED_PACKAGE_SURFACE_MODE,
+} from './external-package-surface.mjs';
+import {
+  PACKAGE_INTEGRITY_MANIFEST_PATH,
+  PACKAGE_INTEGRITY_PUBLISH_FILES,
+  PACKAGE_INTEGRITY_SIGNATURE_PATH,
+  writeSignedPackageIntegrityArtifacts,
+} from './package-integrity.mjs';
+import {
+  PUBLISH_ENV_EXAMPLE_PATH,
+  PUBLISH_SOURCE_ENV_PATH,
+  resolvePublishEnvExampleSurface,
+} from './publish-env-example.mjs';
+
+export const PUBLISH_REPORT_SCHEMA = 'aurajs.publish-report.v1';
+const CLI_ENTRY_PATH = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+const AURAJS_PACKAGE_VERSION = JSON.parse(readFileSync(resolve(DEFAULT_AURAJS_PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+
+export class PublishValidationError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'PublishValidationError';
+    this.reasonCode = typeof reasonCode === 'string' && reasonCode.length > 0
+      ? reasonCode
+      : 'publish_validation_failed';
+    this.details = details && typeof details === 'object' ? details : {};
+    this.reportPath = null;
+    this.report = null;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function resolveNpmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function currentPlatformTarget() {
+  if (process.platform === 'win32') return 'windows';
+  if (process.platform === 'darwin') return 'mac';
+  return 'linux';
+}
+
+function pipeChildStream(stream, target, sink) {
+  if (!stream) return;
+  stream.on('data', (chunk) => {
+    const text = String(chunk);
+    sink.push(text);
+    target?.write?.(chunk);
+  });
+}
+
+function runChildProcess(command, args, {
+  cwd,
+  env,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  failureReasonCode,
+  failureMessage,
+} = {}) {
+  return new Promise((resolveRun, rejectRun) => {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    pipeChildStream(child.stdout, stdout, stdoutChunks);
+    pipeChildStream(child.stderr, stderr, stderrChunks);
+
+    child.on('error', (error) => {
+      rejectRun(new PublishValidationError(
+        failureReasonCode,
+        `${failureMessage}: ${error.message}`,
+        {
+          command,
+          args,
+          cwd,
+        },
+      ));
+    });
+
+    child.on('close', (code, signal) => {
+      if ((code ?? 1) === 0) {
+        resolveRun({
+          ok: true,
+          code: 0,
+          signal: signal ?? null,
+          stdout: stdoutChunks.join(''),
+          stderr: stderrChunks.join(''),
+        });
+        return;
+      }
+
+      rejectRun(new PublishValidationError(
+        failureReasonCode,
+        signal
+          ? `${failureMessage}: process exited by signal ${signal}.`
+          : `${failureMessage}: process exited with code ${code ?? 1}.`,
+        {
+          command,
+          args,
+          cwd,
+          code: code ?? 1,
+          signal: signal ?? null,
+          stdout: stdoutChunks.join(''),
+          stderr: stderrChunks.join(''),
+        },
+      ));
+    });
+  });
+}
+
+function readProjectPackage(projectRoot) {
+  const packagePath = resolve(projectRoot, 'package.json');
+  if (!existsSync(packagePath)) {
+    throw new PublishValidationError(
+      'publish_package_json_missing',
+      'aura publish requires a package.json in the current project root.',
+      { packagePath },
+    );
+  }
+
+  let projectPackage;
+  try {
+    projectPackage = JSON.parse(readFileSync(packagePath, 'utf8'));
+  } catch (error) {
+    throw new PublishValidationError(
+      'publish_package_json_invalid',
+      `Failed to read package.json for aura publish: ${error.message}`,
+      { packagePath },
+    );
+  }
+
+  const packageName = typeof projectPackage?.name === 'string' && projectPackage.name.trim().length > 0
+    ? projectPackage.name.trim()
+    : null;
+  if (!packageName) {
+    throw new PublishValidationError(
+      'publish_package_name_missing',
+      'aura publish requires package.json -> name to be set.',
+      { packagePath },
+    );
+  }
+
+  const packageVersion = typeof projectPackage?.version === 'string' && projectPackage.version.trim().length > 0
+    ? projectPackage.version.trim()
+    : null;
+  if (!packageVersion) {
+    throw new PublishValidationError(
+      'publish_package_version_missing',
+      'aura publish requires package.json -> version to be set.',
+      { packagePath },
+    );
+  }
+
+  return {
+    packagePath,
+    projectPackage,
+    packageName,
+    packageVersion,
+  };
+}
+
+function normalizeBinEntries(projectPackage, packageName) {
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return [{
+      name: packageName.split('/').pop() || packageName,
+      relativePath: normalizeRelativePath(projectPackage.bin.trim()),
+    }];
+  }
+
+  const entries = Object.entries(projectPackage?.bin || {})
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([name, value]) => ({
+      name,
+      relativePath: normalizeRelativePath(value.trim()),
+    }));
+
+  if (entries.length === 0) {
+    throw new PublishValidationError(
+      'publish_bin_missing',
+      'aura publish requires package.json -> bin to point at the generated wrapper entrypoint.',
+      {},
+    );
+  }
+
+  return entries;
+}
+
+function normalizeRelativePath(pathLike) {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replaceAll('\\', '/');
+}
+
+function assertRequiredFileExists(projectRoot, relativePath, reasonCode, message) {
+  const absolutePath = resolve(projectRoot, relativePath);
+  if (!existsSync(absolutePath)) {
+    throw new PublishValidationError(reasonCode, message, {
+      path: relativePath,
+      absolutePath,
+    });
+  }
+  return absolutePath;
+}
+
+function createBaseReport({ projectRoot, packageName, packageVersion }) {
+  const normalizedPackageName = typeof packageName === 'string' && packageName.length > 0
+    ? packageName
+    : null;
+  return {
+    schema: PUBLISH_REPORT_SCHEMA,
+    generatedAt: nowIso(),
+    projectRoot,
+    package: {
+      name: normalizedPackageName,
+      version: packageVersion,
+      scope: normalizedPackageName
+        ? (normalizedPackageName.startsWith('@') ? 'scoped' : 'unscoped')
+        : null,
+    },
+    summary: {
+      pass: false,
+      reasonCode: null,
+    },
+    validation: {
+      metadata: {},
+      binIntegrity: {},
+      packageIntegrity: {},
+      build: {},
+      assets: {},
+      pack: {},
+    },
+  };
+}
+
+function writePublishReport(projectRoot, report) {
+  const reportRoot = resolve(projectRoot, '.aura', 'publish');
+  mkdirSync(reportRoot, { recursive: true });
+  const reportPath = join(reportRoot, 'publish-report.json');
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  return reportPath;
+}
+
+function normalizePackFiles(entry) {
+  if (!entry || typeof entry !== 'object' || !Array.isArray(entry.files)) {
+    throw new PublishValidationError(
+      'publish_pack_json_invalid',
+      'npm pack --json --dry-run did not return a files payload.',
+      { entry },
+    );
+  }
+  return entry.files
+    .filter((file) => file && typeof file.path === 'string')
+    .map((file) => ({
+      path: file.path,
+      size: Number.isFinite(file.size) ? file.size : null,
+      mode: Number.isFinite(file.mode) ? file.mode : null,
+    }));
+}
+
+function validatePackRequiredFiles(packFiles, requiredPaths) {
+  const packagedPaths = new Set(packFiles.map((entry) => entry.path));
+  const missing = requiredPaths.filter((filePath) => !packagedPaths.has(filePath));
+  if (missing.length > 0) {
+    throw new PublishValidationError(
+      'publish_required_file_missing',
+      `npm pack payload is missing required publish files: ${missing.join(', ')}`,
+      { missing },
+    );
+  }
+}
+
+async function defaultBuildProject({ projectRoot, env, stdout, stderr }) {
+  return runChildProcess(
+    process.execPath,
+    [CLI_ENTRY_PATH, 'build'],
+    {
+      cwd: projectRoot,
+      env,
+      stdout,
+      stderr,
+      failureReasonCode: 'publish_build_failed',
+      failureMessage: 'aura publish validation build failed',
+    },
+  );
+}
+
+async function defaultRunPackDryRun({ projectRoot, packRoot, env }) {
+  const pack = await runChildProcess(
+    resolveNpmCommand(),
+    ['pack', '--json', '--dry-run', '--ignore-scripts'],
+    {
+      cwd: packRoot || projectRoot,
+      env,
+      stdout: null,
+      stderr: null,
+      failureReasonCode: 'publish_pack_dry_run_failed',
+      failureMessage: 'aura publish pack dry-run failed',
+    },
+  );
+
+  let payload;
+  try {
+    payload = JSON.parse(pack.stdout || '[]');
+  } catch (error) {
+    throw new PublishValidationError(
+      'publish_pack_json_invalid',
+      `Failed to parse npm pack --json output: ${error.message}`,
+      { stdout: pack.stdout },
+    );
+  }
+
+  if (!Array.isArray(payload) || payload.length === 0 || !payload[0]) {
+    throw new PublishValidationError(
+      'publish_pack_json_invalid',
+      'npm pack --json --dry-run returned no package payload.',
+      { payload },
+    );
+  }
+
+  return payload[0];
+}
+
+export async function validatePublishProject(
+  {
+    projectRoot = process.cwd(),
+    env = process.env,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    buildProject = defaultBuildProject,
+    runPackDryRun = defaultRunPackDryRun,
+  } = {},
+) {
+  let packageSurface = null;
+  const report = createBaseReport({
+    projectRoot,
+    packageName: null,
+    packageVersion: null,
+  });
+
+  try {
+    const { packageName, packageVersion, projectPackage } = readProjectPackage(projectRoot);
+    report.package.name = packageName;
+    report.package.version = packageVersion;
+    report.package.scope = packageName.startsWith('@') ? 'scoped' : 'unscoped';
+    const config = await loadConfig({ projectRoot, mode: 'build' });
+    const binEntries = normalizeBinEntries(projectPackage, packageName);
+    const envExampleSurface = resolvePublishEnvExampleSurface({ projectRoot });
+    const requiredProjectFiles = [
+      'README.md',
+      'aura.config.json',
+      'aura.capabilities.json',
+      'src/main.js',
+      ...binEntries.map((entry) => entry.relativePath),
+    ];
+
+    report.validation.metadata = {
+      reasonCode: 'publish_metadata_ok',
+      bin: binEntries,
+      requiredProjectFiles,
+      publishConfig: projectPackage?.publishConfig || null,
+      environment: envExampleSurface.metadata,
+    };
+
+    for (const binEntry of binEntries) {
+      assertRequiredFileExists(
+        projectRoot,
+        binEntry.relativePath,
+        'publish_bin_target_missing',
+        `aura publish requires bin target "${binEntry.relativePath}" to exist.`,
+      );
+    }
+    for (const requiredFile of requiredProjectFiles) {
+      assertRequiredFileExists(
+        projectRoot,
+        requiredFile,
+        'publish_required_project_file_missing',
+        `aura publish requires "${requiredFile}" to exist before publishing.`,
+      );
+    }
+
+    const binIntegrity = assertProjectBinIntegrity({
+      projectRoot,
+      projectPackage,
+      packageName,
+      aurajsPackageRoot: DEFAULT_AURAJS_PACKAGE_ROOT,
+      expectedAurajsVersion: AURAJS_PACKAGE_VERSION,
+      enforceExactAurajsDependency: true,
+    });
+    report.validation.binIntegrity = {
+      reasonCode: 'publish_bin_integrity_ok',
+      ...binIntegrity,
+    };
+
+    stdout?.write('\n  aura publish: validating project build contract...\n');
+    await buildProject({ projectRoot, env, stdout, stderr });
+
+    const buildTarget = currentPlatformTarget();
+    const buildRoot = resolve(projectRoot, config.build.outDir, buildTarget);
+    const buildManifestPath = resolve(buildRoot, 'build-manifest.json');
+    assertRequiredFileExists(
+      projectRoot,
+      join(config.build.outDir, buildTarget, 'build-manifest.json'),
+      'publish_build_manifest_missing',
+      'aura publish validation requires build-manifest.json to be emitted by aura build.',
+    );
+
+    let buildManifest;
+    try {
+      buildManifest = JSON.parse(readFileSync(buildManifestPath, 'utf8'));
+    } catch (error) {
+      throw new PublishValidationError(
+        'publish_build_manifest_invalid',
+        `Failed to parse build manifest emitted during publish validation: ${error.message}`,
+        { buildManifestPath },
+      );
+    }
+
+    if (buildManifest.schema !== BUILD_MANIFEST_SCHEMA) {
+      throw new PublishValidationError(
+        'publish_build_manifest_schema_invalid',
+        `Publish validation expected ${BUILD_MANIFEST_SCHEMA}, got ${buildManifest?.schema || '<missing>'}.`,
+        { buildManifestPath, schema: buildManifest?.schema || null },
+      );
+    }
+
+    const bundleRelativePath = String(buildManifest.entrypoint || '');
+    const assetsManifestRelativePath = String(buildManifest.assetsManifest || '');
+    if (!bundleRelativePath) {
+      throw new PublishValidationError(
+        'publish_bundle_missing',
+        'Publish validation build manifest is missing the bundled entrypoint path.',
+        { buildManifestPath },
+      );
+    }
+    if (!assetsManifestRelativePath) {
+      throw new PublishValidationError(
+        'publish_assets_manifest_missing',
+        'Publish validation build manifest is missing the assets manifest path.',
+        { buildManifestPath },
+      );
+    }
+
+    const bundlePath = resolve(buildRoot, bundleRelativePath);
+    const assetsManifestPath = resolve(buildRoot, assetsManifestRelativePath);
+    assertRequiredFileExists(
+      buildRoot,
+      bundleRelativePath,
+      'publish_bundle_missing',
+      'Publish validation could not find the built JS bundle referenced by build-manifest.json.',
+    );
+    assertRequiredFileExists(
+      buildRoot,
+      assetsManifestRelativePath,
+      'publish_assets_manifest_missing',
+      'Publish validation could not find the assets manifest referenced by build-manifest.json.',
+    );
+
+    let assetsManifest;
+    try {
+      assetsManifest = JSON.parse(readFileSync(assetsManifestPath, 'utf8'));
+    } catch (error) {
+      throw new PublishValidationError(
+        'publish_assets_manifest_invalid',
+        `Failed to parse assets manifest emitted during publish validation: ${error.message}`,
+        { assetsManifestPath },
+      );
+    }
+
+    if (assetsManifest?.schema !== ASSET_MANIFEST_SCHEMA) {
+      throw new PublishValidationError(
+        'publish_assets_manifest_schema_invalid',
+        `Publish validation expected ${ASSET_MANIFEST_SCHEMA}, got ${assetsManifest?.schema || '<missing>'}.`,
+        {
+          assetsManifestPath,
+          schema: assetsManifest?.schema || null,
+        },
+      );
+    }
+
+    if (config.identity?.icon) {
+      if (buildManifest.icon?.status !== 'copied') {
+        throw new PublishValidationError(
+          'publish_icon_validation_failed',
+          'Publish validation expected the configured identity.icon to be copied into build output.',
+          {
+            configuredIcon: config.identity.icon,
+            icon: buildManifest.icon || null,
+          },
+        );
+      }
+    }
+
+    report.validation.build = {
+      reasonCode: 'publish_build_ok',
+      buildTarget,
+      buildRoot,
+      buildManifestPath,
+      bundlePath,
+      assetsManifestPath,
+      identity: buildManifest.identity || null,
+      icon: buildManifest.icon || null,
+    };
+    const buildMetadata = {
+      buildTarget,
+      buildRoot,
+      identity: buildManifest.identity || null,
+      icon: buildManifest.icon || null,
+    };
+
+    let assetThresholdRecord;
+    try {
+      assetThresholdRecord = evaluateExternalAssetPolicy({
+        projectRoot,
+        buildRoot,
+        assetsManifestPath,
+        assetsManifest,
+        assetDir: config.build.assetDir,
+        env,
+      });
+    } catch (error) {
+      throw new PublishValidationError(
+        'publish_asset_threshold_invalid',
+        error?.message || 'Assets manifest or publish threshold configuration is invalid.',
+        {},
+      );
+    }
+
+    try {
+      packageSurface = preparePublishPackageSurface({
+        projectRoot,
+        projectPackage,
+        assetDir: config.build.assetDir,
+        assetPolicy: assetThresholdRecord,
+        generatedFilePaths: PACKAGE_INTEGRITY_PUBLISH_FILES,
+        generatedFiles: envExampleSurface.generatedFiles,
+        excludedFilePaths: envExampleSurface.excludedFilePaths,
+      });
+    } catch (error) {
+      throw new PublishValidationError(
+        'publish_external_assets_surface_invalid',
+        error?.message || 'Failed to stage the self-hosted external asset publish surface.',
+        {},
+      );
+    }
+
+    const packageIntegrity = writeSignedPackageIntegrityArtifacts({
+      packageRoot: packageSurface.publishRoot,
+      signerProjectRoot: projectRoot,
+      buildMetadata,
+    });
+    report.validation.packageIntegrity = {
+      reasonCode: 'publish_package_integrity_ok',
+      manifestPath: packageIntegrity.manifestPath,
+      signaturePath: packageIntegrity.signaturePath,
+      schema: packageIntegrity.schema,
+      fileCount: packageIntegrity.fileCount,
+      signerFingerprint: packageIntegrity.signerFingerprint,
+      publishedMetadata: packageIntegrity.publishedMetadata,
+    };
+
+    assetThresholdRecord.packageSurfaceMode = packageSurface.mode;
+    assetThresholdRecord.assetPackaging = packageSurface.mode === SELF_HOSTED_PACKAGE_SURFACE_MODE
+      ? 'self_hosted'
+      : 'embedded';
+    report.validation.assets = assetThresholdRecord;
+    if (assetThresholdRecord.blocked) {
+      throw new PublishValidationError(
+        'publish_asset_threshold_exceeded',
+        `AuraJS asset payload is ${assetThresholdRecord.assetBytes} bytes, above the npm-first threshold of ${assetThresholdRecord.thresholdBytes} bytes. Self-host the heavy assets on a public HTTPS base URL (for example Cloudflare R2 or S3), generate the external asset config, then publish the slim package.`,
+        assetThresholdRecord,
+      );
+    }
+
+    const packEntry = await runPackDryRun({
+      projectRoot,
+      packRoot: packageSurface.publishRoot,
+      env,
+    });
+    const packFiles = normalizePackFiles(packEntry);
+    const packInspection = inspectPublishPackFiles(packFiles, {
+      assetDir: packageSurface.assetDir,
+      externalAssetsConfigPath: packageSurface.externalAssetsConfigPath,
+    });
+    const requiredPackFiles = [
+      'package.json',
+      'README.md',
+      'aura.config.json',
+      'aura.capabilities.json',
+      ...binEntries.map((entry) => entry.relativePath),
+      'src/main.js',
+      ...(packageSurface.mode === SELF_HOSTED_PACKAGE_SURFACE_MODE
+        ? [packageSurface.externalAssetsConfigPath]
+        : []),
+      ...PACKAGE_INTEGRITY_PUBLISH_FILES,
+      ...(envExampleSurface.metadata.generatedExample ? [PUBLISH_ENV_EXAMPLE_PATH] : []),
+    ];
+    validatePackRequiredFiles(packFiles, requiredPackFiles);
+
+    if (packFiles.some((entry) => entry.path === PUBLISH_SOURCE_ENV_PATH)) {
+      throw new PublishValidationError(
+        'publish_env_file_included',
+        '.env must not be included in the published npm package. AuraJS generates .env.example instead.',
+        {},
+      );
+    }
+
+    if (packageSurface.mode === SELF_HOSTED_PACKAGE_SURFACE_MODE && packInspection.includesAssetPayload) {
+      throw new PublishValidationError(
+        'publish_external_assets_payload_included',
+        `Self-hosted external asset packages must omit ${packageSurface.assetDir}/ from the npm tarball.`,
+        {
+          assetDir: packageSurface.assetDir,
+        },
+      );
+    }
+
+    if (packageSurface.mode === SELF_HOSTED_PACKAGE_SURFACE_MODE && !packInspection.includesExternalAssetsConfig) {
+      throw new PublishValidationError(
+        'publish_external_assets_config_missing_from_pack',
+        `${packageSurface.externalAssetsConfigPath} must be present in the slim npm tarball for self-hosted assets.`,
+        {
+          configPath: packageSurface.externalAssetsConfigPath,
+        },
+      );
+    }
+
+    report.validation.pack = {
+      reasonCode: 'publish_pack_dry_run_ok',
+      filename: typeof packEntry.filename === 'string' ? packEntry.filename : null,
+      size: Number.isFinite(packEntry.size) ? packEntry.size : null,
+      unpackedSize: Number.isFinite(packEntry.unpackedSize) ? packEntry.unpackedSize : null,
+      surfaceMode: packageSurface.mode,
+      assetDir: packageSurface.assetDir,
+      externalAssetsConfigPath: packageSurface.externalAssetsConfigPath,
+      assetPayloadIncluded: packInspection.includesAssetPayload,
+      externalAssetsConfigIncluded: packInspection.includesExternalAssetsConfig,
+      manifestIncluded: packFiles.some((entry) => entry.path === PACKAGE_INTEGRITY_MANIFEST_PATH),
+      signatureIncluded: packFiles.some((entry) => entry.path === PACKAGE_INTEGRITY_SIGNATURE_PATH),
+      envExampleIncluded: packFiles.some((entry) => entry.path === PUBLISH_ENV_EXAMPLE_PATH),
+      sourceEnvIncluded: packFiles.some((entry) => entry.path === PUBLISH_SOURCE_ENV_PATH),
+      files: packFiles,
+    };
+
+    report.summary = {
+      pass: true,
+      reasonCode: 'publish_validation_ok',
+    };
+
+    const reportPath = writePublishReport(projectRoot, report);
+    return {
+      ok: true,
+      packageName: report.package.name,
+      packageVersion: report.package.version,
+      report,
+      reportPath,
+    };
+  } catch (error) {
+    const normalized = error instanceof PublishValidationError
+      ? error
+      : new PublishValidationError(
+        typeof error?.reasonCode === 'string' && error.reasonCode.length > 0
+          ? error.reasonCode
+          : 'publish_validation_failed',
+        error?.message || 'Publish validation failed.',
+        error?.details && typeof error.details === 'object' ? error.details : {},
+      );
+
+    report.summary = {
+      pass: false,
+      reasonCode: normalized.reasonCode,
+    };
+    report.failure = {
+      reasonCode: normalized.reasonCode,
+      message: normalized.message,
+      details: normalized.details,
+    };
+
+    const reportPath = writePublishReport(projectRoot, report);
+    normalized.reportPath = reportPath;
+    normalized.report = report;
+    throw normalized;
+  } finally {
+    packageSurface?.cleanup?.();
+  }
+}