@jango-blockchained/hoox-cli 0.3.4

package/src/commands/check/index.ts

@@ -0,0 +1,10 @@
+export { registerCheckCommand } from "./check-command.js";
+export { registerPrerequisitesCommand } from "./prerequisites-command.js";
+export type {
+  CheckResult,
+  CheckCategory,
+  CheckReport,
+  HealthCheckResult,
+  FixAction,
+  FixReport,
+} from "./types.js";

package/src/commands/check/prerequisites-command.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { runPrerequisitesCheck } from "./prerequisites-command.js";
+import { PrerequisitesService } from "../../services/prerequisites/index.js";
+
+describe("prerequisites command", () => {
+  describe("runPrerequisitesCheck", () => {
+    it("runs all checks and returns a report", async () => {
+      const svc = new PrerequisitesService();
+      const report = await runPrerequisitesCheck(svc);
+      expect(report.checks.length).toBeGreaterThan(0);
+      expect(typeof report.allPassed).toBe("boolean");
+    });
+
+    it("uses a new PrerequisitesService when none provided", async () => {
+      const report = await runPrerequisitesCheck();
+      expect(report.checks.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/commands/check/prerequisites-command.ts

@@ -0,0 +1,92 @@
+import { Command } from "commander";
+import { PrerequisitesService } from "../../services/prerequisites/index.js";
+import type { PrerequisitesReport } from "../../services/prerequisites/prerequisites-service.js";
+import { theme, icons } from "../../utils/theme.js";
+import { formatError, formatJson } from "../../utils/formatters.js";
+import { CLIError, ExitCode } from "../../utils/errors.js";
+import type { FormatOptions } from "../../utils/formatters.js";
+
+export async function runPrerequisitesCheck(
+  service?: PrerequisitesService,
+): Promise<PrerequisitesReport> {
+  const svc = service ?? new PrerequisitesService();
+  return await svc.runAll();
+}
+
+function renderReport(report: PrerequisitesReport): void {
+  for (const check of report.checks) {
+    const icon = check.passed ? theme.success(icons.success) : theme.error(icons.error);
+    process.stdout.write(`${icon} ${check.name}\n`);
+    process.stdout.write(`   ${theme.dim("Version:")} ${check.version}\n`);
+    process.stdout.write(`   ${theme.dim("Required:")} ${check.required}\n`);
+    if (check.hint) {
+      process.stdout.write(`   ${theme.warning(`${icons.warning} ${check.hint}`)}\n`);
+    }
+    process.stdout.write("\n");
+  }
+
+  const summary = report.allPassed
+    ? `${theme.success(icons.success)} All prerequisites met`
+    : `${theme.error(icons.error)} Some prerequisites not met`;
+  process.stdout.write(summary + "\n");
+}
+
+async function handlePrerequisites(
+  opts: FormatOptions,
+  tool?: string,
+): Promise<void> {
+  try {
+    const svc = new PrerequisitesService();
+    const report = tool ? await svc.runAll(tool) : await svc.runAll();
+
+    if (opts.json) {
+      formatJson(report, opts);
+    } else if (opts.quiet) {
+    } else {
+      renderReport(report);
+    }
+
+    if (!report.allPassed) {
+      process.exitCode = ExitCode.ERROR;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    formatError(new CLIError(message, ExitCode.ERROR), opts);
+    process.exitCode = ExitCode.ERROR;
+  }
+}
+
+export function registerPrerequisitesCommand(parentCmd: Command): void {
+  parentCmd
+    .command("prerequisites")
+    .summary("Validate toolchain and account prerequisites")
+    .description(
+      `Check that all required tools and accounts are set up correctly.
+
+Checks performed:
+  1. Bun version (>=1.2)
+  2. Git version (>=2.40)
+  3. Node.js version (>=18, advisory)
+  4. Wrangler CLI version (latest)
+  5. Cloudflare authentication
+  6. Docker availability (advisory)
+  7. Repository integrity (wrangler.jsonc, submodules)
+
+OPTIONS:
+  --tool <name>    Only check a specific tool (e.g. "bun", "git", "wrangler")
+
+EXAMPLES:
+  hoox check prerequisites
+  hoox check prerequisites --tool bun
+  hoox check prerequisites --json`,
+    )
+    .option("--tool <name>", "Only check a specific tool")
+    .action(async (options: { tool?: string }, cmd: Command) => {
+      const rootCmd = cmd.parent?.parent as Command | undefined;
+      const opts: FormatOptions = {
+        json: Boolean(rootCmd?.optsWithGlobals()?.json),
+        quiet: Boolean(rootCmd?.optsWithGlobals()?.quiet),
+      };
+      await handlePrerequisites(opts, options.tool);
+    });
+}

package/src/commands/check/types.ts

@@ -0,0 +1,103 @@
+/**
+ * `hoox check` command types — validation check results, health status,
+ * and fix reports for the check command group.
+ */
+
+/**
+ * Result of a single validation check within a category.
+ */
+export interface CheckResult {
+  /** Human-readable check name (e.g. "D1 Database", "Wrangler Configs"). */
+  name: string;
+  /** Whether this check passed (no errors). */
+  success: boolean;
+  /** Failing conditions — must be addressed before deployment. */
+  errors: string[];
+  /** Non-blocking issues — should be reviewed. */
+  warnings: string[];
+}
+
+/**
+ * A logical group of related checks (Config, Infrastructure, Secrets, Database).
+ */
+export interface CheckCategory {
+  /** Category label displayed in the report. */
+  name: string;
+  /** Per-check results within this category. */
+  checks: CheckResult[];
+}
+
+/**
+ * Top-level report produced by `hoox check setup`.
+ * Rendered as a table (human mode) or JSON (--json mode).
+ */
+export interface CheckReport {
+  /** True when every check in every category passed (zero errors). */
+  success: boolean;
+  /** Grouped category results. */
+  categories: CheckCategory[];
+  /** Aggregated counts across all checks. */
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Health check types
+// ---------------------------------------------------------------------------
+
+/**
+ * Status of a single worker after a health probe.
+ */
+export interface HealthCheckResult {
+  /** Worker name as defined in wrangler.jsonc. */
+  worker: string;
+  /** Categorised health status. */
+  status: "healthy" | "degraded" | "down";
+  /** Whether `wrangler tail` successfully connected to the worker. */
+  connectivity: boolean;
+  /** Approximate tail response time in ms (if measurable). */
+  responseTime?: number;
+  /** Human-readable error when status is "degraded" or "down". */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Fix / repair types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single fix action to be applied (or simulated in --dry-run) by `hoox check fix`.
+ */
+export interface FixAction {
+  description: string;
+  type: "file" | "binding" | "flag" | "config";
+  /** Target path or identifier (e.g. worker path, binding name). */
+  target: string;
+  /** Textual description of the exact change to apply. */
+  change: string;
+  /** Whether the fix was successfully applied (always false in --dry-run). */
+  applied: boolean;
+  /** Error message if application failed. */
+  error?: string;
+}
+
+/**
+ * Report produced by `hoox check fix` summarising all fix actions.
+ */
+export interface FixReport {
+  /** Ordered list of fix actions. */
+  actions: FixAction[];
+  /** Whether this was a dry-run (no filesystem writes). */
+  dryRun: boolean;
+  /** Aggregated counts. */
+  summary: {
+    total: number;
+    applied: number;
+    skipped: number;
+    failed: number;
+  };
+}

package/src/commands/clone/clone-command.test.ts

@@ -0,0 +1,442 @@
+// @ts-nocheck
+/**
+ * Unit tests for the clone command.
+ *
+ * Uses temp directories with real wrangler.jsonc and .git directories so
+ * ConfigService operates normally.  Only Bun.spawn (git subcommands) is
+ * mocked to keep tests fast and side-effect free.
+ */
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Command } from "commander";
+import { registerCloneCommand } from "./clone-command.js";
+
+// ---------------------------------------------------------------------------
+// Bun.spawn mocking (same pattern as cloudflare-service.test.ts)
+// ---------------------------------------------------------------------------
+
+type MockSpawnResult = {
+  stdout: Blob;
+  stderr: Blob;
+  exited: Promise<number>;
+  stdin?: { write: ReturnType<typeof mock>; end: ReturnType<typeof mock> };
+  kill: ReturnType<typeof mock>;
+};
+
+const realSpawn = Bun.spawn;
+let origCwd: string;
+let lastSpawnCmd: string[] = [];
+
+function successSpawn(stdout = ""): MockSpawnResult {
+  return {
+    stdout: new Blob([stdout]),
+    stderr: new Blob([""]),
+    exited: Promise.resolve(0),
+    stdin: { write: mock(() => {}), end: mock(() => {}) },
+    kill: mock(() => {}),
+  };
+}
+
+function errorSpawn(stderr = "", exitCode = 1): MockSpawnResult {
+  return {
+    stdout: new Blob([""]),
+    stderr: new Blob([stderr]),
+    exited: Promise.resolve(exitCode),
+    stdin: { write: mock(() => {}), end: mock(() => {}) },
+    kill: mock(() => {}),
+  };
+}
+
+/** Queue of spawn results to return in order. */
+let spawnQueue: MockSpawnResult[] = [];
+
+function enqueueSpawn(result: MockSpawnResult): void {
+  spawnQueue.push(result);
+}
+
+function installSpawnMock(): void {
+  lastSpawnCmd = [];
+  const spawnMock = mock((cmd: string[], _opts?: { cwd?: string }) => {
+    lastSpawnCmd = [...cmd];
+    return spawnQueue.shift() ?? errorSpawn("unexpected spawn call", 127);
+  });
+  (Bun as Record<string, unknown>).spawn = spawnMock;
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+let tmpDir: string;
+
+/** Write a minimal wrangler.jsonc into tmpDir for ConfigService to load. */
+async function writeTestConfig(
+  workers: Record<string, { enabled: boolean; path: string }>
+): Promise<string> {
+  const content = JSON.stringify({
+    global: { cloudflare_account_id: "test-account" },
+    workers,
+  });
+  await Bun.write(join(tmpDir, "wrangler.jsonc"), content);
+  return join(tmpDir, "wrangler.jsonc");
+}
+
+/** Create a real .git file to simulate an already-cloned git submodule. */
+function markCloned(workerName: string, workerPath: string): void {
+  const workerDir = join(tmpDir, workerPath);
+  mkdirSync(workerDir, { recursive: true });
+  // Git submodules use a .git FILE (not directory) pointing to superproject
+  writeFileSync(
+    join(workerDir, ".git"),
+    "gitdir: ../.git/modules/" + workerName
+  );
+}
+
+/** Build a fresh commander program with the clone command registered. */
+function buildProgram(): Command {
+  const program = new Command();
+  program.name("hoox");
+  program.option("--json", "JSON output");
+  program.option("--quiet", "Minimal output");
+  program.exitOverride();
+  registerCloneCommand(program);
+  return program;
+}
+
+/** Capture stdout during program.parseAsync, chdir'd to tmpDir first. */
+async function captureStdout(
+  program: Command,
+  args: string[]
+): Promise<string> {
+  const origCwd = process.cwd();
+  process.chdir(tmpDir);
+
+  let output = "";
+  const orig = process.stdout.write.bind(process.stdout);
+  (process.stdout as Record<string, unknown>).write = mock((chunk: string) => {
+    output += chunk;
+    return true;
+  });
+
+  try {
+    await program.parseAsync([...args], { from: "user" });
+  } catch {
+    // exitOverride throws CommanderError — swallow
+  }
+
+  (process.stdout as Record<string, unknown>).write = orig;
+  process.chdir(origCwd);
+  return output;
+}
+
+// ---------------------------------------------------------------------------
+// Setup / Teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "hoox-clone-test-"));
+  origCwd = process.cwd();
+  spawnQueue = [];
+  installSpawnMock();
+});
+
+afterEach(() => {
+  (Bun as Record<string, unknown>).spawn = realSpawn;
+  process.chdir(origCwd);
+  rmSync(tmpDir, { recursive: true, force: true });
+  mock.restore();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("registerCloneCommand", () => {
+  // -- Registration ----------------------------------------------------------
+
+  it("registers the clone command on the program", () => {
+    const program = buildProgram();
+    const names = program.commands.map((c) => c.name());
+    expect(names).toContain("clone");
+  });
+
+  it("clone command has --all and --org options", () => {
+    const program = buildProgram();
+    const cmd = program.commands.find((c) => c.name() === "clone");
+    expect(cmd).toBeDefined();
+    const opts = cmd!.options.map((o) => o.long);
+    expect(opts).toContain("--all");
+    expect(opts).toContain("--org");
+  });
+
+  it("clone command accepts optional [name] argument", () => {
+    const program = buildProgram();
+    const cmd = program.commands.find((c) => c.name() === "clone");
+    expect(cmd).toBeDefined();
+    const args = cmd!.registeredArguments;
+    expect(args).toHaveLength(1);
+    expect(args[0].name()).toBe("name");
+    expect(args[0].required).toBe(false);
+  });
+
+  // -- No-arg mode: list clone status ---------------------------------------
+
+  describe("no-arg mode (list status)", () => {
+    it("lists workers with clone status in table format", async () => {
+      // git remote detection
+      enqueueSpawn(successSpawn("https://github.com/test-org/hoox-setup.git"));
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone"]);
+
+      expect(output).toContain("d1-worker");
+      expect(output).toContain("hoox");
+      expect(output).toContain("test-org");
+    });
+
+    it("marks already cloned workers", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+        "trade-worker": { enabled: true, path: "workers/trade-worker" },
+      });
+      markCloned("d1-worker", "workers/d1-worker");
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone"]);
+
+      // d1-worker should be "cloned", trade-worker should be "not cloned"
+      expect(output).toContain("cloned");
+      expect(output).toContain("not cloned");
+    });
+
+    it("supports --json flag for machine-readable output", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+
+      await writeTestConfig({
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["--json", "clone"]);
+
+      const parsed = JSON.parse(output.trim());
+      expect(Array.isArray(parsed)).toBe(true);
+      expect(parsed[0]).toHaveProperty("worker");
+      expect(parsed[0]).toHaveProperty("cloned");
+      expect(parsed[0]).toHaveProperty("repo");
+      expect(parsed[0].worker).toBe("hoox");
+    });
+
+    it("supports --quiet flag with simple line-per-worker output", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+
+      await writeTestConfig({
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["--quiet", "clone"]);
+
+      expect(output).toContain("hoox: not cloned");
+      expect(output).not.toContain("┌"); // no table borders
+    });
+  });
+
+  // -- --all mode ------------------------------------------------------------
+
+  describe("--all mode", () => {
+    it("clones all workers and prints summary table", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      // git submodule add for d1-worker
+      enqueueSpawn(successSpawn());
+      // git submodule add for hoox
+      enqueueSpawn(successSpawn());
+      // git submodule update
+      enqueueSpawn(successSpawn());
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "--all"]);
+
+      // Summary table is printed to stdout
+      expect(output).toContain("d1-worker");
+      expect(output).toContain("hoox");
+      expect(output).toContain("cloned");
+    });
+
+    it("skips already cloned workers", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      // Only hoox needs cloning
+      enqueueSpawn(successSpawn());
+      enqueueSpawn(successSpawn());
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+      markCloned("d1-worker", "workers/d1-worker"); // already cloned
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "--all"]);
+
+      // Both workers appear in the table as "cloned"
+      expect(output).toContain("d1-worker");
+      expect(output).toContain("hoox");
+    });
+
+    it("reports failures when some clones fail", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      // d1-worker succeeds
+      enqueueSpawn(successSpawn());
+      // hoox fails
+      enqueueSpawn(errorSpawn("repository not found", 128));
+      // submodule update (still runs)
+      enqueueSpawn(successSpawn());
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "--all"]);
+
+      // Table shows both cloned and failed
+      expect(output).toContain("d1-worker");
+      expect(output).toContain("hoox");
+      expect(output).toContain("failed");
+    });
+
+    it("handles empty worker list", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+
+      await writeTestConfig({});
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "--all"]);
+
+      expect(output).toContain("No workers");
+    });
+  });
+
+  // -- <name> mode (single worker) -------------------------------------------
+
+  describe("<name> mode (single worker)", () => {
+    it("clones a specific worker by name", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      enqueueSpawn(successSpawn());
+      enqueueSpawn(successSpawn());
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "d1-worker"]);
+
+      expect(output).toContain("Cloned d1-worker");
+      expect(output).toContain("org");
+    });
+
+    it("validates worker name exists in config", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "nonexistent"]);
+
+      expect(output).toContain("not found");
+    });
+
+    it("exits early when worker is already cloned", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+      });
+      markCloned("d1-worker", "workers/d1-worker");
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "d1-worker"]);
+
+      expect(output).toContain("already cloned");
+    });
+
+    it("reports clone failure", async () => {
+      enqueueSpawn(successSpawn("https://github.com/org/repo.git"));
+      enqueueSpawn(errorSpawn("fatal: could not read from remote", 128));
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone", "d1-worker"]);
+
+      expect(output).toContain("Failed to clone");
+    });
+  });
+
+  // -- --org option ----------------------------------------------------------
+
+  describe("--org option", () => {
+    it("uses --org value for the repo URL", async () => {
+      // No git remote call needed since --org is explicit
+      enqueueSpawn(successSpawn());
+      enqueueSpawn(successSpawn());
+
+      await writeTestConfig({
+        hoox: { enabled: true, path: "workers/hoox" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, [
+        "clone",
+        "hoox",
+        "--org",
+        "custom-org",
+      ]);
+
+      expect(output).toContain("custom-org");
+    });
+  });
+
+  // -- Error handling --------------------------------------------------------
+
+  describe("error handling", () => {
+    it("handles missing wrangler.jsonc gracefully", async () => {
+      // Don't write a config file — ConfigService.load() will fail
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone"]);
+
+      expect(output).toContain("not found");
+    });
+
+    it("falls back to default org when git remote fails", async () => {
+      enqueueSpawn(errorSpawn("fatal: not a git repository", 128));
+
+      await writeTestConfig({
+        "d1-worker": { enabled: true, path: "workers/d1-worker" },
+      });
+
+      const program = buildProgram();
+      const output = await captureStdout(program, ["clone"]);
+
+      expect(output).toContain("jango-blockchained");
+    });
+  });
+});