@napi-rs/cli 3.9.0 → 3.10.0

package/src/utils/misc.ts

@@ -44,6 +44,7 @@ import { setTimeout as delay } from 'node:timers/promises'
 
 import pkgJson from '../../package.json' with { type: 'json' }
 import { debug } from './log.js'
+import { serializeJson } from './serialize.js'
 
 export const readFileAsync = readFile
 export const writeFileAsync = writeFile
@@ -63,13 +64,25 @@ const reconciliationLockKind = 'napi-rs-filesystem-reconciliation-lock'
 const reconciliationReclaimKind = 'napi-rs-filesystem-reconciliation-reclaim'
 const reconciliationStateVersion = 1
 const reconciliationLockAcquisitionTimeout = 120_000
+// Bounds how long acquisition rides out fast probe failures before degrading
+// to lock-free operation. Slow-but-working probes are unaffected: a read that
+// returns a complete identity always wins, regardless of this budget.
+const reconciliationIdentityWaitTimeout = 10_000
 const reconciliationLockCleanupTimeout = 5_000
 const reconciliationLockCleanupRetryInterval = 250
 const reconciliationMetadataMaximumSize = 64 * 1024
 const processIncarnationCommandTimeout = 2_000
+// One-shot host identity probes run once per process and must outlive slow
+// first-start tools (e.g. powershell cold start on fresh CI VMs); per-PID
+// incarnation probes run in poll loops and keep the shorter timeout.
+const processExecutionIdentityCommandTimeout = 15_000
 const incompleteProcessExecutionIdentityCacheDuration =
   processIncarnationCommandTimeout
 const processIncarnationObservationCacheDuration = 1_000
+// A failed current-process incarnation probe (e.g. powershell hitting its
+// kill timeout on a loaded host) is retried at most this often, so a burst
+// of sequential lock acquisitions pays one probe instead of one each.
+const processIncarnationProbeRetryCooldown = 1_000
 const fileSystemTransactionJournalName = '.napi-rs-filesystem-transaction.swp'
 const fileSystemTransactionCandidateMarker = '.candidate.'
 const fileSystemTransactionRetiredMarker = '.retired.'
@@ -132,7 +145,8 @@ interface ReconciliationReclaimState {
 }
 
 type ReconciliationMetadataOwner =
