fix: normalize discovered paths, add a Windows CI job, and require Node 20 (#131)

Discovery normalizes every stored path to forward slashes, rule comparisons and the MiniClaw sandbox use the platform separator, chmod-dependent and POSIX-shell-backed tests skip on Windows, evidence packs redact native, forward-slash, and JSON-escaped paths and normalize separators, and test batches run through a glob-free Node runner. A windows-latest CI job runs typecheck, build, and the full suite. vitest 4 no longer starts on Node 18 (end of life April 2025), so CI runs Node 20 and 22 and engines.node is >=20. Fixes #125.

Author: affaan-m

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [18, 20, 22]
+        node-version: [20, 22]
 
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -50,6 +50,37 @@ jobs:
       - name: Run tests
         run: npm test
 
+  verify-windows:
+    name: Verify (Windows, Node 22)
+    runs-on: windows-latest
+    timeout-minutes: 25
+
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Use Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
   self-scan:
     name: Self-scan examples
     runs-on: ubuntu-latest

package.json

@@ -21,11 +21,11 @@
     "prepublishOnly": "npm run build",
     "dev": "tsx src/index.ts",
     "test": "npm run test:batch:core && npm run test:batch:analysis && npm run test:batch:miniclaw-a && npm run test:batch:miniclaw-b && npm run test:batch:misc",
-    "test:batch:core": "vitest run tests/rules/*.test.ts tests/scanner/*.test.ts tests/reporter/*.test.ts",
-    "test:batch:analysis": "vitest run tests/integration.test.ts tests/injection.test.ts tests/action.test.ts tests/action-policy.test.ts tests/action-supply-chain.test.ts tests/action-hardening.test.ts tests/action-promotion.test.ts",
-    "test:batch:miniclaw-a": "vitest run tests/miniclaw/index.test.ts tests/miniclaw/server.test.ts",
-    "test:batch:miniclaw-b": "vitest run tests/miniclaw/cli.test.ts tests/miniclaw/sandbox.test.ts",
-    "test:batch:misc": "vitest run tests/corpus.test.ts tests/logger.test.ts tests/init/init.test.ts tests/taint/taint.test.ts tests/opus/*.test.ts tests/fixer/*.test.ts tests/types.test.ts tests/skills/*.test.ts tests/llm/*.test.ts tests/miniclaw/router.test.ts tests/miniclaw/tools.test.ts tests/miniclaw/types.test.ts tests/sandbox/sandbox.test.ts tests/threat-intel/*.test.ts tests/watch/*.test.ts tests/runtime/*.test.ts tests/baseline/*.test.ts tests/evidence-pack/*.test.ts tests/supply-chain/*.test.ts tests/policy/*.test.ts tests/sponsor-surface.test.ts",
+    "test:batch:core": "node scripts/test-batch.mjs core",
+    "test:batch:analysis": "node scripts/test-batch.mjs analysis",
+    "test:batch:miniclaw-a": "node scripts/test-batch.mjs miniclaw-a",
+    "test:batch:miniclaw-b": "node scripts/test-batch.mjs miniclaw-b",
+    "test:batch:misc": "node scripts/test-batch.mjs misc",
     "test:coverage": "vitest --coverage",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
@@ -88,6 +88,6 @@
     "flatted": "^3.4.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   }
 }

