@gitlawb/zero 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gitlawb
+
+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

@@ -1,8 +1,301 @@
-# @gitlawb/zero
+<p align="center">
+  <img src="docs/assets/zero-logo.png" alt="Zero" width="385">
+</p>
 
-This version (0.0.0) is a placeholder that reserves the package name and
-enables npm trusted publishing for automated releases.
+<p align="center"><strong>A terminal coding agent you own.</strong></p>
 
-**Zero** — a terminal coding agent you own — ships here starting with v0.1.0.
+<p align="center">
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <img alt="Go 1.25+" src="https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white">
+  <img alt="25+ providers" src="https://img.shields.io/badge/providers-25+-34E2EA">
+</p>
 
-Until then, see [github.com/Gitlawb/zero](https://github.com/Gitlawb/zero).
+Zero is an AI coding agent for your local terminal. It can inspect a repository,
+edit files, run commands, use browser/terminal helpers, and keep durable local
+sessions while you choose the model and the permission level.
+
+```bash
+zero
+zero exec "fix the failing test in ./pkg"
+zero exec --output-format stream-json < turns.jsonl
+```
+
+## Why Zero
+
+- **Use the model you want.** Bring OpenAI, Anthropic, Gemini, Groq, OpenRouter,
+  DeepSeek, Mistral, xAI, Qwen, Kimi, GitHub Models, Ollama, LM Studio, or any
+  OpenAI-/Anthropic-compatible endpoint.
+- **Stay in control.** File writes, shell commands, network access, and
+  out-of-workspace writes go through Zero's permission and sandbox policy.
+- **Works in the terminal.** The TUI has model/provider pickers, image input,
+  slash commands, live plan/tool rendering, scrollback, themes, and resume/fork
+  support.
+- **Works without the TUI.** `zero exec` is scriptable, supports text/JSON/
+  stream-JSON I/O, isolated worktrees, spec-first runs, and meaningful exit
+  codes for CI.
+- **Keeps context local.** Sessions are stored on disk, searchable, resumable,
+  and never uploaded as telemetry by Zero.
+- **Extensible when you need it.** Use MCP servers, skills, plugins, hooks, and
+  specialist subagents from the same CLI.
+
+## Install
+
+### npm
+
+```bash
+npm install -g @gitlawb/zero
+zero
+```
+
+The npm package installs a small wrapper plus the matching Zero binary for your
+platform from GitHub Releases. It supports Linux, macOS, and Windows on x64 and
+arm64.
+
+### Install scripts
+
+Linux/macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Gitlawb/zero/main/scripts/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/Gitlawb/zero/main/scripts/install.ps1 | iex
+```
+
+### From source
+
+Source builds require Go 1.25+.
+
+```bash
+git clone https://github.com/Gitlawb/zero.git
+cd zero
+go run ./cmd/zero
+```
+
+Release installers and the npm wrapper require published GitHub Release assets.
+If you are testing before the first public release, build from source:
+
+```bash
+go build -o zero ./cmd/zero
+```
+
+On Linux, build the sandbox helper too if you want native sandboxing:
+
+```bash
+go build -o zero-linux-sandbox ./cmd/zero-linux-sandbox
+go build -o zero-seccomp ./cmd/zero-seccomp   # optional compatibility wrapper
+```
+
+Put `zero` and `zero-linux-sandbox` in the same directory on `PATH`
+(`~/.local/bin` is a good default). macOS does not need an extra helper binary.
+Windows source builds can use the main `zero.exe` as their sandbox helper; release
+archives still ship standalone Windows helper executables.
+
+More install details: [docs/INSTALL.md](docs/INSTALL.md).
+
+## First Run
+
+Start the TUI:
+
+```bash
+zero
+```
+
+The setup wizard helps you pick a provider and model. You can also configure
+providers from the command line:
+
+```bash
+zero setup
+zero providers list
+zero models list
+zero doctor
+```
+
+For API providers, set the matching environment variable before setup or enter
+the key in the wizard:
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=...
+export GEMINI_API_KEY=...
+```
+
+For local models, run Ollama or LM Studio and then use `zero setup` or
+`zero providers detect`.
+
+## Daily Use
+
+### Interactive TUI
+
+```bash
+zero
+```
+
+Useful controls:
+
+| Control | Action |
+|---|---|
+| `Enter` | send the prompt |
+| `/` | open slash-command suggestions |
+| `Shift+Tab` | cycle permission mode |
+| `Ctrl+B` | show/hide the sidebar |
+| `Ctrl+C` | cancel or exit |
+
+Common slash commands:
+
+| Command | Purpose |
+|---|---|
+| `/model`, `/provider` | switch the active model/provider |
+| `/spec`, `/plan` | draft and review a plan before building |
+| `/image` | attach an image for vision-capable models |
+| `/resume`, `/rewind` | continue or roll back local sessions |
+| `/compact`, `/context` | manage context usage |
+| `/permissions`, `/tools` | inspect available tools and policy |
+| `/add-dir` | allow an extra write directory for this session |
+| `/theme`, `/doctor`, `/config` | adjust appearance and inspect setup |
+
+### Headless `exec`
+
+```bash
+zero exec "explain internal/agent/loop.go"
+zero exec --model claude-sonnet-4.5 "refactor the config loader"
+zero exec --use-spec "add rate limiting to the API client"
+zero exec --worktree "try the migration in an isolated worktree"
+zero exec --resume
+zero exec --fork <session-id> "try the other approach"
+```
+
+Programmatic use:
+
+```bash
+zero exec --input-format stream-json --output-format stream-json < turns.jsonl
+```
+
+The stream-JSON contract is documented in
+[docs/STREAM_JSON_PROTOCOL.md](docs/STREAM_JSON_PROTOCOL.md).
+
+## Safety Model
+
+Zero is designed to make side effects visible.
+
+- Workspace reads are allowed by default.
+- File writes are limited to the workspace unless you grant another directory.
+- Shell commands, network access, destructive commands, and elevated actions are
+  permission-gated.
+- `--add-dir <path>` and `/add-dir <path>` grant additional write roots without
+  giving the agent the whole filesystem.
+- Unsafe/autonomous modes are explicit opt-ins.
+- Secrets are redacted from tool output and logs where Zero controls the surface.
+
+Example:
+
+```bash
+zero --add-dir ../docs-site
+zero exec --add-dir ../shared "update both repos"
+```
+
+Sandbox behavior can be inspected with:
+
+```bash
+zero sandbox policy
+zero sandbox grants list
+```
+
+## Web And Local Control
+
+Zero includes local file/search/edit/shell tools, `web_fetch` for public URLs,
+and MCP support for additional tools.
+
+For local dev servers, use shell commands such as `curl` through `exec_command`
+so the normal sandbox and permission policy applies. Long-running commands stay
+attached to a background terminal session and can be listed or stopped from the
+TUI.
+
+The npm package also includes browser and terminal helper packages used by local
+browser/terminal tools. Source builds can use the same helpers when they are on
+`PATH` or configured in Zero's local-control settings.
+
+## Common Commands
+
+```text
+zero                  interactive TUI
+zero exec             one-shot or scripted agent run
+zero setup            first-run provider setup
+zero auth             OAuth/login helpers for supported providers
+zero models           model registry and capabilities
+zero providers        provider profiles and detection
+zero doctor           setup, key, and connectivity checks
+zero context          context-budget report
+zero repo-map         deterministic repository map
+zero repo-info        local repository summary
+zero search | find    search local session history
+zero sessions         inspect, resume, fork, and rewind sessions
+zero spec             manage spec-mode drafts
+zero specialist       manage specialist subagents
+zero skills           manage markdown instruction skills
+zero plugins          manage plugins
+zero hooks            manage lifecycle hooks
+zero mcp              manage MCP servers and tools
+zero serve --mcp      expose Zero tools over MCP stdio
+zero sandbox          inspect sandbox policy and grants
+zero worktrees        prepare isolated git worktrees
+zero verify           detect and run local verification checks
+zero changes          inspect and commit local git changes
+zero usage            token usage and estimated cost
+zero cron             scheduled agent jobs
+zero update           check for newer releases
+```
+
+## Appearance And Accessibility
+
+| Control | Effect |
+|---|---|
+| `NO_COLOR=<anything>` | disables color output |
+| `ZERO_THEME=<name>` | selects the startup theme (`auto`, `dark`, `light`, or a color theme like `dracula`, `nord`, `gruvbox`, `tokyo-night`, `catppuccin`, `one-dark`, `solarized-dark`, `rose-pine`, `everforest`, `solarized-light`) |
+| `--theme <name>` | selects the TUI theme from the CLI (same names) |
+| `/theme` | opens the theme picker inside the TUI (live preview; `/theme <name>` switches directly) |
+| `ZERO_NO_FADE=1` | disables streaming fade animation |
+
+Meaning does not rely on color alone; diffs, permissions, and statuses also use
+text or glyph markers.
+
+## Development
+
+```bash
+go test ./...
+go run ./cmd/zero-release build
+go run ./cmd/zero-release smoke
+go run ./cmd/zero-perf-bench
+```
+
+Cross-compile examples:
+
+```bash
+go run ./cmd/zero-release build --goos linux --goarch amd64
+go run ./cmd/zero-release build --goos windows --goarch amd64 --output dist/zero.exe
+```
+
+## Documentation
+
+- [Install](docs/INSTALL.md)
+- [Update flow](docs/UPDATE.md)
+- [Stream-JSON protocol](docs/STREAM_JSON_PROTOCOL.md)
+- [Specialists](docs/SPECIALISTS.md)
+- [GitHub Action](docs/GITHUB_ACTION.md)
+- [Benchmarks](docs/BENCHMARK.md)
+- [Performance](docs/PERFORMANCE.md)
+- [Agent evals](docs/AGENT_EVALS.md)
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), run the
+relevant tests, and open a focused pull request.
+
+Security reports should follow [SECURITY.md](SECURITY.md).
+
+## License
+
+Zero is released under the [MIT License](LICENSE).

