fix: query structured Windows source volume properties (#383)

Author: hetaoBackend

docs/installation.md

@@ -41,7 +41,7 @@ This guide builds the 0.4.12 source preview. Workspace/local build manifests rem
 
 For a source build, you need Git, Node.js 22.19+ (22.x), 24.2+ (24.x), 25, or 26, and pnpm 9.12.0. Regular CI uses Node.js 24 across Linux and macOS. The weekly and manual compatibility matrix covers Node.js 22.19.0, 24.2.0, 25, and 26 on both platforms. Windows CI and source-candidate validation are temporarily paused while their checks are made reliable. Initial installation and build require access to public npm.
 
-On Windows, check out this repository on a local NTFS volume before running `pnpm install`. The repository uses pnpm workspace links for vendored packages, and those links require NTFS junctions. FAT32/exFAT volumes, network shares, and other non-local Windows volumes cannot create the required junctions. The preflight command below verifies the volume and stops with a clear message before pnpm creates workspace links; run it immediately before `pnpm install`. A local NTFS volume can still contain a cloud-synced folder, which the preflight cannot identify reliably; keep the checkout outside OneDrive, Google Drive, Dropbox, and similar synced folders.
+On Windows, check out this repository on a local NTFS volume before running `pnpm install`. The repository uses pnpm workspace links for vendored packages, and those links require NTFS junctions. FAT32/exFAT volumes, network shares, and other non-local Windows volumes cannot create the required junctions. The preflight command below verifies the volume and stops with a clear message before pnpm creates workspace links; run it immediately before `pnpm install`. It queries structured volume properties through Windows PowerShell and CIM, without requiring an elevated shell or parsing localized `fsutil` output. If PowerShell or CIM is unavailable or blocked, verification fails with the query error. A local NTFS volume can still contain a cloud-synced folder, which the preflight cannot identify reliably; keep the checkout outside OneDrive, Google Drive, Dropbox, and similar synced folders.
 
 Node 24.0 and 24.1 are unsupported: their bundled libuv can return inconsistent Windows file identity metadata, causing safe configuration reads to fail. [Node 24.2.0](https://nodejs.org/en/blog/release/v24.2.0) includes libuv 1.51.0 with the [upstream fix](https://github.com/libuv/libuv/commit/82cdfb75f). Use a current patch release of a supported Node line.
 

scripts/check-windows-source-location.mjs

@@ -28,30 +28,47 @@ export function checkWindowsSourceLocation({
   if (!/^[a-z]:\\$/iu.test(root) || root.startsWith("\\\\")) {
     return fail("The checkout root is not a local drive-letter path.");
   }
-  // `fsutil` accepts a drive letter more reliably than a root path with a
-  // trailing backslash across Windows runner images.
   const volume = root.slice(0, 2);
 
-  let driveType;
-  let volumeInfo;
+  let disk;
   try {
-    driveType = execFile("fsutil", ["fsinfo", "drivetype", volume], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    volumeInfo = execFile("fsutil", ["fsinfo", "volumeinfo", volume], {
+    // CIM exposes numeric drive types and filesystem identifiers independent of
+    // display language. fsutil prints localized text (e.g. "E: - Fixed Drive")
+    // and its volumeinfo command can require elevation. Query CIM directly so
+    // ordinary contributor shells use the same structured policy as CI.
+    // Only the validated drive letter above is interpolated, never the cwd.
+    const output = execFile("powershell.exe", [
+      "-NoLogo", "-NoProfile", "-NonInteractive", "-Command",
+      "$ErrorActionPreference = 'Stop'; " +
+        `Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID='${volume}'" | ` +
+        "Select-Object DeviceID, DriveType, FileSystem | ConvertTo-Json -Compress",
+    ], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      timeout: 15_000,
+      windowsHide: true,
     });
+    disk = JSON.parse(output.trim());
+    if (
+      !disk || Array.isArray(disk) ||
+      typeof disk.DeviceID !== "string" ||
+      disk.DeviceID.toUpperCase() !== volume.toUpperCase() ||
+      !Number.isInteger(disk.DriveType) ||
+      disk.DriveType < 0 || disk.DriveType > 6 ||
+      typeof disk.FileSystem !== "string"
+    ) {
+      throw new Error("CIM returned incomplete or unexpected volume information");
+    }
   } catch (error) {
     const detail = error instanceof Error ? ` (${error.message})` : "";
     return fail(`Windows could not verify the checkout volume${detail}.`);
   }
 
-  if (!allowNonFixed && !/:\s*DRIVE_FIXED(?:\r?\n|$)/iu.test(driveType)) {
+  // Win32_LogicalDisk.DriveType: 3 = local disk, 4 = network drive.
+  if (!allowNonFixed && disk.DriveType !== 3) {
     return fail("The checkout volume is not a local fixed drive.");
   }
-  if (!/:\s*NTFS(?:\r?\n|$)/iu.test(volumeInfo)) {
+  if (disk.FileSystem.toUpperCase() !== "NTFS") {
     return fail("The checkout volume is not formatted as NTFS.");
   }
 

test/source-sync.test.mjs

@@ -22,65 +22,100 @@ import { compareRuns, exitCodeForStatus, renderReport, spread, validateRun, vali
 import { copyMcodeToolsArtifact, downloadMcodeToolsArtifact, MCODE_TOOLS_ARTIFACT } from '../scripts/lib/mcode-tools-artifact.mjs';
 import { checkWindowsSourceLocation, runWindowsSourceLocationCheck } from '../scripts/check-windows-source-location.mjs';
 
-test('Windows source preflight accepts localized fsutil labels', () => {
-  const result = checkWindowsSourceLocation({
-    platform: 'win32',
-    cwd: 'C:\\repo',
-    execFile: (_command, args) => args[1] === 'drivetype'
-      ? 'Laufwerkstyp: DRIVE_FIXED\n'
-      : 'Dateisystemname: NTFS\n',
-  });
-  assert.deepEqual(result, { ok: true, skipped: false });
+test('Windows source preflight accepts local NTFS without parsing fsutil display text', () => {
+  for (const fsutilOutput of ['E: - Fixed Drive\r\n', 'E: - Festplatte\r\n', new Error('Error 5: Access is denied')]) {
+    const calls = [];
+    const result = checkWindowsSourceLocation({
+      platform: 'win32', cwd: 'E:\\src\\minimax-code', allowNonFixed: false,
+      execFile: (command, args, options) => {
+        calls.push(command);
+        if (command === 'fsutil') {
+          if (fsutilOutput instanceof Error) throw fsutilOutput;
+          return args[1] === 'drivetype' ? fsutilOutput : 'File System Name : NTFS\r\n';
+        }
+        assert.equal(command, 'powershell.exe');
+        assert.deepEqual(args.slice(0, 4), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command']);
+        assert.match(args[4], /\$ErrorActionPreference\s*=\s*'Stop'/);
+        assert.match(args[4], /Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID='E:'"/);
+        assert.match(args[4], /ConvertTo-Json -Compress/);
+        assert.equal(options.encoding, 'utf8');
+        assert.ok(options.timeout > 0);
+        return '\r\n{"DeviceID":"E:","DriveType":3,"FileSystem":"NTFS"}\r\n';
+      },
+    });
+    assert.deepEqual(result, { ok: true, skipped: false });
+    assert.deepEqual(calls, ['powershell.exe']);
+  }
 });
 
-test('Windows source preflight requires a local NTFS checkout', () => {
-  const calls = [];
-  const execFile = (command, args) => {
-    calls.push([command, args]);
-    if (args[1] === 'drivetype') return 'Drive type is : DRIVE_FIXED\n';
-    return 'File System Name             : NTFS\n';
-  };
-  assert.deepEqual(
-    checkWindowsSourceLocation({ platform: 'win32', cwd: 'C:\\repo', execFile }),
-    { ok: true, skipped: false },
-  );
-  assert.deepEqual(calls.map(([command, args]) => [command, args[1], args[2]]), [
-    ['fsutil', 'drivetype', 'C:'],
-    ['fsutil', 'volumeinfo', 'C:'],
-  ]);
+const checkWindowsVolume = (disk, allowNonFixed = false) => checkWindowsSourceLocation({
+  platform: 'win32', cwd: 'C:\\repo', allowNonFixed,
+  execFile: () => JSON.stringify({ DeviceID: 'C:', DriveType: 3, FileSystem: 'NTFS', ...disk }),
 });
 
-test('Windows source preflight rejects unsupported volumes clearly', () => {
-  const run = (driveType, volumeInfo, cwd = 'C:\\repo', allowNonFixed = false) => checkWindowsSourceLocation({
-    platform: 'win32', cwd, allowNonFixed,
-    execFile: (_command, args) => args[1] === 'drivetype' ? driveType : volumeInfo,
-  });
-  assert.match(run('Drive type is : DRIVE_REMOTE\n', 'File System Name : NTFS\n').reason, /not a local fixed drive/);
-  assert.deepEqual(
-    run('Drive type is : DRIVE_REMOTE\n', 'File System Name : NTFS\n', 'C:\\repo', true),
-    { ok: true, skipped: false },
-  );
-  assert.match(run('Drive type is : DRIVE_FIXED\n', 'File System Name : NTFS\n', '\\\\server\\share\\repo').reason, /not a local drive-letter path/);
+test('Windows source preflight rejects unsupported drive types and file systems', () => {
+  for (const DriveType of [0, 1, 2, 4, 5, 6]) {
+    assert.match(checkWindowsVolume({ DriveType }).reason, /not a local fixed drive/);
+  }
+  for (const FileSystem of ['FAT32', 'exFAT', 'ReFS', '']) {
+    for (const allowNonFixed of [false, true]) {
+      assert.match(checkWindowsVolume({ FileSystem }, allowNonFixed).reason, /not formatted as NTFS/);
+    }
+  }
+  // Preserve the existing explicit runner override, but never use it in the
+  // positive fixed-drive regression or native-host acceptance case.
+  assert.deepEqual(checkWindowsVolume({ DriveType: 4 }, true), { ok: true, skipped: false });
+});
+
+test('Windows source preflight rejects UNC paths before querying Windows', () => {
+  for (const allowNonFixed of [false, true]) {
+    const result = checkWindowsSourceLocation({
+      platform: 'win32', cwd: '\\\\server\\share\\repo', allowNonFixed,
+      execFile: () => assert.fail('must not query a UNC path'),
+    });
+    assert.match(result.reason, /not a local drive-letter path/);
+  }
+});
+
+test('Windows source preflight fails closed on missing, malformed or mismatched CIM data', () => {
+  for (const output of [
+    '', 'not JSON', 'null', '[]', '{}',
+    '{"DeviceID":"D:","DriveType":3,"FileSystem":"NTFS"}',
+    '{"DeviceID":"C:","DriveType":"3","FileSystem":"NTFS"}',
+    '{"DeviceID":"C:","DriveType":3,"FileSystem":null}',
+    '{"DeviceID":"C:","DriveType":null,"FileSystem":"NTFS"}',
+    '[{"DeviceID":"C:","DriveType":3,"FileSystem":"NTFS"}]',
+  ]) {
+    for (const allowNonFixed of [false, true]) {
+      const result = checkWindowsSourceLocation({
+        platform: 'win32', cwd: 'C:\\repo', allowNonFixed, execFile: () => output,
+      });
+      assert.equal(result.ok, false, output);
+      assert.match(result.reason, /could not verify the checkout volume/);
+    }
+  }
+  assert.deepEqual(checkWindowsVolume({ DeviceID: 'c:', FileSystem: 'ntfs' }), { ok: true, skipped: false });
 });
 
 test('Windows source preflight is a no-op on non-Windows platforms', () => {
   assert.deepEqual(
-    checkWindowsSourceLocation({ platform: 'linux', execFile: () => assert.fail('must not run fsutil') }),
+    checkWindowsSourceLocation({ platform: 'linux', execFile: () => assert.fail('must not query Windows') }),
     { ok: true, skipped: true },
   );
 });
 
-test('Windows source preflight propagates a failed check to the CLI', () => {
-  const messages = [];
-  const result = runWindowsSourceLocationCheck({
-    platform: 'win32',
-    cwd: 'C:\\repo',
-    execFile: () => { throw new Error('fsutil unavailable'); },
-    report: (message) => messages.push(message),
-  });
-  assert.equal(result.ok, false);
-  assert.equal(messages.length, 1);
-  assert.match(messages[0], /fsutil unavailable/);
+test('Windows source preflight reports command, permission and timeout failures to the CLI', () => {
+  for (const error of [new Error('spawn powershell.exe ENOENT'), new Error('Access is denied'), new Error('ETIMEDOUT')]) {
+    const messages = [];
+    const result = runWindowsSourceLocationCheck({
+      platform: 'win32', cwd: 'C:\\repo', allowNonFixed: false,
+      execFile: () => { throw error; },
+      report: (message) => messages.push(message),
+    });
+    assert.equal(result.ok, false);
+    assert.equal(messages.length, 1);
+    assert.ok(messages[0].includes(error.message));
+  }
 });
 
 test('artifact download recovers from TLS reset and interrupted response bodies', async () => {

test/windows-contract.test.mjs

@@ -20,7 +20,7 @@ afterEach(() => {
 
 describe.skipIf(process.platform !== "win32")("Windows source contract", () => {
   it("accepts the Windows checkout on a local NTFS volume", () => {
-    assert.deepEqual(checkWindowsSourceLocation(), {
+    assert.deepEqual(checkWindowsSourceLocation({ allowNonFixed: false }), {
       ok: true,
       skipped: false,
     });