scripts/test-batch.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Runs one named vitest batch with an explicit file list so the batches do
+// not depend on shell glob expansion (npm runs scripts through cmd.exe on
+// Windows, which leaves *.test.ts untouched and vitest then finds nothing).
+import { spawnSync } from "node:child_process";
+import { globSync } from "glob";
+
+const BATCHES = {
+  core: ["tests/rules/*.test.ts", "tests/scanner/*.test.ts", "tests/reporter/*.test.ts"],
+  analysis: [
+    "tests/integration.test.ts",
+    "tests/injection.test.ts",
+    "tests/action.test.ts",
+    "tests/action-policy.test.ts",
+    "tests/action-supply-chain.test.ts",
+    "tests/action-hardening.test.ts",
+    "tests/action-promotion.test.ts",
+  ],
+  "miniclaw-a": ["tests/miniclaw/index.test.ts", "tests/miniclaw/server.test.ts"],
+  "miniclaw-b": ["tests/miniclaw/cli.test.ts", "tests/miniclaw/sandbox.test.ts"],
+  misc: [
+    "tests/corpus.test.ts",
+    "tests/logger.test.ts",
+    "tests/init/init.test.ts",
+    "tests/taint/taint.test.ts",
+    "tests/opus/*.test.ts",
+    "tests/fixer/*.test.ts",
+    "tests/types.test.ts",
+    "tests/skills/*.test.ts",
+    "tests/llm/*.test.ts",
+    "tests/compliance/*.test.ts",
+    "tests/miniclaw/router.test.ts",
+    "tests/miniclaw/tools.test.ts",
+    "tests/miniclaw/types.test.ts",
+    "tests/sandbox/sandbox.test.ts",
+    "tests/threat-intel/*.test.ts",
+    "tests/watch/*.test.ts",
+    "tests/runtime/*.test.ts",
+    "tests/baseline/*.test.ts",
+    "tests/evidence-pack/*.test.ts",
+    "tests/supply-chain/*.test.ts",
+    "tests/policy/*.test.ts",
+    "tests/sponsor-surface.test.ts",
+  ],
+};
+
+const name = process.argv[2];
+const patterns = BATCHES[name];
+if (!patterns) {
+  console.error(`Unknown test batch "${name}". Known: ${Object.keys(BATCHES).join(", ")}`);
+  process.exit(2);
+}
+
+const files = [...new Set(patterns.flatMap((pattern) => globSync(pattern, { posix: true })))].sort();
+if (files.length === 0) {
+  console.error(`Batch "${name}" matched no test files.`);
+  process.exit(1);
+}
+
+const vitest = process.platform === "win32" ? "npx.cmd" : "npx";
+const result = spawnSync(vitest, ["vitest", "run", ...files], { stdio: "inherit", shell: process.platform === "win32" });
+process.exit(result.status ?? 1);

src/evidence-pack/index.ts