package/bin/zero.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function zeroBinaryName(platform = process.platform) {
+  return platform === 'win32' ? 'zero.exe' : 'zero';
+}
+
+function helperShimNames(name, platform = process.platform) {
+  if (platform === 'win32') {
+    return [`${name}.cmd`, `${name}.exe`, name];
+  }
+  return [name];
+}
+
+function commandForShim(path, platform = process.platform) {
+  if (platform === 'win32' && path.toLowerCase().endsWith('.cmd')) {
+    return {
+      command: process.env.ComSpec || 'cmd.exe',
+      prefixArgs: ['/d', '/s', '/c', `"${path.replace(/"/g, '""')}"`],
+    };
+  }
+  return { command: path, prefixArgs: [] };
+}
+
+function resolveHelper(packageRoot, name) {
+  const binDir = join(packageRoot, 'node_modules', '.bin');
+  for (const shimName of helperShimNames(name)) {
+    const candidate = join(binDir, shimName);
+    if (!existsSync(candidate)) continue;
+    return {
+      ...commandForShim(candidate),
+      pathPrepend: [binDir],
+    };
+  }
+  return null;
+}
+
+function localControlHelperManifest(packageRoot) {
+  const helpers = {};
+  for (const name of ['agent-browser', 'tuistory']) {
+    const helper = resolveHelper(packageRoot, name);
+    if (helper) helpers[name] = helper;
+  }
+  if (Object.keys(helpers).length === 0) return '';
+  return JSON.stringify({ version: 1, helpers });
+}
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const nativePath = join(packageRoot, zeroBinaryName());
+const localControlHelpers = localControlHelperManifest(packageRoot);
+
+if (!existsSync(nativePath)) {
+  console.error(
+    '[zero] No native binary found next to the npm wrapper. Reinstall the zero package or run `go run ./cmd/zero-release build` from the repository.'
+  );
+  process.exit(1);
+}
+
+const env = { ...process.env };
+if (localControlHelpers) {
+  env.ZERO_LOCAL_CONTROL_HELPERS = localControlHelpers;
+} else {
+  delete env.ZERO_LOCAL_CONTROL_HELPERS;
+}
+
+const child = spawnSync(nativePath, process.argv.slice(2), {
+  stdio: 'inherit',
+  env,
+});
+
+if (child.error) {
+  console.error(`[zero] Failed to launch wrapper target: ${child.error.message}`);
+  process.exit(1);
+}
+
+if (child.signal) {
+  process.kill(process.pid, child.signal);
+}
+
+process.exit(child.status ?? 1);

