refactor: extract isDirectExecution + windows-shim helpers into @coder-studio/utils

pallyoung · pallyoung · commit 92fa99281f3e · 2026-05-07T15:46:00.000+08:00
The server package and root build scripts previously kept identical copies of
isDirectExecution (with its path-normalizing helpers) and the
WINDOWS_CMD_SHIMS / shouldUseShellForCommand pair. Both areas care about the
same Windows / ESM entry-point gotchas, so any fix needed to be made twice and
risked drifting.

- Add packages/utils workspace package mirroring the @coder-studio/core layout.
- Move helpers into utils with co-located vitest coverage.
- packages/server now depends on @coder-studio/utils; server.ts and
  provider-runtime/command-runner.ts import from it and the duplicate
  direct-execution.ts is removed.
- scripts/shared/process.ts re-exports the helpers from utils (call sites
  unchanged) and the obsolete process.test.ts is dropped in favor of the new
  utils tests.
- Wire @coder-studio/utils into the root devDependencies, ci:typecheck, the
  esbuild alias map, and scripts/shared/paths so the CLI bundle resolves it
  correctly.
diff --git a/package.json b/package.json
@@ -13,10 +13,10 @@
     "version-packages": "changeset version",
     "publish:cli": "tsx scripts/publish-cli.ts",
     "ci:lint": "pnpm exec biome check --diagnostic-level=error --max-diagnostics=none .",
-    "ci:test:scripts": "pnpm exec vitest run scripts/publish-cli.test.ts scripts/build-cli.test.ts scripts/validate-changesets.test.ts scripts/husky-pre-commit.test.ts scripts/shared/process.test.ts --environment node",
+    "ci:test:scripts": "pnpm exec vitest run scripts/publish-cli.test.ts scripts/build-cli.test.ts scripts/validate-changesets.test.ts scripts/husky-pre-commit.test.ts --environment node",
     "ci:test:workspace": "pnpm -r --filter './packages/**' --if-present run test",
     "ci:test": "pnpm ci:test:scripts && pnpm ci:test:workspace",
-    "ci:typecheck": "pnpm --filter @spencer-kit/coder-studio exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/core exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/providers exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/server exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/web exec tsc -p tsconfig.json --noEmit",
+    "ci:typecheck": "pnpm --filter @spencer-kit/coder-studio exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/utils exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/core exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/providers exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/server exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/web exec tsc -p tsconfig.json --noEmit",
     "ci:build": "pnpm build",
     "ci:verify": "pnpm changeset:validate && pnpm ci:lint && pnpm ci:test && pnpm ci:build",
     "ci:release:validate": "pnpm ci:verify && pnpm publish:cli -- --no-build",
@@ -33,6 +33,7 @@
     "@biomejs/biome": "^2.4.14",
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
+    "@coder-studio/utils": "workspace:*",
     "@types/node": "^25.6.0",
     "esbuild": "^0.28.0",
     "husky": "^9.1.7",
