@git.zone/tsbundle 2.11.4 → 2.13.0

package/ts/mod_output/artifactpublisher.ts

@@ -0,0 +1,1185 @@
+import * as plugins from './plugins.js';
+
+const artifactOwner = '@git.zone/tsbundle';
+const chunkManifestKind = 'chunk-namespace';
+const chunkManifestSchemaVersion = 1;
+const buildStageKind = 'build-stage';
+const buildStageSchemaVersion = 1;
+const lockKind = 'artifact-publication-lock';
+const lockSchemaVersion = 1;
+const lockWaitTimeoutMs = 60_000;
+const lockLeaseTimeoutMs = 60 * 60 * 1000;
+const ownershipHeartbeatIntervalMs = 30_000;
+const staleStageThresholdMs = 24 * 60 * 60 * 1000;
+const buildStageHeartbeats = new Map<string, () => void>();
+
+export const chunkManifestFile = '.tsbundle-artifacts.json';
+
+interface IChunkManifest {
+  owner: string;
+  kind: string;
+  logicalOutputName: string;
+  namespace: string;
+  schemaVersion: 1;
+}
+
+export interface IProcessOwnership {
+  leaseManaged?: boolean;
+  processId: number;
+  processIdentity?: string;
+}
+
+interface IBuildStageMarker extends IProcessOwnership {
+  owner: string;
+  kind: string;
+  createdAt: string;
+  invocationId: string;
+  schemaVersion: 1;
+}
+
+interface IArtifactLockMarker extends IProcessOwnership {
+  owner: string;
+  kind: string;
+  createdAt: string;
+  ownerToken: string;
+  targetPath: string;
+  schemaVersion: 1;
+}
+
+interface ILockOwner {
+  lockPath: string;
+  marker: IArtifactLockMarker;
+  ownerPath: string;
+}
+
+interface IReaperOwnership {
+  createdAt: number;
+  processId: number;
+  processIdentityToken: string;
+}
+
+interface IPreparedArtifact {
+  content: Buffer;
+  mode: number;
+  relativePath?: string;
+  targetPath: string;
+}
+
+interface IFileSnapshot {
+  content?: Buffer;
+  existed: boolean;
+  mode?: number;
+  path: string;
+}
+
+export interface IAdditionalArtifact {
+  sourcePath: string;
+  targetPath: string;
+}
+
+interface IPublishGeneratedArtifactsOptions {
+  additionalArtifacts?: IAdditionalArtifact[];
+  chunkNamespace: string;
+  lockTargetPath?: string;
+  logicalOutputName: string;
+  sourceDirectory: string;
+  sourceMainPath: string;
+  sourceMapsEnabled: boolean;
+  targetPath: string;
+}
+
+const hasErrorCode = (errorArg: unknown): errorArg is NodeJS.ErrnoException => (
+  typeof errorArg === 'object' && errorArg !== null && 'code' in errorArg
+);
+
+const createToken = (): string => plugins.crypto.randomBytes(16).toString('hex');
+
+const isProcessAlive = (processIdArg: number): boolean => {
+  try {
+    process.kill(processIdArg, 0);
+    return true;
+  } catch (error: unknown) {
+    return hasErrorCode(error) && error.code === 'EPERM';
+  }
+};
+
+export const getProcessIdentity = (processIdArg: number): string | undefined => {
+  if (process.platform !== 'linux') {
+    return undefined;
+  }
+  try {
+    const processStat = plugins.fsSync.readFileSync(`/proc/${processIdArg}/stat`, 'utf8');
+    const commandEnd = processStat.lastIndexOf(')');
+    if (commandEnd === -1) {
+      return undefined;
+    }
+    const fieldsAfterCommand = processStat.slice(commandEnd + 2).trim().split(/\s+/);
+    const processStartTicks = fieldsAfterCommand[19];
+    return processStartTicks ? `linux-proc-start:${processStartTicks}` : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const encodeProcessIdentity = (processIdentityArg: string): string => (
+  plugins.crypto.createHash('sha256').update(processIdentityArg).digest('base64url').slice(0, 16)
+);
+
+const getProcessIdentityToken = (processIdArg: number): string => {
+  const processIdentity = getProcessIdentity(processIdArg);
+  return processIdentity
+    ? encodeProcessIdentity(processIdentity)
+    : 'lease';
+};
+
+export const createProcessOwnership = (): Required<IProcessOwnership> => ({
+  leaseManaged: true,
+  processId: process.pid,
+  processIdentity: getProcessIdentity(process.pid) || '',
+});
+
+export const isProcessOwnershipActive = (
+  ownershipArg: IProcessOwnership,
+  markerPathArg: string,
+  leaseTimeoutMsArg: number,
+): boolean => {
+  if (!isProcessAlive(ownershipArg.processId)) {
+    return false;
+  }
+  if (ownershipArg.processIdentity) {
+    const currentIdentity = getProcessIdentity(ownershipArg.processId);
+    return currentIdentity === undefined || currentIdentity === ownershipArg.processIdentity;
+  }
+  if (!ownershipArg.leaseManaged) {
+    return true;
+  }
+  try {
+    return Date.now() - plugins.fsSync.statSync(markerPathArg).mtimeMs < leaseTimeoutMsArg;
+  } catch {
+    return false;
+  }
+};
+
+export const startOwnershipHeartbeat = (markerPathArg: string): (() => void) => {
+  const heartbeat = setInterval(() => {
+    try {
+      const now = new Date();
+      plugins.fsSync.utimesSync(markerPathArg, now, now);
+    } catch (error: unknown) {
+      if (!hasErrorCode(error) || error.code !== 'ENOENT') {
+        console.warn(`tsbundle: unable to update ownership lease ${markerPathArg}: ${String(error)}`);
+      }
+    }
+  }, ownershipHeartbeatIntervalMs);
+  heartbeat.unref();
+  return () => clearInterval(heartbeat);
+};
+
+const assertPathNotSymbolicLink = (pathArg: string, descriptionArg: string): void => {
+  if (!plugins.fsSync.existsSync(pathArg)) {
+    return;
+  }
+  const stat = plugins.fsSync.lstatSync(pathArg);
+  if (stat.isSymbolicLink()) {
+    throw new Error(`Refusing to use symbolic-link ${descriptionArg}: ${pathArg}`);
+  }
+};
+
+const assertRegularFile = (pathArg: string, descriptionArg: string): void => {
+  const stat = plugins.fsSync.lstatSync(pathArg);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`Expected a regular ${descriptionArg}: ${pathArg}`);
+  }
+};
+
+const sameFile = (firstPathArg: string, secondPathArg: string): boolean => {
+  const firstStat = plugins.fsSync.statSync(firstPathArg);
+  const secondStat = plugins.fsSync.statSync(secondPathArg);
+  return firstStat.dev === secondStat.dev && firstStat.ino === secondStat.ino;
+};
+
+const getLockPath = (targetPathArg: string): string => `${targetPathArg}.tsbundle-lock`;
+
+const getLockOwnerPath = (lockPathArg: string, ownerTokenArg: string): string => (
+  `${lockPathArg}.owner-${ownerTokenArg}`
+);
+
+const parseLockMarker = (rawMarkerArg: string, targetPathArg: string): IArtifactLockMarker => {
+  const marker = JSON.parse(rawMarkerArg) as Partial<IArtifactLockMarker>;
+  if (
+    marker.owner !== artifactOwner
+    || marker.kind !== lockKind
+    || typeof marker.processId !== 'number'
+    || !Number.isSafeInteger(marker.processId)
+    || marker.processId <= 0
+    || (marker.processIdentity !== undefined && typeof marker.processIdentity !== 'string')
+    || (marker.leaseManaged !== undefined && typeof marker.leaseManaged !== 'boolean')
+    || typeof marker.createdAt !== 'string'
+    || typeof marker.ownerToken !== 'string'
+    || !/^[a-f0-9]{32}$/.test(marker.ownerToken)
+    || typeof marker.targetPath !== 'string'
+    || plugins.path.resolve(marker.targetPath) !== plugins.path.resolve(targetPathArg)
+    || marker.schemaVersion !== lockSchemaVersion
+  ) {
+    throw new Error(`Refusing to use invalid artifact publication lock for ${targetPathArg}`);
+  }
+  return marker as IArtifactLockMarker;
+};
+
+const readLockMarker = (lockPathArg: string, targetPathArg: string): IArtifactLockMarker | undefined => {
+  try {
+    const stat = plugins.fsSync.lstatSync(lockPathArg);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      throw new Error(`Refusing to use unsafe artifact publication lock: ${lockPathArg}`);
+    }
+    return parseLockMarker(plugins.fsSync.readFileSync(lockPathArg, 'utf8'), targetPathArg);
+  } catch (error: unknown) {
+    if (hasErrorCode(error) && error.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+const createLockOwner = (targetPathArg: string): ILockOwner => {
+  const lockPath = getLockPath(targetPathArg);
+  const marker: IArtifactLockMarker = {
+    owner: artifactOwner,
+    kind: lockKind,
+    ...createProcessOwnership(),
+    createdAt: new Date().toISOString(),
+    ownerToken: createToken(),
+    targetPath: plugins.path.resolve(targetPathArg),
+    schemaVersion: lockSchemaVersion,
+  };
+  const ownerPath = getLockOwnerPath(lockPath, marker.ownerToken);
+  try {
+    plugins.fsSync.writeFileSync(ownerPath, `${JSON.stringify(marker, null, 2)}\n`, {
+      flag: 'wx',
+      mode: 0o600,
+    });
+    return { lockPath, marker, ownerPath };
+  } catch (error: unknown) {
+    plugins.fsSync.rmSync(ownerPath, { force: true });
+    throw error;
+  }
+};
+
+const cleanupOrphanLockOwners = (targetPathArg: string): void => {
+  const lockPath = getLockPath(targetPathArg);
+  const directory = plugins.path.dirname(lockPath);
+  const lockBasename = plugins.path.basename(lockPath);
+  const escapedLockBasename = lockBasename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const ownerPattern = new RegExp(
+    `^${escapedLockBasename}\\.owner-([a-f0-9]{32})(?:\\.reaping-(\\d+)-([A-Za-z0-9_-]{1,32})-(\\d+)-[a-f0-9]{32})?$`,
+  );
+  for (const entry of plugins.fsSync.readdirSync(directory, { withFileTypes: true })) {
+    const match = ownerPattern.exec(entry.name);
+    if (!match || !entry.isFile()) {
+      continue;
+    }
+    const ownerPath = plugins.path.join(directory, entry.name);
+    const marker = parseLockMarker(plugins.fsSync.readFileSync(ownerPath, 'utf8'), targetPathArg);
+    if (isProcessOwnershipActive(marker, ownerPath, lockLeaseTimeoutMs)) {
+      continue;
+    }
+    const baseOwnerPath = getLockOwnerPath(lockPath, match[1]);
+    const reaperOwnership = match[2]
+      ? parseReaperOwnership(baseOwnerPath, ownerPath)
+      : undefined;
+    if (match[2] && !reaperOwnership) {
+      throw new Error(`Refusing to use invalid artifact lock reaping path: ${ownerPath}`);
+    }
+    if (reaperOwnership && isReaperOwnershipActive(reaperOwnership)) {
+      continue;
+    }
+    if (plugins.fsSync.existsSync(lockPath) && sameFile(lockPath, ownerPath)) {
+      continue;
+    }
+    plugins.fsSync.rmSync(ownerPath, { force: true });
+  }
+};
+
+const getReapingPath = (ownerPathArg: string): string => (
+  `${ownerPathArg}.reaping-${process.pid}-${getProcessIdentityToken(process.pid)}-${Date.now()}-${createToken()}`
+);
+
+const parseReaperOwnership = (
+  ownerPathArg: string,
+  reapingPathArg: string,
+): IReaperOwnership | undefined => {
+  const suffix = plugins.path.basename(reapingPathArg).slice(plugins.path.basename(ownerPathArg).length);
+  const match = /^\.reaping-(\d+)-([A-Za-z0-9_-]{1,32})-(\d+)-[a-f0-9]{32}$/.exec(suffix);
+  if (!match) {
+    return undefined;
+  }
+  const processId = Number(match[1]);
+  const createdAt = Number(match[3]);
+  if (
+    !Number.isSafeInteger(processId)
+    || processId <= 0
+    || !Number.isSafeInteger(createdAt)
+    || createdAt <= 0
+  ) {
+    return undefined;
+  }
+  return {
+    processId,
+    processIdentityToken: match[2],
+    createdAt,
+  };
+};
+
+const isReaperOwnershipActive = (ownershipArg: IReaperOwnership): boolean => {
+  if (!isProcessAlive(ownershipArg.processId)) {
+    return false;
+  }
+  if (ownershipArg.processIdentityToken !== 'lease') {
+    const currentIdentity = getProcessIdentity(ownershipArg.processId);
+    if (currentIdentity) {
+      return encodeProcessIdentity(currentIdentity) === ownershipArg.processIdentityToken;
+    }
+  }
+  return Date.now() - ownershipArg.createdAt < lockLeaseTimeoutMs;
+};
+
+const claimReapingOwner = (
+  lockPathArg: string,
+  ownerPathArg: string,
+): string | undefined => {
+  const reapingPath = getReapingPath(ownerPathArg);
+  try {
+    plugins.fsSync.renameSync(ownerPathArg, reapingPath);
+    return reapingPath;
+  } catch (error: unknown) {
+    if (!hasErrorCode(error) || error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const directory = plugins.path.dirname(ownerPathArg);
+  const prefix = `${plugins.path.basename(ownerPathArg)}.reaping-`;
+  let entries: string[];
+  try {
+    entries = plugins.fsSync.readdirSync(directory).filter((entry) => entry.startsWith(prefix));
+  } catch (error: unknown) {
+    if (hasErrorCode(error) && error.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+  for (const entry of entries) {
+    const existingReapingPath = plugins.path.join(directory, entry);
+    const reaperOwnership = parseReaperOwnership(ownerPathArg, existingReapingPath);
+    if (!reaperOwnership) {
+      throw new Error(`Refusing to use invalid artifact lock reaping path: ${existingReapingPath}`);
+    }
+    if (isReaperOwnershipActive(reaperOwnership)) {
+      return undefined;
+    }
+    try {
+      plugins.fsSync.renameSync(existingReapingPath, reapingPath);
+      return reapingPath;
+    } catch (error: unknown) {
+      if (hasErrorCode(error) && error.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  // The stale lock may already have been removed between inspection and claim.
+  if (!plugins.fsSync.existsSync(lockPathArg)) {
+    return undefined;
+  }
+  return undefined;
+};
+
+const tryReapStaleLock = (targetPathArg: string): boolean => {
+  const lockPath = getLockPath(targetPathArg);
+  const marker = readLockMarker(lockPath, targetPathArg);
+  if (!marker || isProcessOwnershipActive(marker, lockPath, lockLeaseTimeoutMs)) {
+    return false;
+  }
+  const ownerPath = getLockOwnerPath(lockPath, marker.ownerToken);
+  const reapingPath = claimReapingOwner(lockPath, ownerPath);
+  if (!reapingPath) {
+    return false;
+  }
+
+  try {
+    if (plugins.fsSync.existsSync(lockPath) && sameFile(lockPath, reapingPath)) {
+      plugins.fsSync.unlinkSync(lockPath);
+    }
+  } finally {
+    plugins.fsSync.rmSync(reapingPath, { force: true });
+  }
+  return true;
+};
+
+const releaseLockOwner = (ownerArg: ILockOwner): void => {
+  let canRemoveOwner = false;
+  try {
+    if (!plugins.fsSync.existsSync(ownerArg.lockPath)) {
+      canRemoveOwner = true;
+    } else if (
+      plugins.fsSync.existsSync(ownerArg.ownerPath)
+      && sameFile(ownerArg.lockPath, ownerArg.ownerPath)
+    ) {
+      plugins.fsSync.unlinkSync(ownerArg.lockPath);
+      canRemoveOwner = true;
+    } else {
+      canRemoveOwner = true;
+    }
+  } catch (error: unknown) {
+    console.warn(`tsbundle: unable to release artifact publication lock ${ownerArg.lockPath}: ${String(error)}`);
+    try {
+      const abandonedMarker: IArtifactLockMarker = {
+        ...ownerArg.marker,
+        leaseManaged: false,
+        processId: 2_147_483_647,
+        processIdentity: '',
+      };
+      plugins.fsSync.writeFileSync(
+        ownerArg.ownerPath,
+        `${JSON.stringify(abandonedMarker, null, 2)}\n`,
+        { flag: 'w', mode: 0o600 },
+      );
+    } catch (markerError: unknown) {
+      console.warn(`tsbundle: unable to mark artifact lock abandoned ${ownerArg.ownerPath}: ${String(markerError)}`);
+    }
+  }
+  if (canRemoveOwner) {
+    try {
+      plugins.fsSync.rmSync(ownerArg.ownerPath, { force: true });
+    } catch (error: unknown) {
+      console.warn(`tsbundle: unable to remove artifact lock owner ${ownerArg.ownerPath}: ${String(error)}`);
+    }
+  }
+};
+
+export const withArtifactPublicationLock = async <T>(
+  targetPathArg: string,
+  callbackArg: () => Promise<T>,
+): Promise<T> => {
+  const resolvedTargetPath = plugins.path.resolve(targetPathArg);
+  plugins.fsSync.mkdirSync(plugins.path.dirname(resolvedTargetPath), { recursive: true });
+  cleanupOrphanLockOwners(resolvedTargetPath);
+  const owner = createLockOwner(resolvedTargetPath);
+  const deadline = Date.now() + lockWaitTimeoutMs;
+  let acquired = false;
+  let stopHeartbeat: (() => void) | undefined;
+  try {
+    while (!acquired) {
+      try {
+        plugins.fsSync.linkSync(owner.ownerPath, owner.lockPath);
+        acquired = true;
+        stopHeartbeat = startOwnershipHeartbeat(owner.ownerPath);
+      } catch (error: unknown) {
+        if (!hasErrorCode(error) || error.code !== 'EEXIST') {
+          const detail = hasErrorCode(error) ? ` (${error.code})` : '';
+          throw new Error(`Unable to acquire hard-link artifact publication lock${detail}: ${owner.lockPath}`);
+        }
+        tryReapStaleLock(resolvedTargetPath);
+        if (Date.now() >= deadline) {
+          throw new Error(`Timed out waiting for artifact publication lock: ${owner.lockPath}`);
+        }
+        await plugins.delay(25);
+      }
+    }
+    return await callbackArg();
+  } finally {
+    stopHeartbeat?.();
+    if (acquired) {
+      releaseLockOwner(owner);
+    } else {
+      plugins.fsSync.rmSync(owner.ownerPath, { force: true });
+    }
+  }
+};
+
+const getArtifactPublicationLockTargets = (
+  targetPathArg: string,
+  additionalTargetPathsArg: string[] = [],
+): string[] => {
+  const targetPath = plugins.path.resolve(targetPathArg);
+  return [...new Set([
+    targetPath,
+    plugins.path.join(plugins.path.dirname(targetPath), '.tsbundle-output-directory'),
+    ...additionalTargetPathsArg.map((additionalPath) => plugins.path.resolve(additionalPath)),
+  ])].sort((first, second) => first.localeCompare(second));
+};
+
+export const withArtifactPublicationLocks = async <T>(
+  targetPathArg: string,
+  callbackArg: () => Promise<T>,
+  additionalTargetPathsArg: string[] = [],
+): Promise<T> => {
+  const lockTargetPaths = getArtifactPublicationLockTargets(
+    targetPathArg,
+    additionalTargetPathsArg,
+  );
+  const acquireLock = async (indexArg: number): Promise<T> => {
+    if (indexArg === lockTargetPaths.length) {
+      return await callbackArg();
+    }
+    return await withArtifactPublicationLock(
+      lockTargetPaths[indexArg],
+      async () => await acquireLock(indexArg + 1),
+    );
+  };
+  return await acquireLock(0);
+};
+
+export const writeFileAtomically = (
+  targetPathArg: string,
+  contentArg: string | Buffer,
+  modeArg?: number,
+): void => {
+  const targetPath = plugins.path.resolve(targetPathArg);
+  plugins.fsSync.mkdirSync(plugins.path.dirname(targetPath), { recursive: true });
+  assertPathNotSymbolicLink(targetPath, 'artifact target');
+  if (plugins.fsSync.existsSync(targetPath) && !plugins.fsSync.lstatSync(targetPath).isFile()) {
+    throw new Error(`Refusing to replace non-file artifact target: ${targetPath}`);
+  }
+  const temporaryPath = plugins.path.join(
+    plugins.path.dirname(targetPath),
+    `.${plugins.path.basename(targetPath)}.${process.pid}.${createToken()}.tsbundle-tmp`,
+  );
+  try {
+    plugins.fsSync.writeFileSync(temporaryPath, contentArg, {
+      flag: 'wx',
+      mode: modeArg,
+    });
+    plugins.fsSync.renameSync(temporaryPath, targetPath);
+  } finally {
+    plugins.fsSync.rmSync(temporaryPath, { force: true });
+  }
+};
+
+export const getChunkNamespace = (logicalOutputNameArg: string): string => (
+  plugins.crypto
+    .createHash('sha256')
+    .update(logicalOutputNameArg)
+    .digest('base64url')
+    .slice(0, 24)
+);
+
+const getChunkNamespaceDirectory = (directoryArg: string, namespaceArg: string): string => (
+  plugins.path.join(directoryArg, 'chunks', namespaceArg)
+);
+
+const getChunkManifestPath = (namespaceDirectoryArg: string): string => (
+  plugins.path.join(namespaceDirectoryArg, chunkManifestFile)
+);
+
+const parseChunkManifest = (rawManifestArg: string): IChunkManifest | undefined => {
+  try {
+    const manifest = JSON.parse(rawManifestArg) as Partial<IChunkManifest>;
+    if (
+      manifest.owner === artifactOwner
+      && manifest.kind === chunkManifestKind
+      && typeof manifest.logicalOutputName === 'string'
+      && typeof manifest.namespace === 'string'
+      && manifest.schemaVersion === chunkManifestSchemaVersion
+    ) {
+      return manifest as IChunkManifest;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+};
+
+const readChunkManifest = (namespaceDirectoryArg: string): IChunkManifest | undefined => {
+  const manifestPath = getChunkManifestPath(namespaceDirectoryArg);
+  try {
+    assertRegularFile(manifestPath, 'chunk ownership manifest');
+    return parseChunkManifest(plugins.fsSync.readFileSync(manifestPath, 'utf8'));
+  } catch (error: unknown) {
+    if (hasErrorCode(error) && error.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+const assertOwnedChunkNamespace = (
+  namespaceDirectoryArg: string,
+  logicalOutputNameArg: string,
+  namespaceArg: string,
+): void => {
+  const manifest = readChunkManifest(namespaceDirectoryArg);
+  if (
+    !manifest
+    || manifest.logicalOutputName !== logicalOutputNameArg
+    || manifest.namespace !== namespaceArg
+  ) {
+    throw new Error(`Refusing to modify unowned chunk namespace: ${namespaceDirectoryArg}`);
+  }
+};
+
+const assertSafeArtifactTree = (directoryArg: string): void => {
+  if (!plugins.fsSync.existsSync(directoryArg)) {
+    return;
+  }
+  const stat = plugins.fsSync.lstatSync(directoryArg);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`Refusing to use unsafe generated artifact directory: ${directoryArg}`);
+  }
+  for (const entry of plugins.fsSync.readdirSync(directoryArg, { withFileTypes: true })) {
+    const entryPath = plugins.path.join(directoryArg, entry.name);
+    const entryStat = plugins.fsSync.lstatSync(entryPath);
+    if (entryStat.isSymbolicLink()) {
+      throw new Error(`Refusing to use symbolic-link generated artifact: ${entryPath}`);
+    }
+    if (entryStat.isDirectory()) {
+      assertSafeArtifactTree(entryPath);
+    } else if (!entryStat.isFile()) {
+      throw new Error(`Refusing to use non-file generated artifact: ${entryPath}`);
+    }
+  }
+};
+
+const listArtifactFiles = (directoryArg: string): string[] => {
+  if (!plugins.fsSync.existsSync(directoryArg)) {
+    return [];
+  }
+  assertSafeArtifactTree(directoryArg);
+  const files: string[] = [];
+  const collect = (currentDirectoryArg: string): void => {
+    for (const entry of plugins.fsSync.readdirSync(currentDirectoryArg, { withFileTypes: true })) {
+      const entryPath = plugins.path.join(currentDirectoryArg, entry.name);
+      if (entry.isDirectory()) {
+        collect(entryPath);
+      } else if (entry.isFile() && entry.name !== chunkManifestFile) {
+        files.push(entryPath);
+      }
+    }
+  };
+  collect(directoryArg);
+  return files.sort((first, second) => first.localeCompare(second));
+};
+
+const rebaseSourceMap = (
+  sourceMapContentArg: Buffer,
+  sourceDirectoryArg: string,
+  targetDirectoryArg: string,
+  targetFileNameArg?: string,
+): Buffer => {
+  const sourceMap = JSON.parse(sourceMapContentArg.toString('utf8')) as {
+    file?: string;
+    sourceRoot?: string;
+    sources?: string[];
+  };
+  if (Array.isArray(sourceMap.sources)) {
+    const sourceRoot = sourceMap.sourceRoot || '';
+    sourceMap.sources = sourceMap.sources.map((source) => {
+      if (/^(?:[a-z]+:|\/)/i.test(source)) {
+        return source;
+      }
+      const absoluteSource = plugins.path.resolve(sourceDirectoryArg, sourceRoot, source);
+      return plugins.path.relative(targetDirectoryArg, absoluteSource).split(plugins.path.sep).join('/');
+    });
+    if (sourceMap.sourceRoot) {
+      sourceMap.sourceRoot = '';
+    }
+  }
+  if (targetFileNameArg) {
+    sourceMap.file = targetFileNameArg;
+  }
+  return Buffer.from(JSON.stringify(sourceMap));
+};
+
+const prepareChunkArtifacts = (
+  sourceNamespaceDirectoryArg: string,
+  targetNamespaceDirectoryArg: string,
+): IPreparedArtifact[] => listArtifactFiles(sourceNamespaceDirectoryArg).map((sourcePath) => {
+  const relativePath = plugins.path.relative(sourceNamespaceDirectoryArg, sourcePath);
+  const targetPath = plugins.path.join(targetNamespaceDirectoryArg, relativePath);
+  const sourceStat = plugins.fsSync.statSync(sourcePath);
+  const sourceContent = plugins.fsSync.readFileSync(sourcePath);
+  return {
+    content: sourcePath.endsWith('.map')
+      ? rebaseSourceMap(sourceContent, sourceNamespaceDirectoryArg, targetNamespaceDirectoryArg)
+      : sourceContent,
+    mode: sourceStat.mode,
+    relativePath,
+    targetPath,
+  };
+});
+
+const snapshotFile = (pathArg: string): IFileSnapshot => {
+  if (!plugins.fsSync.existsSync(pathArg)) {
+    return { existed: false, path: pathArg };
+  }
+  assertRegularFile(pathArg, 'destination artifact');
+  const stat = plugins.fsSync.statSync(pathArg);
+  return {
+    content: plugins.fsSync.readFileSync(pathArg),
+    existed: true,
+    mode: stat.mode,
+    path: pathArg,
+  };
+};
+
+const restoreSnapshot = (snapshotArg: IFileSnapshot): void => {
+  if (snapshotArg.existed) {
+    writeFileAtomically(snapshotArg.path, snapshotArg.content!, snapshotArg.mode);
+  } else {
+    assertPathNotSymbolicLink(snapshotArg.path, 'rollback target');
+    plugins.fsSync.rmSync(snapshotArg.path, { force: true });
+  }
+};
+
+const removeEmptyDirectories = (startDirectoryArg: string, stopDirectoryArg: string): void => {
+  let currentDirectory = plugins.path.resolve(startDirectoryArg);
+  const stopDirectory = plugins.path.resolve(stopDirectoryArg);
+  while (currentDirectory !== stopDirectory && currentDirectory.startsWith(`${stopDirectory}${plugins.path.sep}`)) {
+    try {
+      plugins.fsSync.rmdirSync(currentDirectory);
+    } catch (error: unknown) {
+      if (hasErrorCode(error) && ['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code || '')) {
+        return;
+      }
+      throw error;
+    }
+    currentDirectory = plugins.path.dirname(currentDirectory);
+  }
+};
+
+const prepareAdditionalArtifacts = (
+  artifactsArg: IAdditionalArtifact[],
+  targetPathArg: string,
+  targetMapPathArg: string,
+  targetChunksDirectoryArg: string,
+  lockTargetPathsArg: string[],
+): IPreparedArtifact[] => {
+  const outputDirectory = plugins.path.dirname(targetPathArg);
+  const seenTargets = new Set<string>();
+  return artifactsArg.map((artifact) => {
+    const sourcePath = plugins.path.resolve(artifact.sourcePath);
+    const targetPath = plugins.path.resolve(artifact.targetPath);
+    assertRegularFile(sourcePath, 'included source file');
+    if (plugins.path.dirname(targetPath) !== outputDirectory) {
+      throw new Error(`Included artifact must target the bundle output directory: ${targetPath}`);
+    }
+    if (
+      targetPath === targetPathArg
+      || targetPath === targetMapPathArg
+      || lockTargetPathsArg.some((lockTargetPath) => (
+        targetPath === plugins.path.resolve(lockTargetPath)
+        || targetPath === plugins.path.resolve(getLockPath(lockTargetPath))
+      ))
+      || targetPath === targetChunksDirectoryArg
+      || targetPath.startsWith(`${targetChunksDirectoryArg}${plugins.path.sep}`)
+      || plugins.path.basename(targetPath).includes('.tsbundle-')
+    ) {
+      throw new Error(`Included artifact collides with a reserved bundle path: ${targetPath}`);
+    }
+    if (seenTargets.has(targetPath)) {
+      throw new Error(`Multiple included artifacts target the same output path: ${targetPath}`);
+    }
+    seenTargets.add(targetPath);
+    const sourceStat = plugins.fsSync.statSync(sourcePath);
+    return {
+      content: plugins.fsSync.readFileSync(sourcePath),
+      mode: sourceStat.mode,
+      targetPath,
+    };
+  });
+};
+
+const ensureChunkNamespace = (
+  namespaceDirectoryArg: string,
+  logicalOutputNameArg: string,
+  namespaceArg: string,
+): boolean => {
+  if (plugins.fsSync.existsSync(namespaceDirectoryArg)) {
+    assertSafeArtifactTree(namespaceDirectoryArg);
+    assertOwnedChunkNamespace(namespaceDirectoryArg, logicalOutputNameArg, namespaceArg);
+    return false;
+  }
+  plugins.fsSync.mkdirSync(namespaceDirectoryArg, { recursive: true });
+  try {
+    const manifest: IChunkManifest = {
+      owner: artifactOwner,
+      kind: chunkManifestKind,
+      logicalOutputName: logicalOutputNameArg,
+      namespace: namespaceArg,
+      schemaVersion: chunkManifestSchemaVersion,
+    };
+    writeFileAtomically(getChunkManifestPath(namespaceDirectoryArg), `${JSON.stringify(manifest, null, 2)}\n`);
+  } catch (error: unknown) {
+    plugins.fsSync.rmSync(namespaceDirectoryArg, { recursive: true, force: true });
+    throw error;
+  }
+  return true;
+};
+
+const reconcileChunkNamespace = (
+  namespaceDirectoryArg: string,
+  chunksDirectoryArg: string,
+  desiredRelativePathsArg: Set<string>,
+  logicalOutputNameArg: string,
+  namespaceArg: string,
+): void => {
+  if (!plugins.fsSync.existsSync(namespaceDirectoryArg)) {
+    return;
+  }
+  assertSafeArtifactTree(namespaceDirectoryArg);
+  assertOwnedChunkNamespace(namespaceDirectoryArg, logicalOutputNameArg, namespaceArg);
+  if (desiredRelativePathsArg.size === 0) {
+    plugins.fsSync.rmSync(namespaceDirectoryArg, { recursive: true, force: true });
+  } else {
+    for (const artifactPath of listArtifactFiles(namespaceDirectoryArg)) {
+      const relativePath = plugins.path.relative(namespaceDirectoryArg, artifactPath);
+      if (!desiredRelativePathsArg.has(relativePath)) {
+        plugins.fsSync.rmSync(artifactPath, { force: true });
+        removeEmptyDirectories(plugins.path.dirname(artifactPath), namespaceDirectoryArg);
+      }
+    }
+  }
+  try {
+    plugins.fsSync.rmdirSync(chunksDirectoryArg);
+  } catch (error: unknown) {
+    if (!hasErrorCode(error) || !['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code || '')) {
+      throw error;
+    }
+  }
+};
+
+export const publishGeneratedArtifacts = async (
+  optionsArg: IPublishGeneratedArtifactsOptions,
+): Promise<void> => {
+  const sourceDirectory = plugins.path.resolve(optionsArg.sourceDirectory);
+  const sourceMainPath = plugins.path.resolve(optionsArg.sourceMainPath);
+  const targetPath = plugins.path.resolve(optionsArg.targetPath);
+  const targetDirectory = plugins.path.dirname(targetPath);
+  const targetMapPath = `${targetPath}.map`;
+  const additionalLockTargets = optionsArg.lockTargetPath
+    ? [optionsArg.lockTargetPath]
+    : [];
+  const lockTargetPaths = getArtifactPublicationLockTargets(targetPath, additionalLockTargets);
+  const sourceNamespaceDirectory = getChunkNamespaceDirectory(sourceDirectory, optionsArg.chunkNamespace);
+  const targetChunksDirectory = plugins.path.join(targetDirectory, 'chunks');
+  const targetNamespaceDirectory = getChunkNamespaceDirectory(targetDirectory, optionsArg.chunkNamespace);
+
+  const publishUnderLocks = async (): Promise<void> => {
+    assertRegularFile(sourceMainPath, 'generated main bundle');
+    assertPathNotSymbolicLink(targetPath, 'bundle target');
+    assertPathNotSymbolicLink(targetMapPath, 'bundle source map target');
+    assertPathNotSymbolicLink(targetChunksDirectory, 'chunk directory');
+    if (plugins.fsSync.existsSync(targetPath)) {
+      assertRegularFile(targetPath, 'bundle target');
+    }
+    if (plugins.fsSync.existsSync(targetNamespaceDirectory)) {
+      assertSafeArtifactTree(targetNamespaceDirectory);
+      assertOwnedChunkNamespace(
+        targetNamespaceDirectory,
+        optionsArg.logicalOutputName,
+        optionsArg.chunkNamespace,
+      );
+    }
+
+    const sourceMainStat = plugins.fsSync.statSync(sourceMainPath);
+    let mainContent = plugins.fsSync.readFileSync(sourceMainPath, 'utf8');
+    const sourceMainName = plugins.path.basename(sourceMainPath);
+    const targetMainName = plugins.path.basename(targetPath);
+    const sourceMapPattern = new RegExp(
+      `//# sourceMappingURL=${sourceMainName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.map`,
+      'g',
+    );
+    mainContent = mainContent.replace(sourceMapPattern, `//# sourceMappingURL=${targetMainName}.map`);
+
+    const sourceMapPath = `${sourceMainPath}.map`;
+    let preparedMainMap: Buffer | undefined;
+    let sourceMapMode: number | undefined;
+    if (optionsArg.sourceMapsEnabled) {
+      assertRegularFile(sourceMapPath, 'generated source map');
+      preparedMainMap = rebaseSourceMap(
+        plugins.fsSync.readFileSync(sourceMapPath),
+        sourceDirectory,
+        targetDirectory,
+        targetMainName,
+      );
+      sourceMapMode = plugins.fsSync.statSync(sourceMapPath).mode;
+    }
+
+    const preparedChunks = prepareChunkArtifacts(sourceNamespaceDirectory, targetNamespaceDirectory);
+    const desiredChunkPaths = new Set(preparedChunks.map((artifact) => artifact.relativePath!));
+    for (const artifact of preparedChunks) {
+      if (plugins.fsSync.existsSync(artifact.targetPath)) {
+        assertRegularFile(artifact.targetPath, 'generated chunk target');
+        if (!plugins.fsSync.readFileSync(artifact.targetPath).equals(artifact.content)) {
+          throw new Error(`Generated chunk name collision with different content: ${artifact.targetPath}`);
+        }
+      }
+    }
+
+    const preparedAdditionalArtifacts = prepareAdditionalArtifacts(
+      optionsArg.additionalArtifacts || [],
+      targetPath,
+      targetMapPath,
+      targetChunksDirectory,
+      lockTargetPaths,
+    );
+    const additionalSnapshots = preparedAdditionalArtifacts.map((artifact) => snapshotFile(artifact.targetPath));
+    const mapSnapshot = snapshotFile(targetMapPath);
+    const newlyCreatedChunkPaths: string[] = [];
+    let namespaceCreated = false;
+    let mainCommitted = false;
+
+    try {
+      if (preparedChunks.length > 0) {
+        namespaceCreated = ensureChunkNamespace(
+          targetNamespaceDirectory,
+          optionsArg.logicalOutputName,
+          optionsArg.chunkNamespace,
+        );
+        for (const artifact of preparedChunks) {
+          if (plugins.fsSync.existsSync(artifact.targetPath)) {
+            continue;
+          }
+          writeFileAtomically(artifact.targetPath, artifact.content, artifact.mode);
+          newlyCreatedChunkPaths.push(artifact.targetPath);
+        }
+      }
+
+      for (const artifact of preparedAdditionalArtifacts) {
+        writeFileAtomically(artifact.targetPath, artifact.content, artifact.mode);
+      }
+      if (preparedMainMap) {
+        writeFileAtomically(targetMapPath, preparedMainMap, sourceMapMode);
+      }
+      writeFileAtomically(targetPath, mainContent, sourceMainStat.mode);
+      mainCommitted = true;
+    } catch (error: unknown) {
+      const rollbackErrors: unknown[] = [];
+      for (const snapshot of [...additionalSnapshots].reverse()) {
+        try {
+          restoreSnapshot(snapshot);
+        } catch (rollbackError: unknown) {
+          rollbackErrors.push(rollbackError);
+        }
+      }
+      try {
+        restoreSnapshot(mapSnapshot);
+      } catch (rollbackError: unknown) {
+        rollbackErrors.push(rollbackError);
+      }
+      try {
+        if (namespaceCreated) {
+          plugins.fsSync.rmSync(targetNamespaceDirectory, { recursive: true, force: true });
+          try {
+            plugins.fsSync.rmdirSync(targetChunksDirectory);
+          } catch (cleanupError: unknown) {
+            if (
+              !hasErrorCode(cleanupError)
+              || !['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(cleanupError.code || '')
+            ) {
+              throw cleanupError;
+            }
+          }
+        } else {
+          for (const chunkPath of [...newlyCreatedChunkPaths].reverse()) {
+            plugins.fsSync.rmSync(chunkPath, { force: true });
+            removeEmptyDirectories(plugins.path.dirname(chunkPath), targetNamespaceDirectory);
+          }
+        }
+      } catch (rollbackError: unknown) {
+        rollbackErrors.push(rollbackError);
+      }
+      if (rollbackErrors.length > 0) {
+        throw new AggregateError([error, ...rollbackErrors], 'Artifact publication failed and rollback was incomplete.');
+      }
+      throw error;
+    }
+
+    if (mainCommitted) {
+      try {
+        if (!optionsArg.sourceMapsEnabled) {
+          assertPathNotSymbolicLink(targetMapPath, 'stale source map target');
+          plugins.fsSync.rmSync(targetMapPath, { force: true });
+        }
+        reconcileChunkNamespace(
+          targetNamespaceDirectory,
+          targetChunksDirectory,
+          desiredChunkPaths,
+          optionsArg.logicalOutputName,
+          optionsArg.chunkNamespace,
+        );
+      } catch (error: unknown) {
+        console.warn(`tsbundle: output committed but stale artifact cleanup was incomplete: ${String(error)}`);
+      }
+    }
+  };
+
+  await withArtifactPublicationLocks(targetPath, publishUnderLocks, additionalLockTargets);
+};
+
+const assertBuildStageDirectory = (stageDirectoryArg: string, outputDirectoryArg: string): void => {
+  const stageDirectory = plugins.path.resolve(stageDirectoryArg);
+  const outputDirectory = plugins.path.resolve(outputDirectoryArg);
+  if (
+    plugins.path.dirname(stageDirectory) !== outputDirectory
+    || !plugins.path.basename(stageDirectory).startsWith('.tsbundle-stage-')
+  ) {
+    throw new Error(`Refusing to use unexpected build stage: ${stageDirectoryArg}`);
+  }
+  const stat = plugins.fsSync.lstatSync(stageDirectory);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`Refusing to use unsafe build stage: ${stageDirectoryArg}`);
+  }
+};
+
+const getBuildStageMarkerPath = (stageDirectoryArg: string): string => (
+  plugins.path.join(stageDirectoryArg, '.tsbundle-stage.json')
+);
+
+const parseBuildStageMarker = (rawMarkerArg: string): IBuildStageMarker | undefined => {
+  try {
+    const marker = JSON.parse(rawMarkerArg) as Partial<IBuildStageMarker>;
+    if (
+      marker.owner === artifactOwner
+      && marker.kind === buildStageKind
+      && typeof marker.processId === 'number'
+      && Number.isSafeInteger(marker.processId)
+      && marker.processId > 0
+      && (marker.processIdentity === undefined || typeof marker.processIdentity === 'string')
+      && (marker.leaseManaged === undefined || typeof marker.leaseManaged === 'boolean')
+      && typeof marker.createdAt === 'string'
+      && typeof marker.invocationId === 'string'
+      && /^[A-Za-z0-9._-]{1,128}$/.test(marker.invocationId)
+      && marker.schemaVersion === buildStageSchemaVersion
+    ) {
+      return marker as IBuildStageMarker;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+};
+
+const readBuildStageMarker = (stageDirectoryArg: string): IBuildStageMarker | undefined => {
+  try {
+    const markerPath = getBuildStageMarkerPath(stageDirectoryArg);
+    assertRegularFile(markerPath, 'build stage marker');
+    return parseBuildStageMarker(plugins.fsSync.readFileSync(markerPath, 'utf8'));
+  } catch (error: unknown) {
+    if (hasErrorCode(error) && error.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+};
+
+const buildStageMarkersMatch = (
+  firstMarkerArg: IBuildStageMarker,
+  secondMarkerArg: IBuildStageMarker,
+): boolean => (
+  firstMarkerArg.owner === secondMarkerArg.owner
+  && firstMarkerArg.kind === secondMarkerArg.kind
+  && firstMarkerArg.processId === secondMarkerArg.processId
+  && firstMarkerArg.processIdentity === secondMarkerArg.processIdentity
+  && firstMarkerArg.leaseManaged === secondMarkerArg.leaseManaged
+  && firstMarkerArg.createdAt === secondMarkerArg.createdAt
+  && firstMarkerArg.invocationId === secondMarkerArg.invocationId
+  && firstMarkerArg.schemaVersion === secondMarkerArg.schemaVersion
+);
+
+export const cleanupStaleBuildStages = (outputDirectoryArg: string): void => {
+  const outputDirectory = plugins.path.resolve(outputDirectoryArg);
+  if (!plugins.fsSync.existsSync(outputDirectory)) {
+    return;
+  }
+  for (const entry of plugins.fsSync.readdirSync(outputDirectory, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith('.tsbundle-stage-')) {
+      continue;
+    }
+    const stageDirectory = plugins.path.join(outputDirectory, entry.name);
+    let marker: IBuildStageMarker | undefined;
+    try {
+      assertBuildStageDirectory(stageDirectory, outputDirectory);
+      marker = readBuildStageMarker(stageDirectory);
+    } catch (error: unknown) {
+      if (hasErrorCode(error) && error.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
+    }
+    if (!marker) {
+      continue;
+    }
+    const createdAt = Date.parse(marker.createdAt);
+    if (
+      !Number.isFinite(createdAt)
+      || Date.now() - createdAt < staleStageThresholdMs
+      || isProcessOwnershipActive(
+        marker,
+        getBuildStageMarkerPath(stageDirectory),
+        staleStageThresholdMs,
+      )
+    ) {
+      continue;
+    }
+    const currentMarker = readBuildStageMarker(stageDirectory);
+    if (currentMarker && buildStageMarkersMatch(marker, currentMarker)) {
+      plugins.fsSync.rmSync(stageDirectory, { recursive: true, force: true });
+    }
+  }
+};
+
+export const createBuildStage = (
+  outputDirectoryArg: string,
+): { marker: IBuildStageMarker; stageDirectory: string } => {
+  const outputDirectory = plugins.path.resolve(outputDirectoryArg);
+  plugins.fsSync.mkdirSync(outputDirectory, { recursive: true });
+  assertPathNotSymbolicLink(outputDirectory, 'build output directory');
+  cleanupStaleBuildStages(outputDirectory);
+  const stageDirectory = plugins.fsSync.mkdtempSync(plugins.path.join(outputDirectory, '.tsbundle-stage-'));
+  try {
+    assertBuildStageDirectory(stageDirectory, outputDirectory);
+    const marker: IBuildStageMarker = {
+      owner: artifactOwner,
+      kind: buildStageKind,
+      ...createProcessOwnership(),
+      createdAt: new Date().toISOString(),
+      invocationId: `${process.pid}-${Date.now()}-${createToken()}`,
+      schemaVersion: buildStageSchemaVersion,
+    };
+    plugins.fsSync.writeFileSync(
+      getBuildStageMarkerPath(stageDirectory),
+      `${JSON.stringify(marker, null, 2)}\n`,
+      { flag: 'wx', mode: 0o600 },
+    );
+    buildStageHeartbeats.set(
+      stageDirectory,
+      startOwnershipHeartbeat(getBuildStageMarkerPath(stageDirectory)),
+    );
+    return { marker, stageDirectory };
+  } catch (error: unknown) {
+    plugins.fsSync.rmSync(stageDirectory, { recursive: true, force: true });
+    throw error;
+  }
+};
+
+export const cleanupBuildStage = (
+  stageDirectoryArg: string,
+  outputDirectoryArg: string,
+  expectedMarkerArg: IBuildStageMarker,
+): void => {
+  buildStageHeartbeats.get(stageDirectoryArg)?.();
+  buildStageHeartbeats.delete(stageDirectoryArg);
+  try {
+    assertBuildStageDirectory(stageDirectoryArg, outputDirectoryArg);
+    const currentMarker = readBuildStageMarker(stageDirectoryArg);
+    if (currentMarker && buildStageMarkersMatch(currentMarker, expectedMarkerArg)) {
+      plugins.fsSync.rmSync(stageDirectoryArg, { recursive: true, force: true });
+    }
+  } catch (error: unknown) {
+    if (!hasErrorCode(error) || error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+};