package/package.json

@@ -1,11 +1,42 @@
 {
   "name": "@gitlawb/zero",
-  "version": "0.0.0",
-  "description": "Placeholder for Zero, a terminal coding agent. The real package ships with v0.1.0 — see https://github.com/Gitlawb/zero.",
+  "version": "0.1.0",
+  "description": "Zero — a fast, multi-provider terminal coding agent.",
+  "type": "module",
+  "module": "bin/zero.js",
+  "bin": {
+    "zero": "bin/zero.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "files": [
+    "bin/zero.js",
+    "scripts/postinstall.mjs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "agent-browser": "^0.30.1",
+    "tuistory": "^0.10.0"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Gitlawb/zero.git"
   },
   "homepage": "https://github.com/Gitlawb/zero#readme",
+  "bugs": {
+    "url": "https://github.com/Gitlawb/zero/issues"
+  },
   "license": "MIT"
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// postinstall: fetch the prebuilt `zero` binary for this platform from the
+// matching GitHub Release and place it next to bin/zero.js, which execs it.
+//
+// Mirrors scripts/install.sh and scripts/install.ps1. The asset-name scheme is
+// the source of truth in internal/release/release.go:
+//   zero-v{version}-{linux|macos|windows}-{x64|arm64}.{tar.gz|zip}  (+ .sha256)
+//
+// Safety: HTTPS-only download from the pinned repo, SHA-256 verification against
+// the release's own .sha256, and extraction that never trusts archive paths —
+// we extract to a temp dir and copy only known binary basenames into place, so a
+// crafted archive cannot write outside the package (no zip-slip).
+//
+// Env overrides (testing / mirrors / locked-down installs):
+//   ZERO_SKIP_DOWNLOAD=1      skip entirely, exit 0 (wrapper will guide if run)
+//   ZERO_INSTALL_DRY_RUN=1    print the resolved plan as JSON, no network, exit 0
+//   ZERO_INSTALL_PLATFORM=…   override process.platform (linux|darwin|win32)
+//   ZERO_INSTALL_ARCH=…       override process.arch (x64|arm64)
+//   ZERO_REPO=owner/name      override the GitHub repo (default Gitlawb/zero)
+//   ZERO_GITHUB_BASE_URL=…    override the download host (default https://github.com)
+
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+const VERSION = pkg.version;
+
+const REPO = process.env.ZERO_REPO || 'Gitlawb/zero';
+const BASE = (process.env.ZERO_GITHUB_BASE_URL || 'https://github.com').replace(/\/+$/, '');
+// The .sha256 is fetched from the same origin as the archive, so TLS authenticity
+// is the only real integrity control — require https unless explicitly overridden
+// for local testing (e.g. a localhost mirror in tests).
+const ALLOW_INSECURE = process.env.ZERO_ALLOW_INSECURE_DOWNLOAD === '1';
+const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+
+function fail(message) {
+  console.error(`[zero] ${message}`);
+  process.exit(1);
+}
+
+function warnSkip(message) {
+  // Exit 0 so an unsupported platform or an opt-out does not break `npm install`;
+  // bin/zero.js reports a clear "no native binary" message if the user runs zero.
+  console.error(`[zero] ${message}`);
+  process.exit(0);
+}
+
+// Maps mirror internal/release/release.go (ReleasePlatform / ReleaseArch).
+function resolvePlatform(p) {
+  switch (p) {
+    case 'linux':
+      return 'linux';
+    case 'darwin':
+      return 'macos';
+    case 'win32':
+      return 'windows';
+    default:
+      return null;
+  }
+}
+
+function resolveArch(a) {
+  switch (a) {
+    case 'x64':
+      return 'x64';
+    case 'arm64':
+      return 'arm64';
+    default:
+      return null;
+  }
+}
+
+if (process.env.ZERO_SKIP_DOWNLOAD === '1') {
+  warnSkip('ZERO_SKIP_DOWNLOAD=1 set — skipping native binary download.');
+}
+
+const rawPlatform = process.env.ZERO_INSTALL_PLATFORM || process.platform;
+const rawArch = process.env.ZERO_INSTALL_ARCH || process.arch;
+const platform = resolvePlatform(rawPlatform);
+const arch = resolveArch(rawArch);
+
+if (!platform || !arch) {
+  warnSkip(
+    `no prebuilt binary for ${rawPlatform}/${rawArch}. Build from source: ` +
+      `https://github.com/${REPO} (go run ./cmd/zero).`,
+  );
+}
+
+// The release matrix builds linux/macos {x64,arm64} and windows-x64 — there is no
+// windows-arm64 artifact. (win32, arm64) otherwise resolves to a valid
+// platform/arch, so it would proceed to download a non-existent asset and hard
+// -fail npm install on a 404. Guard it explicitly to skip gracefully; Windows on
+// ARM runs the x64 build under emulation, so the x64 package is the fallback.
+if (platform === 'windows' && arch === 'arm64') {
+  warnSkip(
+    `no prebuilt binary for windows-arm64 (the windows-x64 build runs under ` +
+      `emulation on Windows on ARM). Build from source or install the x64 package: ` +
+      `https://github.com/${REPO} (go run ./cmd/zero).`,
+  );
+}
+
+const ext = platform === 'windows' ? 'zip' : 'tar.gz';
+const binaryName = platform === 'windows' ? 'zero.exe' : 'zero';
+const tag = `v${VERSION}`;
+const assetName = `zero-v${VERSION}-${platform}-${arch}.${ext}`;
+const assetUrl = `${BASE}/${REPO}/releases/download/${tag}/${assetName}`;
+const checksumUrl = `${assetUrl}.sha256`;
+
+// Extra binaries the archive may carry; copied when present so the platform
+// sandbox finds its adjacent helpers (tier-1 discovery), but never required.
+const optionalBinaries =
+  platform === 'windows'
+    ? ['zero-windows-command-runner.exe', 'zero-windows-sandbox-setup.exe']
+    : platform === 'linux'
+      ? ['zero-linux-sandbox', 'zero-seccomp']
+      : [];
+
+if (process.env.ZERO_INSTALL_DRY_RUN === '1') {
+  process.stdout.write(
+    JSON.stringify({
+      version: VERSION,
+      platform,
+      arch,
+      tag,
+      assetName,
+      assetUrl,
+      checksumUrl,
+      binaryName,
+      optionalBinaries,
+    }) + '\n',
+  );
+  process.exit(0);
+}
+
+// Idempotent: skip if the binary for this exact version is already in place.
+const markerPath = join(packageRoot, '.zero-binary-version');
+const installedBinary = join(packageRoot, binaryName);
+if (
+  existsSync(installedBinary) &&
+  existsSync(markerPath) &&
+  readFileSync(markerPath, 'utf8').trim() === VERSION
+) {
+  process.exit(0);
+}
+
+async function download(url) {
+  if (!ALLOW_INSECURE && !url.startsWith('https://')) {
+    fail(
+      `refusing insecure download origin for ${url}: only https:// is allowed ` +
+        `(set ZERO_ALLOW_INSECURE_DOWNLOAD=1 to override for local testing).`,
+    );
+  }
+  let response;
+  try {
+    response = await fetch(url, { redirect: 'follow' });
+  } catch (error) {
+    fail(`download failed for ${url}: ${error.message}`);
+  }
+  // Catch an https->http downgrade across redirects: the verified bytes must
+  // still have arrived over TLS for the same-origin checksum to mean anything.
+  if (!ALLOW_INSECURE && response.url && !response.url.startsWith('https://')) {
+    fail(`refusing insecure redirect to ${response.url}`);
+  }
+  if (!response.ok) {
+    fail(
+      `download failed (HTTP ${response.status}) for ${url} (release tag ${tag}). ` +
+        `If no release exists yet, or the tag and package.json version disagree, ` +
+        `build from source: https://github.com/${REPO} (go run ./cmd/zero).`,
+    );
+  }
+  const declared = Number(response.headers.get('content-length') || 0);
+  if (declared && declared > MAX_DOWNLOAD_BYTES) {
+    fail(`refusing oversized download (${declared} bytes) from ${url}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (buffer.length > MAX_DOWNLOAD_BYTES) {
+    fail(`download from ${url} exceeded ${MAX_DOWNLOAD_BYTES} bytes`);
+  }
+  return buffer;
+}
+
+// Parse a sha256sum-style file. Anchored per line, and when the line carries a
+// filename field it must equal the requested asset — mirrors the Go
+// ParseSHA256Checksum so a checksum file cannot misattribute a digest.
+function parseSha256(text, wantName) {
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const match = line.match(/^([a-fA-F0-9]{64})(?:\s+\*?(.+))?$/);
+    if (!match) continue;
+    const [, hex, name] = match;
+    if (!name || name.trim() === wantName) {
+      return hex.toLowerCase();
+    }
+  }
+  fail(`could not find a SHA-256 digest for ${wantName} in ${wantName}.sha256`);
+}
+
+function findByBasename(dir, name) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = findByBasename(full, name);
+      if (nested) return nested;
+    } else if (entry.name === name) {
+      return full;
+    }
+  }
+  return null;
+}
+
+// extract runs from `workDir` and passes RELATIVE names so no Windows drive
+// letter (e.g. C:\) appears in tar's archive argument — GNU tar otherwise reads
+// `C:foo` as a remote `host:path` and fails. archiveName and destName are both
+// relative to workDir.
+function extract(workDir, archiveName, destName) {
+  const opts = { stdio: 'inherit', cwd: workDir };
+  if (ext === 'zip') {
+    // Windows 10+ ships bsdtar as tar.exe, which extracts zips; fall back to
+    // PowerShell Expand-Archive if tar is unavailable or cannot read the zip.
+    const viaTar = spawnSync('tar', ['-xf', archiveName, '-C', destName], opts);
+    if (viaTar.status === 0) return;
+    const absArchive = join(workDir, archiveName);
+    const absDest = join(workDir, destName);
+    const viaPwsh = spawnSync(
+      'powershell',
+      [
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        `Expand-Archive -LiteralPath '${absArchive.replace(/'/g, "''")}' ` +
+          `-DestinationPath '${absDest.replace(/'/g, "''")}' -Force`,
+      ],
+      { stdio: 'inherit' },
+    );
+    if (viaPwsh.status !== 0) fail(`failed to extract ${assetName}`);
+    return;
+  }
+  const viaTar = spawnSync('tar', ['-xzf', archiveName, '-C', destName], opts);
+  if (viaTar.status !== 0) fail(`failed to extract ${assetName} (tar exited ${viaTar.status})`);
+}
+
+async function main() {
+  const archiveBuffer = await download(assetUrl);
+  const checksumText = (await download(checksumUrl)).toString('utf8');
+  const expected = parseSha256(checksumText, assetName);
+  const actual = createHash('sha256').update(archiveBuffer).digest('hex');
+  if (actual !== expected) {
+    fail(`checksum mismatch for ${assetName}: expected ${expected}, got ${actual}`);
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'zero-install-'));
+  try {
+    const archivePath = join(tempDir, assetName);
+    writeFileSync(archivePath, archiveBuffer);
+    const extractDir = join(tempDir, 'extracted');
+    mkdirSync(extractDir);
+    extract(tempDir, assetName, 'extracted');
+
+    // Copy only known basenames into the package root. We never honor
+    // archive-relative paths, so a crafted entry cannot escape the package.
+    const primarySource = findByBasename(extractDir, binaryName);
+    if (!primarySource) fail(`archive ${assetName} did not contain ${binaryName}`);
+    copyFileSync(primarySource, installedBinary);
+    if (platform !== 'windows') chmodSync(installedBinary, 0o755);
+
+    for (const name of optionalBinaries) {
+      const source = findByBasename(extractDir, name);
+      if (!source) {
+        console.error(
+          `[zero] note: optional helper ${name} was not in ${assetName}; ` +
+            `the sandbox may run with reduced isolation.`,
+        );
+        continue;
+      }
+      const dest = join(packageRoot, name);
+      copyFileSync(source, dest);
+      if (platform !== 'windows') chmodSync(dest, 0o755);
+    }
+
+    writeFileSync(markerPath, VERSION + '\n');
+    const sizeKb = Math.round(statSync(installedBinary).size / 1024);
+    console.error(`[zero] installed ${binaryName} ${VERSION} (${platform}-${arch}, ${sizeKb} KB).`);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => fail(error.message));