diff --git a/packages/server/package.json b/packages/server/package.json
@@ -31,6 +31,7 @@
   "dependencies": {
     "@coder-studio/core": "workspace:*",
     "@coder-studio/providers": "workspace:*",
+    "@coder-studio/utils": "workspace:*",
     "@fastify/compress": "^8.3.1",
     "@fastify/cors": "^11.2.0",
     "@fastify/multipart": "^10.0.0",
diff --git a/packages/server/src/provider-runtime/command-runner.ts b/packages/server/src/provider-runtime/command-runner.ts
@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { shouldUseShellForCommand } from "@coder-studio/utils";
 
 export type CommandRunnerOptions = { windowsHide?: boolean };
 
@@ -13,15 +14,6 @@ export type CommandRunner = (
   options?: CommandRunnerOptions
 ) => Promise<CommandRunnerResult>;
 
-// Windows ships these as .cmd shims that Node refuses to spawn directly post
-// CVE-2024-27980. Routing them through cmd.exe via shell:true is the only
-// approach that survives both ENOENT (bare name) and EINVAL (full .cmd path).
-const WINDOWS_CMD_SHIMS = new Set(["pnpm", "npm", "npx"]);
-
-function shouldUseShellForCommand(file: string, platform: NodeJS.Platform): boolean {
-  return platform === "win32" && WINDOWS_CMD_SHIMS.has(file.toLowerCase());
-}
-
 export async function runCommandAsString(
   file: string,
   args: string[],
diff --git a/packages/server/src/server.ts b/packages/server/src/server.ts
@@ -10,6 +10,7 @@ import {
   writeRuntimeConfig,
 } from "@coder-studio/core/runtime";
 import { providerRegistry } from "@coder-studio/providers";
+import { isDirectExecution } from "@coder-studio/utils";
 import type { FastifyInstance } from "fastify";
 import { buildFastifyApp } from "./app.js";
 import { EventBus } from "./bus/event-bus.js";
@@ -21,7 +22,6 @@ import {
   cleanupCodexConfigToml,
 } from "./config/codex-config-audit.js";
 import { ensureDataDir, parseServerConfig, type ServerConfig } from "./config.js";
-import { isDirectExecution } from "./direct-execution.js";
 import { runCommandAsString } from "./provider-runtime/command-runner.js";
 import { ProviderInstallManager } from "./provider-runtime/install-manager.js";
 import type { RuntimeStatusDeps } from "./provider-runtime/runtime-status.js";
diff --git a/packages/utils/package.json b/packages/utils/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@coder-studio/utils",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  }
+}
diff --git a/packages/utils/src/direct-execution.test.ts b/packages/utils/src/direct-execution.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isDirectExecution, shouldUseShellForCommand } from "./process.js";
+import { isDirectExecution } from "./direct-execution.js";
 
 describe("isDirectExecution", () => {
   it("matches direct execution for POSIX script paths", () => {
@@ -15,18 +15,12 @@ describe("isDirectExecution", () => {
   it("returns false when the current module differs from argv[1]", () => {
     expect(isDirectExecution("file:///repo/scripts/build.ts", "/repo/scripts/dev.ts")).toBe(false);
   });
-});
-
-describe("shouldUseShellForCommand", () => {
-  it("uses a shell for pnpm on Windows because pnpm.cmd is not directly executable", () => {
-    expect(shouldUseShellForCommand("pnpm", "win32")).toBe(true);
-  });
 
-  it("does not use a shell for native executables like git on Windows", () => {
-    expect(shouldUseShellForCommand("git", "win32")).toBe(false);
+  it("returns false when argv[1] is undefined", () => {
+    expect(isDirectExecution("file:///repo/scripts/dev.ts", undefined)).toBe(false);
   });
 
-  it("does not use a shell on POSIX platforms", () => {
-    expect(shouldUseShellForCommand("pnpm", "linux")).toBe(false);
+  it("returns false when moduleUrl is not a file: URL", () => {
+    expect(isDirectExecution("https://example.com/dev.ts", "/repo/scripts/dev.ts")).toBe(false);
   });
 });
diff --git a/packages/utils/src/direct-execution.ts b/packages/utils/src/direct-execution.ts
@@ -41,6 +41,11 @@ function normalizeModuleUrlPath(moduleUrl: string): string | null {
   return normalizeComparablePath(path);
 }
 
+function normalizeArgvPath(argv1: string): string {
+  const isAbsoluteWindowsPath = /^[A-Za-z]:[\\/]/.test(argv1) || /^\\\\/.test(argv1);
+  return normalizeComparablePath(isAbsoluteWindowsPath ? argv1 : resolve(argv1));
+}
+
 export function isDirectExecution(
   moduleUrl: string,
   argv1: string | undefined = process.argv[1]
@@ -55,8 +60,5 @@ export function isDirectExecution(
     return false;
   }
 
-  const isAbsoluteWindowsPath = /^[A-Za-z]:[\\/]/.test(argv1) || /^\\\\/.test(argv1);
-  const argvPath = normalizeComparablePath(isAbsoluteWindowsPath ? argv1 : resolve(argv1));
-
-  return modulePath === argvPath;
+  return modulePath === normalizeArgvPath(argv1);
 }
diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts
@@ -0,0 +1,2 @@
+export { isDirectExecution } from "./direct-execution.js";
+export { shouldUseShellForCommand } from "./windows-shim.js";
diff --git a/packages/utils/src/windows-shim.test.ts b/packages/utils/src/windows-shim.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { shouldUseShellForCommand } from "./windows-shim.js";
+
+describe("shouldUseShellForCommand", () => {
+  it("uses a shell for pnpm on Windows because pnpm.cmd is not directly executable", () => {
+    expect(shouldUseShellForCommand("pnpm", "win32")).toBe(true);
+  });
+
+  it("uses a shell for npm and npx on Windows", () => {
+    expect(shouldUseShellForCommand("npm", "win32")).toBe(true);
+    expect(shouldUseShellForCommand("npx", "win32")).toBe(true);
+  });
+
+  it("does not use a shell for native executables like git on Windows", () => {
+    expect(shouldUseShellForCommand("git", "win32")).toBe(false);
+  });
+
+  it("does not use a shell on POSIX platforms", () => {
+    expect(shouldUseShellForCommand("pnpm", "linux")).toBe(false);
+    expect(shouldUseShellForCommand("pnpm", "darwin")).toBe(false);
+  });
+
+  it("matches shim names case-insensitively", () => {
+    expect(shouldUseShellForCommand("NPM", "win32")).toBe(true);
+    expect(shouldUseShellForCommand("Pnpm", "win32")).toBe(true);
+  });
+});
diff --git a/packages/utils/src/windows-shim.ts b/packages/utils/src/windows-shim.ts
@@ -0,0 +1,18 @@
+/**
+ * Helpers for spawning child processes that may resolve to Windows .cmd / .bat
+ * shims.
+ *
+ * Why: Node 18.20.2 / 20.12.2 / 21.7.2 (CVE-2024-27980) refuses to spawn
+ * .cmd or .bat files unless `shell: true` is set. The shims below ship as
+ * .cmd on Windows, so they need shell:true; native executables (git, etc.)
+ * must keep shell:false to avoid breaking argument escaping.
+ */
+
+const WINDOWS_CMD_SHIMS = new Set(["pnpm", "npm", "npx"]);
+
+export function shouldUseShellForCommand(
+  command: string,
+  platform: NodeJS.Platform = process.platform
+): boolean {
+  return platform === "win32" && WINDOWS_CMD_SHIMS.has(command.toLowerCase());
+}
diff --git a/packages/utils/tsconfig.json b/packages/utils/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/scripts/shared/esbuild.ts b/scripts/shared/esbuild.ts
@@ -4,7 +4,7 @@
 
 import { type BuildOptions } from "esbuild";
 import { resolve } from "path";
-import { CLI_DIR, CORE_DIR, PACKAGES_DIR, PROVIDERS_DIR, SERVER_DIR } from "./paths.js";
+import { CLI_DIR, CORE_DIR, PACKAGES_DIR, PROVIDERS_DIR, SERVER_DIR, UTILS_DIR } from "./paths.js";
 
 /**
  * Get external dependencies from package.json
@@ -33,13 +33,15 @@ export async function createCliBuildOptions(format: "esm" | "cjs"): Promise<Buil
   const serverExternal = await getExternalDeps(SERVER_DIR);
   const coreExternal = await getExternalDeps(CORE_DIR);
   const providersExternal = await getExternalDeps(PROVIDERS_DIR);
+  const utilsExternal = await getExternalDeps(UTILS_DIR);
 
   // Combine all dependencies
   const allDeps = new Set([
     ...cliExternal,
     ...serverExternal,
     ...coreExternal,
     ...providersExternal,
+    ...utilsExternal,
   ]);
 
   // Only externalize third-party dependencies (not internal @coder-studio/* packages)
@@ -73,6 +75,7 @@ export async function createCliBuildOptions(format: "esm" | "cjs"): Promise<Buil
       "@coder-studio/core/runtime": resolve(CORE_DIR, "src/runtime.ts"),
       "@coder-studio/core": resolve(CORE_DIR, "src/index.ts"),
       "@coder-studio/providers": resolve(PROVIDERS_DIR, "src/index.ts"),
+      "@coder-studio/utils": resolve(UTILS_DIR, "src/index.ts"),
     },
     banner: format === "esm" ? { js: "// @spencer-kit/coder-studio - ESM bundle" } : undefined,
   };
@@ -86,13 +89,15 @@ export async function getProductionDeps(): Promise<string[]> {
   const serverExternal = await getExternalDeps(SERVER_DIR);
   const coreExternal = await getExternalDeps(CORE_DIR);
   const providersExternal = await getExternalDeps(PROVIDERS_DIR);
+  const utilsExternal = await getExternalDeps(UTILS_DIR);
 
   // Combine all dependencies and filter out internal packages
   const allDeps = new Set([
     ...cliExternal,
     ...serverExternal,
     ...coreExternal,
     ...providersExternal,
+    ...utilsExternal,
   ]);
 
   return Array.from(allDeps).filter((dep) => !dep.startsWith("@coder-studio/"));
diff --git a/scripts/shared/paths.ts b/scripts/shared/paths.ts
@@ -16,6 +16,7 @@ export const PACKAGES_DIR = resolve(ROOT_DIR, "packages");
 export const CORE_DIR = resolve(PACKAGES_DIR, "core");
 export const PROVIDERS_DIR = resolve(PACKAGES_DIR, "providers");
 export const SERVER_DIR = resolve(PACKAGES_DIR, "server");
+export const UTILS_DIR = resolve(PACKAGES_DIR, "utils");
 export const WEB_DIR = resolve(PACKAGES_DIR, "web");
 export const CLI_DIR = resolve(PACKAGES_DIR, "cli");
 
diff --git a/scripts/shared/process.ts b/scripts/shared/process.ts
@@ -2,8 +2,10 @@
  * Process utilities for running child processes
  */
 
+import { isDirectExecution, shouldUseShellForCommand } from "@coder-studio/utils";
 import { type ChildProcess, type SpawnOptions, spawn } from "child_process";
-import { posix, resolve } from "path";
+
+export { isDirectExecution, shouldUseShellForCommand };
 
 export interface ProcessOptions {
   cwd?: string;
@@ -17,75 +19,6 @@ interface SpawnConfig {
   platform?: NodeJS.Platform;
 }
 
-const WINDOWS_CMD_SHIMS = new Set(["pnpm", "npm", "npx"]);
-
-function isWindowsDrivePath(path: string): boolean {
-  return /^[A-Za-z]:\//.test(path);
-}
-
-function normalizeComparablePath(path: string): string {
-  let normalized = path.replace(/\\/g, "/");
-
-  if (/^\/[A-Za-z]:\//.test(normalized)) {
-    normalized = normalized.slice(1);
-  }
-
-  if (normalized.startsWith("//")) {
-    normalized = `//${posix.normalize(normalized.slice(2))}`;
-  } else {
-    normalized = posix.normalize(normalized);
-  }
-
-  if (isWindowsDrivePath(normalized) || normalized.startsWith("//")) {
-    normalized = normalized.toLowerCase();
-  }
-
-  return normalized;
-}
-
-function normalizeModuleUrlPath(moduleUrl: string): string | null {
-  let url: URL;
-
-  try {
-    url = new URL(moduleUrl);
-  } catch {
-    return null;
-  }
-
-  if (url.protocol !== "file:") {
-    return null;
-  }
-
-  const path = `${url.host ? `//${url.host}` : ""}${decodeURIComponent(url.pathname)}`;
-  return normalizeComparablePath(path);
-}
-
-function normalizeArgvPath(argv1: string): string {
-  const isAbsoluteWindowsPath = /^[A-Za-z]:[\\/]/.test(argv1) || /^\\\\/.test(argv1);
-  return normalizeComparablePath(isAbsoluteWindowsPath ? argv1 : resolve(argv1));
-}
-
-export function isDirectExecution(moduleUrl: string, argv1: string | undefined = process.argv[1]) {
-  if (argv1 === undefined) {
-    return false;
-  }
-
-  const modulePath = normalizeModuleUrlPath(moduleUrl);
-
-  if (modulePath === null) {
-    return false;
-  }
-
-  return modulePath === normalizeArgvPath(argv1);
-}
-
-export function shouldUseShellForCommand(
-  command: string,
-  platform: NodeJS.Platform = process.platform
-): boolean {
-  return platform === "win32" && WINDOWS_CMD_SHIMS.has(command.toLowerCase());
-}
-
 function createSpawnOptions({
   command,
   options,

Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,11 @@ function normalizeModuleUrlPath(moduleUrl: string): string \| null {`
`41`	`41`	`return normalizeComparablePath(path);`
`42`	`42`	`}`
`43`	`43`
	`44`	`+function normalizeArgvPath(argv1: string): string {`
	`45`	`+ const isAbsoluteWindowsPath = /^[A-Za-z]:[\\/]/.test(argv1) \|\| /^\\\\/.test(argv1);`
	`46`	`+ return normalizeComparablePath(isAbsoluteWindowsPath ? argv1 : resolve(argv1));`
	`47`	`+}`
	`48`	`+`
`44`	`49`	`export function isDirectExecution(`
`45`	`50`	`moduleUrl: string,`
`46`	`51`	`argv1: string \| undefined = process.argv[1]`
`@@ -55,8 +60,5 @@ export function isDirectExecution(`
`55`	`60`	`return false;`
`56`	`61`	`}`
`57`	`62`
`58`		`- const isAbsoluteWindowsPath = /^[A-Za-z]:[\\/]/.test(argv1) \|\| /^\\\\/.test(argv1);`
`59`		`- const argvPath = normalizeComparablePath(isAbsoluteWindowsPath ? argv1 : resolve(argv1));`
`60`		`-`
`61`		`- return modulePath === argvPath;`
	`63`	`+ return modulePath === normalizeArgvPath(argv1);`
`62`	`64`	`}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export { isDirectExecution } from "./direct-execution.js";`
	`2`	`+export { shouldUseShellForCommand } from "./windows-shim.js";`