@cofferdam/cofferdam 0.2.3-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cofferdam contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# cofferdam
+
+TypeScript code-quality analyzer with a Rust core. Sorts findings by
+priority across five categories (Consistency, Design, Readability,
+Refactor, Warning) and gates CI on a configurable severity axis.
+Inspired by Elixir's [Credo](https://github.com/rrrene/credo).
+
+## Install
+
+```bash
+pnpm add -D cofferdam        # pnpm
+npm install -D cofferdam     # npm
+yarn add -D cofferdam        # yarn
+```
+
+The package downloads a pre-built binary for your platform on install
+(Linux x64/arm64 gnu+musl, macOS x64/arm64, Windows x64) and runs it
+through a tiny JS shim.
+
+> **pnpm users:** pnpm v10's default sandbox blocks postinstall scripts
+> unless the package is on the allowlist. `pnpm add -D cofferdam` will
+> "succeed" without ever downloading the binary. Add this to your
+> `package.json` so the binary install actually runs:
+>
+> ```json
+> { "pnpm": { "onlyBuiltDependencies": ["cofferdam"] } }
+> ```
+>
+> Then re-run `pnpm install` (or `pnpm rebuild cofferdam` for an existing
+> install). Verified you're hit by this if `pnpm exec cofferdam --version`
+> errors with "binary not found".
+
+## First run
+
+```bash
+pnpm exec cofferdam init
+```
+
+`init` writes three things and asks once whether to capture a baseline
+of your current findings:
+
+- **`cofferdam.toml`** — every check stanza commented out so you can
+  see what's tunable. Edit only the values you care about; defaults
+  cover the rest.
+- **`.cofferdam/baseline.json`** — snapshot of findings the build
+  should *not* fail on (your existing tech debt). Commit this file.
+- **`.gitignore`** — `.cofferdam/` is added with a
+  `!.cofferdam/baseline.json` negation, so the baseline stays
+  tracked while future cache content is ignored.
+
+After `init`:
+
+```bash
+pnpm exec cofferdam check src/        # exits 0 — everything baselined
+```
+
+Add a fresh `==` to your code, re-run, and CI will fail with only the
+new finding flagged.
+
+## Built-in checks
+
+Cofferdam ships 20+ built-in checks across all five categories,
+including project-graph rules (`Design.OrphanExport`,
+`Design.ImportCycle`, `Design.LayerViolation`, `Refactor.DeadExport`)
+and complexity rules (`Refactor.CyclomaticComplexity`,
+`Refactor.CognitiveComplexity`). Severity gates CI; priority sorts
+the report — the two are deliberately separate axes.
+
+Full catalog with bad/good examples, options, and per-check defaults:
+**<https://tajd.github.io/cofferdam/checks/>**.
+
+## CI integration
+
+### GitHub Actions
+
+```yaml
+- uses: actions/checkout@v6
+  with:
+    # fetch-depth: 0 so --since can resolve the base branch ref
+    fetch-depth: 0
+- run: pnpm install --frozen-lockfile
+- run: pnpm exec cofferdam check src/ --since origin/${{ github.base_ref }} --fail-on=high
+```
+
+`--since <git-ref>` runs only against files changed in `<ref>...HEAD`,
+so PR checks stay fast on large repos. `--fail-on=high` exits 1 only
+when at least one finding is High or Critical — Medium and below
+print but don't fail CI.
+
+### Husky pre-commit
+
+```bash
+# .husky/pre-commit
+pnpm exec cofferdam check --since HEAD --fail-on=high
+```
+
+## Configuration
+
+`cofferdam.toml` at the project root. Discovered by walking up from the
+working directory until a `.git` is reached. Every key is optional —
+unset values fall back to the defaults.
+
+```toml
+# Lower a check's severity so it stops failing CI but still appears in reports
+[checks."Refactor.CyclomaticComplexity"]
+severity = "low"
+
+# Tighten a limit
+[checks."Readability.MaxLineLength"]
+limit = 100
+```
+
+Override per invocation: `--config <path>` points at a specific file,
+`--no-config` skips discovery entirely.
+
+## Suppression
+
+Inline directives let you silence a finding with an auditable reason
+field. Canonical form:
+
+```ts
+// cofferdam-ignore: Warning.NoEval: codegen bootstrap, not user input
+eval(generatedCode);
+```
+
+Range and file-scoped variants:
+
+```ts
+// cofferdam-ignore-start: Refactor.CyclomaticComplexity
+function generatedRouter(req, res) { /* ... */ }
+// cofferdam-ignore-end
+
+// cofferdam-ignore-file: Readability.MaxLineLength
+```
+
+ESLint-style aliases (`// cofferdam-disable-next-line <CheckId>`,
+`/* cofferdam-disable */ ... /* cofferdam-enable */`) are also
+recognised for ergonomic continuity. Full syntax and reason-field
+rules: <https://tajd.github.io/cofferdam/suppression/>.
+
+## Custom checks
+
+Author project-specific checks in TypeScript with
+[`@cofferdam/check-sdk`](https://www.npmjs.com/package/@cofferdam/check-sdk).
+The `defineCheck` API gives you AST and line views over the same
+sources cofferdam already parsed; the cofferdam binary spawns a Node
+host and merges your findings into its stream. Plugin authoring guide:
+<https://tajd.github.io/cofferdam/plugin-sdk/> (in progress).
+
+## Architectural specs
+
+Pin the shape of your codebase in `cofferdam.invariants.toml` —
+declare layer boundaries (`ui` cannot import `db`), freeze a public
+surface (`packages/sdk` exports may not change without a deliberate
+update), and let `Design.LayerViolation` and `Design.BoundaryFrozen`
+fail CI on drift. Spec reference:
+<https://tajd.github.io/cofferdam/invariants/>.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | No findings at or above `--fail-on` (default: `medium`). Baselined findings never trigger the gate. |
+| 1    | At least one finding triggers the gate. |
+| 2    | Invocation, IO, or config error. |
+
+## Sandboxed installs / `--ignore-scripts`
+
+If your installer disables postinstall scripts, the binary won't be
+downloaded. Two recovery paths:
+
+1. **Manual binary** — download the release archive from
+   [GitHub Releases](https://github.com/TAJD/cofferdam/releases),
+   extract it, set `COFFERDAM_BINARY_PATH` to the binary, then
+   `npm rebuild cofferdam`.
+2. **Pre-baked image** — set `COFFERDAM_SKIP_DOWNLOAD=1` if the
+   binary is already at `node_modules/cofferdam/bin/cofferdam`
+   (or `cofferdam.exe` on Windows).
+
+> **Windows + npm 6:** bare `npx cofferdam` falls back to `npm run` and
+> fails with `Missing script: 'cofferdam'`. Use `npx -p cofferdam cofferdam`,
+> `pnpm exec cofferdam`, or `.\node_modules\.bin\cofferdam.cmd`, or
+> upgrade to npm ≥ 7.
+
+## Versioning
+
+The npm package version tracks the cofferdam release version.
+`cofferdam@0.1.0` downloads the binary from the `v0.1.0` GitHub
+Release. Lockfile-pinned installs are deterministic. The Rust
+workspace and the `cofferdam` + `@cofferdam/check-sdk` npm packages
+are released in lockstep — a `cofferdam@X.Y.Z` install always pairs
+with an SDK at the same `X.Y.Z`.
+
+## License
+
+MIT. Full source and project documentation:
+[github.com/TAJD/cofferdam](https://github.com/TAJD/cofferdam).

package/bin/cofferdam.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Tiny shim: forward all argv + stdio to the platform-specific binary that
+// postinstall placed alongside this script.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const binaryName = process.platform === 'win32' ? 'cofferdam.exe' : 'cofferdam';
+const binaryPath = path.join(__dirname, binaryName);
+
+if (!fs.existsSync(binaryPath)) {
+  // Tailor the recovery hint to the package manager. pnpm v10's default
+  // sandbox silently blocks postinstall unless the package is in
+  // `pnpm.onlyBuiltDependencies`, so a `pnpm add -D cofferdam` 'succeeds'
+  // with no binary on disk. Recommending `npm rebuild` to those users is
+  // wrong — they need pnpm syntax + the allowlist edit (cd-iui / gh #9).
+  const pkgManager = detectPackageManager();
+  let recovery;
+  if (pkgManager === 'pnpm') {
+    recovery =
+      "Looks like a pnpm install. pnpm v10 blocks postinstall scripts unless\n" +
+      "the package is in `pnpm.onlyBuiltDependencies`. To fix:\n\n" +
+      '  1. Add to your package.json:\n' +
+      '       { "pnpm": { "onlyBuiltDependencies": ["cofferdam"] } }\n' +
+      '  2. Then run:  pnpm rebuild cofferdam\n';
+  } else if (pkgManager === 'yarn') {
+    recovery =
+      'Looks like a yarn install. Run:\n' +
+      '  yarn rebuild cofferdam\n';
+  } else {
+    recovery = 'Run:\n  npm rebuild cofferdam\n';
+  }
+
+  console.error(
+    `[cofferdam] binary not found at ${binaryPath}\n\n` +
+      'This usually means the postinstall step did not complete.\n\n' +
+      recovery + '\n' +
+      'If you installed with --ignore-scripts (or your CI does), the binary\n' +
+      'must be installed manually. See:\n' +
+      '  https://github.com/TAJD/cofferdam#install'
+  );
+  process.exit(1);
+}
+
+// Cheap heuristic: walk up from this script's location looking for the
+// canonical lockfile / metadata each package manager leaves behind. Falls
+// back to `process.env.npm_config_user_agent` when we're inside a fresh
+// shell invocation that hasn't touched node_modules. Returns one of
+// 'pnpm' | 'yarn' | 'npm' | null.
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || '';
+  if (/^pnpm\//.test(ua)) return 'pnpm';
+  if (/^yarn\//.test(ua)) return 'yarn';
+  if (/^npm\//.test(ua)) return 'npm';
+
+  // Walk up from __dirname looking for tell-tale files. Most reliable:
+  // an adjacent `node_modules/.pnpm/` (pnpm's content-addressed store).
+  let dir = path.resolve(__dirname);
+  for (let i = 0; i < 20; i++) {
+    if (fs.existsSync(path.join(dir, 'node_modules', '.pnpm'))) return 'pnpm';
+    if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm';
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Guard against broken-pipe conditions (e.g. `cofferdam check --format=json | head`).
+//
+// On POSIX, when the consumer closes the pipe, the kernel sends SIGPIPE to the
+// child process first (Rust's stdlib already handles it cleanly). The pnpm
+// wrapper — this script — may still have its own writes fail with EPIPE (e.g.
+// the error-not-found message path above, or any Node internal flush). Node 22+
+// delivers SIGPIPE to non-default handlers; older versions silently terminate.
+// Belt-and-suspenders: listen for both the signal and the stream error.
+//
+// On Windows there is no SIGPIPE signal; writes to a closed pipe throw EPIPE
+// synchronously through the stream 'error' event. The error handlers cover that
+// path — registering the signal handler on Windows is harmless (never fires).
+process.on('SIGPIPE', () => process.exit(0));
+process.stdout.on('error', (err) => { if (err.code === 'EPIPE') process.exit(0); else throw err; });
+process.stderr.on('error', (err) => { if (err.code === 'EPIPE') process.exit(0); else throw err; });
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+
+if (result.error) {
+  console.error(`[cofferdam] failed to spawn binary: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cofferdam/cofferdam",
+  "version": "0.2.3-rc.0",
+  "description": "TypeScript code-quality analyzer — Rust core + JS plugin layer, inspired by Elixir's Credo",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TAJD/cofferdam.git",
+    "directory": "packages/cofferdam"
+  },
+  "homepage": "https://tajd.github.io/cofferdam",
+  "bugs": "https://github.com/TAJD/cofferdam/issues",
+  "keywords": [
+    "typescript",
+    "linter",
+    "static-analysis",
+    "code-quality",
+    "credo",
+    "oxc"
+  ],
+  "bin": {
+    "cofferdam": "bin/cofferdam.js"
+  },
+  "files": [
+    "bin/cofferdam.js",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "scripts/postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=16",
+    "npm": ">=7"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// cofferdam postinstall — downloads the matching binary from the GitHub Release
+// for this package version. Stopgap until phase 4 ships @cofferdam/node via
+// napi-rs prebuilt binaries through optionalDependencies.
+//
+// Zero runtime deps: uses only Node stdlib (https, fs, path, crypto, child_process).
+// Designed to fail loudly with actionable error messages so users know exactly
+// what went wrong when corp proxies, offline installs, or sandbox environments
+// block the download.
+//
+// Override paths:
+//   - COFFERDAM_BINARY_PATH=/abs/path  → skip download, use this binary
+//   - COFFERDAM_SKIP_DOWNLOAD=1        → skip postinstall entirely (CI / Docker layers)
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+
+const PACKAGE_DIR = path.resolve(__dirname, '..');
+const PKG = require(path.join(PACKAGE_DIR, 'package.json'));
+const BIN_DIR = path.join(PACKAGE_DIR, 'bin');
+const VERSION = PKG.version;
+const REPO = 'TAJD/cofferdam';
+
+if (process.env.COFFERDAM_SKIP_DOWNLOAD === '1') {
+  console.log('[cofferdam] COFFERDAM_SKIP_DOWNLOAD=1 set, skipping binary download.');
+  process.exit(0);
+}
+
+// pnpm v10+ silently blocks postinstall scripts unless the package is in
+// `pnpm.onlyBuiltDependencies` — when the user runs
+// `pnpm add -D @cofferdam/cofferdam` without that allowlist, this script
+// never executes and the binary never lands. By the time we DO run
+// (typically `pnpm rebuild @cofferdam/cofferdam` after the user notices the
+// missing binary), surface a one-line hint pointing at the durable fix so
+// they don't hit the same trap on subsequent fresh installs (cd-iui / gh #9).
+if (/^pnpm\//.test(process.env.npm_config_user_agent || '')) {
+  console.log(
+    '[cofferdam] pnpm detected. To make future installs work without `pnpm rebuild`,\n' +
+      '            add this to your package.json:\n' +
+      '              { "pnpm": { "onlyBuiltDependencies": ["@cofferdam/cofferdam"] } }'
+  );
+}
+
+if (process.env.COFFERDAM_BINARY_PATH) {
+  const src = process.env.COFFERDAM_BINARY_PATH;
+  if (!fs.existsSync(src)) {
+    console.error(`[cofferdam] COFFERDAM_BINARY_PATH=${src} does not exist.`);
+    process.exit(1);
+  }
+  const dest = path.join(BIN_DIR, binaryName());
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+  fs.copyFileSync(src, dest);
+  if (process.platform !== 'win32') fs.chmodSync(dest, 0o755);
+  console.log(`[cofferdam] using binary from ${src}`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error(`[cofferdam] postinstall failed: ${err.message || err}`);
+  console.error('');
+  console.error('Manual install fallback:');
+  console.error(`  1. Download from https://github.com/${REPO}/releases/tag/v${VERSION}`);
+  console.error(`  2. Extract the archive for your platform`);
+  console.error(`  3. Set COFFERDAM_BINARY_PATH to the extracted binary and run \`npm rebuild @cofferdam/cofferdam\``);
+  process.exit(1);
+});
+
+async function main() {
+  const target = detectTarget();
+  const archive = archiveName(target);
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${archive}`;
+  const shaUrl = `${url}.sha256`;
+
+  console.log(`[cofferdam] platform: ${target}`);
+  console.log(`[cofferdam] downloading ${archive} ...`);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+  const archivePath = path.join(BIN_DIR, archive);
+
+  try {
+    await download(url, archivePath);
+  } catch (err) {
+    // Clean up partial download so a retry doesn't see a corrupt zero-byte file.
+    if (fs.existsSync(archivePath)) {
+      try { fs.unlinkSync(archivePath); } catch {}
+    }
+    throw err;
+  }
+
+  // SHA verification — non-fatal if .sha256 is missing (older releases),
+  // fatal if present and mismatched.
+  try {
+    const expectedHash = (await fetchText(shaUrl)).trim().split(/\s+/)[0];
+    const actualHash = sha256File(archivePath);
+    if (expectedHash && expectedHash.toLowerCase() !== actualHash.toLowerCase()) {
+      throw new Error(`SHA-256 mismatch: expected ${expectedHash}, got ${actualHash}`);
+    }
+    if (expectedHash) console.log(`[cofferdam] SHA-256 verified: ${actualHash}`);
+  } catch (e) {
+    if (/SHA-256 mismatch/.test(e.message)) throw e;
+    console.warn(`[cofferdam] could not verify SHA-256 (${e.message}); continuing.`);
+  }
+
+  extract(archivePath, BIN_DIR);
+
+  const binaryPath = path.join(BIN_DIR, binaryName());
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error(`expected ${binaryPath} after extraction but did not find it`);
+  }
+  if (process.platform !== 'win32') fs.chmodSync(binaryPath, 0o755);
+  fs.unlinkSync(archivePath);
+
+  console.log(`[cofferdam] installed ${binaryPath}`);
+}
+
+function binaryName() {
+  return process.platform === 'win32' ? 'cofferdam.exe' : 'cofferdam';
+}
+
+function detectTarget() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === 'win32' && arch === 'x64') return 'x86_64-pc-windows-msvc';
+  if (platform === 'darwin' && arch === 'x64') return 'x86_64-apple-darwin';
+  if (platform === 'darwin' && arch === 'arm64') return 'aarch64-apple-darwin';
+  if (platform === 'linux' && arch === 'x64') return isMusl() ? 'x86_64-unknown-linux-musl' : 'x86_64-unknown-linux-gnu';
+  if (platform === 'linux' && arch === 'arm64') return isMusl() ? 'aarch64-unknown-linux-musl' : 'aarch64-unknown-linux-gnu';
+
+  throw new Error(`unsupported platform/arch combination: ${platform}/${arch}`);
+}
+
+function isMusl() {
+  // Use process.report when available (Node 16+) — checks the running binary's
+  // libc, not the system's. This is what we want: even on a glibc host running
+  // a musl-built Node (alpine in docker), pick the musl artifact.
+  try {
+    const report = process.report.getReport();
+    if (report.header && report.header.glibcVersionRuntime) return false;
+    return true;
+  } catch {
+    // Fall back to ldd parsing on older Node.
+    try {
+      const out = execSync('ldd --version 2>&1', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      return /musl/i.test(out);
+    } catch {
+      return false; // assume gnu if we can't tell
+    }
+  }
+}
+
+function archiveName(target) {
+  const isWin = target.includes('windows');
+  return `cofferdam-v${VERSION}-${target}.${isWin ? 'zip' : 'tar.gz'}`;
+}
+
+function download(url, dest, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    const opts = {
+      headers: {
+        'User-Agent': `cofferdam-postinstall/${VERSION}`,
+        Accept: 'application/octet-stream',
+      },
+    };
+    https.get(url, opts, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        if (redirectsLeft <= 0) return reject(new Error('too many redirects'));
+        file.close();
+        fs.unlinkSync(dest);
+        return resolve(download(res.headers.location, dest, redirectsLeft - 1));
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode} fetching ${url}`));
+      }
+      res.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+function fetchText(url, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const opts = { headers: { 'User-Agent': `cofferdam-postinstall/${VERSION}` } };
+    https.get(url, opts, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        if (redirectsLeft <= 0) return reject(new Error('too many redirects'));
+        return resolve(fetchText(res.headers.location, redirectsLeft - 1));
+      }
+      if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode}`));
+      let buf = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => (buf += c));
+      res.on('end', () => resolve(buf));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+function sha256File(filePath) {
+  const h = crypto.createHash('sha256');
+  h.update(fs.readFileSync(filePath));
+  return h.digest('hex');
+}
+
+function extract(archivePath, dest) {
+  // System tar handles both .tar.gz and .zip on modern Windows / macOS / Linux.
+  // We could pull tar.js as a dep but it would dominate the install footprint.
+  if (archivePath.endsWith('.zip')) {
+    if (process.platform === 'win32') {
+      // Use PowerShell's Expand-Archive — built into every supported Windows.
+      execSync(`powershell -NoProfile -Command "Expand-Archive -Force -Path '${archivePath}' -DestinationPath '${dest}'"`, {
+        stdio: 'inherit',
+      });
+    } else {
+      // On unix we'd need an unzip — should never reach here because windows is the only zip target.
+      throw new Error(`zip extraction is only supported on Windows; got ${process.platform}`);
+    }
+  } else {
+    execSync(`tar -xzf "${archivePath}" -C "${dest}"`, { stdio: 'inherit' });
+  }
+}