-  ReconciliationLockOwner | ReconciliationReclaimOwner
+  | ReconciliationLockOwner
+  | ReconciliationReclaimOwner
 
 interface ReconciliationCandidateState {
   owner: ReconciliationMetadataOwner
@@ -147,13 +161,20 @@ interface ProcessIncarnationObservation {
   incarnation: string | null
 }
 
-interface ProcessExecutionIdentity {
+export interface ProcessExecutionIdentity {
   boot: string | null
   bootSession: string | null
   machine: string | null
   namespace: string | null
 }
 
+export interface FileSystemReconciliationOptions {
+  getProcessExecutionIdentity?: () => Promise<ProcessExecutionIdentity>
+  getProcessIncarnation?: () => Promise<string | null>
+  identityWaitTimeout?: number
+  lockAcquisitionTimeout?: number
+}
+
 interface ProcessOwnerState {
   stale: boolean
   unverifiableReason?: string
@@ -183,8 +204,6 @@ const processIncarnationObservations = new Map<
   number,
   ProcessIncarnationObservation
 >()
-let currentProcessIncarnation: string | undefined
-let currentProcessIncarnationProbe: Promise<string | null> | undefined
 let linuxBootId: string | undefined
 
 interface TransactionParentIdentity {
@@ -345,6 +364,7 @@ export async function copyFileAtomic(
 export async function withFileSystemReconciliation<T>(
   path: string,
   operation: () => Promise<T>,
+  options?: FileSystemReconciliationOptions,
 ): Promise<T> {
   const localKey = resolve(path)
   const previous = reconciliationTails.get(localKey) ?? Promise.resolve()
@@ -356,21 +376,54 @@ export async function withFileSystemReconciliation<T>(
   reconciliationTails.set(localKey, tail)
 
   const releaseCrossProcessLocks: Array<() => Promise<void>> = []
+  let lockAcquisitionDegraded = false
   let operationFailed = false
   let operationError: unknown
   let result!: T
   try {
     await previous.catch(() => {})
     const identities = await resolveReconciliationLockIdentities(path)
+    const injectedIdentityGetter = options?.getProcessExecutionIdentity
+    const identityWaitTimeout =
+      options?.identityWaitTimeout ?? reconciliationIdentityWaitTimeout
+    // Injected getters bypass the degraded-decision memo entirely; only the
+    // default singleton path memoizes so one build pays the wait once.
+    const resolveExecutionIdentity =
+      (): Promise<ProcessExecutionIdentityResolution> =>
+        injectedIdentityGetter === undefined
+          ? resolveDefaultProcessExecutionIdentityForLocking(
+              identityWaitTimeout,
+            )
+          : resolveProcessExecutionIdentityForLocking(
+              injectedIdentityGetter,
+              createReconciliationLockDeadline(identityWaitTimeout),
+            )
+    const getProcessExecutionIdentity =
+      injectedIdentityGetter ?? getCurrentProcessExecutionIdentity
+    const getProcessIncarnation =
+      options?.getProcessIncarnation ?? getCurrentProcessIncarnation
     const acquisitionDeadline = createReconciliationLockDeadline(
-      reconciliationLockAcquisitionTimeout,
+      options?.lockAcquisitionTimeout ?? reconciliationLockAcquisitionTimeout,
     )
     for (const identity of identities) {
-      releaseCrossProcessLocks.push(
-        await acquireReconciliationLock(identity, acquisitionDeadline),
+      const acquisition = await acquireReconciliationLock(
+        identity,
+        acquisitionDeadline,
+        resolveExecutionIdentity,
+        getProcessExecutionIdentity,
+        getProcessIncarnation,
       )
+      releaseCrossProcessLocks.push(acquisition.release)
+      lockAcquisitionDegraded ||= acquisition.degraded
+    }
+    if (!lockAcquisitionDegraded) {
+      // Recovery assumes cross-process exclusivity: without a verifiable lock
+      // it could roll back a live transaction, so degraded (lock-free) hosts
+      // keep pre-3.8.0 behavior and skip it. A genuinely crashed journal then
+      // fails the next transaction publish loudly and is recovered by the
+      // next run whose identity probes succeed.
+      await recoverFileSystemTransaction(identities[0].anchorPath)
     }
-    await recoverFileSystemTransaction(identities[0].anchorPath)
     const currentCapability = fileSystemReconciliationCapability.getStore()
     const roots = new Set(currentCapability?.roots)
     roots.add(fileSystemReconciliationCapabilityRoot(identities[0].anchorPath))
@@ -561,13 +614,18 @@ export async function withPackageFileSystemReconciliation<T>(
     'boundary' | 'cwd' | 'packageRoot'
   >,
   operation: () => Promise<T>,
+  options?: FileSystemReconciliationOptions,
 ): Promise<T> {
   const roots = getPackageReconciliationRoots(paths)
   const acquire = (index: number): Promise<T> => {
     if (index === roots.length) {
       return operation()
     }
-    return withFileSystemReconciliation(roots[index], () => acquire(index + 1))
+    return withFileSystemReconciliation(
+      roots[index],
+      () => acquire(index + 1),
+      options,
+    )
   }
 
   // Build takes the package lock before widening to its transaction root.
@@ -1567,16 +1625,25 @@ async function resolveReconciliationLockIdentities(
   if (!anchorStats.isDirectory()) {
     throw reconciliationAnchorError(anchorPath, 'is not a directory', 'ENOTDIR')
   }
-  const guardKeys = new Set<string>()
+  const guardKeys = new Map<string, string | undefined>()
   if (await directoryIsWritable(dirname(anchorPath))) {
-    guardKeys.add(anchorPath)
+    guardKeys.set(anchorPath, undefined)
   }
   let currentPath = requestedPath
   while (true) {
     const currentStats = await lstatIfExists(currentPath)
     if (currentStats?.isSymbolicLink()) {
-      if (await directoryIsWritable(dirname(currentPath))) {
-        guardKeys.add(currentPath)
+      // Far-ancestor symlink guards scatter locks outside the project (up to
+      // a writable filesystem root, #3444); topology swaps are still caught
+      // fail-safe by the anchor assertions, so a guard is kept only where its
+      // lock stays within the anchor's parent. The lock root is resolved once
+      // here at walk time so the checked root is the root used.
+      const lockRoot = await realpath(dirname(currentPath))
+      if (
+        managedPackagePathIsWithin(dirname(anchorPath), lockRoot) &&
+        (await directoryIsWritable(dirname(currentPath)))
+      ) {
+        guardKeys.set(currentPath, lockRoot)
       }
     }
     const parent = dirname(currentPath)
@@ -1587,8 +1654,8 @@ async function resolveReconciliationLockIdentities(
   }
 
   const pathIdentities = await Promise.all(
-    [...guardKeys].map(async (key) => {
-      const lockRootPath = await realpath(dirname(key))
+    [...guardKeys].map(async ([key, carriedLockRoot]) => {
+      const lockRootPath = carriedLockRoot ?? (await realpath(dirname(key)))
       const lockRootStats = await lstat(lockRootPath, { bigint: true })
       if (!lockRootStats.isDirectory()) {
         throw reconciliationPathCollisionError(
@@ -1784,11 +1851,14 @@ function reconciliationRetiredPath(path: string) {
 async function acquireReconciliationLock(
   identity: ReconciliationLockIdentity,
   acquisitionDeadline: ReconciliationLockDeadline,
+  resolveExecutionIdentity: () => Promise<ProcessExecutionIdentityResolution>,
+  getProcessExecutionIdentity: () => Promise<ProcessExecutionIdentity>,
+  getProcessIncarnation: () => Promise<string | null>,
 ) {
   const { key } = identity
-  const [incarnation, executionIdentity] = await Promise.all([
-    getCurrentProcessIncarnation(),
-    getCurrentProcessExecutionIdentity(),
+  const [incarnation, identityResolution] = await Promise.all([
+    getProcessIncarnation(),
+    resolveExecutionIdentity(),
   ])
   const lockPath = reconciliationLockPath(identity)
   await assertReconciliationAnchorUnchanged(identity)
@@ -1805,6 +1875,53 @@ async function acquireReconciliationLock(
     isReconciliationReclaimOwner,
   )
 
+  let executionIdentity = identityResolution.identity
+  if (!identityResolution.complete) {
+    // Degraded (lock-free) wait: on hosts that cannot provide a complete
+    // execution identity (FreeBSD, containers without /etc/machine-id,
+    // policy-blocked Windows tools), skipping the owner write preserves
+    // pre-reconciliation (3.7.4) behavior for uncontended builds; an owner we
+    // cannot write verifiably could never be reclaimed. An existing lock is
+    // still respected fail-closed: never bypassed, and an error only if it
+    // outlives the acquisition deadline.
+    while (true) {
+      await waitForReconciliationReclaim(identity, acquisitionDeadline)
+      const state = await inspectReconciliationLock(identity, lockPath)
+      if (state === undefined) {
+        debug.warn(
+          `Skipping cross-process filesystem reconciliation lock for ${key}: the system did not provide a complete machine, boot-session, and process-namespace identity (missing: ${missingProcessExecutionIdentityComponents(executionIdentity)})`,
+        )
+        return { release: async () => {}, degraded: true }
+      }
+      // Re-probe with the raw getter every iteration: a transient probe
+      // failure heals here, and the existing lock can then be evaluated and
+      // reclaimed through the normal path instead of failing at the deadline.
+      const healedIdentity = await getProcessExecutionIdentity()
+      if (isCompleteProcessExecutionIdentity(healedIdentity)) {
+        degradedProcessExecutionIdentityMemo = undefined
+        executionIdentity = healedIdentity
+        break
+      }
+      if (performance.now() >= acquisitionDeadline.expiresAt) {
+        throw reconciliationExecutionIdentityUnavailableError(
+          key,
+          healedIdentity,
+        )
+      }
+      try {
+        await delayReconciliationLockRetry(acquisitionDeadline, key)
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ETIMEDOUT') {
+          throw reconciliationExecutionIdentityUnavailableError(
+            key,
+            healedIdentity,
+          )
+        }
+        throw error
+      }
+    }
+  }
+
   while (true) {
     assertReconciliationLockAcquisitionTimeRemaining(acquisitionDeadline, key)
     await assertReconciliationAnchorUnchanged(identity)
@@ -1854,7 +1971,14 @@ async function acquireReconciliationLock(
       if (
         state?.owner &&
         state.stale &&
-        (await tryReclaimStaleReconciliationLock(identity, lockPath, state))
+        (await tryReclaimStaleReconciliationLock(
+          identity,
+          lockPath,
+          state,
+          getProcessExecutionIdentity,
+          getProcessIncarnation,
+          acquisitionDeadline,
+        ))
       ) {
         continue
       }
@@ -1876,7 +2000,15 @@ async function acquireReconciliationLock(
           `Lost filesystem reconciliation lock ownership before initialization: ${key}`,
         )
       }
-      return maintainReconciliationLock(identity, lockPath, lockStats, token)
+      return {
+        release: maintainReconciliationLock(
+          identity,
+          lockPath,
+          lockStats,
+          token,
+        ),
+        degraded: false,
+      }
     } catch (error) {
       await cleanupFailedReconciliationLock(
         identity,
@@ -2385,13 +2517,26 @@ async function tryReclaimStaleReconciliationLock(
   identity: ReconciliationLockIdentity,
   lockPath: string,
   expectedState: ReconciliationLockState,
+  getProcessExecutionIdentity: () => Promise<ProcessExecutionIdentity>,
+  getProcessIncarnation: () => Promise<string | null>,
+  acquisitionDeadline: ReconciliationLockDeadline,
 ) {
   const reclaimPath = reconciliationReclaimPath(identity)
   const token = randomUUID()
-  const [incarnation, executionIdentity] = await Promise.all([
-    getCurrentProcessIncarnation(),
-    getCurrentProcessExecutionIdentity(),
+  const [incarnation, identityResolution] = await Promise.all([
+    getProcessIncarnation(),
+    resolveProcessExecutionIdentityForLocking(
+      getProcessExecutionIdentity,
+      acquisitionDeadline,
+    ),
   ])
+  // Never publish a reclaim owner with incomplete identity; an unverifiable
+  // reclaim owner could never be reclaimed itself. Reachable in practice only
+  // when the current side already proved complete (state.stale requires it).
+  if (!identityResolution.complete) {
+    return false
+  }
+  const executionIdentity = identityResolution.identity
   const reclaimOwner: ReconciliationReclaimOwner = {
     candidate: reconciliationCandidateName(reclaimPath, token),
     createdAt: Date.now(),
@@ -3131,6 +3276,32 @@ function reconciliationHardLinkRequiredError(path: string, cause: unknown) {
   return error
 }
 
+function missingProcessExecutionIdentityComponents(
+  identity: ProcessExecutionIdentity,
+) {
+  return (
+    [
+      ['machine', identity.machine],
+      ['boot', identity.boot],
+      ['namespace', identity.namespace],
+    ] as const
+  )
+    .filter(([, value]) => value === null)
+    .map(([name]) => name)
+    .join(', ')
+}
+
+function reconciliationExecutionIdentityUnavailableError(
+  key: string,
+  identity: ProcessExecutionIdentity,
+) {
+  const error = new Error(
+    `Filesystem reconciliation lock was not created for ${key}: the system did not provide a complete machine, boot-session, and process-namespace identity (missing: ${missingProcessExecutionIdentityComponents(identity)}), and an existing reconciliation lock cannot be evaluated without it. On Windows this means reg.exe or powershell.exe was blocked or too slow; retry the build or unblock those tools`,
+  ) as NodeJS.ErrnoException
+  error.code = 'EAGAIN'
+  return error
+}
+
 function reconciliationOwnerCannotBeVerifiedError(
   path: string,
   owner: ReconciliationMetadataOwner,
@@ -3335,34 +3506,59 @@ function processExists(pid: number) {
   }
 }
 
-function getCurrentProcessIncarnation() {
-  if (currentProcessIncarnation !== undefined) {
-    return Promise.resolve(currentProcessIncarnation)
-  }
-  if (currentProcessIncarnationProbe !== undefined) {
-    return currentProcessIncarnationProbe
+export function createProcessIncarnationGetter(
+  readIncarnation: () => Promise<string | null>,
+  failureRetryCooldown: number,
+  now: () => number = () => performance.now(),
+) {
+  // The current process incarnation is fixed for the process lifetime; only
+  // the probe reading it can fail. A success is cached forever and an
+  // in-flight probe is shared. A failure is reused for the cooldown window
+  // so a burst of sequential lock acquisitions on a probe-failing host (e.g.
+  // powershell hitting its kill timeout under load) spawns one probe instead
+  // of one per acquisition.
+  let incarnation: string | undefined
+  let activeProbe: Promise<string | null> | undefined
+  let retryAt = 0
+  return function getProcessIncarnation() {
+    if (incarnation !== undefined) {
+      return Promise.resolve(incarnation)
+    }
+    if (activeProbe !== undefined) {
+      return activeProbe
+    }
+    if (now() < retryAt) {
+      return Promise.resolve(null)
+    }
+    const probe = readIncarnation()
+    activeProbe = probe
+    void probe.then(
+      (observed) => {
+        if (observed !== null) {
+          incarnation = observed
+        } else {
+          retryAt = now() + failureRetryCooldown
+        }
+        if (activeProbe === probe) {
+          activeProbe = undefined
+        }
+      },
+      () => {
+        retryAt = now() + failureRetryCooldown
+        if (activeProbe === probe) {
+          activeProbe = undefined
+        }
+      },
+    )
+    return probe
   }
-
-  const probe = readProcessIncarnation(process.pid)
-  currentProcessIncarnationProbe = probe
-  void probe.then(
-    (incarnation) => {
-      if (incarnation !== null) {
-        currentProcessIncarnation = incarnation
-      }
-      if (currentProcessIncarnationProbe === probe) {
-        currentProcessIncarnationProbe = undefined
-      }
-    },
-    () => {
-      if (currentProcessIncarnationProbe === probe) {
-        currentProcessIncarnationProbe = undefined
-      }
-    },
-  )
-  return probe
 }
 
+const getCurrentProcessIncarnation = createProcessIncarnationGetter(
+  () => readProcessIncarnation(process.pid),
+  processIncarnationProbeRetryCooldown,
+)
+
 export function createProcessExecutionIdentityGetter(
   readIdentity: () => Promise<ProcessExecutionIdentity>,
   incompleteCacheDuration: number,
@@ -3440,11 +3636,74 @@ function isCompleteProcessExecutionIdentity(
   )
 }
 
+// An owner written with an incomplete identity can never be verified or
+// reclaimed (processOwnerState fails closed), so publishing one would wedge
+// the lock until manual cleanup. Re-probe within the wait budget instead, then
+// report the outcome: callers degrade to lock-free operation rather than fail.
+// Slow-but-working probes win on the first read regardless of the budget; the
+// budget only bounds riding out fast probe failures.
+export async function resolveProcessExecutionIdentityForLocking(
+  getIdentity: () => Promise<ProcessExecutionIdentity>,
+  waitBudget: ReconciliationLockDeadline,
+): Promise<
+  | { complete: true; identity: ProcessExecutionIdentity }
+  | { complete: false; identity: ProcessExecutionIdentity }
+> {
+  while (true) {
+    const identity = await getIdentity()
+    if (isCompleteProcessExecutionIdentity(identity)) {
+      return { complete: true, identity }
+    }
+    if (performance.now() >= waitBudget.expiresAt) {
+      return { complete: false, identity }
+    }
+    await delay(
+      Math.max(0, Math.min(20, waitBudget.expiresAt - performance.now())),
+    )
+  }
+}
+
+type ProcessExecutionIdentityResolution = Awaited<
+  ReturnType<typeof resolveProcessExecutionIdentityForLocking>
+>
+
 const getCurrentProcessExecutionIdentity = createProcessExecutionIdentityGetter(
   readProcessExecutionIdentity,
   incompleteProcessExecutionIdentityCacheDuration,
 )
 
+const degradedProcessExecutionIdentityMemoDuration = 30_000
+// One build pays the probe-failure wait once: a degraded outcome is memoized
+// briefly so later acquisitions in this process skip the wait loop. 30s
+// outlives a single build but not separate invocations.
+let degradedProcessExecutionIdentityMemo: { decidedAt: number } | undefined
+
+async function resolveDefaultProcessExecutionIdentityForLocking(
+  identityWaitTimeout: number,
+): Promise<ProcessExecutionIdentityResolution> {
+  const memo = degradedProcessExecutionIdentityMemo
+  if (
+    memo !== undefined &&
+    performance.now() - memo.decidedAt <
+      degradedProcessExecutionIdentityMemoDuration
+  ) {
+    const identity = await getCurrentProcessExecutionIdentity()
+    if (isCompleteProcessExecutionIdentity(identity)) {
+      degradedProcessExecutionIdentityMemo = undefined
+      return { complete: true, identity }
+    }
+    return { complete: false, identity }
+  }
+  const resolution = await resolveProcessExecutionIdentityForLocking(
+    getCurrentProcessExecutionIdentity,
+    createReconciliationLockDeadline(identityWaitTimeout),
+  )
+  degradedProcessExecutionIdentityMemo = resolution.complete
+    ? undefined
+    : { decidedAt: performance.now() }
+  return resolution
+}
+
 async function readProcessExecutionIdentity(): Promise<ProcessExecutionIdentity> {
   if (process.platform === 'linux') {
     const [bootId, machineId, productUuid, pidNamespace] = await Promise.all([
@@ -3481,19 +3740,29 @@ async function readProcessExecutionIdentity(): Promise<ProcessExecutionIdentity>
         )
       : 'powershell.exe'
     const [machineOutput, boot] = await Promise.all([
-      executeProcessIncarnationCommand(reg, [
-        'query',
-        String.raw`HKLM\SOFTWARE\Microsoft\Cryptography`,
-        '/v',
-        'MachineGuid',
-      ]),
-      executeProcessIncarnationCommand(powershell, [
-        '-NoLogo',
-        '-NoProfile',
-        '-NonInteractive',
-        '-Command',
-        '(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().Ticks',
-      ]),
+      executeProcessIncarnationCommand(
+        reg,
+        [
+          'query',
+          String.raw`HKLM\SOFTWARE\Microsoft\Cryptography`,
+          '/v',
+          'MachineGuid',
+        ],
+        process.env,
+        processExecutionIdentityCommandTimeout,
+      ),
+      executeProcessIncarnationCommand(
+        powershell,
+        [
+          '-NoLogo',
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          '(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().Ticks',
+        ],
+        process.env,
+        processExecutionIdentityCommandTimeout,
+      ),
     ])
     const machineGuid = machineOutput?.match(
       /\bMachineGuid\s+REG_SZ\s+([0-9a-f-]+)\s*$/i,
@@ -3510,19 +3779,24 @@ async function readProcessExecutionIdentity(): Promise<ProcessExecutionIdentity>
   if (process.platform === 'darwin') {
     const [machineOutput, bootSessionOutput, bootTimeOutput] =
       await Promise.all([
-        executeProcessIncarnationCommand('/usr/sbin/ioreg', [
-          '-rd1',
-          '-c',
-          'IOPlatformExpertDevice',
-        ]),
-        executeProcessIncarnationCommand('/usr/sbin/sysctl', [
-          '-n',
-          'kern.bootsessionuuid',
-        ]),
-        executeProcessIncarnationCommand('/usr/sbin/sysctl', [
-          '-n',
-          'kern.boottime',
-        ]),
+        executeProcessIncarnationCommand(
+          '/usr/sbin/ioreg',
+          ['-rd1', '-c', 'IOPlatformExpertDevice'],
+          process.env,
+          processExecutionIdentityCommandTimeout,
+        ),
+        executeProcessIncarnationCommand(
+          '/usr/sbin/sysctl',
+          ['-n', 'kern.bootsessionuuid'],
+          process.env,
+          processExecutionIdentityCommandTimeout,
+        ),
+        executeProcessIncarnationCommand(
+          '/usr/sbin/sysctl',
+          ['-n', 'kern.boottime'],
+          process.env,
+          processExecutionIdentityCommandTimeout,
+        ),
       ])
     const platformUuid = machineOutput?.match(
       /"IOPlatformUUID"\s*=\s*"([0-9a-f-]+)"/i,
@@ -3685,6 +3959,7 @@ function executeProcessIncarnationCommand(
   command: string,
   args: string[],
   env: NodeJS.ProcessEnv = process.env,
+  timeout: number = processIncarnationCommandTimeout,
 ): Promise<string | null> {
   return new Promise((resolveCommand) => {
     execFile(
@@ -3693,7 +3968,7 @@ function executeProcessIncarnationCommand(
       {
         encoding: 'utf8',
         env,
-        timeout: processIncarnationCommandTimeout,
+        timeout,
         windowsHide: true,
       },
       (error, stdout) => {
@@ -6153,10 +6428,7 @@ export async function updatePackageJson(
     return
   }
   const old = JSON.parse(await readFileAsync(path, 'utf8'))
-  await writeFileAsync(
-    path,
-    JSON.stringify(mergePackageJson(old, partial), null, 2),
-  )
+  await writeFileAsync(path, serializeJson(mergePackageJson(old, partial)))
 }
 
 export const CLI_VERSION = pkgJson.version

package/src/utils/serialize.ts

@@ -0,0 +1,47 @@
+import { stringify as stringifyToml } from '@std/toml'
+import { dump as yamlDump } from 'js-yaml'
+
+/**
+ * Canonical JSON for files the CLI writes (package.json, napi config).
+ *
+ * Always 2-space indent and a POSIX trailing newline. Callers must not
+ * add another `\n` or omit one — every JSON writer uses this helper.
+ */
+export function serializeJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`
+}
+
+/**
+ * Canonical TOML for files the CLI rewrites (Cargo.toml).
+ *
+ * `@std/toml` stringify inserts a leading blank line and drops comments.
+ * We cannot preserve comments through parse→stringify. We only strip the
+ * leading blank and keep exactly one trailing newline — no regex rewrite
+ * of array contents, which would split commas inside quoted strings.
+ */
+export function serializeToml(value: Record<string, unknown>): string {
+  let serialized = stringifyToml(value)
+  if (serialized.startsWith('\n')) {
+    serialized = serialized.slice(1)
+  }
+  if (!serialized.endsWith('\n')) {
+    serialized += '\n'
+  }
+  return serialized
+}
+
+/**
+ * Canonical YAML for files the CLI rewrites (GitHub Actions workflows).
+ *
+ * Matches `napi new` / `napi rename` dump options and always ends with a
+ * trailing newline. Blank lines from the original document are not
+ * preserved — js-yaml dump cannot round-trip those.
+ */
+export function serializeYaml(value: unknown): string {
+  const serialized = yamlDump(value, {
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false,
+  })
+  return serialized.endsWith('\n') ? serialized : `${serialized}\n`
+}