@@ -1311,9 +1311,11 @@ function createRedactor(
 
   const redactString = (value: string): string => {
     if (!enabled) return value;
-    return replacements.reduce(
-      (redacted, [pattern, replacement]) => redacted.replace(pattern, replacement),
-      value
+    return normalizeRedactedPathSeparators(
+      replacements.reduce(
+        (redacted, [pattern, replacement]) => redacted.replace(pattern, replacement),
+        value
+      )
     );
   };
 
@@ -1335,12 +1337,12 @@ function buildReplacements(targetPath: string): ReadonlyArray<[RegExp, string]>
   const home = homedir();
   const targetReplacements: ReadonlyArray<[RegExp, string]> = targetPath
     ? [
-        [literalPattern(resolve(targetPath)), "<target-path>"],
-        [literalPattern(targetPath), "<target-path>"],
+        ...pathPatterns(resolve(targetPath)).map((pattern): [RegExp, string] => [pattern, "<target-path>"]),
+        ...pathPatterns(targetPath).map((pattern): [RegExp, string] => [pattern, "<target-path>"]),
       ]
     : [];
   const homeReplacements: ReadonlyArray<[RegExp, string]> = home && home !== "/"
-    ? [[literalPattern(home), "<home>"]]
+    ? pathPatterns(home).map((pattern): [RegExp, string] => [pattern, "<home>"])
     : [];
   const userNames: ReadonlyArray<string> = [
     basename(home),
@@ -1381,6 +1383,29 @@ function literalPattern(value: string): RegExp {
   return new RegExp(escapeRegExp(value), "g");
 }
 
+/**
+ * Patterns for a filesystem path as it may appear in report text: native
+ * form, forward-slash form, and the JSON-escaped form Windows paths take
+ * once serialized. Evidence packs must redact all three to stay portable.
+ */
+function pathPatterns(value: string): ReadonlyArray<RegExp> {
+  const backslash = String.fromCharCode(92);
+  const variants = new Set<string>([
+    value,
+    value.split(backslash).join("/"),
+    value.split(backslash).join(backslash + backslash),
+  ]);
+  return [...variants].filter((variant) => variant.length > 0).map(literalPattern);
+}
+
+/** Forward-slash the remainder of any redacted path so packs match across platforms. */
+function normalizeRedactedPathSeparators(text: string): string {
+  const backslash = String.fromCharCode(92);
+  const tail = new RegExp("(<target-path>|<home>)((?:" + backslash + backslash + backslash + backslash + "|" + backslash + backslash + ")[^\\s\"'<>]*)", "g");
+  const separators = new RegExp(backslash + backslash + backslash + backslash + "|" + backslash + backslash, "g");
+  return text.replace(tail, (_match, placeholder: string, rest: string) => placeholder + rest.replace(separators, "/"));
+}
+
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

src/miniclaw/sandbox.ts

@@ -9,7 +9,7 @@
  */
 
 import { mkdir, rm, stat, realpath, access } from "node:fs/promises";
-import { join, resolve, relative, extname } from "node:path";
+import { join, resolve, relative, extname, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import type {
   SandboxConfig,
@@ -51,7 +51,7 @@ export async function validatePath(
   // WHY: This is the primary containment check. After resolution, any path
   // that doesn't start with the sandbox root has escaped.
   const normalizedSandbox = resolve(sandboxPath);
-  if (!absoluteRequested.startsWith(normalizedSandbox + "/") && absoluteRequested !== normalizedSandbox) {
+  if (!absoluteRequested.startsWith(normalizedSandbox + sep) && absoluteRequested !== normalizedSandbox) {
     return {
       valid: false,
       resolvedPath: absoluteRequested,
@@ -65,7 +65,7 @@ export async function validatePath(
   try {
     await access(absoluteRequested);
     const realPath = await realpath(absoluteRequested);
-    if (!realPath.startsWith(normalizedSandbox + "/") && realPath !== normalizedSandbox) {
+    if (!realPath.startsWith(normalizedSandbox + sep) && realPath !== normalizedSandbox) {
       return {
         valid: false,
         resolvedPath: realPath,
@@ -216,7 +216,7 @@ export async function destroySandbox(
   const normalizedSandbox = resolve(sandboxPath);
   const normalizedRoot = resolve(rootPath);
 
-  if (!normalizedSandbox.startsWith(normalizedRoot + "/")) {
+  if (!normalizedSandbox.startsWith(normalizedRoot + sep)) {
     return {
       success: false,
       reason: `Sandbox path "${sandboxPath}" is not under root "${rootPath}" — refusing to delete`,
@@ -227,7 +227,7 @@ export async function destroySandbox(
   // WHY: Prevents deletion of the root itself or deeply nested system paths
   // that happen to share the root prefix
   const relativePath = relative(normalizedRoot, normalizedSandbox);
-  if (relativePath.includes("/") || relativePath === "" || relativePath === "..") {
+  if (relativePath.includes("/") || relativePath.includes("\\") || relativePath === "" || relativePath === "..") {
     return {
       success: false,
       reason: `Sandbox path must be a direct child of root — got relative path "${relativePath}"`,

src/rules/agents.ts

@@ -176,7 +176,7 @@ function isSlashCommandConfig(file: ConfigFile, isStructuredDefinition: boolean)
   return (
     file.type === "command-md" &&
     isStructuredDefinition &&
-    file.path.toLowerCase().includes("slash-commands/")
+    normalizePath(file.path).includes("slash-commands/")
   );
 }
 

src/rules/mcp.ts

@@ -78,7 +78,7 @@ function findEnabledBooleanFlag(
 }
 
 function isLikelyMcpTemplatePath(filePath: string): boolean {
-  const normalized = filePath.toLowerCase();
+  const normalized = filePath.replace(/\\/g, "/").toLowerCase();
   return (
     normalized.startsWith("mcp-configs/") ||
     normalized.includes("/mcp-configs/") ||
@@ -108,7 +108,7 @@ function classifyMcpRuntimeConfidence(file: ConfigFile): RuntimeConfidence {
     return "template-example";
   }
 
-  const normalizedPath = file.path.toLowerCase();
+  const normalizedPath = file.path.replace(/\\/g, "/").toLowerCase();
   if (normalizedPath === "settings.local.json" || normalizedPath.endsWith("/settings.local.json")) {
     return "project-local-optional";
   }

src/rules/permissions.ts

@@ -9,7 +9,7 @@ import {
 } from "./permission-entries.js";
 
 function isHookManifestConfig(file: ConfigFile, config: unknown): boolean {
-  if (!/(^|\/)hooks\/[^/]+\.json$/i.test(file.path)) return false;
+  if (!/(^|[\\/])hooks[\\/][^\\/]+\.json$/i.test(file.path)) return false;
   if (!config || typeof config !== "object") return false;
   return "hooks" in config;
 }
@@ -1129,6 +1129,11 @@ export const permissionRules: ReadonlyArray<Rule> = [
     check(file: ConfigFile): ReadonlyArray<Finding> {
       if (file.type !== "claude-md") return [];
 
+      // NTFS has no POSIX mode bits. Node reports 0o666 for every writable
+      // file on Windows, so the check would flag every CLAUDE.md as
+      // world-writable. Skip it there instead of emitting a bogus finding.
+      if (process.platform === "win32") return [];
+
       // Only check CLAUDE.md files that are likely to be the user's global
       // config or project-level config — both are prompt injection surfaces.
       const normalizedPath = file.path.replace(/\\/g, "/");

src/scanner/discovery.ts

@@ -3,6 +3,7 @@ import type { Stats } from "node:fs";
 import { join, basename, extname, relative } from "node:path";
 import type { ConfigFile, ConfigFileType, DanglingSymlink, ScanTarget } from "../types.js";
 import { isExampleLikePath } from "../source-context.js";
+import { toPosixPath } from "./paths.js";
 
 const IGNORED_DIRS = new Set([
   ".dmux",
@@ -322,7 +323,7 @@ function scanClaudeRoot(
       if (entryStat === null) {
         if (isDanglingSymlink(entryPath)) {
           danglingSymlinks.push({
-            path: relative(scanRoot, entryPath),
+            path: toPosixPath(relative(scanRoot, entryPath)),
             target: readSymlinkTarget(entryPath),
             type,
           });
@@ -547,7 +548,7 @@ function addDiscoveredFile(
   files: ConfigFile[],
   seenFiles: Set<string>
 ): void {
-  const relativePath = relative(scanRoot, fullPath);
+  const relativePath = toPosixPath(relative(scanRoot, fullPath));
   if (seenFiles.has(relativePath)) return;
 
   const content = readFileSync(fullPath, "utf-8");

src/scanner/paths.ts

@@ -0,0 +1,15 @@
+/**
+ * Path normalization for scan output.
+ *
+ * Policy: every path stored on a ConfigFile (`path`), on a DanglingSymlink
+ * (`path`), or compared against a literal such as ".vscode/tasks.json" uses
+ * forward slashes, regardless of host platform. Normalization happens at the
+ * point the relative path is produced (right after `relative()`), so rules,
+ * reporters, and tests can rely on a single separator. File system access
+ * keeps using the native path returned by `join()`; Node's `path.resolve`
+ * and `path.join` on Windows accept forward slashes when a consumer needs to
+ * turn a stored path back into a native one.
+ */
+export function toPosixPath(filePath: string): string {
+  return filePath.replace(/\\/g, "/");
+}