zerocheck 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerocheck
+
+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,56 @@
+# Zerocheck CLI
+
+AI-powered end-to-end testing from your terminal. Point it at a staging URL, get a recorded browser replay back.
+
+Tests run in Zerocheck cloud — no local Playwright, no API keys to manage. Your source code, secrets, and git history stay on your machine.
+
+## Install
+
+Requires Node 20+.
+
+```sh
+npx zerocheck@latest login
+npx zerocheck@latest run --url https://staging.yourapp.com
+```
+
+Or install globally:
+
+```sh
+npm install -g zerocheck
+zerocheck login
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `zerocheck login` | Device-code auth. Opens a browser for approval; token stored at `~/.zerocheck/config.json` (mode 0600). |
+| `zerocheck logout` | Revoke the current device's token. |
+| `zerocheck whoami` | Show auth state + linked project. |
+| `zerocheck run [file] --url <url>` | Run tests. Auto-generates starter tests on an empty project unless `--no-bootstrap`. |
+| `zerocheck generate --url <url>` | AI-generate tests against a URL. `--save` to write them to `./zerocheck/tests/`. |
+| `zerocheck discover --url <url>` | Crawl the app and draft an initial suite. |
+| `zerocheck validate [path]` | Lint `.zc` files server-side. |
+| `zerocheck doctor` | Config, token, backend reachability, version compat. |
+
+## MCP server (coming soon)
+
+An MCP server for Claude Code, Cursor, Codex, and Amp is on the roadmap — see [tryzerocheck.com/cli](https://tryzerocheck.com/cli).
+
+## Privacy boundary
+
+**Leaves your machine:** target URLs, rendered screenshots, accessibility tree, `.zc` file contents.
+
+**Stays local:** source code, environment variables, secrets, git history beyond explicit diffs.
+
+## Configuration
+
+Override the API endpoint (for self-hosted Zerocheck):
+
+```sh
+ZEROCHECK_API=https://api.example.com zerocheck login
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index.js

