@napi-rs/cli 3.7.4 → 3.8.0

package/src/api/templates/wasi-worker-template.ts

@@ -6,7 +6,13 @@ import { parentPort, Worker } from "node:worker_threads";
 
 const require = createRequire(import.meta.url);
 
-const { instantiateNapiModuleSync, MessageHandler, getDefaultContext } = require("@napi-rs/wasm-runtime");
+const {
+  instantiateNapiModuleSync,
+  MessageHandler,
+  getDefaultContext,
+  emnapiAsyncWorkPlugin,
+  emnapiTSFNPlugin,
+} = require("@napi-rs/wasm-runtime");
 
 if (parentPort) {
   parentPort.on("message", (data) => {
@@ -46,6 +52,11 @@ const handler = new MessageHandler({
       childThread: true,
       wasi,
       context: emnapiContext,
+      // The wasm links a "basic" emnapi archive (no C async-work /
+      // threadsafe-function implementations), so every thread that
+      // instantiates it must provide the JavaScript implementations
+      // through the emnapi plugins.
+      plugins: [emnapiAsyncWorkPlugin, emnapiTSFNPlugin],
       overwriteImports(importObject) {
         importObject.env = {
           ...importObject.env,
@@ -68,11 +79,24 @@ export const createWasiBrowserWorkerBinding = (
   errorEvent: boolean,
 ) => {
   const fsImport = fs
-    ? `import { instantiateNapiModuleSync, MessageHandler, WASI, createFsProxy } from '@napi-rs/wasm-runtime'
+    ? `import {
+  instantiateNapiModuleSync,
+  MessageHandler,
+  WASI,
+  createFsProxy,
+  emnapiAsyncWorkPlugin,
+  emnapiTSFNPlugin,
+} from '@napi-rs/wasm-runtime'
 import { memfsExported as __memfsExported } from '@napi-rs/wasm-runtime/fs'
 
 const fs = createFsProxy(__memfsExported)`
-    : `import { instantiateNapiModuleSync, MessageHandler, WASI } from '@napi-rs/wasm-runtime'`
+    : `import {
+  instantiateNapiModuleSync,
+  MessageHandler,
+  WASI,
+  emnapiAsyncWorkPlugin,
+  emnapiTSFNPlugin,
+} from '@napi-rs/wasm-runtime'`
   const errorOutputsAppend = errorEvent
     ? `\n        errorOutputs.push([...arguments])`
     : ''
@@ -118,6 +142,11 @@ const handler = new MessageHandler({
     return instantiateNapiModuleSync(wasmModule, {
       childThread: true,
       wasi,
+      // The wasm links a "basic" emnapi archive (no C async-work /
+      // threadsafe-function implementations), so every thread that
+      // instantiates it must provide the JavaScript implementations
+      // through the emnapi plugins.
+      plugins: [emnapiAsyncWorkPlugin, emnapiTSFNPlugin],
       overwriteImports(importObject) {
         importObject.env = {
           ...importObject.env,

package/src/commands/rename.ts

@@ -6,14 +6,19 @@ import { BaseRenameCommand } from '../def/rename.js'
 export class RenameCommand extends BaseRenameCommand {
   async execute() {
     const options = this.getOptions()
-    if (!options.name) {
+    const hasExplicitRename = [
+      options.name,
+      options.binaryName,
+      options.packageName,
+      options.repository,
+      options.description,
+    ].some((value) => value !== undefined)
+    if (!hasExplicitRename) {
       const name = await input({
         message: `Enter the new package name in the package.json`,
         required: true,
       })
       options.name = name
-    }
-    if (!options.binaryName) {
       const binaryName = await input({
         message: `Enter the new binary name`,
         required: true,

package/src/def/artifacts.ts

@@ -34,7 +34,7 @@ export abstract class BaseArtifactsCommand extends Command {
 
   buildOutputDir?: string = Option.String('--build-output-dir', {
     description:
-      'Path to the build output dir, only needed when targets contains `wasm32-wasi-*`',
+      'Path to the build output dir, only needed when targets contain a WASI target',
   })
 
   getOptions() {
@@ -82,7 +82,7 @@ export interface ArtifactsOptions {
    */
   npmDir?: string
   /**
-   * Path to the build output dir, only needed when targets contains `wasm32-wasi-*`
+   * Path to the build output dir, only needed when targets contain a WASI target
    */
   buildOutputDir?: string
 }

package/src/utils/__tests__/__snapshots__/target.spec.ts.md

@@ -167,8 +167,8 @@ Generated by [AVA](https://avajs.dev).
         abi: 'wasi',
         arch: 'wasm32',
         platform: 'wasi',
-        platformArchABI: 'wasm32-wasi',
-        triple: 'wasm32-wasi-preview1-threads',
+        platformArchABI: 'wasm32-wasip1',
+        triple: 'wasm32-wasip1',
       },
       {
         abi: 'wasi',

package/src/utils/__tests__/misc.spec.ts

@@ -1,11 +1,29 @@
-import { existsSync } from 'node:fs'
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { existsSync, type BigIntStats } from 'node:fs'
+import {
+  lstat,
+  mkdtemp,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
 import ava, { type TestFn } from 'ava'
 
-import { updatePackageJson } from '../misc.js'
+import {
+  retireFailedSnapshotLeftover,
+  snapshotLeftoverIsTransactionOwned,
+  statIdentitiesMatch,
+  updatePackageJson,
+} from '../misc.js'
+
+async function fileIdentityStrings(path: string) {
+  const stats = await lstat(path, { bigint: true })
+  return { dev: String(stats.dev), ino: String(stats.ino) }
+}
 
 const test = ava as TestFn<{
   tmpDir: string
@@ -54,3 +72,106 @@ test('updatePackageJson merges nested objects instead of overwriting them', asyn
     '@napi-rs/fixture-darwin-arm64': '1.0.1',
   })
 })
+
+test('statIdentitiesMatch distinguishes inodes that collide as lossy Numbers', (t) => {
+  const dev = 1n
+  const ino = 2n ** 53n
+  const owned = { dev, ino }
+  const successor = { dev, ino: ino + 1n }
+
+  // The defect being guarded against: past Number.MAX_SAFE_INTEGER two
+  // distinct 64-bit identifiers collapse onto the same JS double, so a
+  // numeric Stats.dev/ino comparison cannot tell these files apart.
+  t.is(Number(owned.ino), Number(successor.ino))
+
+  t.false(statIdentitiesMatch(owned, successor))
+  t.false(statIdentitiesMatch({ dev: dev + 1n, ino }, owned))
+  t.true(statIdentitiesMatch(owned, { dev, ino }))
+  t.false(statIdentitiesMatch(owned, undefined))
+})
+
+test('snapshotLeftoverIsTransactionOwned rejects Number-colliding successors', (t) => {
+  const identity = { dev: '1', ino: String(2n ** 53n) }
+  const ownedStats = {
+    isFile: () => true,
+    dev: 1n,
+    ino: 2n ** 53n,
+  } as unknown as BigIntStats
+  const successorStats = {
+    isFile: () => true,
+    dev: 1n,
+    ino: 2n ** 53n + 1n,
+  } as unknown as BigIntStats
+
+  t.true(snapshotLeftoverIsTransactionOwned(ownedStats, identity))
+  t.false(snapshotLeftoverIsTransactionOwned(successorStats, identity))
+  t.false(snapshotLeftoverIsTransactionOwned(undefined, identity))
+})
+
+test('retireFailedSnapshotLeftover removes the transaction-owned inode', async (t) => {
+  const destination = join(t.context.tmpDir, 'leftover.tmp')
+  await writeFile(destination, 'partial snapshot')
+  const identity = await fileIdentityStrings(destination)
+
+  const result = await retireFailedSnapshotLeftover(destination, identity)
+
+  t.deepEqual(result, { outcome: 'removed' })
+  t.false(existsSync(destination))
+  t.deepEqual(await readdir(t.context.tmpDir), [])
+})
+
+test('retireFailedSnapshotLeftover reports a missing leftover', async (t) => {
+  const destination = join(t.context.tmpDir, 'leftover.tmp')
+  await writeFile(destination, 'partial snapshot')
+  const identity = await fileIdentityStrings(destination)
+  await rm(destination)
+
+  const result = await retireFailedSnapshotLeftover(destination, identity)
+
+  t.deepEqual(result, { outcome: 'missing' })
+  t.deepEqual(await readdir(t.context.tmpDir), [])
+})
+
+test('retireFailedSnapshotLeftover keeps a pre-existing non-owned successor', async (t) => {
+  const destination = join(t.context.tmpDir, 'leftover.tmp')
+  await writeFile(destination, 'partial snapshot')
+  const identity = await fileIdentityStrings(destination)
+
+  // Replace the owned inode with a distinct one before cleanup runs. The
+  // successor is created as a sibling first so it deterministically has a
+  // different inode, then atomically renamed over the destination.
+  const successor = join(t.context.tmpDir, 'successor.tmp')
+  await writeFile(successor, 'successor content')
+  await rename(successor, destination)
+
+  const result = await retireFailedSnapshotLeftover(destination, identity)
+
+  t.deepEqual(result, { outcome: 'kept' })
+  t.is(await readFile(destination, 'utf8'), 'successor content')
+  t.deepEqual(await readdir(t.context.tmpDir), ['leftover.tmp'])
+})
+
+test('retireFailedSnapshotLeftover restores a successor swapped in during the race window', async (t) => {
+  const destination = join(t.context.tmpDir, 'leftover.tmp')
+  await writeFile(destination, 'partial snapshot')
+  const identity = await fileIdentityStrings(destination)
+
+  const successor = join(t.context.tmpDir, 'successor.tmp')
+  await writeFile(successor, 'successor content')
+
+  // Swap the successor onto the pathname after the ownership pre-check and
+  // before the retirement rename — the exact interval in which the previous
+  // lstat-then-unlink cleanup would have deleted a file the transaction never
+  // owned.
+  const result = await retireFailedSnapshotLeftover(
+    destination,
+    identity,
+    async () => {
+      await rename(successor, destination)
+    },
+  )
+
+  t.deepEqual(result, { outcome: 'kept' })
+  t.is(await readFile(destination, 'utf8'), 'successor content')
+  t.deepEqual(await readdir(t.context.tmpDir), ['leftover.tmp'])
+})

package/src/utils/__tests__/version.spec.ts

@@ -1,7 +1,53 @@
 import test from 'ava'
 
-import { napiEngineRequirement, SUPPORTED_NAPI_VERSIONS } from '../version.js'
+import {
+  MINIMUM_WASI_NODE_VERSION,
+  napiEngineRequirement,
+  restrictWasiNodeEngine,
+  SUPPORTED_NAPI_VERSIONS,
+} from '../version.js'
 
 test('should generate correct napi engine requirement', (t) => {
   t.snapshot(SUPPORTED_NAPI_VERSIONS.map(napiEngineRequirement))
 })
+
+test('should keep node engine ranges inside the WASI floor', (t) => {
+  t.is(restrictWasiNodeEngine('^22.14.0'), '^22.14.0')
+  t.is(restrictWasiNodeEngine('>=24'), '>=24')
+})
+
+test('should return the WASI floor for superset node engine ranges', (t) => {
+  t.is(restrictWasiNodeEngine('>=18'), MINIMUM_WASI_NODE_VERSION)
+  t.is(restrictWasiNodeEngine('>=12 <14 || >=18'), MINIMUM_WASI_NODE_VERSION)
+})
+
+test('should preserve partial intersections with the WASI floor', (t) => {
+  t.is(restrictWasiNodeEngine('>=22'), '>=22.13.0 <23.0.0-0 || >=23.5.0')
+  t.is(restrictWasiNodeEngine('<21'), '>=20.19.0 <21.0.0-0')
+})
+
+test('should reject node engine ranges disjoint from the WASI floor', (t) => {
+  for (const nodeRange of ['>=21 <22', '<20', '13.0.0', '21.0.0']) {
+    const error = t.throws(() => restrictWasiNodeEngine(nodeRange))
+    t.true(
+      error.message.includes(`"${nodeRange}"`),
+      `error should name the rejected range ${nodeRange}`,
+    )
+    t.true(
+      error.message.includes(`"${MINIMUM_WASI_NODE_VERSION}"`),
+      'error should name the supported WASI versions',
+    )
+  }
+})
+
+test('should fall back to the WASI floor for malformed node engine ranges', (t) => {
+  t.is(restrictWasiNodeEngine('not-a-range'), MINIMUM_WASI_NODE_VERSION)
+})
+
+test('napi engine requirements always intersect the WASI floor', (t) => {
+  for (const napiVersion of SUPPORTED_NAPI_VERSIONS) {
+    t.notThrows(() =>
+      restrictWasiNodeEngine(napiEngineRequirement(napiVersion)),
+    )
+  }
+})

package/src/utils/config.ts

@@ -64,7 +64,7 @@ export interface UserNapiConfig {
   wasm?: {
     /**
      * https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Memory
-     * @default 4000 pages (256MiB)
+     * @default 4000 pages (250 MiB), or 1024 pages (64 MiB) for the deferred workerd loader
      */
     initialMemory?: number
     /**
@@ -151,6 +151,7 @@ export interface CommonPackageJsonFields {
 
   dependencies?: Record<string, string>
   devDependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
 
   ava?: {
     timeout?: string
@@ -265,7 +266,19 @@ export async function readNapiConfig(
     throw new Error(`Duplicate targets are not allowed: ${duplicateTarget}`)
   }
 
-  napiConfig.targets = targets.map(parseTriple)
+  const parsedTargets = targets.map(parseTriple)
+  const outputTargets = new Map<string, string>()
+  for (const [index, target] of parsedTargets.entries()) {
+    const previous = outputTargets.get(target.platformArchABI)
+    if (previous) {
+      throw new Error(
+        `Targets ${previous} and ${targets[index]} produce the same ${target.platformArchABI} artifact set. Choose one target spelling.`,
+      )
+    }
+    outputTargets.set(target.platformArchABI, targets[index])
+  }
+
+  napiConfig.targets = parsedTargets
 
   return napiConfig
 }

package/src/utils/metadata.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process'
 import fs from 'node:fs'
+import { dirname, resolve } from 'node:path'
 
 import { debugFactory } from './log.js'
 
@@ -32,7 +33,7 @@ export interface Crate {
   manifest_path: string
   dependencies: Array<{
     name: string
-    source: string
+    source: string | null
     req: string
     kind: string | null
     rename: string | null
@@ -44,11 +45,16 @@ export interface Crate {
   }>
 }
 
-export interface CrateResolveNode {
+export interface CargoResolveNode {
   id: string
+  dependencies: string[]
   deps: Array<{
     name: string
     pkg: string
+    dep_kinds: Array<{
+      kind: string | null
+      target: string | null
+    }>
   }>
   features: string[]
 }
@@ -59,24 +65,18 @@ export interface CargoWorkspaceMetadata {
   workspace_members: string[]
   target_directory: string
   workspace_root: string
-  resolve?: {
-    nodes: CrateResolveNode[]
+  resolve: {
     root: string | null
+    nodes: CargoResolveNode[]
   } | null
 }
 
-export interface CargoFeatureOptions {
-  features?: string[]
-  allFeatures?: boolean
-  noDefaultFeatures?: boolean
-}
-
 // Crates that will actually compile `napi-derive` in this build, and are therefore
 // expected to emit a type-def intermediate file. Prefer the resolved dependency graph:
-// a crate whose `napi-derive` dependency is optional and stays disabled never emits a
-// type-def file, so force-building it would invalidate cargo's fingerprint on every
-// build without ever satisfying the type-def check. Fall back to declared dependencies
-// when the resolve graph is unavailable.
+// a crate whose `napi-derive` dependency is optional and stays disabled in the current
+// build never emits a type-def file, so force-building it would invalidate cargo's
+// fingerprint on every build without ever satisfying the type-def check. Fall back
+// to declared dependencies when the resolve graph is unavailable.
 export function getNapiDeriveDependentCrates(
   metadata: CargoWorkspaceMetadata,
 ): Crate[] {
@@ -99,56 +99,164 @@ export function getNapiDeriveDependentCrates(
   return metadata.packages.filter((crate) => dependentPackageIds.has(crate.id))
 }
 
-export async function parseMetadata(
+interface ParseMetadataOptions {
+  allFeatures?: boolean
+  cargoOptions?: string[]
+  cwd?: string
+  featurePackage?: string
+  features?: string[]
+  filterPlatform?: string
+  noDefaultFeatures?: boolean
+}
+
+export function createCargoMetadataInvocation(
   manifestPath: string,
-  featureOptions?: CargoFeatureOptions,
+  options: ParseMetadataOptions = {},
 ) {
-  if (!fs.existsSync(manifestPath)) {
-    throw new Error(`No crate found in manifest: ${manifestPath}`)
+  const globalArgs: string[] = []
+  const metadataArgs = [
+    'metadata',
+    '--manifest-path',
+    manifestPath,
+    '--format-version',
+    '1',
+  ]
+  const features = [
+    ...new Set(
+      (options.features ?? []).flatMap((feature) =>
+        feature.split(/[,\s]+/).filter(Boolean),
+      ),
+    ),
+  ]
+  let allFeatures = options.allFeatures === true
+  let noDefaultFeatures = options.noDefaultFeatures === true
+  const cargoOptions = options.cargoOptions ?? []
+  for (let index = 0; index < cargoOptions.length; index += 1) {
+    const option = cargoOptions[index]
+    if (option === '--config' || option === '-Z') {
+      const value = cargoOptions[index + 1]
+      if (value !== undefined) {
+        globalArgs.push(option, value)
+        index += 1
+      }
+    } else if (option.startsWith('--config=') || option.startsWith('-Z')) {
+      globalArgs.push(option)
+    } else if (option === '--features' || option === '-F') {
+      const value = cargoOptions[index + 1]
+      if (value !== undefined) {
+        features.push(...value.split(/[,\s]+/).filter(Boolean))
+        index += 1
+      }
+    } else if (option.startsWith('--features=') || option.startsWith('-F=')) {
+      features.push(
+        ...option
+          .slice(option.indexOf('=') + 1)
+          .split(/[,\s]+/)
+          .filter(Boolean),
+      )
+    } else if (option.startsWith('-F') && option.length > 2) {
+      features.push(
+        ...option
+          .slice(2)
+          .split(/[,\s]+/)
+          .filter(Boolean),
+      )
+    } else if (option === '--all-features') {
+      allFeatures = true
+    } else if (option === '--no-default-features') {
+      noDefaultFeatures = true
+    } else if (
+      option === '--locked' ||
+      option === '--offline' ||
+      option === '--frozen'
+    ) {
+      metadataArgs.push(option)
+    }
   }
-
-  const featureArgs: string[] = []
-  if (featureOptions?.allFeatures) {
-    featureArgs.push('--all-features')
+  const selectedFeatures = [
+    ...new Set(
+      features.map((feature) =>
+        options.featurePackage && !feature.includes('/')
+          ? `${options.featurePackage}/${feature}`
+          : feature,
+      ),
+    ),
+  ].sort()
+  if (selectedFeatures.length > 0) {
+    metadataArgs.push('--features', selectedFeatures.join(','))
   }
-  if (featureOptions?.noDefaultFeatures) {
-    featureArgs.push('--no-default-features')
+  if (allFeatures) {
+    metadataArgs.push('--all-features')
   }
-  if (featureOptions?.features?.length) {
-    featureArgs.push('--features', featureOptions.features.join(','))
+  if (noDefaultFeatures) {
+    metadataArgs.push('--no-default-features')
+  }
+  if (options.filterPlatform) {
+    metadataArgs.push('--filter-platform', options.filterPlatform)
+  }
+
+  return {
+    // Deliberately NOT `process.env.CARGO ?? 'cargo'`: `$CARGO` only overrides
+    // the cargo/cross binary spawned for the actual build (see the Builder in
+    // api/build.ts) — tests poison `$CARGO` with a nonexistent path to assert
+    // no real build is spawned, and `cross metadata` is not a thing either.
+    // Metadata always comes from the host `cargo`.
+    command: 'cargo',
+    args: [...globalArgs, ...metadataArgs],
+    cwd: resolve(options.cwd ?? dirname(manifestPath)),
+  }
+}
+
+export async function parseMetadata(
+  manifestPath: string,
+  options: ParseMetadataOptions = {},
+) {
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`No crate found in manifest: ${manifestPath}`)
   }
 
-  // Resolving with the build's feature flags keeps `metadata.resolve` in sync with what
-  // `cargo build` will actually compile. Feature flags are rejected in some setups
-  // (e.g. a virtual workspace root manifest), so fall back to a plain invocation.
-  if (featureArgs.length) {
+  const invocation = createCargoMetadataInvocation(manifestPath, options)
+  // Resolving with the build's feature flags keeps `metadata.resolve` in sync
+  // with what `cargo build` will actually compile. Feature flags are rejected
+  // in some setups (e.g. a virtual workspace root manifest), so fall back to a
+  // plain invocation without them.
+  const featurelessArgs = stripFeatureArgs(invocation.args)
+  if (featurelessArgs.length !== invocation.args.length) {
     try {
-      return await execCargoMetadata(manifestPath, featureArgs)
+      return await execCargoMetadata(invocation)
     } catch (e) {
       debug.warn(
         `cargo metadata failed with feature flags, retrying without them: ${e}`,
       )
     }
+    return execCargoMetadata({ ...invocation, args: featurelessArgs })
   }
+  return execCargoMetadata(invocation)
+}
 
-  return execCargoMetadata(manifestPath, [])
+function stripFeatureArgs(args: string[]): string[] {
+  const stripped: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg === '--features') {
+      // also skip the flag's value
+      index += 1
+    } else if (arg !== '--all-features' && arg !== '--no-default-features') {
+      stripped.push(arg)
+    }
+  }
+  return stripped
 }
 
-async function execCargoMetadata(manifestPath: string, extraArgs: string[]) {
-  const childProcess = spawn(
-    'cargo',
-    [
-      'metadata',
-      '--manifest-path',
-      manifestPath,
-      '--format-version',
-      '1',
-      ...extraArgs,
-    ],
-    {
-      stdio: 'pipe',
-    },
-  )
+async function execCargoMetadata(invocation: {
+  command: string
+  args: string[]
+  cwd: string
+}) {
+  const childProcess = spawn(invocation.command, invocation.args, {
+    cwd: invocation.cwd,
+    stdio: 'pipe',
+  })
 
   let stdout = ''
   let stderr = ''