@bleedingdev/modern-js-app-tools-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.20

package/src/deploy-output/npmAliases.ts

@@ -0,0 +1,382 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+type PackageJson = {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  [key: string]: unknown;
+};
+
+type PackageRecord = {
+  directory: string;
+  packageJson: PackageJson;
+};
+
+export type NpmAlias = {
+  aliasName: string;
+  targetName: string;
+  targetVersion: string;
+};
+
+const dependencyKeys = ['dependencies', 'optionalDependencies'] as const;
+const rootDependencyKeys = [...dependencyKeys, 'devDependencies'] as const;
+const exactVersionPattern =
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+
+async function readPackageJson(filePath: string): Promise<PackageJson> {
+  return JSON.parse(await fs.readFile(filePath, 'utf8')) as PackageJson;
+}
+
+function parseNpmAlias(
+  aliasName: string,
+  specifier: string,
+): NpmAlias | undefined {
+  if (!specifier.startsWith('npm:')) {
+    return undefined;
+  }
+
+  const target = specifier.slice('npm:'.length);
+  const versionSeparator = target.lastIndexOf('@');
+  if (versionSeparator <= 0 || versionSeparator === target.length - 1) {
+    throw new Error(
+      `Invalid npm alias specifier for ${aliasName}: ${specifier}`,
+    );
+  }
+
+  return {
+    aliasName,
+    targetName: target.slice(0, versionSeparator),
+    targetVersion: target.slice(versionSeparator + 1),
+  };
+}
+
+function aliasesFromPackageJson(
+  packageJson: PackageJson,
+  keys: readonly (typeof rootDependencyKeys)[number][] = dependencyKeys,
+): NpmAlias[] {
+  const aliases: NpmAlias[] = [];
+  for (const dependencyKey of keys) {
+    for (const [aliasName, specifier] of Object.entries(
+      packageJson[dependencyKey] ?? {},
+    )) {
+      const alias = parseNpmAlias(aliasName, specifier);
+      if (alias) {
+        aliases.push(alias);
+      }
+    }
+  }
+  return aliases;
+}
+
+async function catalogAliasesFromInstalledPackages(
+  appDirectory: string,
+  packageJson: PackageJson,
+): Promise<NpmAlias[]> {
+  const aliases: NpmAlias[] = [];
+  for (const dependencyKey of rootDependencyKeys) {
+    for (const [aliasName, specifier] of Object.entries(
+      packageJson[dependencyKey] ?? {},
+    )) {
+      if (!specifier.startsWith('catalog:')) {
+        continue;
+      }
+      let installedPackage: PackageJson;
+      try {
+        installedPackage = await readPackageJson(
+          path.join(appDirectory, 'node_modules', aliasName, 'package.json'),
+        );
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          continue;
+        }
+        throw error;
+      }
+      if (!installedPackage.name || !installedPackage.version) {
+        throw new Error(
+          `Installed catalog package ${aliasName} has no identity`,
+        );
+      }
+      if (installedPackage.name !== aliasName) {
+        aliases.push({
+          aliasName,
+          targetName: installedPackage.name,
+          targetVersion: installedPackage.version,
+        });
+      }
+    }
+  }
+  return aliases;
+}
+
+async function collectPackageRecords(
+  nodeModulesDirectory: string,
+): Promise<PackageRecord[]> {
+  const records: PackageRecord[] = [];
+  const visitedNodeModules = new Set<string>();
+
+  const visitPackage = async (directory: string) => {
+    const packageJsonPath = path.join(directory, 'package.json');
+    try {
+      const packageJson = await readPackageJson(packageJsonPath);
+      if (packageJson.name && packageJson.version) {
+        records.push({ directory, packageJson });
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    await visitNodeModules(path.join(directory, 'node_modules'));
+  };
+
+  const visitScope = async (scopeDirectory: string) => {
+    const entries = await fs.readdir(scopeDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await visitPackage(path.join(scopeDirectory, entry.name));
+      }
+    }
+  };
+
+  const visitNdepeStore = async (storeDirectory: string) => {
+    const entries = await fs.readdir(storeDirectory, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const entryPath = path.join(storeDirectory, entry.name);
+        if (entry.name.startsWith('@')) {
+          // ndepe preserves the slash in a scoped package name, so a
+          // multi-version package is stored as
+          // .ndepe/@scope/package@version/node_modules/@scope/package.
+          await visitScope(entryPath);
+        } else {
+          await visitNodeModules(path.join(entryPath, 'node_modules'));
+        }
+      }
+    }
+  };
+
+  const visitNodeModules = async (directory: string): Promise<void> => {
+    const resolvedDirectory = path.resolve(directory);
+    if (visitedNodeModules.has(resolvedDirectory)) {
+      return;
+    }
+    visitedNodeModules.add(resolvedDirectory);
+
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return;
+      }
+      throw error;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const entryPath = path.join(directory, entry.name);
+      if (entry.name === '.ndepe') {
+        await visitNdepeStore(entryPath);
+      } else if (entry.name.startsWith('@')) {
+        await visitScope(entryPath);
+      } else {
+        await visitPackage(entryPath);
+      }
+    }
+  };
+
+  await visitNodeModules(nodeModulesDirectory);
+  return records;
+}
+
+async function resolveAliasTarget(
+  ownerDirectory: string,
+  alias: NpmAlias,
+  outputDirectory: string,
+): Promise<PackageRecord | undefined> {
+  let directory = ownerDirectory;
+  const outputRoot = path.resolve(outputDirectory);
+  const resolvedOutputRoot = await fs.realpath(outputRoot);
+  while (
+    directory === outputRoot ||
+    directory.startsWith(`${outputRoot}${path.sep}`)
+  ) {
+    const candidate = path.join(directory, 'node_modules', alias.targetName);
+    try {
+      const resolvedCandidate = await fs.realpath(candidate);
+      if (
+        resolvedCandidate !== resolvedOutputRoot &&
+        !resolvedCandidate.startsWith(`${resolvedOutputRoot}${path.sep}`)
+      ) {
+        throw new Error(
+          `Cannot preserve npm alias ${alias.aliasName}: emitted target ${candidate} resolves outside deployment output to ${resolvedCandidate}`,
+        );
+      }
+      const packageJson = await readPackageJson(
+        path.join(candidate, 'package.json'),
+      );
+      if (packageJson.name !== alias.targetName || !packageJson.version) {
+        throw new Error(
+          `npm alias ${alias.aliasName} resolved ${candidate} to unexpected package ${String(packageJson.name)}`,
+        );
+      }
+      if (
+        exactVersionPattern.test(alias.targetVersion) &&
+        packageJson.version !== alias.targetVersion
+      ) {
+        return undefined;
+      }
+      // Keep the lexical path inside .output. realpath can cross an operating
+      // system alias such as macOS /var -> /private/var, which would turn the
+      // deployment link into a non-relocatable path outside the artifact.
+      return { directory: candidate, packageJson };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    if (directory === outputRoot) {
+      break;
+    }
+    directory = path.dirname(directory);
+  }
+  return undefined;
+}
+
+async function ensureAliasLink(
+  ownerDirectory: string,
+  alias: NpmAlias,
+  target: PackageRecord,
+) {
+  const aliasPath = path.join(ownerDirectory, 'node_modules', alias.aliasName);
+  await fs.mkdir(path.dirname(aliasPath), { recursive: true });
+
+  try {
+    const [existing, expected] = await Promise.all([
+      fs.realpath(aliasPath),
+      fs.realpath(target.directory),
+    ]);
+    if (existing === expected) {
+      return;
+    }
+    throw new Error(
+      `Cannot preserve npm alias ${alias.aliasName}: ${aliasPath} already resolves to ${existing}, expected ${expected}`,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const linkTarget = path.relative(path.dirname(aliasPath), target.directory);
+  await fs.symlink(linkTarget, aliasPath, 'dir');
+}
+
+function aliasSpecifier(alias: NpmAlias) {
+  return `npm:${alias.targetName}@${alias.targetVersion}`;
+}
+
+export async function readPackageIdentity(
+  entryPath: string,
+): Promise<{ name: string; version: string }> {
+  let directory = path.dirname(entryPath);
+  const root = path.parse(directory).root;
+  while (directory !== root) {
+    try {
+      const packageJson = await readPackageJson(
+        path.join(directory, 'package.json'),
+      );
+      if (packageJson.name && packageJson.version) {
+        return { name: packageJson.name, version: packageJson.version };
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw error;
+      }
+    }
+    directory = path.dirname(directory);
+  }
+  throw new Error(
+    `Cannot find owning package for deployment entry ${entryPath}`,
+  );
+}
+
+export async function preserveNpmAliases({
+  appDirectory,
+  outputDirectory,
+  implicitAliases = [],
+}: {
+  appDirectory: string;
+  outputDirectory: string;
+  implicitAliases?: NpmAlias[];
+}) {
+  const records = await collectPackageRecords(
+    path.join(outputDirectory, 'node_modules'),
+  );
+
+  const appPackageJson = await readPackageJson(
+    path.join(appDirectory, 'package.json'),
+  );
+  const rootAliases = [
+    ...aliasesFromPackageJson(appPackageJson, rootDependencyKeys),
+    ...(await catalogAliasesFromInstalledPackages(
+      appDirectory,
+      appPackageJson,
+    )),
+    ...implicitAliases,
+  ].filter(alias => alias.aliasName !== alias.targetName);
+
+  const emittedRootAliases: NpmAlias[] = [];
+  for (const alias of rootAliases) {
+    const target = await resolveAliasTarget(
+      outputDirectory,
+      alias,
+      outputDirectory,
+    );
+    if (!target) {
+      if (implicitAliases.includes(alias)) {
+        throw new Error(
+          `Cannot preserve implicit npm alias ${alias.aliasName}: emitted target ${alias.targetName}@${alias.targetVersion} is missing`,
+        );
+      }
+      continue;
+    }
+    await ensureAliasLink(outputDirectory, alias, target);
+    emittedRootAliases.push(alias);
+  }
+
+  for (const record of records) {
+    for (const alias of aliasesFromPackageJson(record.packageJson).filter(
+      candidate => candidate.aliasName !== candidate.targetName,
+    )) {
+      const target = await resolveAliasTarget(
+        record.directory,
+        alias,
+        outputDirectory,
+      );
+      if (!target) {
+        // ndepe emits only runtime-traced packages. A package manifest can
+        // still declare type-only or otherwise unused aliases whose targets
+        // correctly are not part of this deployment output.
+        continue;
+      }
+      await ensureAliasLink(record.directory, alias, target);
+    }
+  }
+
+  const outputPackageJsonPath = path.join(outputDirectory, 'package.json');
+  const outputPackageJson = await readPackageJson(outputPackageJsonPath);
+  outputPackageJson.dependencies ??= {};
+  for (const alias of emittedRootAliases) {
+    outputPackageJson.dependencies[alias.aliasName] = aliasSpecifier(alias);
+  }
+  await fs.writeFile(
+    outputPackageJsonPath,
+    `${JSON.stringify(outputPackageJson, null, 2)}\n`,
+  );
+}

package/src/deploy-output/plugin.ts

@@ -0,0 +1,86 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { NodePublicAssetConfig } from '../config';
+import { preserveNpmAliases, readPackageIdentity } from './npmAliases';
+import {
+  NODE_PUBLIC_ASSET_SCOPE,
+  normalizeDeclaredPublicAssets,
+  stageDeclaredPublicAssets,
+} from './public-assets';
+import { getDeployingTarget, type ResolvedDeployTarget } from './target';
+
+export interface DeployOutputAppContext {
+  appDirectory: string;
+  metaName: string;
+  deployTarget?: ResolvedDeployTarget;
+}
+
+export interface DeployOutputPluginApi {
+  getAppContext(): DeployOutputAppContext;
+  onAfterDeploy(handler: () => Promise<void>): void;
+}
+
+export const createDeployOutputAliasesPlugin = () => ({
+  name: '@modern-js/deploy-output-aliases',
+  setup(api: DeployOutputPluginApi) {
+    api.onAfterDeploy(async () => {
+      const appContext = api.getAppContext();
+      if (getDeployingTarget(appContext) !== 'node') {
+        return;
+      }
+      const { appDirectory } = appContext;
+
+      const entry = createRequire(__filename).resolve('@modern-js/prod-server');
+      const identity = await readPackageIdentity(entry);
+      await preserveNpmAliases({
+        appDirectory,
+        outputDirectory: path.join(appDirectory, '.output'),
+        implicitAliases: [
+          {
+            aliasName: '@modern-js/prod-server',
+            targetName: identity.name,
+            targetVersion: identity.version,
+          },
+        ],
+      });
+    });
+  },
+});
+
+export interface DeployOutputPublicAssetsConfig {
+  deploy?: { node?: { publicAssets?: NodePublicAssetConfig[] } };
+}
+
+export interface DeployOutputPublicAssetsPluginApi {
+  getAppContext(): DeployOutputAppContext;
+  getNormalizedConfig(): DeployOutputPublicAssetsConfig;
+  onAfterDeploy(handler: () => Promise<void>): void;
+}
+
+/**
+ * Stage `deploy.node.publicAssets` into the Node deploy output. Cloudflare
+ * stages `deploy.worker.publicAssets` inside its deploy preset.
+ */
+export const createDeployOutputPublicAssetsPlugin = () => ({
+  name: '@modern-js/deploy-output-public-assets',
+  setup(api: DeployOutputPublicAssetsPluginApi) {
+    api.onAfterDeploy(async () => {
+      const appContext = api.getAppContext();
+      if (getDeployingTarget(appContext) !== 'node') {
+        return;
+      }
+      const { appDirectory } = appContext;
+      const config = api.getNormalizedConfig();
+
+      await stageDeclaredPublicAssets({
+        appDirectory,
+        outputDirectory: path.join(appDirectory, '.output'),
+        assets: normalizeDeclaredPublicAssets(
+          config.deploy?.node?.publicAssets,
+          NODE_PUBLIC_ASSET_SCOPE,
+        ),
+        scope: NODE_PUBLIC_ASSET_SCOPE,
+      });
+    });
+  },
+});

package/src/deploy-output/public-assets.ts

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeRelativePath } from '../cloudflare/utils';
+
+/**
+ * Deploy output directory that receives declared public assets on every
+ * target: Cloudflare Worker Static Assets and the Node deploy output.
+ */
+export const DECLARED_PUBLIC_ASSET_DIRECTORY = 'public';
+
+export interface DeclaredPublicAssetConfig {
+  from: string;
+  to: string;
+}
+
+export interface DeclaredPublicAssetScope {
+  /** Config path used in errors, for example `deploy.node.publicAssets`. */
+  label: string;
+  /** Output described in destination errors. */
+  output: string;
+}
+
+export interface DeclaredPublicAsset {
+  from: string;
+  to: string;
+  index: number;
+}
+
+export const CLOUDFLARE_PUBLIC_ASSET_SCOPE: DeclaredPublicAssetScope = {
+  label: 'deploy.worker.publicAssets',
+  output: 'Cloudflare public output',
+};
+
+export const NODE_PUBLIC_ASSET_SCOPE: DeclaredPublicAssetScope = {
+  label: 'deploy.node.publicAssets',
+  output: 'Node public output',
+};
+
+export const normalizeDeclaredPublicAssets = (
+  assets: readonly DeclaredPublicAssetConfig[] | undefined,
+  scope: DeclaredPublicAssetScope,
+): DeclaredPublicAsset[] =>
+  (assets ?? []).map((asset, index) => ({
+    from: normalizeRelativePath(
+      asset?.from,
+      `${scope.label}[${index}].from`,
+      'app root',
+    ),
+    to: normalizeRelativePath(
+      asset?.to,
+      `${scope.label}[${index}].to`,
+      scope.output,
+      { allowRoot: true },
+    ),
+    index,
+  }));
+
+interface DeclaredPublicAssetFile {
+  index: number;
+  /** Destination relative to the deploy output root, POSIX separators. */
+  logicalPath: string;
+}
+
+const isMissingPathError = (error: unknown) =>
+  error instanceof Error &&
+  'code' in error &&
+  (error as NodeJS.ErrnoException).code === 'ENOENT';
+
+const pathExists = async (filePath: string) => {
+  try {
+    await fs.lstat(filePath);
+    return true;
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return false;
+    }
+    throw error;
+  }
+};
+
+const listDeclaredPublicAssetFiles = async (
+  appDirectory: string,
+  assets: readonly DeclaredPublicAsset[],
+  scope: DeclaredPublicAssetScope,
+): Promise<DeclaredPublicAssetFile[]> => {
+  const files: DeclaredPublicAssetFile[] = [];
+  const owners = new Map<string, number>();
+  const add = (index: number, logicalPath: string) => {
+    const owner = owners.get(logicalPath);
+    if (owner !== undefined) {
+      throw new Error(
+        `${scope.label}[${index}] and ${scope.label}[${owner}] both stage ${JSON.stringify(logicalPath)}.`,
+      );
+    }
+    owners.set(logicalPath, index);
+    files.push({ index, logicalPath });
+  };
+  const visit = async (
+    asset: DeclaredPublicAsset,
+    sourcePath: string,
+    destination: string,
+  ): Promise<void> => {
+    const stat = await fs.lstat(sourcePath);
+    if (stat.isSymbolicLink()) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from must not contain symbolic links: ${path
+          .relative(appDirectory, sourcePath)
+          .replace(/\\/gu, '/')}`,
+      );
+    }
+    if (stat.isFile()) {
+      if (destination === DECLARED_PUBLIC_ASSET_DIRECTORY) {
+        throw new Error(
+          `${scope.label}[${asset.index}].to must name a file when ${scope.label}[${asset.index}].from is a file.`,
+        );
+      }
+      add(asset.index, destination);
+      return;
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from must contain only files and directories: ${path
+          .relative(appDirectory, sourcePath)
+          .replace(/\\/gu, '/')}`,
+      );
+    }
+    const entries = (await fs.readdir(sourcePath)).sort();
+    for (const entry of entries) {
+      await visit(
+        asset,
+        path.join(sourcePath, entry),
+        path.posix.join(destination, entry),
+      );
+    }
+  };
+
+  for (const asset of assets) {
+    const sourcePath = path.join(appDirectory, asset.from);
+    if (!(await pathExists(sourcePath))) {
+      throw new Error(
+        `${scope.label}[${asset.index}].from does not exist: ${asset.from}`,
+      );
+    }
+    await visit(
+      asset,
+      sourcePath,
+      path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to),
+    );
+  }
+  return files;
+};
+
+/**
+ * Resolve the files declared public assets add to a deploy output that was
+ * copied from `generatedRoot`, relative to the deploy output root. Declared
+ * files that replace a generated file are not part of the result, matching
+ * {@link stageDeclaredPublicAssets}.
+ */
+export const resolveAddedDeclaredPublicAssetPaths = async ({
+  appDirectory,
+  assets,
+  generatedRoot,
+  scope,
+}: {
+  appDirectory: string;
+  assets: readonly DeclaredPublicAsset[];
+  generatedRoot: string;
+  scope: DeclaredPublicAssetScope;
+}): Promise<string[]> => {
+  const added: string[] = [];
+  for (const file of await listDeclaredPublicAssetFiles(
+    appDirectory,
+    assets,
+    scope,
+  )) {
+    if (!(await pathExists(path.join(generatedRoot, file.logicalPath)))) {
+      added.push(file.logicalPath);
+    }
+  }
+  return added.sort();
+};
+
+/**
+ * Copy declared public assets into the deploy output after the framework has
+ * staged its own public files.
+ *
+ * A declared file may replace a generated public file, such as an app-owned
+ * `robots.txt`; the replaced file keeps its generated release classification.
+ *
+ * @returns the files the declarations added, relative to the deploy output
+ * root. The release envelope records these as declared public assets.
+ */
+export const stageDeclaredPublicAssets = async ({
+  appDirectory,
+  outputDirectory,
+  assets,
+  scope,
+}: {
+  appDirectory: string;
+  outputDirectory: string;
+  assets: readonly DeclaredPublicAsset[];
+  scope: DeclaredPublicAssetScope;
+}): Promise<string[]> => {
+  const files = await listDeclaredPublicAssetFiles(appDirectory, assets, scope);
+  const added: string[] = [];
+  for (const file of files) {
+    const asset = assets.find(candidate => candidate.index === file.index)!;
+    const relativePath = path.posix.relative(
+      path.posix.join(DECLARED_PUBLIC_ASSET_DIRECTORY, asset.to),
+      file.logicalPath,
+    );
+    const destination = path.join(outputDirectory, file.logicalPath);
+    const replacesGeneratedFile = await pathExists(destination);
+    await fs.mkdir(path.dirname(destination), { recursive: true });
+    await fs.copyFile(
+      path.join(appDirectory, asset.from, relativePath),
+      destination,
+    );
+    if (!replacesGeneratedFile) {
+      added.push(file.logicalPath);
+    }
+  }
+  return added.sort();
+};