gemiterm 2.0.0 → 2.1.1

package/openspec/changes/cross-platform-build-and-ci/design.md

@@ -1,213 +0,0 @@
-## Context
-
-The Bun rewrite of GemiTerm is functionally complete (432/432 unit/integration/parity/smoke tests pass on Bun 1.3.13, all 11 CLI commands registered, auth flow working) but two structural pieces are missing: the **delivery pipeline** (build fix, CI, release) and the **path-and-file mediation layer** (a single source of truth for `node:fs` and `node:path` access in `src/`).
-
-The current `package.json:20-22` build scripts:
-
-```json
-"build": "bun build --compile --target=bun --outdir=dist src/cli/index.ts",
-"build:linux": "bun build --compile --target=bun-linux-x64 --outdir=dist src/cli/index.ts",
-"build:windows": "bun build --compile --target=bun-windows-x64 --outdir=dist src/cli/index.ts"
-```
-
-Verified failure mode on Bun 1.3.13 (current dev environment): `bun run build` exits 1 with `error: cannot use --compile with --outdir`. Bun 1.3.x removed support for combining `--compile` with `--outdir` because the resulting tree semantics are undefined for a single-file executable.
-
-The Python release workflow at `docs/python-release-for-reference.md` (used by v1.4.1) is the target shape for the new Bun release workflow, but with PyInstaller-specific steps replaced by `bun build --compile`. The Python release tagged artifacts as `GemiTerm` (Linux) and `GemiTerm.exe` (Windows); the Bun release MUST preserve those names so the v1.4.1 `install.ps1` referenced by the related `v2-install-migration` change keeps working.
-
-A read-only audit of `src/` shows the rewrite does **node:fs** and **node:path** access in 9 files, with at least 4 copy-pasted write-to-disk blocks and ~20 open-coded `mkdirSync` / `existsSync` / `renameSync` calls. The original OpenSpec change proposed a `platform-detect.ts` module to share one private `isWsl()` helper; that helper does not need a new file, and the broader duplication is the actual cross-platform work.
-
-The audit found:
-
-- **`src/cli/commands/export-command.ts:72-82`**, **`export-all-command.ts:79-80` + 96-104`**, **`list-command.ts:138-143`**, **`fetch-command.ts:121-127`** — the same "resolve path + ensure parent dir + writeFileSync UTF-8" block, copied 4 times. Two of those (`list` and `fetch`) are byte-identical 6-line `writeOutput` methods.
-- **`src/infrastructure/storage.ts`** — 11 inline `mkdirSync` / `writeFileSync` / `readFileSync` / `rmSync` / `renameSync` / `existsSync` calls in 6 methods.
-- **`src/infrastructure/config.ts`** — 64 lines, of which 30 are open-coded `node:fs` operations wrapping the `path-utils.ts` getters.
-- **`src/services/install-browser-service.ts`** — 11 inline `existsSync` / `readFileSync` calls; 2 near-identical `getEdgePaths` / `getChromePaths` methods; a private `isWsl()` that is the only consumer of `/proc/version` detection.
-- **`src/cli/index.ts:33-35`** — the only place in the rewrite that needs `__filename` / `__dirname` and is the only consumer of `fileURLToPath`; a one-liner helper would clean it up.
-
-The previous `isWsl()` is duplicated logic that will be needed by future command code, so it makes sense to lift it into `path-utils.ts`. The lift MUST be behavior-preserving; the 5 existing unit tests in `tests/services/install-browser-service.test.ts` are the regression gate. The `src/services/playwright-cli-driver.ts`, `src/services/cookie-monitor.ts`, and `src/services/auth-service.ts` files are off-limits and will not be touched by this change.
-
-Constraints:
-
-- **Bun 1.3.13** is the pinned toolchain (the env has it; `devDependencies.@types/bun: ^1.3.14`).
-- **GitHub Actions** is the CI/CD host (the repo is on GitHub per `docs/python-release-for-reference.md`).
-- **No breaking changes** to the CLI user surface; all changes are internal build/CI plus internal refactoring.
-- **No new runtime dependencies** are added; only removal of the unused `commander`.
-- **WSL** must be supported as a first-class target because GemiTerm's primary auth flow is browser-driven and WSL users invoke the Linux binary while their Chromium lives in the Windows host filesystem (handled today by `findWslBrowser` in `src/services/install-browser-service.ts:124-141`).
-- **The "no `node:fs` outside path-utils and io" rule is enforced by a CI lint check** in `.github/workflows/test.yml`, not by human review. The check excludes `tests/` and `tests/parity/` (a test-helper script) and the two allowed `src/` consumers (`path-utils.ts` and `install-browser-service.ts`).
-
-Stakeholders: maintainer (who ships the release), contributors (who need fast PR feedback), end users on Linux/Windows/WSL (who download the binary from GitHub Releases).
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Fix `bun run build` / `build:linux` / `build:windows` so they produce a working single-file executable on Bun 1.3.13.
-- Add a `release-pipeline` capability: three GitHub Actions workflows (`test.yml`, `build.yml`, `release.yml`) plus the build/clean/install-browser shell scripts that produce v2.0.0 cross-platform artifacts.
-- Add a `path-and-file-mediation` capability: extend `src/infrastructure/path-utils.ts` with `isWSL()`, `getProjectRoot()`, and `getPackageJson()`; create `src/infrastructure/io.ts` with the file-ops helpers; refactor the 7 call sites that currently use `node:fs` / `node:path` directly; add a CI lint check that enforces the rule going forward.
-- Keep the artifact naming convention `GemiTerm` (Linux/WSL) and `GemiTerm.exe` (Windows) so the v1.4.1 `install.ps1` keeps working.
-- Cleanup: remove the orphan `{` file at the repo root, remove the stray `{` line in `.gitignore:23`, remove the unused `commander` dependency, decide the fate of the empty `src/commands/` placeholder.
-- Update README with a "Building from source" section and a "Release artifacts" section.
-
-**Non-Goals:**
-
-- Touching `src/services/playwright-cli-driver.ts`, `src/services/cookie-monitor.ts`, or `src/services/auth-service.ts` (sensitive area per the change's explicit warning).
-- Publishing to npm, PyPI, Homebrew, or any package registry — distribution is GitHub Releases + raw `install.sh` / `install.ps1` only.
-- Adding a code-signing step for Windows binaries (would require a cert and is deferred).
-- Adding macOS / Darwin builds to the matrix (no users on that platform have requested it; `isWSL()` is not relevant on macOS and the rewrite does not need a `isDarwin()` helper).
-- Migrating the existing Python `v1.4.1 install.ps1` (that lives in the related `v2-install-migration` change).
-- Adding new test cases for `install-browser-service` — the 5 existing tests are the regression gate and that is sufficient.
-- Switching the CI provider away from GitHub Actions.
-
-## Decisions
-
-### D1. `src/infrastructure/io.ts` is a separate file from `path-utils.ts`, not a re-export
-
-`path-utils.ts` is about **storage paths and config directories** (functions: `resolvePath`, `getConfigDir`, `getProfilesDir`, `getProfilePath`, `getProfileDir`, `getDefaultProfileMarkerPath`, plus three constants, plus the new `isWSL`, `getProjectRoot`, `getPackageJson`). `io.ts` is about **file-system operations** (`ensureDir`, `existsFile`, `readTextFile`, `writeTextFile`, `readJsonFile`, `writeJsonFile`, `removeDir`, `renameDir`, `isDirectory`, `listSubdirectories`). The two concerns are distinct: paths are values; file ops are side effects. Conflating them would create a God-module.
-
-The dependency direction is one-way: `io.ts` may import from `path-utils.ts` (for path joining and the WSL detection), but `path-utils.ts` does not import from `io.ts`. This is verifiable by `grep` and is part of the lint rule.
-
-**Alternative considered:** Put everything in `path-utils.ts`. Rejected: mixes concerns, makes the file longer, and obscures the dependency direction.
-
-**Alternative considered:** Put everything in `io.ts` and re-export from `path-utils.ts` for backward compatibility. Rejected: forces every call site to know which is the "real" home; the dependency direction is the wrong way around.
-
-### D2. Drop `--outdir` from `bun build --compile`; use `--outfile` for deterministic artifact paths
-
-Verified failure mode on Bun 1.3.13: `bun build --compile --target=bun --outdir=dist src/cli/index.ts` exits 1 with `error: cannot use --compile with --outdir`. Bun 1.3.x removed this combination because a single-file executable has no meaningful relationship to an output directory tree.
-
-Two viable fixes in Bun 1.3.x:
-
-1. **Drop `--outdir` entirely** → Bun places the binary in `cwd` named after the **parent directory** of the entrypoint. Fragile and surprising.
-2. **Use `--outfile <path>`** → Bun places the binary at the specified path. Matches the v1.4.1 PyInstaller convention and gives CI a deterministic upload path.
-
-**Chosen: option 2** — `--outfile dist/gemiterm` for the platform-specific scripts. The resulting build scripts:
-
-```json
-"build": "bun build --compile --target=bun --outfile dist/gemiterm src/cli/index.ts",
-"build:linux": "bun build --compile --target=bun-linux-x64 --outfile dist/gemiterm src/cli/index.ts",
-"build:windows": "bun build --compile --target=bun-windows-x64 --outfile dist/gemiterm src/cli/index.ts",
-"build:release": "bun build --compile --target=bun --outfile dist/gemiterm --minify src/cli/index.ts"
-```
-
-### D3. The `isWSL()` helper is in `path-utils.ts`, not in a separate `platform-detect.ts`
-
-The original spec proposed a 7-helper `platform-detect.ts` module (`isWindows`, `isLinux`, `isWSL`, `isDarwin`, `detectPlatform`, `getPlatformName`, `normalizePath`). A read-only audit found **zero callers** for six of those helpers; the only non-trivial check (`isWSL()`) is the one with a real consumer. Putting `isWSL()` in its own file is over-engineering; lifting it into `path-utils.ts` keeps the cross-platform concern in the same module as the other path-related code.
-
-The 6 unnecessary helpers (`isWindows`, `isLinux`, `isDarwin`, `detectPlatform`, `getPlatformName`, `normalizePath`) are **dropped**. The only `process.platform` checks in the rewrite are 3 inline in `install-browser-service.ts` (lines 58, 61, 185), all of which are clearer as inline `=== 'win32'` / `=== 'linux'` checks than as named boolean predicates.
-
-The `isWSL()` implementation is a strict superset of the old private `isWsl()`: it checks both `/proc/version` (for "microsoft" or "WSL" case-insensitive) AND the `WSL_DISTRO_NAME` env var. This is a minor improvement in detection coverage; the 5 unit tests in `tests/services/install-browser-service.test.ts` are not affected because they do not exercise WSL detection directly.
-
-### D4. The 4-copy "write to disk" block becomes a single `writeTextFile()` helper
-
-The same 3-line pattern (`resolve path + ensure parent dir + writeFileSync UTF-8`) appears in `export-command.ts`, `export-all-command.ts`, `list-command.ts`, and `fetch-command.ts`. Two of those (`list` and `fetch`) are byte-identical 6-line `writeOutput` private methods. A single `writeTextFile(path, content)` in `io.ts` consolidates the pattern; the call sites collapse to one line each.
-
-### D5. The CI lint check is a hard failure on PRs
-
-The rule "no `node:fs` / `node:path` / `node:os` imports in `src/` outside `path-utils.ts` and `install-browser-service.ts`" is enforced by a grep-based check in `.github/workflows/test.yml`:
-
-```bash
-! grep -rn --include='*.ts' --exclude-dir=infrastructure --exclude-dir=install-browser-service \
-  "from \"node:\\(fs\\|path\\|os\\)\"" src/
-```
-
-Wait, `--exclude-dir` in grep is for the directory the match is in, not the filename. The right invocation is:
-
-```bash
-grep -rn --include='*.ts' "from \"node:\\(fs\\|path\\|os\\)\"" src/ \
-  | grep -v "src/infrastructure/path-utils.ts" \
-  | grep -v "src/services/install-browser-service.ts" \
-  | (! grep .)
-```
-
-The check is a hard failure: if any forbidden import is found, the test job exits non-zero. The exclusion list is `path-utils.ts` (the canonical home) and `install-browser-service.ts` (the only legitimate cross-platform `node:path` consumer, for the WSL mount parser). `tests/` is not in scope of the check (the rule is about `src/` only).
-
-**Alternative considered:** ESLint plugin with `no-restricted-imports`. Rejected: adds a new dev dependency and a config file; the grep check is one line and requires no additional tooling.
-
-### D6. Three separate workflow files (test.yml, build.yml, release.yml) instead of one combined workflow
-
-The Python reference (`docs/python-release-for-reference.md:1-175`) uses a single `Release` workflow with all jobs inside. We will split into three because:
-
-1. **`test.yml` runs on every PR** — it must be fast and not blocked by the slower build matrix.
-2. **`build.yml` runs on tag push + manual dispatch** — it has a matrix that takes 5-10 minutes.
-3. **`release.yml` is the only one that creates the GitHub Release** — splitting it means a re-publish can be done by re-running just `release.yml` after fixing a release-note mistake.
-
-This is the standard GitHub Actions pattern for "test on PR, build on tag, release on tag" and is well-supported by `actions/upload-artifact@v4` (artifacts persist 90 days by default, which is enough for `release.yml` to download them).
-
-### D7. WSL is a separate build job, not a runtime check
-
-WSL needs its own `build-wsl` job that runs on `ubuntu-latest` and produces a Linux x64 binary. WSL itself can run any Linux ELF binary, so a regular Linux build is sufficient — but having a dedicated `build-wsl` job in the matrix makes the artifact explicit and named consistently in the GitHub Actions UI.
-
-### D8. Artifact naming preserves v1.4.1 convention
-
-| Platform | Local build path | CI artifact name | Release asset name |
-|----------|------------------|------------------|--------------------|
-| Linux x64 | `dist/gemiterm` | `GemiTerm` | `GemiTerm` |
-| Windows x64 | `dist/gemiterm.exe` | `GemiTerm.exe` | `GemiTerm.exe` |
-| WSL (Linux x64) | `dist/gemiterm` | `GemiTerm` | (not released — only Linux) |
-
-The v1.4.1 `install.ps1` looks for `GemiTerm.exe` in the release assets.
-
-### D9. `bunx @playwright/cli install chromium` is the canonical install command
-
-The existing `src/services/install-browser-service.ts:183` already spawns `bunx @playwright/cli install chromium`. The new user-facing `scripts/install-browser.sh` and `scripts/install-browser.ps1` will use the exact same command.
-
-### D10. The `src/commands/` placeholder is removed
-
-The directory contains only a `.gitkeep`. Decision: remove both the directory and the `.gitkeep`. No code references it. The CLI commands live in `src/cli/commands/`.
-
-## Risks / Trade-offs
-
-- **Risk:** `--outfile` was added in Bun 1.3.x; older Bun versions (1.2.x) don't have it. → **Mitigation:** `devDependencies.@types/bun: ^1.3.14` already pins us to 1.3.x; CI uses `oven-sh/setup-bun@v2` with `bun-version: 1.3.13` explicitly.
-
-- **Risk:** Cross-compile from Linux to Windows requires a Bun-built-for-Windows toolchain at compile time. → **Mitigation:** the `build-windows` job runs on `windows-latest`. We never cross-compile Windows FROM Linux.
-
-- **Risk:** The `isWSL()` is broader than the old private `isWsl()`. If any test or code path assumed the old narrower check, behavior could change. → **Mitigation:** the WSL branch in `findLinuxBrowser` only adds extra candidate paths; it never removes any. Worst case, more browsers are detected. The 5 unit tests in `tests/services/install-browser-service.test.ts` all pass against the new code.
-
-- **Risk:** The CI lint check uses `grep` rather than a proper linter, so it can be fooled by multi-line imports or import-string concatenation. → **Mitigation:** the rule is enforced on `src/`; all current `src/` files use single-line `import … from "node:fs"` statements. Future authors who try to obfuscate the import will fail code review.
-
-- **Risk:** A new contributor legitimately needs `node:fs` for a new feature in `src/`. → **Mitigation:** the right answer is to add a new helper to `io.ts` and use that. If the helper is genuinely impossible to write in `io.ts` (e.g. it requires direct `fs.watch` access), the contributor edits the `.github/workflows/test.yml` exclusion list with a comment explaining why.
-
-- **Risk:** `safeReadTextFile` returns `""` on any error (preserves the existing `readFileSafe` behavior in `install-browser-service.ts:173-179`). An empty return confuses "file does not exist" with "file exists but is empty". → **Mitigation:** the only current caller (`isWsl()` check on `/proc/version`) is robust to both `""` and `null`; the result is used in a `.toLowerCase().includes("microsoft")` check that returns false on `""`. A code comment in `io.ts` notes the `""` semantic and its implication for future callers.
-
-- **Risk:** The `io.ts` module grows over time and becomes its own God-module. → **Mitigation:** the module is already 10 functions focused on a single concern (file-system access). New functions should be added only if they are used in at least 2 call sites; ad-hoc single-use helpers should stay in the call site.
-
-- **Risk:** `softprops/action-gh-release@v2` is a third-party action. If it breaks, the release pipeline fails. → **Mitigation:** pin to a specific minor version (`@v2.3.x`); the Python reference already uses this action.
-
-- **Risk:** GitHub Actions matrix can fail intermittently. → **Mitigation:** no retry for v1.4.1; we match that. The maintainer re-runs on flake.
-
-- **Risk:** Removing `commander` from `package.json` and `bun.lock` requires `bun install` to regenerate the lockfile. → **Mitigation:** the verification task includes running `bun install --frozen-lockfile` to detect drift.
-
-- **Risk:** The orphan `{` file has been there long enough to be a known-good. Removing it could break a downstream tool that `cat`s the repo. → **Mitigation:** search the repo for any reference to a file named `{` (none found) before deletion. The file is untracked, so deletion is a no-op for git history.
-
-- **Trade-off:** Splitting CI into three workflows means the `release.yml` job has to re-run `test` and `build` jobs because of the `needs:` chain. → **Accepted:** with three workflows, `test.yml` and `build.yml` cache their results via `actions/upload-artifact@v4`; `release.yml` only re-runs the release step on manual re-run.
-
-- **Trade-off:** A separate `build-wsl` job doubles the matrix time vs. reusing `build-linux`. → **Accepted:** matrix runs in parallel; total wall-clock time is `max(linux, windows, wsl) ≈ 5 minutes` either way.
-
-## Migration Plan
-
-The change is purely additive plus one CLI build fix and a refactor of 7 internal call sites. There is no user-visible migration.
-
-**Deploy steps** (all done in this PR):
-
-1. Land the `path-utils.ts` extensions + `io.ts` module + refactor of the 7 call sites. Run `bun test` — must stay at 432/432 plus the new tests.
-2. Fix `package.json:20-22` build scripts. Run `bun run build` and `bun run build:linux` locally — both must produce an executable.
-3. Add the shell scripts (`scripts/clean-build.{sh,ps1}`, `scripts/install-browser.{sh,ps1}`).
-4. Add the three GitHub Actions workflows, including the lint check in `test.yml`.
-5. Cleanup: `.gitignore:23` (remove stray `{`), repo root (remove orphan `{`), `package.json:29` and `bun.lock` (remove `commander`), `src/commands/` (remove placeholder).
-6. Update README with "Building from source" + "Release artifacts" sections.
-7. After merge, push a `v2.0.0` tag. The `build.yml` matrix produces Linux + Windows + WSL binaries. The `release.yml` job attaches them to a GitHub Release with auto-generated notes.
-
-**Rollback strategy:**
-
-- The CLI build fix is not yet shipped, so there's nothing to roll back for end users.
-- The workflows only fire on tag push; if a `v2.0.0` tag is pushed and the release breaks, the maintainer can delete the GitHub Release or re-tag with a patch version.
-- The `install-browser-service` refactor has the 5 unit tests as a safety net; if any test fails post-refactor, revert the change to that file only.
-- The `io.ts` additions are additive; if they cause a circular import (verified not the case by inspection), revert by removing the import from the affected call site.
-
-## Open Questions
-
-- **Q1:** Should `safeReadTextFile` return `""` (preserves the old `readFileSafe` behavior) or `null` (more honest API)? **Decision:** keep `""` for minimum diff and add a code comment noting the implication. Future contributors can add a `safeReadTextFileOrNull` if needed.
-- **Q2:** Should the WSL build be a separate artifact in the GitHub Release, or is it identical to the Linux artifact? **Decision:** WSL is a CI-only check; the artifact is not released. If users complain, add it later.
-- **Q3:** Should the `install-browser.sh` and `install-browser.ps1` scripts also be uploaded to the GitHub Release? **Decision:** yes, attach both, but the v1.4.1 `install.ps1` will be the one referenced by `v2-install-migration`.
-- **Q4:** Should the `test.yml` workflow also run on `windows-latest`? **Decision:** start with `ubuntu-latest` only; expand later if a Windows-only bug appears.
-- **Q5:** What is the minimum Bun version for the `build` scripts to work? **Decision:** Bun 1.3.13. Document in README.
-- **Q6:** Should the shared `isWSL()` also read `/proc/sys/kernel/osrelease` as a fallback? **Decision:** stick with `/proc/version` + `WSL_DISTRO_NAME`.

package/openspec/changes/cross-platform-build-and-ci/proposal.md

@@ -1,50 +0,0 @@
-## Why
-
-The Bun rewrite is functionally complete (432/432 tests pass, all 11 commands registered, auth flow working), but the **delivery pipeline is missing**: `bun run build` is broken in Bun 1.3.x (`--compile` no longer accepts `--outdir`), there is no CI to catch regressions on PRs, no cross-platform build matrix, no GitHub release automation, and the rewrite's `src/` is full of direct `node:fs` and `node:path` imports that duplicate the same patterns in 4–8 places each (the "resolve + dirname + mkdirSync + writeFileSync" block alone appears in 4 export commands; `mkdirSync`/`existsSync`/`renameSync` are open-coded in `storage.ts` and `config.ts`).
-
-Two findings drive the change:
-
-1. **The build/CI/release work** — fixing `bun run build`, adding `test.yml` / `build.yml` / `release.yml` workflows, and the repo-hygiene cleanup — is the original scope and stands as-is.
-2. **Path and file-system access is duplicated across the rewrite** and is the actual cross-platform work. A read-only audit of `src/` finds **9 files** importing `node:fs` and `node:path` directly, with at least 4 copy-pasted "write to disk" blocks and ~20 open-coded `mkdirSync` / `existsSync` / `renameSync` calls. The original spec proposed a `platform-detect.ts` module to share one private `isWsl()` helper, but the duplication is much wider: the rewrite does not need a platform-detection module — it needs **mandatory mediation** of all file-system and path operations through `src/infrastructure/path-utils.ts` and a new `src/infrastructure/io.ts`.
-
-This change makes that mediation the rule, with a CI lint check that fails the build if any new `node:fs`/`node:path`/`node:os` import is added to `src/` outside the two allowed modules.
-
-## What Changes
-
-- **Fix `package.json` build scripts** so `bun run build`, `bun run build:linux`, and `bun run build:windows` produce a working single-file executable on Bun 1.3.x (drop the `--outdir` flag from `--compile` invocations; use `--outfile`).
-- **Add `src/infrastructure/path-utils.ts` extensions**: `isWSL()`, `getProjectRoot()`, and `getPackageJson()`. The single private `isWsl()` in `install-browser-service.ts` is lifted into `path-utils.ts` (the only platform-detection helper we actually need; the rest of the proposed `platform-detect.ts` module is dropped).
-- **Add `src/infrastructure/io.ts`**: a new sibling module that consolidates every `node:fs` and `node:path` operation the rewrite actually uses. Exports: `ensureDir`, `existsFile`, `readTextFile`, `safeReadTextFile`, `writeTextFile`, `readJsonFile`, `writeJsonFile`, `removeDir`, `renameDir`, `isDirectory`, `listSubdirectories`. This is the **canonical home for all file-system access**; the rule is "no other file in `src/` imports from `node:fs` or `node:path` directly" (the only allowed exception is `install-browser-service.ts`, which keeps `node:path` for the WSL mount parser).
-- **Refactor `src/services/install-browser-service.ts`** to consume `isWSL()`, `safeReadTextFile`, `existsFile` from the new modules. The two near-identical `getEdgePaths` / `getChromePaths` methods are unified behind a `getWindowsKnownDirs()` local helper. The 5 existing unit tests in `tests/services/install-browser-service.test.ts` are the regression gate; the 432/432 baseline MUST be preserved.
-- **Refactor `src/infrastructure/storage.ts` and `src/infrastructure/config.ts`** to route all file-system access through `io.ts`. `config.ts` shrinks from 64 lines to ~40; `storage.ts` loses all `node:fs` imports.
-- **Refactor the 4 export commands** (`src/cli/commands/export-command.ts`, `export-all-command.ts`, `list-command.ts`, `fetch-command.ts`) to use `writeTextFile` and `ensureDir`. The 3-line "resolve + mkdir + write" block that appears in 4 places collapses to a single call. The two byte-identical `writeOutput` private methods in `list-command.ts` and `fetch-command.ts` each collapse to 2 lines.
-- **Refactor `src/cli/index.ts`** to use `getPackageJson()` from `path-utils.ts` instead of the inline `fileURLToPath` / `__dirname` / `readFileSync` / `JSON.parse` dance at lines 33–35.
-- **Add `.github/workflows/test.yml`**: trigger on `push` to `main` and on `pull_request`; single `test` job on `ubuntu-latest`; steps: `actions/checkout@v4`, `oven-sh/setup-bun@v2`, `bun install --frozen-lockfile`, `bun test`, `bun run typecheck`, and a final lint check that fails the build if any new `node:fs`/`node:path`/`node:os` import is added to `src/` outside the allowed files.
-- **Add `.github/workflows/build.yml`**: trigger on `push` of tags matching `v*` and `workflow_dispatch`; matrix jobs `build-linux`, `build-windows`, and `build-wsl`; each verifies its artifact exists, reports size, and uploads via `actions/upload-artifact@v4`.
-- **Add `.github/workflows/release.yml`**: trigger on `push` of tags matching `v*`; chains `test → build → release`; release job uses `softprops/action-gh-release@v2` with auto-generated notes and attaches `GemiTerm`, `GemiTerm.exe`, `install.sh`, and `install.ps1`.
-- **Add `scripts/clean-build.sh`** (POSIX) and **`scripts/clean-build.ps1`** (PowerShell) that remove `dist/` and any temp build artifacts.
-- **Add `scripts/install-browser.sh`** and **`scripts/install-browser.ps1`** as user-facing shell wrappers that run `bunx @playwright/cli install chromium` and verify the install.
-- **Cleanup**: remove the unused `commander` dependency from `package.json` and `bun.lock` (it is installed but never imported). Remove the stray bare `{` line from `.gitignore` and the orphan file literally named `{` at the repo root. Remove the empty `src/commands/` placeholder (contains only `.gitkeep`).
-- **README updates**: add a "Building from source" section and a "Release artifacts" section; update the "Development" section to mention the new `bun run typecheck` and the `scripts/install-browser.{sh,ps1}` wrappers.
-
-**No breaking changes** to the CLI user surface. The 4 export commands keep their existing flags and behavior; the rewrite is purely internal refactoring plus build/CI.
-
-## Capabilities
-
-### New Capabilities
-
-- `release-pipeline`: GitHub Actions workflows (test, build, release), the build/clean scripts, the install-browser shell wrappers, and the repo-hygiene cleanup. Creates `openspec/changes/cross-platform-build-and-ci/specs/release-pipeline/spec.md`.
-- `path-and-file-mediation`: A mandatory mediation layer that makes `src/infrastructure/path-utils.ts` and the new `src/infrastructure/io.ts` the only consumers of `node:fs`, `node:path`, and `node:os` in `src/`. Adds `isWSL()`, `getProjectRoot()`, and `getPackageJson()` to `path-utils.ts`; adds the file-ops helpers to the new `io.ts`. Refactors all 7 existing call sites to use the new helpers. Adds a CI lint check that enforces the rule on every PR. Creates `openspec/changes/cross-platform-build-and-ci/specs/path-and-file-mediation/spec.md`.
-
-### Modified Capabilities
-
-- (none) — no existing capability has a spec-level requirement change. The `install-browser-service` refactor is an implementation detail covered by the regression test gate.
-
-## Impact
-
-- **Code:** `src/infrastructure/path-utils.ts` (add 3 helpers), new `src/infrastructure/io.ts` (~120 lines), `src/services/install-browser-service.ts` (delegate to shared module — no behavior change), `src/infrastructure/storage.ts` (lose 6 `node:fs` imports, shrink to use `io.ts` helpers), `src/infrastructure/config.ts` (shrink from 64 to ~40 lines), `src/cli/commands/{export,export-all,list,fetch}-command.ts` (lose `node:fs`/`node:path` imports, replace 3-line write block with `writeTextFile`), `src/cli/index.ts` (lose `node:url`/`node:path`/`node:fs` imports).
-- **Build:** `package.json:20-22` (3 `build*` scripts) and `bun.lock` (drop `commander`).
-- **Tests:** Add ~15–20 tests to `tests/unit/path-utils.test.ts` for the new path-utils helpers. Add `tests/infrastructure/io.test.ts` with ~15 tests for the new `io.ts` helpers. The existing 5 `install-browser-service.test.ts` cases are the regression gate for the `install-browser-service` refactor. CI must pass with `bun test` (currently 432/432) and `bun run typecheck` (currently 0 errors).
-- **Repo hygiene:** `.gitignore:23` (remove stray `{`) and the untracked file named `{` at the repo root. Delete empty `src/commands/` (only `.gitkeep` inside).
-- **README:** new "Building from source" and "Release artifacts" sections; update "Development" section.
-- **Docs dependency:** the related `v2-install-migration` change will reference the release artifacts and the v2.0.0 install scripts.
-- **SENSITIVE AREA:** the `install-browser-service` refactor MUST be behavior-preserving. The `playwright-cli-driver` and auth flow files are NOT touched by this change. The CI lint check is the enforcement mechanism for the "no direct `node:fs`" rule; existing code is migrated by hand as part of this change.

package/openspec/changes/cross-platform-build-and-ci/specs/path-and-file-mediation/spec.md

@@ -1,335 +0,0 @@
-## Purpose
-
-This spec defines the **path-and-file mediation layer** for the GemiTerm Bun rewrite. Its success criterion is:
-
-> **No file in `src/` (other than the allowed exemptions) imports from `node:fs`, `node:path`, or `node:os` directly. All file-system and path operations route through `src/infrastructure/path-utils.ts` (path values) and `src/infrastructure/io.ts` (file-system side effects).**
-
-A CI lint check (added in `release-pipeline/spec.md` §CI Test Job) enforces this rule on every PR.
-
-The only allowed `node:fs` / `node:path` / `node:os` consumers in `src/` are:
-
-- `src/infrastructure/path-utils.ts` — the canonical home for all path-related code.
-- `src/services/install-browser-service.ts` — keeps a `node:path` import for the WSL `9p`/`drvfs` mount parser, which is inherently Unix-specific and not a general-purpose cross-platform concern.
-
----
-
-## ADDED Requirements
-
-### Requirement: `path-utils.ts` is the only path value source in `src/`
-
-The system MUST provide `src/infrastructure/path-utils.ts` as the canonical home for all path-related functions and constants. No other source file in `src/` MAY import from `node:path` or `node:os` directly. The only allowed `node:path` consumer in `src/` is `src/services/install-browser-service.ts`, which uses `join` and `sep` for the WSL mount parser.
-
-The `path-utils.ts` module MUST export the existing 9 symbols (the 6 path functions: `resolvePath`, `getConfigDir`, `getProfilesDir`, `getProfilePath`, `getProfileDir`, `getDefaultProfileMarkerPath`; plus 3 constants: `STORAGE_STATE_FILE`, `PROFILES_DIR`, `DEFAULT_PROFILE_MARKER`).
-
-#### Scenario: A new src/ file wants to build a path
-
-- **WHEN** a developer needs to build a path inside `src/`
-- **THEN** they MUST use one of the exported functions from `path-utils.ts` (e.g. `join(getProfileDir(name), "subdir")` is fine, but `join` from `node:path` is not)
-
-#### Scenario: An existing src/ file is audited
-
-- **WHEN** the CI lint check runs over `src/`
-- **THEN** the only matches for `from "node:path"` or `from "node:os"` are `src/infrastructure/path-utils.ts` and `src/services/install-browser-service.ts`
-
-### Requirement: `io.ts` is the only file-system operation source in `src/`
-
-The system MUST provide `src/infrastructure/io.ts` as the canonical home for all file-system operations. No other source file in `src/` MAY import from `node:fs` directly. The CI lint check enforces this rule.
-
-The `io.ts` module MUST export the following 11 functions plus one error class: `ensureDir`, `existsFile`, `readTextFile`, `safeReadTextFile`, `writeTextFile`, `readJsonFile`, `writeJsonFile`, `removeDir`, `renameDir`, `isDirectory`, `listSubdirectories`, and `IOError`.
-
-#### Scenario: A new src/ file wants to read a file
-
-- **WHEN** a developer needs to read a file inside `src/`
-- **THEN** they MUST use `readTextFile` or `readJsonFile` from `io.ts`, never `readFileSync` from `node:fs`
-
-#### Scenario: A new src/ file wants to write a file
-
-- **WHEN** a developer needs to write a file inside `src/`
-- **THEN** they MUST use `writeTextFile` or `writeJsonFile` from `io.ts`, which creates the parent directory if it does not exist, never `writeFileSync` from `node:fs`
-
-#### Scenario: A new src/ file wants to check file existence
-
-- **WHEN** a developer needs to check whether a file or directory exists
-- **THEN** they MUST use `existsFile` from `io.ts`, never `existsSync` from `node:fs`
-
-### Requirement: `isWSL()` detects WSL via `/proc/version` or `WSL_DISTRO_NAME`
-
-The system MUST provide `isWSL(): boolean` in `src/infrastructure/path-utils.ts`. The function MUST return `false` on any platform other than Linux. On Linux, it MUST return `true` if either:
-
-- `/proc/version` exists and contains the substring `microsoft` or `WSL` (case-insensitive), OR
-- the `WSL_DISTRO_NAME` environment variable is set and non-empty.
-
-If neither condition holds, the function MUST return `false`.
-
-#### Scenario: WSL detected via `/proc/version`
-
-- **WHEN** `process.platform === "linux"` and `/proc/version` contains the substring `microsoft`
-- **THEN** `isWSL()` returns `true`
-
-#### Scenario: WSL detected via `WSL_DISTRO_NAME`
-
-- **WHEN** `process.platform === "linux"` and `WSL_DISTRO_NAME` is set to any non-empty string
-- **THEN** `isWSL()` returns `true` even if `/proc/version` does not contain the `microsoft` substring
-
-#### Scenario: Native Linux returns false
-
-- **WHEN** `process.platform === "linux"` and neither `/proc/version` contains `microsoft` or `WSL` nor `WSL_DISTRO_NAME` is set
-- **THEN** `isWSL()` returns `false`
-
-#### Scenario: macOS or Windows returns false
-
-- **WHEN** `process.platform` is `"darwin"` or `"win32"`
-- **THEN** `isWSL()` returns `false` regardless of `/proc/version` or environment variable contents
-
-### Requirement: `getProjectRoot()` finds the repository root from `import.meta.url`
-
-The system MUST provide `getProjectRoot(importMetaUrl?: string): string` in `src/infrastructure/path-utils.ts`. The function MUST walk up from the caller (or the provided `import.meta.url`) until it finds a directory containing `package.json`, then return the absolute path. The function MUST throw `IOError` if no `package.json` is found in any parent directory.
-
-#### Scenario: Called from a file in the repo
-
-- **WHEN** `getProjectRoot()` is called from any file under the repository root
-- **THEN** it returns the absolute path of the repository root (the directory containing `package.json`)
-
-#### Scenario: Called with no `package.json` ancestors
-
-- **WHEN** `getProjectRoot()` is called from a file that has no `package.json` in any parent directory
-- **THEN** it throws an `IOError` with a message indicating the walk completed without finding `package.json`
-
-### Requirement: `getPackageJson()` reads and parses `package.json`
-
-The system MUST provide `getPackageJson(): { name: string; version: string; [key: string]: unknown }` in `src/infrastructure/path-utils.ts`. The function MUST call `getProjectRoot(import.meta.url)`, read `<root>/package.json` as UTF-8, parse it as JSON, and return the parsed object. On any error (file missing, file unparseable, no `package.json` ancestor), the function MUST return `{ name: "gemiterm", version: "unknown" }` as a fallback.
-
-#### Scenario: Normal call
-
-- **WHEN** `getPackageJson()` is called from a file under the repository root
-- **THEN** it returns the parsed `package.json` object, with `name === "gemiterm"` and `version === "2.0.0"`
-
-#### Scenario: `package.json` missing or unparseable
-
-- **WHEN** the resolved `package.json` does not exist or is unparseable JSON
-- **THEN** `getPackageJson()` returns the fallback object `{ name: "gemiterm", version: "unknown" }`
-
-### Requirement: `writeTextFile` consolidates the 4-copy "resolve + mkdir + write" block
-
-The system MUST provide `writeTextFile(path: string, content: string): void` in `src/infrastructure/io.ts`. The function MUST resolve `path` to an absolute path, ensure the parent directory exists (recursively), and write `content` as UTF-8. The function MUST throw `IOError` on EACCES, ENOSPC, or any other write error.
-
-The 4 CLI commands `src/cli/commands/export-command.ts`, `export-all-command.ts`, `list-command.ts`, and `fetch-command.ts` MUST use `writeTextFile` in place of their existing `resolve + dirname + mkdirSync + writeFileSync` sequences.
-
-#### Scenario: Writing a new file to an existing directory
-
-- **WHEN** `writeTextFile("/tmp/gemiterm-test/output.md", "# Hello")` is called and `/tmp/gemiterm-test` exists
-- **THEN** the file `/tmp/gemiterm-test/output.md` is created with the content `# Hello`
-
-#### Scenario: Writing a new file to a nested non-existent directory
-
-- **WHEN** `writeTextFile("/tmp/gemiterm-test/nested/dir/output.md", "# Hello")` is called and neither `/tmp/gemiterm-test/nested` nor `/tmp/gemiterm-test/nested/dir` exist
-- **THEN** both directories are created recursively, and the file is written
-
-### Requirement: `readJsonFile` and `writeJsonFile` provide typed JSON I/O
-
-The system MUST provide `readJsonFile<T>(path: string): T` and `writeJsonFile(path: string, data: unknown): void` in `src/infrastructure/io.ts`. `readJsonFile` MUST read the file as UTF-8, parse it as JSON, and cast the result to `T`. `writeJsonFile` MUST serialize `data` with `JSON.stringify(data, null, 2)` and write it via `writeTextFile`. Both functions MUST throw `IOError` (with a `cause` field for the original error) on any failure.
-
-#### Scenario: Round-trip a JSON object
-
-- **WHEN** a developer writes an object via `writeJsonFile(path, obj)` and reads it back via `readJsonFile<typeof obj>(path)`
-- **THEN** the deep-equal comparison of the two values is true
-
-#### Scenario: `readJsonFile` on a missing file
-
-- **WHEN** `readJsonFile` is called with a path that does not exist
-- **THEN** it throws `IOError` whose `cause` is the underlying `ENOENT` error
-
-#### Scenario: `readJsonFile` on unparseable content
-
-- **WHEN** `readJsonFile` is called with a path whose content is not valid JSON
-- **THEN** it throws `IOError` whose `cause` is the underlying `SyntaxError`
-
-### Requirement: `safeReadTextFile` returns `""` on any error
-
-The system MUST provide `safeReadTextFile(path: string): string` in `src/infrastructure/io.ts`. The function MUST read the file as UTF-8 and return the content; on any error (ENOENT, EACCES, EISDIR), it MUST return the empty string `""`. The function MUST include a JSDoc comment noting that the `""` return conflates "file does not exist" with "file exists but is empty" and is appropriate for callers that only need a string for `.includes()` / `.trim()` checks.
-
-#### Scenario: Reading an existing file
-
-- **WHEN** `safeReadTextFile` is called with a path that exists
-- **THEN** it returns the file's content
-
-#### Scenario: Reading a missing file
-
-- **WHEN** `safeReadTextFile` is called with a path that does not exist
-- **THEN** it returns `""` and does not throw
-
-#### Scenario: Code comment is present
-
-- **WHEN** the source of `safeReadTextFile` is inspected
-- **THEN** the JSDoc comment is present and explicitly notes the `""` return and its implication
-
-### Requirement: `ensureDir`, `removeDir`, `renameDir`, `isDirectory`, `listSubdirectories` provide safe file-system access
-
-The system MUST provide the following 5 functions in `src/infrastructure/io.ts`:
-
-- `ensureDir(path: string): void` — calls `mkdirSync(path, { recursive: true })`. Throws `IOError` on EACCES, EPERM, EROFS, or any other error.
-- `removeDir(path: string): void` — calls `rmSync(path, { recursive: true, force: true })`. The `force: true` flag means the function is a no-op if the path does not exist. Throws `IOError` on EACCES, EBUSY, or any other error.
-- `renameDir(src: string, dest: string): void` — calls `renameSync`. Throws `IOError` with a clear message on ENOENT (source missing) or EEXIST (destination present).
-- `isDirectory(path: string): boolean` — returns `true` if `statSync(path).isDirectory()` succeeds and the result is `true`; returns `false` on any error (including ENOENT).
-- `listSubdirectories(path: string): string[]` — reads the directory and returns the names of immediate subdirectories only. Returns `[]` if the path does not exist. The `.default` marker file (or any other non-directory entry) is excluded.
-
-#### Scenario: `ensureDir` creates nested directories
-
-- **WHEN** `ensureDir("/tmp/a/b/c")` is called and `/tmp/a` does not exist
-- **THEN** `/tmp/a`, `/tmp/a/b`, and `/tmp/a/b/c` are all created
-
-#### Scenario: `removeDir` is a no-op on missing path
-
-- **WHEN** `removeDir("/tmp/nonexistent")` is called
-- **THEN** no error is thrown and the function returns
-
-#### Scenario: `renameDir` throws on missing source
-
-- **WHEN** `renameDir("/tmp/nope", "/tmp/dest")` is called and `/tmp/nope` does not exist
-- **THEN** `IOError` is thrown with a message that includes the source path
-
-#### Scenario: `listSubdirectories` excludes the marker file
-
-- **WHEN** `listSubdirectories` is called on a profile directory containing both subdirectories and a `.default` marker file
-- **THEN** the returned array contains only the subdirectory names; `.default` is excluded
-
-### Requirement: `IOError` provides structured error context
-
-The system MUST export an `IOError` class from `src/infrastructure/io.ts` that extends `Error` and includes a `cause` field (of type `Error | undefined`) for the original error. All other functions in `io.ts` MUST throw `IOError` (with a populated `cause` when the original error is available) rather than raw `Error` or re-throwing the original error.
-
-#### Scenario: `IOError` carries a cause
-
-- **WHEN** a function in `io.ts` catches an `ENOENT` error from `node:fs` and re-throws as `IOError`
-- **THEN** the `IOError.cause` field is the original `ENOENT` error
-
-#### Scenario: Error name is set
-
-- **WHEN** an `IOError` is constructed
-- **THEN** its `name` field is `"IOError"` (so `error.name === "IOError"` is true)
-
-### Requirement: `install-browser-service` is the only WSL-detection consumer
-
-The system MUST refactor `src/services/install-browser-service.ts` to:
-
-- import `isWSL` from `path-utils.ts` and delete the private `isWsl()` method.
-- import `existsFile` and `safeReadTextFile` from `io.ts` and delete the private `readFileSafe` helper.
-- unify `getEdgePaths()` and `getChromePaths()` behind a single local `getWindowsKnownDirs()` helper.
-
-The 5 unit tests in `tests/services/install-browser-service.test.ts` MUST continue to pass without modification; the 432/432 baseline MUST be maintained.
-
-#### Scenario: `isWsl()` private method is gone
-
-- **WHEN** `src/services/install-browser-service.ts` is inspected
-- **THEN** the file does not define a private `isWsl()` method
-
-#### Scenario: `isWSL()` is the only WSL detection source
-
-- **WHEN** the rewrite needs to check whether it is running under WSL
-- **THEN** the check is made via the shared `isWSL()` from `path-utils.ts`, not via inline `/proc/version` reads
-
-#### Scenario: `getEdgePaths` and `getChromePaths` are unified
-
-- **WHEN** `src/services/install-browser-service.ts` is inspected
-- **THEN** both methods are short (≤5 lines each) and delegate path construction to a shared `getWindowsKnownDirs()` helper
-
-### Requirement: `storage.ts` and `config.ts` route all file access through `io.ts`
-
-The system MUST refactor `src/infrastructure/storage.ts` and `src/infrastructure/config.ts` to import from `./io.ts` instead of `node:fs`. After the refactor, neither file MUST import from `node:fs` or `node:path` directly. `config.ts` MUST shrink from 64 lines to approximately 40 lines.
-
-The 21 unit tests in `tests/infrastructure/storage.test.ts` and the 13 unit tests in `tests/unit/config.test.ts` MUST continue to pass without modification.
-
-#### Scenario: `storage.ts` has no `node:fs` import
-
-- **WHEN** `src/infrastructure/storage.ts` is inspected
-- **THEN** the file does not contain `from "node:fs"`
-
-#### Scenario: `config.ts` has no `node:fs` or `node:path` import
-
-- **WHEN** `src/infrastructure/config.ts` is inspected
-- **THEN** the file does not contain `from "node:fs"` or `from "node:path"`
-
-#### Scenario: `storage.ts` tests still pass
-
-- **WHEN** `bun test tests/infrastructure/storage.test.ts` is run after the refactor
-- **THEN** all 21 tests pass
-
-#### Scenario: `config.ts` tests still pass
-
-- **WHEN** `bun test tests/unit/config.test.ts` is run after the refactor
-- **THEN** all 13 tests pass
-
-### Requirement: 4 export commands use `writeTextFile`
-
-The system MUST refactor `src/cli/commands/export-command.ts`, `export-all-command.ts`, `list-command.ts`, and `fetch-command.ts` so that each file uses `writeTextFile` and `ensureDir` from `io.ts` instead of inline `node:fs` operations. After the refactor, none of the 4 files MUST import from `node:fs` or `node:path` directly. The integration tests in `tests/integration/commands/{export,list,fetch}.test.ts` and `tests/cli/export-all-command.test.ts` MUST continue to pass without modification.
-
-#### Scenario: `export-command.ts` uses `writeTextFile`
-
-- **WHEN** `src/cli/commands/export-command.ts` is inspected
-- **THEN** the file imports `writeTextFile` from `../../infrastructure/io.ts` and does not import from `node:fs` or `node:path`
-
-#### Scenario: `export-all-command.ts` uses `writeTextFile` and `ensureDir`
-
-- **WHEN** `src/cli/commands/export-all-command.ts` is inspected
-- **THEN** the file imports `writeTextFile` and `ensureDir` from `../../infrastructure/io.ts` and does not import from `node:fs` or `node:path`
-
-#### Scenario: `list-command.ts` and `fetch-command.ts` have a 2-line `writeOutput`
-
-- **WHEN** `src/cli/commands/list-command.ts` and `src/cli/commands/fetch-command.ts` are inspected
-- **THEN** the `writeOutput` private method in each is 2 lines (a `writeTextFile` call and a `console.log`)
-
-#### Scenario: Integration tests still pass
-
-- **WHEN** `bun test tests/integration/commands/{export,list,fetch}.test.ts tests/cli/export-all-command.test.ts` is run after the refactor
-- **THEN** all tests pass
-
-### Requirement: `cli/index.ts` uses `getPackageJson()`
-
-The system MUST refactor `src/cli/index.ts` to import `getPackageJson` from `src/infrastructure/path-utils.ts` and remove the inline `fileURLToPath` / `__dirname` / `readFileSync` / `JSON.parse` sequence at lines 33-35. After the refactor, `src/cli/index.ts` MUST NOT import from `node:fs`, `node:path`, or `node:url`. The `--version` flag MUST continue to print `2.0.0`; the smoke test in `tests/smoke/smoke.test.ts` is the regression gate.
-
-#### Scenario: `cli/index.ts` has no `node:fs` / `node:path` / `node:url` import
-
-- **WHEN** `src/cli/index.ts` is inspected
-- **THEN** the file does not contain `from "node:fs"`, `from "node:path"`, or `from "node:url"`
-
-#### Scenario: `--version` still prints `2.0.0`
-
-- **WHEN** `gemiterm --version` is run
-- **THEN** the output includes the string `2.0.0`
-
-### Requirement: CI lint check fails the build on a forbidden import
-
-The system MUST add a step to `.github/workflows/test.yml` that runs the following command and fails the workflow if the command exits non-zero:
-
-```bash
-! grep -rn --include='*.ts' "from \"node:\\(fs\\|path\\|os\\)\"" src/ \
-  | grep -v "src/infrastructure/path-utils.ts" \
-  | grep -v "src/services/install-browser-service.ts" \
-  | grep -q .
-```
-
-The check MUST exclude `src/infrastructure/path-utils.ts` (the canonical home) and `src/services/install-browser-service.ts` (the only legitimate cross-platform `node:path` consumer). The check MUST NOT exclude any other file.
-
-#### Scenario: A new src/ file imports from `node:fs`
-
-- **WHEN** a contributor adds `import { readFileSync } from "node:fs";` to a new file `src/services/foo.ts` and opens a PR
-- **THEN** the `test.yml` workflow's "Enforce path-utils mediation" step exits non-zero and the PR cannot be merged
-
-#### Scenario: A new src/ file imports from `node:path`
-
-- **WHEN** a contributor adds `import { join } from "node:path";` to `src/services/foo.ts`
-- **THEN** the workflow fails with a clear error message naming the file
-
-#### Scenario: A new src/ file imports from `node:os`
-
-- **WHEN** a contributor adds `import { homedir } from "node:os";` to `src/services/foo.ts`
-- **THEN** the workflow fails
-
-#### Scenario: The two allowed files are exempt
-
-- **WHEN** the check is run and the only matches are in `src/infrastructure/path-utils.ts` and `src/services/install-browser-service.ts`
-- **THEN** the check exits 0 (success)
-
-#### Scenario: Tests directory is out of scope
-
-- **WHEN** the check is run and a test file in `tests/` imports from `node:fs`
-- **THEN** the check is unaffected (it scans `src/` only)