Enable cross-platform E2E tests (Windows, Linux, macOS)

- Remove the Windows exclusion guard from E2E test step in CI workflow
- The process-isolated child-process harness uses only cross-platform Node.js
  APIs (spawn, readline, stdio pipes) and is verified to work on Windows
- Add .gitattributes to enforce LF line endings on snapshot golden files
- Add normalizeEOL() helper in snapshot tests for Windows CRLF handling
- Add E2E_TIMEOUT_MS env var support for configurable test timeouts
- Add engines.node >=22 to package.json
- Add tsconfig.json for type checking
- Update CI documentation in CONTRIBUTING.md

Closes #12

Author: ofriw

.gitattributes

@@ -0,0 +1 @@
+tests/__snapshots__/**/*.txt text eol=lf

.github/workflows/test.yml

@@ -0,0 +1,93 @@
+# Cross-platform CI for pi-agenticoding
+#
+# Runs the full unit suite on Linux, macOS, and Windows
+# on the minimum Node.js version required by pi coding agent. Snapshot
+# tests verify TUI render output against golden files.
+
+name: test
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main]
+    paths-ignore: ['*.md', '**/docs/**']
+  pull_request:
+    branches: [main]
+    paths-ignore: ['*.md', '**/docs/**']
+
+jobs:
+  # ── Quick-check gate — catch trivial failures before the full matrix ──
+  quick-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22"
+          cache: "npm"
+      - run: npm ci
+
+      # Fast pre-flight checks — type errors and security issues before matrix
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Security audit
+        run: npm audit --audit-level=moderate
+
+  # ── Cross-platform test matrix ──────────────────────────────────────
+  # Node 22 (minimum) is tested only on Linux — the primary platform and the only one
+  # guaranteed to have the oldest toolchain. macOS and Windows test Node 24 (latest)
+  # to catch regressions in the newest runtime. This asymmetry is intentional: it
+  # balances CI cost with meaningful coverage while ensuring the minimum version works
+  # correctly on the platform most likely to encounter toolchain edge cases.
+  test:
+    needs: quick-check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false          # report every combination, don't cancel
+      matrix:
+        include:
+          - os: ubuntu-latest
+            node-version: "22"    # minimum version on primary platform
+          - os: ubuntu-latest
+            node-version: "24"    # latest on primary platform
+          - os: macos-latest
+            node-version: "24"    # latest on macOS
+          - os: windows-latest
+            node-version: "24"    # latest on Windows
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - run: npm ci
+
+      # Unit suite (unit tests + snapshot tests + property-based tests)
+      - name: Unit tests
+        run: npm test
+
+      # E2E tests — process-isolated child-process harness (stdin/stdout, no PTY).
+      # Verified cross-platform: runs on Linux, macOS, and Windows.
+      # See https://github.com/agenticoding/pi-agenticoding/issues/12
+      - name: E2E tests
+        run: npm run test:e2e
+
+      # Upload test results for debugging — artifacts available for 30 days.
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.os }}-node-${{ matrix.node-version }}
+          path: |
+            test-results/
+            tests/__snapshots__/
+          retention-days: 30

CONTRIBUTING.md

@@ -46,6 +46,16 @@ Before submitting, check that your change:
 - `npm run test:snapshots:update` — rewrites the golden files in `tests/__snapshots__/` after an intentional render change. Review the diff carefully: snapshot updates are the only signal that catches unintended UI regressions.
 - `npm run test:e2e` — runs the process-isolated end-to-end suite under `tests/e2e/`.
 
+## CI
+
+Pull requests are automatically tested via GitHub Actions. The pipeline runs:
+
+1. **Quick-check** (Ubuntu, Node 22): `npm ci`, type check (`npx tsc --noEmit`), and security audit (`npm audit`). Catches trivial failures before the full matrix.
+2. **Cross-platform matrix** (depends on quick-check): Unit tests on Ubuntu (Node 22 + 24), macOS (Node 24), and Windows (Node 24). E2E tests on all platforms.
+
+Snapshot golden files in `tests/__snapshots__/` are stored with LF line endings (enforced by `.gitattributes`). The `normalizeEOL` helper in the snapshot test file normalizes `\r\n` to `\n` on read, so Windows developers get correct comparisons even if their working tree has CRLF. If you update snapshots, the CI matrix validates them on all platforms.
+The E2E suite runs on all platforms including Windows (verified in issue #12).
+
 ## Community
 
 Use GitHub Issues for bug reports and feature requests. Keep discussions concrete: describe the agent workflow you expected, what happened instead, and any reproduction steps.

package.json

@@ -11,6 +11,9 @@
     "type": "git",
     "url": "git+https://github.com/agenticoding/pi-agenticoding.git"
   },
+  "engines": {
+    "node": ">=22"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",

tests/e2e/pty-harness.ts

@@ -15,6 +15,8 @@ const ROOT = resolve(HERE, "..", "..");
 const LOADER = pathToFileURL(resolve(ROOT, "register-loader.mjs")).href;
 
 export const DEFAULT_SCRIPT = resolve(HERE, "test-host.ts");
+const DEFAULT_TIMEOUT_MS = 5000;
+const TIMEOUT_MS = parseInt(process.env.E2E_TIMEOUT_MS ?? "", 10) || DEFAULT_TIMEOUT_MS;
 
 export class PytestHarness {
   private child: ChildProcessWithoutNullStreams;
@@ -27,7 +29,7 @@ export class PytestHarness {
     scriptPath = DEFAULT_SCRIPT,
     options?: { timeoutMs?: number },
   ) {
-    this.timeoutMs = options?.timeoutMs ?? 5000;
+    this.timeoutMs = options?.timeoutMs ?? TIMEOUT_MS;
 
     const entry = isAbsolute(scriptPath) ? scriptPath : resolve(ROOT, scriptPath);
 

tests/unit/render-snapshots.test.ts

@@ -56,17 +56,22 @@ function ensureSnapshotDir(): void {
 	}
 }
 
+/** Normalize line endings so golden files (stored with \n) match on Windows (\r\n). */
+function normalizeEOL(s: string): string {
+	return s.replace(/\r?\n/g, "\n");
+}
+
 function matchSnapshot(name: string, actual: string): void {
 	ensureSnapshotDir();
 	const file = join(SNAPSHOT_DIR, `${name}.txt`);
 	if (process.env.UPDATE_SNAPSHOTS) {
-		writeFileSync(file, actual);
+		writeFileSync(file, normalizeEOL(actual));
 		return;
 	}
 	if (!existsSync(file)) {
 		assert.fail(`Snapshot ${name} is missing. Re-run with UPDATE_SNAPSHOTS=1 to create it.`);
 	}
-	const expected = readFileSync(file, "utf-8");
+	const expected = normalizeEOL(readFileSync(file, "utf-8"));
 	assert.equal(actual, expected, `Snapshot ${name} does not match`);
 }
 

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["*.ts", "**/*.ts"]
+}