@youdie006/prodex 0.40.16 → 0.40.18

package/docs/platform-verification.md

@@ -0,0 +1,164 @@
+# Platform Verification
+
+Open source does not mean every operating system, architecture, filesystem, or
+browser version has been tested. This record distinguishes configured CI jobs,
+completed checks, installed versions, and live account-dependent behavior.
+
+## 0.40.18 verification
+
+Branch: `fix/cross-platform-verification`.
+Tracking PR: <https://github.com/youdie006/prodex/pull/6>.
+Verified runtime commit: `ba9551be75586b7ab603964a6cbf117483578766`.
+Completed six-job CI: <https://github.com/youdie006/prodex/actions/runs/34980308069>.
+Final release/publication and machine installation records are kept in the
+version-specific GitHub Release; this source verification is not an installation
+or an existing-client reconnection claim.
+
+| Environment | Completed result at verified runtime commit | Scope |
+| --- | --- | --- |
+| Ubuntu 24.04 x64, Node 20/22/24 | PASS | Each job: 1,614 passed, 0 failed, 3 platform exclusions; full release verification and headless smoke |
+| macOS 15 ARM, Node 22 | PASS | 1,613 passed, 0 failed, 4 platform exclusions; full release verification and headless smoke |
+| macOS 15 Intel, Node 22 | PASS | 1,613 passed, 0 failed, 4 platform exclusions; full release verification and headless smoke |
+| Windows Server 2025 x64, Node 22 | PASS | 1,615 passed, 0 failed, 4 platform exclusions; metadata, installed-package verification and headless smoke |
+| Windows 11 x64, Node 22.22.0 | Partial native verification | Actual installed command and fresh MCP passed; 42 CLI/product checks and 7 service-error checks passed. Local full security fixtures require file-symlink privileges and are not claimed as passed |
+| WSL Linux x64, Node 22.22.0 | PASS | Full release verification: 1,614 passed, 0 failed, 3 platform exclusions; earlier real headless browser smoke also passed |
+| Physical M3 macOS ARM, Node 22.22.3 | PASS | Full release verification: 1,613 passed, 0 failed, 4 platform exclusions; earlier real headless browser smoke also passed |
+
+## Earlier attempts
+
+Initial matrix commit: `37b1684795271f69afdca492562d99aa9c203e6d`.
+CI run: <https://github.com/youdie006/prodex/actions/runs/34964947086>.
+Integrated compatibility commit: `8569391d525e15e16e67665dbc19e04da53ee042`.
+Integrated CI run: <https://github.com/youdie006/prodex/actions/runs/34970055803>.
+Candidate commit: `33646bd4cdffca376f332f103f3c5a00932cf767`.
+Candidate CI run: <https://github.com/youdie006/prodex/actions/runs/34974010179>.
+Follow-up commit: `afec42d3e7f9f4e82601db6fe553dd742664f54d`.
+Follow-up CI run: <https://github.com/youdie006/prodex/actions/runs/34976162000>.
+
+The Windows initialization and junction regressions failed before correction and
+passed afterward. Additional native checks reproduced file replacement and
+concurrent initialization failures; their six focused regressions now pass.
+The additional concurrent gitignore replacement regression passed on native
+Windows after both initializers adopted the same verified, idempotent write path.
+The later 48-test Windows run also passed the original concurrent follow-up
+reservation test, npm credential-isolated dry runs, and anchored writer checks.
+M3's first integrated command incorrectly exported `PRODEX_NO_AUTO_LOGIN=1`,
+which disabled five mocked recovery tests. The complete release-verification
+command passed after removing that conflicting harness override. No account
+browser or login profile was used by those mocked tests.
+The initial Windows suite also lacks file-symlink creation privileges on this
+machine. This is recorded separately from product failures; no security test is
+declared passed by ignoring an `EPERM` error. Directory-junction checks can run
+without granting administrator privileges or changing Windows Developer Mode.
+
+Candidate 0.40.18 uses the unique root bin `prodex.mjs`: native npm produced
+archive modes 0755 for that bin and 0644 for `dist/cli.js` and `LICENSE`.
+The native metadata check and independent tar-header inspection passed. An
+initial root name `cli.js` was rejected because npm also marked the same-named
+nested compiled file executable. Strict release checks were not relaxed.
+WSL's installed-package smoke passed for the corrected 0.40.18 candidate.
+At that point, final candidate CI and installation checks were still pending.
+Native Windows focused reruns passed the 11 CLI regressions, two browser-send
+and profile cases, and all 21 release-pack tests. The candidate package smoke
+passed its formerly failing archive-mode check, then stopped at a real file
+symlink creation `EPERM`; that run is partial, not a package-smoke pass.
+The three link-swap regressions now assert their fixture was actually installed,
+so an unsupported symlink operation cannot masquerade as a rejected attack.
+
+One local staging attempt began before its source archive finished writing and
+failed with a truncated TypeScript file. That invalid snapshot was discarded;
+the complete archive was extracted and source hashes checked before rerunning.
+This was a verification setup failure, not accepted product evidence.
+
+The candidate Windows CI failure was reproduced locally by inheriting uppercase
+`NPM_EXECPATH`. It silently displaced explicit lowercase overrides, causing real
+npm to run instead of the intended fixture. After normalizing environment names
+before subprocess creation, the native npm/release suites passed 54 tests with
+one POSIX-only exclusion; their two file-symlink cases still failed with `EPERM`.
+The matching WSL checks passed 91 tests with one Windows-only exclusion.
+Follow-up changes also canonicalize Windows temporary paths, retain private-mode
+assertions only where POSIX modes apply, bound Windows file concurrency to four,
+and give the four-consult approval-renewal test a separate 60-second deadline.
+Those corrections required the subsequent complete matrix before publication.
+
+Follow-up commit `afec42d3e7f9f4e82601db6fe553dd742664f54d` was tested in
+<https://github.com/youdie006/prodex/actions/runs/34976162000>. Ubuntu Node
+20/22/24 and macOS ARM passed. Windows passed 1,597 tests with 8 failures and
+4 platform exclusions: every failure was an unhandled process-inspection error
+in product diagnostics. The strict Windows identity parser correctly refused
+incomplete process records, but diagnostics incorrectly aborted the rest of the
+report. The new regression reproduced that crash before correction. The fix
+reports an unknown-identity blocker without login/reset guidance, keeps shutdown
+ownership checks strict, and isolates refused-connection fixtures from the host's
+real process table. Focused checks passed on native Windows (42 tests) and WSL
+(49 tests); typecheck and the npm-helper declaration type probe also passed.
+macOS Intel passed 1,600 tests with 4 exclusions and three 30-second timeouts:
+the paired project-warning cases, paired terminal-state cases, and eight-task
+concurrent creation. The independent cases are now separate tests, and the
+concurrent case retains all eight tasks with a dedicated 60-second deadline.
+All five affected cases passed on WSL after this test-only correction. The
+subsequent complete matrix passed; no global or production timeout was raised.
+The two affected storage/send files also passed all 178 tests on physical M3.
+
+The user subsequently reported a rendered Cloudflare 502 page. Seven focused
+regressions verify service-error classification, exclusion of ordinary chat
+content, genuine authentication/protection precedence, and no automatic resend
+after submission on both WSL and native Windows. The full affected browser,
+process and product-check files passed 173 tests on WSL; typecheck passed.
+The page error itself is upstream; these
+simulated checks do not establish restored ChatGPT availability or a new live
+Pro answer, and no visible login window or account profile reset was attempted.
+
+The same `afec42d` snapshot passed full `CI=1 npm run release:verify` on WSL
+(1,604 tests, 3 platform exclusions) and physical M3 (1,603 tests, 4 exclusions),
+including installed-package checks. Native Windows installed the candidate into
+a temporary consumer path containing spaces; its actual `prodex.cmd` launched a
+fresh non-tmux MCP, reported 0.40.18 and 20 tools, and read the intended explicit
+working-directory fixture. The transport exited and left no matching child
+process. These are isolated candidate installs, not global deployment or public
+publication. Existing account browsers and the attached MCP were not restarted.
+
+## What each check proves
+
+- Unit/integration tests: local ledger, routing, path policy, and simulated UI.
+- Package smoke: installed CLI and MCP transports against disposable local data.
+- Browser launch smoke: a fresh headless profile with `about:blank`, CDP readiness,
+  script evaluation, owned-process shutdown, and cleanup. No ChatGPT login.
+- Live Pro verification: a separate, manually triggered account test with request
+  identity, model evidence, and saved result validation. None of the checks above
+  substitutes for this test.
+
+## Limits and prerequisites
+
+- Node 20+, Git, ripgrep, and a supported Chromium-family browser are prerequisites.
+- Virtual display requires Linux/WSL, Xvfb and xauth. Native macOS and Windows do
+  not support this mode; they must report that limitation without opening a window.
+- WSL uses a Linux browser/profile. Native Windows browser discovery is not WSL
+  cross-host browser support.
+- Native Windows storage inherits Windows ACLs. See [SECURITY.md](../SECURITY.md#local-storage-permissions).
+- Generated native Windows commands target PowerShell, not `cmd.exe`; compound
+  examples with `&&` require PowerShell 7. Internal subprocesses use literal argv.
+- Authentication, CAPTCHA, Cloudflare, permissions, and usage limits remain
+  explicit blockers. No automatic visible fallback or protection bypass is tested.
+- ARM Windows, Linux ARM, BSD, containers without browser dependencies, and every
+  historical OS/browser version are not covered by this matrix.
+
+## Installation and running processes
+
+At the start of this work WSL and M3 had CLI 0.40.17 installed. The MCP attached to
+the existing Codex client still had 0.40.16 loaded. Updating a package on disk does
+not reconnect that MCP or change an already-running browser's mode. No client
+restart has been performed in this verification task.
+
+The previously verified WSL no-desktop-window session uses ordinary headed Chrome
+on a private virtual display. It is not pure headless Chrome. M3's prior pure
+headless ChatGPT check stopped at Cloudflare. Neither installing this branch nor
+passing a no-account browser launch test removes that account-dependent blocker.
+
+After the reported 502, bounded read-only probes on 2026-09-15 at approximately
+14:38 UTC used the tested candidate adapter against the existing dedicated
+browsers. WSL was reachable with saved-login signals and a composer, with no
+blocker. M3 was reachable but returned `cloudflare_check`, not a 502. Neither
+probe opened a browser, changed profiles, reloaded a page, logged in, or sent a
+prompt. WSL readiness does not prove the upstream error's cause or a new Pro
+answer; M3 authenticated pure-headless access remains blocked.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdie006/prodex",
-  "version": "0.40.16",
+  "version": "0.40.18",
   "description": "Local receipt bus for coordinating Codex execution with ChatGPT Pro/Projects consultation.",
   "author": "youdie006",
   "license": "MIT",
@@ -26,18 +26,22 @@
   ],
   "type": "module",
   "bin": {
-    "prodex": "dist/cli.js"
+    "prodex": "prodex.mjs"
   },
   "exports": {},
   "files": [
+    "prodex.mjs",
     "dist",
     "LICENSE",
     "README.md",
+    "SECURITY.md",
     "docs/claude.md",
     "docs/clients.md",
     "docs/http-mcp.md",
     "docs/releasing.md",
     "docs/cli-reference.md",
+    "docs/platform-verification.md",
+    "scripts/npm-command.mjs",
     "scripts/release-check.mjs",
     "scripts/release-pack.mjs"
   ],