@@ -0,0 +1,777 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/login.ts
+import { hostname } from "os";
+import chalk from "chalk";
+
+// src/api-client.ts
+import { request } from "undici";
+
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "fs";
+var CONFIG_DIR = join(homedir(), ".zerocheck");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var DEFAULT_API_BASE = "https://api.tryzerocheck.com";
+function apiBase() {
+  const raw = process.env.ZEROCHECK_API ?? DEFAULT_API_BASE;
+  return raw.replace(/\/+$/, "");
+}
+function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(cfg) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 384 });
+}
+function clearConfig() {
+  if (existsSync(CONFIG_FILE)) rmSync(CONFIG_FILE);
+}
+function configPath() {
+  return CONFIG_FILE;
+}
+
+// src/api-client.ts
+function isApiError(e) {
+  return !!e && typeof e === "object" && "status" in e && "error" in e;
+}
+async function apiRequest(path, init = {}) {
+  const url = apiBase() + path;
+  const headers = { "content-type": "application/json" };
+  if (init.authed !== false) {
+    const cfg = loadConfig();
+    if (cfg.access_token) {
+      headers["authorization"] = `Bearer ${cfg.access_token}`;
+    }
+  }
+  const { statusCode, body } = await request(url, {
+    method: init.method ?? "POST",
+    headers,
+    body: init.body !== void 0 ? JSON.stringify(init.body) : void 0
+  });
+  const text = await body.text();
+  let parsed = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
+    }
+  }
+  if (statusCode >= 400) {
+    const payload = parsed && typeof parsed === "object" ? parsed : {};
+    const err = {
+      status: statusCode,
+      error: typeof payload["error"] === "string" ? payload["error"] : "http_error",
+      message: typeof payload["message"] === "string" ? payload["message"] : void 0
+    };
+    throw err;
+  }
+  return parsed;
+}
+
+// src/commands/login.ts
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+async function loginCommand() {
+  const existing = loadConfig();
+  if (existing.access_token) {
+    console.log(chalk.yellow("Already logged in.") + " Run `zerocheck logout` first to re-authenticate.");
+    return;
+  }
+  const deviceName = hostname();
+  console.log(chalk.dim(`Connecting to ${apiBase()}...`));
+  let device;
+  try {
+    device = await apiRequest("/v1/cli/auth/device", {
+      body: { device_name: deviceName, client_version: "0.1.0" },
+      authed: false
+    });
+  } catch (err) {
+    if (isApiError(err)) {
+      console.error(chalk.red(`Login failed (${err.status}): ${err.message ?? err.error}`));
+    } else {
+      console.error(chalk.red("Could not reach Zerocheck:"), err);
+    }
+    process.exit(1);
+  }
+  console.log();
+  console.log(chalk.bold("Open this URL in your browser:"));
+  console.log("  " + chalk.cyan(device.verification_uri_complete));
+  console.log();
+  console.log(chalk.bold("Confirm this code:") + "  " + chalk.green.bold(device.user_code));
+  console.log();
+  console.log(chalk.dim(`Waiting for approval (expires in ${Math.floor(device.expires_in / 60)} min)...`));
+  const deadline = Date.now() + device.expires_in * 1e3;
+  const intervalMs = device.interval * 1e3;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    try {
+      const poll = await apiRequest("/v1/cli/auth/poll", {
+        body: { device_code: device.device_code },
+        authed: false
+      });
+      if (poll.status === "approved") {
+        saveConfig({
+          access_token: poll.access_token,
+          created_at: (/* @__PURE__ */ new Date()).toISOString(),
+          device_name: deviceName
+        });
+        console.log();
+        console.log(chalk.green("\u2713 Logged in as ") + chalk.bold(deviceName));
+        console.log();
+        console.log(chalk.dim("Privacy: target URLs, screenshots, and accessibility trees of tests you"));
+        console.log(chalk.dim("run are sent to Zerocheck backend for AI execution. Your source code and"));
+        console.log(chalk.dim("env vars stay on your machine."));
+        return;
+      }
+    } catch (err) {
+      if (isApiError(err)) {
+        if (err.status === 410 || err.status === 403) {
+          console.error();
+          console.error(chalk.red(err.message ?? err.error));
+          process.exit(1);
+        }
+      }
+    }
+  }
+  console.error();
+  console.error(chalk.red("Login timed out. Run `zerocheck login` to try again."));
+  process.exit(1);
+}
+
+// src/commands/logout.ts
+import chalk2 from "chalk";
+async function logoutCommand() {
+  const cfg = loadConfig();
+  if (!cfg.access_token) {
+    console.log(chalk2.dim("Not logged in."));
+    return;
+  }
+  try {
+    await apiRequest("/v1/cli/auth/revoke", { body: {} });
+  } catch (err) {
+    if (isApiError(err) && err.status !== 401) {
+      console.warn(chalk2.yellow(`Server revoke returned ${err.status}. Clearing local config anyway.`));
+    }
+  }
+  clearConfig();
+  console.log(chalk2.green("\u2713 Logged out."));
+}
+
+// src/commands/whoami.ts
+import chalk3 from "chalk";
+async function whoamiCommand() {
+  const cfg = loadConfig();
+  if (!cfg.access_token) {
+    console.log(chalk3.yellow("Not logged in.") + " Run `zerocheck login`.");
+    process.exit(1);
+  }
+  try {
+    const status = await apiRequest("/v1/cli/status", { method: "GET" });
+    console.log(chalk3.bold("Zerocheck"));
+    console.log(`  API          ${apiBase()}`);
+    console.log(`  Token        ${status.token?.prefix ?? "\u2014"}`);
+    console.log(`  Device       ${status.token?.device_name ?? "\u2014"}`);
+    if (status.project) {
+      console.log(`  Project      ${status.project.name}`);
+      console.log(`  Staging URL  ${status.project.staging_url ?? chalk3.dim("(not set)")}`);
+      console.log(
+        `  GitHub       ${status.project.github_linked ? status.project.github_repo ?? "(linked)" : chalk3.dim("not linked")}`
+      );
+    }
+  } catch (err) {
+    if (isApiError(err)) {
+      if (err.status === 401) {
+        console.error(chalk3.red("Session expired.") + " Run `zerocheck login` again.");
+      } else {
+        console.error(chalk3.red(`Status check failed (${err.status}): ${err.message ?? err.error}`));
+      }
+    } else {
+      console.error(chalk3.red("Status check failed:"), err);
+    }
+    process.exit(1);
+  }
+}
+
+// src/commands/validate.ts
+import { readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { join as join2, resolve } from "path";
+import chalk4 from "chalk";
+function findZcFiles(target) {
+  const abs = resolve(target);
+  let stat;
+  try {
+    stat = statSync(abs);
+  } catch {
+    return [];
+  }
+  if (stat.isFile()) return [abs];
+  if (!stat.isDirectory()) return [];
+  const out = [];
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    const full = join2(abs, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...findZcFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".zc")) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+async function validateCommand(target) {
+  const dir = target ?? "./zerocheck/tests";
+  const files = findZcFiles(dir);
+  if (files.length === 0) {
+    console.log(chalk4.yellow(`No .zc files found at ${dir}.`));
+    process.exit(1);
+  }
+  let anyFailed = false;
+  for (const path of files) {
+    let content;
+    try {
+      content = readFileSync2(path, "utf-8");
+    } catch (err) {
+      console.error(chalk4.red(`${path}: could not read (${err instanceof Error ? err.message : err})`));
+      anyFailed = true;
+      continue;
+    }
+    try {
+      const result = await apiRequest("/v1/cli/validate", {
+        body: { path, content }
+      });
+      const rel = path.replace(process.cwd() + "/", "");
+      if (result.valid) {
+        console.log(chalk4.green("\u2713") + ` ${rel} ` + chalk4.dim(`(${result.test_count} test${result.test_count === 1 ? "" : "s"})`));
+      } else {
+        anyFailed = true;
+        console.log(chalk4.red("\u2717") + ` ${rel}`);
+        for (const err of result.errors) {
+          console.log(chalk4.dim(`  ${rel}:${err.line_number}`) + `  ${err.message}`);
+        }
+      }
+    } catch (err) {
+      anyFailed = true;
+      if (isApiError(err)) {
+        if (err.status === 401) {
+          console.error(chalk4.red("Not logged in.") + " Run `zerocheck login` first.");
+          process.exit(2);
+        }
+        console.error(chalk4.red(`${path}: validate failed (${err.status}): ${err.message ?? err.error}`));
+      } else {
+        console.error(chalk4.red(`${path}: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    }
+  }
+  process.exit(anyFailed ? 1 : 0);
+}
+
+// src/commands/generate.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+import chalk5 from "chalk";
+function sanitize(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "test";
+}
+async function generateCommand(opts) {
+  if (!opts.url) {
+    console.error(chalk5.red("--url is required."));
+    process.exit(2);
+  }
+  const maxTests = opts.maxTests ? Math.max(1, Math.min(10, parseInt(opts.maxTests, 10) || 3)) : 3;
+  console.log(chalk5.dim(`Generating ${maxTests} test${maxTests === 1 ? "" : "s"} for ${opts.url}...`));
+  let result;
+  try {
+    result = await apiRequest("/v1/cli/generate", {
+      body: { url: opts.url, description: opts.description, max_tests: maxTests }
+    });
+  } catch (err) {
+    if (isApiError(err)) {
+      if (err.status === 401) {
+        console.error(chalk5.red("Not logged in.") + " Run `zerocheck login` first.");
+        process.exit(2);
+      }
+      if (err.status === 429) {
+        console.error(chalk5.red(err.message ?? "Rate limited."));
+        process.exit(3);
+      }
+      console.error(chalk5.red(`Generate failed (${err.status}): ${err.message ?? err.error}`));
+    } else {
+      console.error(chalk5.red("Generate failed:"), err);
+    }
+    process.exit(1);
+  }
+  console.log(chalk5.green(`
+\u2713 Generated ${result.count} test${result.count === 1 ? "" : "s"}
+`));
+  for (const test of result.tests) {
+    console.log(chalk5.bold(`  ${test.name}`));
+    if (test.reasoning) console.log(chalk5.dim(`    ${test.reasoning}`));
+  }
+  if (opts.save) {
+    const outDir = opts.output ?? "./zerocheck/tests";
+    mkdirSync2(outDir, { recursive: true });
+    const written = [];
+    for (const test of result.tests) {
+      const filename = `${sanitize(test.name)}.zc`;
+      const path = join3(outDir, filename);
+      if (existsSync2(path)) {
+        console.warn(chalk5.yellow(`  skipped ${path} (already exists)`));
+        continue;
+      }
+      writeFileSync2(path, test.yaml, "utf-8");
+      written.push(path);
+    }
+    if (written.length > 0) {
+      console.log(chalk5.green(`
+\u2713 Wrote ${written.length} file${written.length === 1 ? "" : "s"}:`));
+      for (const p of written) console.log(chalk5.dim(`  ${p}`));
+    }
+  } else {
+    console.log(chalk5.dim("\nRerun with --save to write these to ./zerocheck/tests/."));
+  }
+}
+
+// src/commands/run.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "fs";
+import { join as join4, resolve as resolve2 } from "path";
+import chalk6 from "chalk";
+
+// src/stream-client.ts
+import WebSocket from "ws";
+function openRunStream(runId, onEvent) {
+  const cfg = loadConfig();
+  const base = apiBase().replace(/^http/, "ws");
+  const url = `${base}/v1/cli/stream?run_id=${encodeURIComponent(runId)}`;
+  const headers = {};
+  if (cfg.access_token) headers["Authorization"] = `Bearer ${cfg.access_token}`;
+  let ws = null;
+  let closed = false;
+  try {
+    ws = new WebSocket(url, { headers });
+    ws.on("message", (raw) => {
+      try {
+        const event = JSON.parse(raw.toString());
+        onEvent(event);
+      } catch {
+      }
+    });
+    ws.on("error", () => {
+    });
+  } catch {
+  }
+  return {
+    close: () => {
+      if (closed) return;
+      closed = true;
+      try {
+        ws?.close();
+      } catch {
+      }
+    }
+  };
+}
+
+// src/commands/run.ts
+var TESTS_DIR = "./zerocheck/tests";
+var POLL_INTERVAL_MS = 2e3;
+var MAX_POLL_MS = 15 * 60 * 1e3;
+function findZcFiles2(dir) {
+  try {
+    const stat = statSync2(dir);
+    if (!stat.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    const full = join4(dir, entry.name);
+    if (entry.isDirectory()) out.push(...findZcFiles2(full));
+    else if (entry.isFile() && entry.name.endsWith(".zc")) out.push(full);
+  }
+  return out;
+}
+function sanitize2(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "test";
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function bootstrapTests(url) {
+  console.log(chalk6.dim(`No tests at ${TESTS_DIR}. Generating starter tests for ${url}...`));
+  let result;
+  try {
+    result = await apiRequest("/v1/cli/generate", {
+      body: { url, max_tests: 3 }
+    });
+  } catch (err) {
+    if (isApiError(err) && err.status === 401) {
+      console.error(chalk6.red("Not logged in.") + " Run `zerocheck login` first.");
+      process.exit(2);
+    }
+    throw err;
+  }
+  mkdirSync3(TESTS_DIR, { recursive: true });
+  const written = [];
+  for (const test of result.tests) {
+    const path = join4(TESTS_DIR, `${sanitize2(test.name)}.zc`);
+    if (existsSync3(path)) continue;
+    writeFileSync3(path, test.yaml, "utf-8");
+    written.push(path);
+  }
+  console.log(chalk6.green(`\u2713 Generated ${result.count} starter test${result.count === 1 ? "" : "s"}:`));
+  for (const p of written) console.log(chalk6.dim(`  ${p}`));
+  console.log();
+  return written;
+}
+function renderFinalReport(detail) {
+  console.log();
+  const statusColor = detail.status === "passed" ? chalk6.green : detail.status === "failed" ? chalk6.red : chalk6.yellow;
+  console.log(statusColor(`\u25CF Run ${detail.status}`) + chalk6.dim(`  (${(detail.totalDuration / 1e3).toFixed(1)}s)`));
+  console.log(chalk6.dim(`  ${detail.totalPassed} passed  ${detail.totalFailed} failed  confidence ${detail.confidence}%`));
+  console.log();
+  for (const t of detail.testResults) {
+    const mark = t.status === "pass" ? chalk6.green("\u2713") : chalk6.red("\u2717");
+    console.log(`${mark} ${t.testName} ` + chalk6.dim(`(${(t.duration / 1e3).toFixed(1)}s)`));
+    if (t.status !== "pass" && t.steps) {
+      for (const s of t.steps) {
+        if (s.status === "fail") {
+          console.log(chalk6.dim(`    ${s.keyword}`) + (s.argument ? ` ${s.argument}` : ""));
+          if (s.error) console.log(chalk6.red(`    error: ${s.error}`));
+          if (s.screenshotBeforePath) console.log(chalk6.dim(`    screenshot: ${s.screenshotBeforePath}`));
+        }
+      }
+    }
+  }
+}
+async function runCommand(fileArg, opts) {
+  let url = opts.url;
+  const paths = fileArg ? [resolve2(fileArg)] : findZcFiles2(TESTS_DIR);
+  let contentFiles = [];
+  if (paths.length === 0) {
+    if (opts.bootstrap === false) {
+      console.error(chalk6.red(`No tests found at ${TESTS_DIR} and --no-bootstrap was passed.`));
+      process.exit(1);
+    }
+    if (!url) {
+      console.error(chalk6.red("No tests found and no --url provided to bootstrap from."));
+      console.error(chalk6.dim("Either:  zerocheck run --url https://staging.example.com"));
+      console.error(chalk6.dim("Or add a .zc file to ./zerocheck/tests/ and rerun."));
+      process.exit(2);
+    }
+    contentFiles = await bootstrapTests(url);
+  } else {
+    contentFiles = paths;
+  }
+  const content = contentFiles.map((p) => readFileSync3(p, "utf-8")).join("\n\n");
+  console.log(chalk6.dim(`Starting run${url ? ` against ${url}` : ""}...`));
+  let start;
+  try {
+    start = await apiRequest("/v1/cli/runs", {
+      body: { url, content }
+    });
+  } catch (err) {
+    if (isApiError(err)) {
+      if (err.status === 401) {
+        console.error(chalk6.red("Not logged in.") + " Run `zerocheck login` first.");
+        process.exit(2);
+      }
+      if (err.status === 429) {
+        console.error(chalk6.red(err.message ?? "Rate limited."));
+        process.exit(3);
+      }
+      if (err.status === 400 && err.error === "parse_error") {
+        console.error(chalk6.red("Could not parse tests.") + " Run `zerocheck validate` to see details.");
+        process.exit(1);
+      }
+      console.error(chalk6.red(`Run start failed (${err.status}): ${err.message ?? err.error}`));
+    } else {
+      console.error(chalk6.red("Run start failed:"), err);
+    }
+    process.exit(1);
+  }
+  console.log(chalk6.dim(`  run_id=${start.run_id}  ${start.total_tests} test${start.total_tests === 1 ? "" : "s"}`));
+  console.log();
+  const stream = openRunStream(start.run_id, (event) => {
+    if (event.type === "run:test:completed") {
+      const d = event.data;
+      const mark = d.status === "pass" ? chalk6.green("\u2713") : chalk6.red("\u2717");
+      const name = typeof d.testName === "string" ? d.testName : "(unknown test)";
+      const dur = typeof d.duration === "number" ? ` ${chalk6.dim(`(${(d.duration / 1e3).toFixed(1)}s)`)}` : "";
+      console.log(`${mark} ${name}${dur}`);
+    }
+  });
+  const deadline = Date.now() + MAX_POLL_MS;
+  try {
+    while (Date.now() < deadline) {
+      await sleep2(POLL_INTERVAL_MS);
+      try {
+        const detail = await apiRequest(`/v1/cli/runs/${start.run_id}`, { method: "GET" });
+        if (detail.status === "passed" || detail.status === "failed" || detail.status === "error") {
+          stream.close();
+          renderFinalReport(detail);
+          process.exit(detail.status === "passed" ? 0 : 1);
+        }
+      } catch (err) {
+        if (isApiError(err) && err.status === 404) continue;
+        throw err;
+      }
+    }
+    console.error(chalk6.red("\nRun did not complete within the polling window."));
+    process.exit(1);
+  } finally {
+    stream.close();
+  }
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync4, statSync as statSync3 } from "fs";
+import { platform, arch, release } from "os";
+import chalk7 from "chalk";
+var CLI_VERSION = "0.1.0";
+function line(status, label, detail, hint) {
+  const icon = status === "ok" ? chalk7.green("\u2713") : status === "warn" ? chalk7.yellow("!") : chalk7.red("\u2717");
+  const line2 = `${icon}  ${label}`;
+  console.log(detail ? `${line2}  ${chalk7.dim(detail)}` : line2);
+  if (hint) console.log(chalk7.dim("    \u2192 " + hint));
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+function checkConfig() {
+  const path = configPath();
+  if (!existsSync4(path)) {
+    return { ok: false, detail: "not found", hint: "Run `zerocheck login`." };
+  }
+  try {
+    const stat = statSync3(path);
+    if ((stat.mode & 63) !== 0) {
+      return { ok: false, detail: `mode ${(stat.mode & 511).toString(8)}`, hint: `Run chmod 600 ${path}` };
+    }
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message : String(err), hint: "Check file permissions." };
+  }
+  return { ok: true, detail: path };
+}
+function checkToken() {
+  const cfg = loadConfig();
+  if (!cfg.access_token) {
+    return { ok: false, detail: "no token", hint: "Run `zerocheck login`." };
+  }
+  return { ok: true, detail: cfg.access_token.slice(0, 15) + "..." };
+}
+async function checkBackend() {
+  try {
+    const status = await apiRequest("/v1/cli/status", { method: "GET" });
+    return { ok: true, detail: `API v${status.api_version}`, status };
+  } catch (err) {
+    if (isApiError(err)) {
+      if (err.status === 401) {
+        return { ok: false, detail: "unauthorized", hint: "Session expired \u2014 run `zerocheck login` again." };
+      }
+      return { ok: false, detail: `HTTP ${err.status}`, hint: err.message ?? err.error };
+    }
+    return { ok: false, detail: err instanceof Error ? err.message : String(err), hint: `Can't reach ${apiBase()}. Check network or set ZEROCHECK_API.` };
+  }
+}
+function checkVersion(minVersion) {
+  if (compareSemver(CLI_VERSION, minVersion) >= 0) {
+    return { ok: true, detail: `cli ${CLI_VERSION} >= min ${minVersion}` };
+  }
+  return {
+    ok: false,
+    detail: `cli ${CLI_VERSION} < min ${minVersion}`,
+    hint: "Upgrade: npm i -g zerocheck@latest"
+  };
+}
+async function doctorCommand() {
+  console.log(chalk7.bold("zerocheck doctor\n"));
+  console.log(chalk7.dim(`  platform:    ${platform()} ${arch()} (${release()})`));
+  console.log(chalk7.dim(`  node:        ${process.version}`));
+  console.log(chalk7.dim(`  cli:         ${CLI_VERSION}`));
+  console.log(chalk7.dim(`  api base:    ${apiBase()}
+`));
+  let anyFailed = false;
+  const cfgCheck = checkConfig();
+  if (cfgCheck.ok) line("ok", "Local config", cfgCheck.detail);
+  else {
+    anyFailed = true;
+    line("fail", "Local config", cfgCheck.detail, cfgCheck.hint);
+  }
+  const tokenCheck = checkToken();
+  if (tokenCheck.ok) line("ok", "Token present", tokenCheck.detail);
+  else {
+    anyFailed = true;
+    line("fail", "Token present", tokenCheck.detail, tokenCheck.hint);
+  }
+  if (!tokenCheck.ok) {
+    console.log();
+    console.log(chalk7.yellow("Skipping remote checks \u2014 no token."));
+    process.exit(1);
+  }
+  const backendCheck = await checkBackend();
+  if (backendCheck.ok) line("ok", "Backend reachable", backendCheck.detail);
+  else {
+    anyFailed = true;
+    line("fail", "Backend reachable", backendCheck.detail, backendCheck.hint);
+  }
+  if (backendCheck.ok && backendCheck.status) {
+    const versionCheck = checkVersion(backendCheck.status.min_cli_version);
+    if (versionCheck.ok) line("ok", "CLI version", versionCheck.detail);
+    else {
+      anyFailed = true;
+      line("fail", "CLI version", versionCheck.detail, versionCheck.hint);
+    }
+    const project = backendCheck.status.project;
+    if (project) {
+      const stagingOk = !!project.staging_url;
+      if (stagingOk) line("ok", "Project staging URL", project.staging_url ?? "");
+      else line("warn", "Project staging URL", "not set", "Pass --url on run, or set in dashboard Settings.");
+      if (project.github_linked) line("ok", "GitHub linked");
+      else line("warn", "GitHub linked", "not linked", "Run `zerocheck link github` for PR automation.");
+    } else {
+      line("warn", "Project", "no active project");
+    }
+  }
+  console.log();
+  if (anyFailed) {
+    console.log(chalk7.red("Some checks failed. Follow the hints above."));
+    process.exit(1);
+  }
+  console.log(chalk7.green("All checks passed."));
+}
+
+// src/commands/discover.ts
+import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4, existsSync as existsSync5 } from "fs";
+import { join as join5 } from "path";
+import chalk8 from "chalk";
+function sanitize3(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "test";
+}
+function sleep3(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "cancelled", "error"]);
+var POLL_INTERVAL_MS2 = 2500;
+var MAX_WAIT_MS = 15 * 60 * 1e3;
+async function discoverCommand(opts) {
+  if (!opts.url) {
+    console.error(chalk8.red("--url is required."));
+    process.exit(2);
+  }
+  const maxPages = opts.maxPages ? Math.min(100, Math.max(1, parseInt(opts.maxPages, 10) || 20)) : 20;
+  const maxDepth = opts.maxDepth ? Math.min(5, Math.max(1, parseInt(opts.maxDepth, 10) || 3)) : 3;
+  console.log(chalk8.dim(`Discovering ${opts.url}  (max ${maxPages} pages, depth ${maxDepth})...`));
+  let start;
+  try {
+    start = await apiRequest("/v1/cli/discover", {
+      body: { url: opts.url, max_pages: maxPages, max_depth: maxDepth }
+    });
+  } catch (err) {
+    if (isApiError(err)) {
+      if (err.status === 401) {
+        console.error(chalk8.red("Not logged in.") + " Run `zerocheck login` first.");
+        process.exit(2);
+      }
+      if (err.status === 429) {
+        console.error(chalk8.red(err.message ?? "Rate limited."));
+        process.exit(3);
+      }
+      console.error(chalk8.red(`Discover start failed (${err.status}): ${err.message ?? err.error}`));
+    } else {
+      console.error(chalk8.red("Discover start failed:"), err);
+    }
+    process.exit(1);
+  }
+  console.log(chalk8.dim(`  session_id=${start.session_id}`));
+  const deadline = Date.now() + MAX_WAIT_MS;
+  let lastRoutes = -1;
+  let lastTests = -1;
+  while (Date.now() < deadline) {
+    await sleep3(POLL_INTERVAL_MS2);
+    let detail;
+    try {
+      detail = await apiRequest(`/v1/cli/discover/${start.session_id}`, { method: "GET" });
+    } catch (err) {
+      if (isApiError(err) && err.status === 404) continue;
+      throw err;
+    }
+    const { status, pages_visited, routes_discovered, tests_generated, error } = detail.session;
+    if (routes_discovered !== lastRoutes || tests_generated !== lastTests) {
+      process.stdout.write(
+        `\r  ${chalk8.dim(status.padEnd(11))} pages=${pages_visited}  routes=${routes_discovered}  tests=${tests_generated}  `
+      );
+      lastRoutes = routes_discovered;
+      lastTests = tests_generated;
+    }
+    if (TERMINAL_STATUSES.has(status)) {
+      process.stdout.write("\n\n");
+      if (status === "error") {
+        console.error(chalk8.red(`Discovery failed: ${error ?? "unknown error"}`));
+        process.exit(1);
+      }
+      if (status === "cancelled") {
+        console.log(chalk8.yellow("Discovery cancelled."));
+        process.exit(1);
+      }
+      console.log(chalk8.green(`\u2713 Discovered ${detail.routes.length} route${detail.routes.length === 1 ? "" : "s"}, generated ${detail.tests.length} test${detail.tests.length === 1 ? "" : "s"}.`));
+      console.log();
+      for (const test of detail.tests) {
+        console.log(chalk8.bold(`  ${test.name}`) + chalk8.dim(`  ${test.target_route ?? ""}`));
+      }
+      if (opts.save && detail.tests.length > 0) {
+        const outDir = opts.output ?? "./zerocheck/tests";
+        mkdirSync4(outDir, { recursive: true });
+        const written = [];
+        for (const test of detail.tests) {
+          const path = join5(outDir, `${sanitize3(test.name)}.zc`);
+          if (existsSync5(path)) continue;
+          writeFileSync4(path, test.yaml, "utf-8");
+          written.push(path);
+        }
+        console.log();
+        console.log(chalk8.green(`\u2713 Wrote ${written.length} file${written.length === 1 ? "" : "s"} to ${outDir}`));
+        for (const p of written) console.log(chalk8.dim(`  ${p}`));
+      } else if (!opts.save) {
+        console.log();
+        console.log(chalk8.dim("Rerun with --save to write tests to ./zerocheck/tests/."));
+        console.log(chalk8.dim("Or review + approve via the dashboard /generated-tests page."));
+      }
+      return;
+    }
+  }
+  console.error(chalk8.red("\nDiscovery did not complete within the polling window."));
+  process.exit(1);
+}
+
+// src/index.ts
+var program = new Command();
+program.name("zerocheck").description("Zerocheck \u2014 AI-powered E2E testing. Auth to Zerocheck cloud; your code stays local.").version("0.1.0");
+program.command("login").description("Authenticate this device with Zerocheck").action(loginCommand);
+program.command("logout").description("Revoke this device's token and clear local config").action(logoutCommand);
+program.command("whoami").description("Show authentication state + linked project").action(whoamiCommand);
+program.command("validate [path]").description("Lint .zc files (default: ./zerocheck/tests)").action(validateCommand);
+program.command("generate").description("Generate .zc tests from a URL using hosted AI").requiredOption("--url <url>", "Target URL to generate tests against").option("--description <text>", "Short hint on what kind of tests you want").option("--max-tests <n>", "Maximum tests to generate (1-10)", "3").option("--save", "Write generated tests to disk at ./zerocheck/tests/").option("--output <dir>", "Override output directory", "./zerocheck/tests").action(generateCommand);
+program.command("run [file]").description("Run .zc tests. On an empty repo, generates starter tests first.").option("--url <url>", "Target URL (overrides project staging URL)").option("--no-bootstrap", "Do not auto-generate starter tests when repo is empty").action(runCommand);
+program.command("doctor").description("Health check: config, token, backend reachability, version compat").action(doctorCommand);
+program.command("discover").description("Crawl a URL and generate an initial .zc test suite").requiredOption("--url <url>", "URL to start crawling from").option("--max-pages <n>", "Maximum pages to crawl (1-100)", "20").option("--max-depth <n>", "Maximum crawl depth (1-5)", "3").option("--save", "Write generated tests to ./zerocheck/tests/").option("--output <dir>", "Override output directory", "./zerocheck/tests").action(discoverCommand);
+program.parseAsync().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "zerocheck",
+  "version": "0.0.1",
+  "description": "Zerocheck CLI — AI-powered E2E testing. Auth-only, hosted execution.",
+  "type": "module",
+  "bin": {
+    "zerocheck": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "ora": "^8.2.0",
+    "undici": "^7.10.0",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}