@@ -49,6 +53,7 @@
     "release:pack": "node scripts/release-pack.mjs",
     "release:verify": "node scripts/release-check.mjs --verification-only",
     "smoke:package": "node scripts/package-smoke.mjs",
+    "smoke:browser": "node scripts/browser-launch-smoke.mjs",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build",

package/prodex.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from "./dist/cli.js";
+
+runCli(process.argv.slice(2))
+  .then((code) => {
+    if (code !== 0) process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });

package/scripts/npm-command.mjs

@@ -0,0 +1,71 @@
+import { execFile } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export function resolveNpmCliPath(options = {}) {
+  const env = normalizeNpmEnvironment(options.env ?? process.env);
+  const execPath = options.execPath ?? process.execPath;
+  const cwd = options.cwd ?? process.cwd();
+  const candidates = [];
+  const npmExecPath = envValue(env, "npm_execpath");
+  if (npmExecPath && !isCompetingPackageManagerCli(npmExecPath)) candidates.push(path.resolve(cwd, npmExecPath));
+
+  const pathValue = envValue(env, "PATH");
+  for (const entry of pathValue?.split(path.delimiter) ?? []) {
+    if (!entry) continue;
+    for (const commandName of process.platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"]) {
+      const commandPath = path.join(entry, commandName);
+      const resolvedCommand = existingJavaScriptFile(commandPath);
+      if (resolvedCommand) candidates.push(resolvedCommand);
+    }
+    candidates.push(path.join(entry, "node_modules", "npm", "bin", "npm-cli.js"));
+    candidates.push(path.resolve(entry, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+  }
+
+  const nodeDir = path.dirname(execPath);
+  candidates.push(path.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js"));
+  candidates.push(path.resolve(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+
+  for (const candidate of candidates) {
+    const resolved = existingJavaScriptFile(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error(`Could not locate npm's JavaScript CLI for ${execPath}`);
+}
+
+export function execNpm(args, options = {}) {
+  const env = normalizeNpmEnvironment(options.env ?? process.env);
+  const npmCliPath = resolveNpmCliPath({ cwd: options.cwd, env, execPath: process.execPath });
+  return execFileAsync(process.execPath, [npmCliPath, ...args], { ...options, env, encoding: "utf8" });
+}
+
+export function normalizeNpmEnvironment(env, platform = process.platform) {
+  if (platform !== "win32") return env;
+  // Node otherwise sorts duplicate Windows names and can keep the inherited
+  // spelling instead of an explicit override appended by the caller.
+  const entries = new Map();
+  for (const [name, value] of Object.entries(env)) entries.set(name.toLowerCase(), [name, value]);
+  return Object.fromEntries(entries.values());
+}
+
+function envValue(env, name) {
+  if (typeof env[name] === "string") return env[name];
+  const entry = Object.entries(env).find(([key, value]) => key.toLowerCase() === name.toLowerCase() && typeof value === "string");
+  return entry?.[1];
+}
+
+function isCompetingPackageManagerCli(candidate) {
+  return /^(?:pnpm|pnpx|yarn|yarnpkg)(?:\.(?:cjs|mjs|js))?$/i.test(path.basename(candidate));
+}
+
+function existingJavaScriptFile(candidate) {
+  try {
+    const resolved = realpathSync(candidate);
+    return /\.(?:cjs|mjs|js)$/i.test(resolved) && statSync(resolved).isFile() ? resolved : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/scripts/release-check.mjs

@@ -4,6 +4,7 @@ import { lstat, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { execNpm } from "./npm-command.mjs";
 
 const execFileAsync = promisify(execFile);
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -159,7 +160,7 @@ async function runFullReleaseVerification(rootDir) {
   ];
   for (const [command, commandArgs] of checks) {
     const key = [command, ...commandArgs].join(" ");
-    await run(commandForPlatform(command), commandArgs, rootDir, CHECK_TIMEOUT_MS[key] ?? CHECK_TIMEOUT_MS.default);
+    await run(command, commandArgs, rootDir, CHECK_TIMEOUT_MS[key] ?? CHECK_TIMEOUT_MS.default);
   }
 }
 
@@ -205,7 +206,7 @@ async function assertPackedFileModes(rootDir, packageJson) {
 async function readPackedFiles(rootDir) {
   let stdout;
   try {
-    ({ stdout } = await execFileAsync(commandForPlatform("npm"), ["pack", "--json", "--dry-run", "--ignore-scripts"], {
+    ({ stdout } = await execNpm(["pack", "--json", "--dry-run", "--ignore-scripts"], {
       cwd: rootDir,
       timeout: 120_000,
       maxBuffer: 20 * 1024 * 1024
@@ -282,6 +283,9 @@ function findNonExecutableBinPackedFiles(files, packageJson) {
 }
 
 async function findNonExecutableBinSourceFiles(rootDir, packageJson) {
+  // Windows ACLs do not map to POSIX execute bits. npm still reports package
+  // bin entries with canonical executable modes in the packed file metadata.
+  if (process.platform === "win32") return [];
   const invalid = [];
   for (const packagePath of packageBinPaths(packageJson)) {
     const filePath = path.join(rootDir, packagePath);
@@ -349,11 +353,18 @@ async function run(command, commandArgs, cwd, timeoutMs = 300_000) {
   const commandLine = [command, ...commandArgs].join(" ");
   console.log(`release_check: ${commandLine}`);
   try {
-    await execFileAsync(command, commandArgs, {
-      cwd,
-      timeout: timeoutMs,
-      maxBuffer: 20 * 1024 * 1024
-    });
+    const execute = command === "npm"
+      ? execNpm(commandArgs, {
+          cwd,
+          timeout: timeoutMs,
+          maxBuffer: 20 * 1024 * 1024
+        })
+      : execFileAsync(command === "node" ? process.execPath : command, commandArgs, {
+          cwd,
+          timeout: timeoutMs,
+          maxBuffer: 20 * 1024 * 1024
+        });
+    await execute;
   } catch (error) {
     // Surface the real failure: the one-line detail used to show the FIRST
     // stderr line, which npm noise ("npm warn ...") could occupy while the
@@ -376,10 +387,6 @@ function printCapturedOutputTail(error, commandLine) {
   }
 }
 
-function commandForPlatform(command) {
-  return process.platform === "win32" && command === "npm" ? "npm.cmd" : command;
-}
-
 function parseArgs(values) {
   const parsed = {
     root: undefined,

package/scripts/release-pack.mjs

@@ -5,10 +5,10 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { execNpm } from "./npm-command.mjs";
 
 const execFileAsync = promisify(execFile);
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
 
 try {
   const args = parseArgs(process.argv.slice(2));
@@ -71,7 +71,7 @@ async function ensureDistBuiltForSource(root) {
   const tsconfigPath = path.join(root, "tsconfig.json");
   const srcDir = path.join(root, "src");
   if (!(await pathExists(tsconfigPath)) || !(await pathExists(srcDir))) return false;
-  await execFileAsync(npmCommand, ["run", "build"], { cwd: root, maxBuffer: 20 * 1024 * 1024 });
+  await execNpm(["run", "build"], { cwd: root, maxBuffer: 20 * 1024 * 1024 });
   return true;
 }
 
@@ -211,7 +211,11 @@ async function run(command, commandArgs, cwd) {
 
 async function runNpmPack(commandArgs, cwd, label) {
   try {
-    return await run(npmCommand, commandArgs, cwd);
+    return await execNpm(commandArgs, {
+      cwd,
+      timeout: 120_000,
+      maxBuffer: 20 * 1024 * 1024
+    });
   } catch (error) {
     throw new Error(`${label} failed: ${commandFailureDetail(error)}`);
   }
@@ -340,7 +344,12 @@ function errorMessage(error) {
 }
 
 function shellQuote(value) {
-  return /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+  const shellSafe = /^[A-Za-z0-9_./:@=-]+$/.test(value);
+  if (shellSafe && (process.platform !== "win32" || !value.startsWith("@"))) return value;
+  const escaped = process.platform === "win32"
+    ? value.replaceAll("'", "''")
+    : value.replaceAll("'", "'\\''");
+  return `'${escaped}'`;
 }
 
 async function readReleaseGitStatus(root) {