@jango-blockchained/hoox-cli 0.3.4

package/src/commands/config/env-command.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "bun:test";
+import { EnvService } from "../../services/env/index.js";
+
+describe("env command", () => {
+  describe("EnvService integration", () => {
+    it("validate catches missing required vars", () => {
+      const result = EnvService.validate({});
+      expect(result.missing.length).toBeGreaterThan(0);
+      expect(result.missing).toContain("CLOUDFLARE_API_TOKEN");
+    });
+
+    it("validate passes with all required vars", () => {
+      const vars: Record<string, string> = {
+        CLOUDFLARE_API_TOKEN: "cfut_xxx",
+        CLOUDFLARE_ACCOUNT_ID: "abc123",
+        SUBDOMAIN_PREFIX: "myapp",
+        D1_INTERNAL_KEY: "d1-key",
+        TRADE_INTERNAL_KEY: "trade-key",
+        AGENT_INTERNAL_KEY: "agent-key",
+        WEBHOOK_API_KEY_BINDING: "webhook-key",
+        INTERNAL_KEY_BINDING: "inter-key",
+        API_SERVICE_KEY: "api-key",
+        DASHBOARD_USER: "admin",
+        DASHBOARD_PASS: "pass123",
+        SESSION_SECRET: "a".repeat(32),
+      };
+      const result = EnvService.validate(vars);
+      expect(result.missing.length).toBe(0);
+    });
+
+    it("generateEnvLocal produces valid output", () => {
+      const content = EnvService.generateEnvLocal();
+      expect(content).toContain("CLOUDFLARE_API_TOKEN");
+      expect(content).toContain("# NEVER commit this file");
+    });
+
+    it("show redacts secrets", () => {
+      const output = EnvService.show({ CLOUDFLARE_API_TOKEN: "s3kr3t" });
+      expect(output).toContain("********");
+      expect(output).not.toContain("s3kr3t");
+    });
+  });
+});

package/src/commands/config/env-command.ts

@@ -0,0 +1,314 @@
+/**
+ * `hoox config env` subcommand group — environment variable management.
+ *
+ * Subcommands:
+ *   init              — Interactive wizard to generate .env.local and .dev.vars
+ *   show              — Display current .env.local (secrets redacted)
+ *   validate          — Check required vars are set
+ *   generate-dev-vars — Create/update per-worker .dev.vars from .env.local
+ */
+
+import { Command } from "commander";
+import * as p from "@clack/prompts";
+
+import { EnvService } from "../../services/env/index.js";
+import { CLIError, ExitCode } from "../../utils/errors.js";
+import {
+  formatSuccess,
+  formatError,
+  formatJson,
+} from "../../utils/formatters.js";
+import type { FormatOptions } from "../../utils/formatters.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Get FormatOptions from the command opts using optsWithGlobals() so that
+ * globally defined flags (--json, --quiet) are resolved correctly even when
+ * called from deeply nested subcommands.
+ */
+function formatOpts(cmd: Command): FormatOptions {
+  const opts = cmd.optsWithGlobals<{ json?: boolean; quiet?: boolean }>();
+  return { json: Boolean(opts.json), quiet: Boolean(opts.quiet) };
+}
+
+// ---------------------------------------------------------------------------
+// env init — interactive wizard
+// ---------------------------------------------------------------------------
+
+async function handleInit(opts: FormatOptions): Promise<void> {
+  p.intro("Environment Setup");
+
+  // Warn if .env.local already exists
+  const existingEnv = Bun.file(".env.local");
+  if (await existingEnv.exists()) {
+    const overwrite = await p.confirm({
+      message: ".env.local already exists. Overwrite?",
+      initialValue: false,
+    });
+    if (p.isCancel(overwrite)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    if (!overwrite) {
+      p.outro("Setup cancelled. Existing .env.local preserved.");
+      return;
+    }
+  }
+
+  const collected: Record<string, string> = {};
+  const sections = EnvService.getSections();
+
+  for (const section of sections) {
+    const sectionDefs = EnvService.getDefinitions().filter(
+      (d) => d.section === section,
+    );
+    if (sectionDefs.length === 0) continue;
+
+    p.log.step(`Configuring ${section}...`);
+
+    for (const def of sectionDefs) {
+      let value: string | symbol;
+      if (def.secret) {
+        value = await p.password({
+          message: `${def.name}:${def.hint ? ` (${def.hint})` : ""}`,
+          validate: def.required
+            ? (v: string | undefined) => (v ? undefined : "Required")
+            : undefined,
+        });
+      } else {
+        value = await p.text({
+          message: `${def.name}:${def.hint ? ` (${def.hint})` : ""}`,
+          defaultValue: def.default ?? "",
+          validate: def.required
+            ? (v: string | undefined) => (v ? undefined : "Required")
+            : undefined,
+        });
+      }
+      if (p.isCancel(value)) {
+        p.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+      collected[def.name] = typeof value === "string" ? value : "";
+    }
+  }
+
+  p.log.step("Writing .env.local...");
+  const envContent = EnvService.generateEnvLocal(collected);
+  await Bun.write(".env.local", envContent);
+  if (!opts.quiet) formatSuccess(".env.local written", opts);
+
+  p.log.step("Writing .dev.vars files...");
+  const devVars = EnvService.getWorkerDevVars(collected);
+  for (const [workerPath, vars] of Object.entries(devVars)) {
+    const content = [
+      `# .dev.vars - local secrets for ${workerPath}`,
+      "# Generated by `hoox config env init`. NEVER commit this file.",
+      "",
+      ...Object.entries(vars).map(([k, v]) => `${k}=${v}`),
+      "",
+    ].join("\n");
+    await Bun.write(`${workerPath}/.dev.vars`, content);
+    if (!opts.quiet)
+      formatSuccess(`Created ${workerPath}/.dev.vars`, opts);
+  }
+
+  p.outro("Environment setup complete!");
+}
+
+// ---------------------------------------------------------------------------
+// env show
+// ---------------------------------------------------------------------------
+
+async function handleShow(opts: FormatOptions): Promise<void> {
+  const file = Bun.file(".env.local");
+  if (!(await file.exists())) {
+    throw new CLIError(
+      ".env.local not found. Run `hoox config env init`.",
+      ExitCode.INVALID_USAGE,
+    );
+  }
+
+  const vars = await EnvService.loadDotEnvAsync(".env.local");
+
+  if (opts.json) {
+    formatJson(vars, opts);
+  } else {
+    process.stdout.write(EnvService.show(vars));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// env validate
+// ---------------------------------------------------------------------------
+
+async function handleValidate(opts: FormatOptions): Promise<void> {
+  let vars: Record<string, string> = {};
+  const file = Bun.file(".env.local");
+  if (await file.exists()) {
+    vars = await EnvService.loadDotEnvAsync(".env.local");
+  }
+
+  const result = EnvService.validate(vars);
+
+  if (opts.json) {
+    formatJson(result, opts);
+  } else if (!opts.quiet) {
+    if (!(await file.exists())) {
+      process.stdout.write(".env.local not found. Run `hoox config env init` first.\n\n");
+    }
+    if (result.missing.length > 0) {
+      process.stdout.write("Missing required variables:\n");
+      for (const v of result.missing) {
+        process.stdout.write(`  ${v}\n`);
+      }
+    }
+    if (result.warnings.length > 0) {
+      process.stdout.write("Warnings:\n");
+      for (const w of result.warnings) {
+        process.stdout.write(`  ${w}\n`);
+      }
+    }
+    if (result.missing.length === 0 && result.warnings.length === 0) {
+      formatSuccess("All required environment variables are set", opts);
+    }
+  }
+
+  if (result.missing.length > 0) {
+    process.exitCode = ExitCode.ERROR;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// env generate-dev-vars
+// ---------------------------------------------------------------------------
+
+async function handleGenerateDevVars(opts: FormatOptions): Promise<void> {
+  const file = Bun.file(".env.local");
+  if (!(await file.exists())) {
+    throw new CLIError(
+      ".env.local not found. Run `hoox config env init`.",
+      ExitCode.INVALID_USAGE,
+    );
+  }
+
+  const vars = await EnvService.loadDotEnvAsync(".env.local");
+  const devVars = EnvService.getWorkerDevVars(vars);
+
+  let count = 0;
+  for (const [workerPath, workerVars] of Object.entries(devVars)) {
+    const content = [
+      `# .dev.vars - local secrets for ${workerPath}`,
+      "# Generated by `hoox config env generate-dev-vars`. NEVER commit this file.",
+      "",
+      ...Object.entries(workerVars).map(([k, v]) => `${k}=${v}`),
+      "",
+    ].join("\n");
+    await Bun.write(`${workerPath}/.dev.vars`, content);
+    count++;
+  }
+
+  formatSuccess(`Generated .dev.vars for ${count} worker(s)`, opts);
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register the `hoox config env` subcommand group.
+ */
+export function registerEnvCommand(parentCmd: Command): void {
+  const envCmd = parentCmd
+    .command("env")
+    .summary("Manage environment variables")
+    .description(
+      `Manage environment variables for the Hoox trading system.
+
+SUBCOMMANDS:
+  init               Interactive wizard to generate .env.local and .dev.vars
+  show               Display current .env.local (secrets redacted)
+  validate           Check required environment variables
+  generate-dev-vars  Create per-worker .dev.vars from .env.local
+
+EXAMPLES:
+  hoox config env init
+  hoox config env show
+  hoox config env validate
+  hoox config env generate-dev-vars`,
+    );
+
+  envCmd
+    .command("init")
+    .description("Interactive wizard to generate .env.local and .dev.vars")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        await handleInit(opts);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  envCmd
+    .command("show")
+    .description("Display current .env.local (secrets redacted)")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        await handleShow(opts);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  envCmd
+    .command("validate")
+    .description("Check required environment variables")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        await handleValidate(opts);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  envCmd
+    .command("generate-dev-vars")
+    .description("Create per-worker .dev.vars from .env.local")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        await handleGenerateDevVars(opts);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+}

package/src/commands/config/index.ts

@@ -0,0 +1,3 @@
+export { registerConfigCommand } from "./config-command.js";
+export { registerEnvCommand } from "./env-command.js";
+export { registerKvCommand } from "./kv-command.js";

package/src/commands/config/kv-command.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "bun:test";
+import { KvSyncService } from "../../services/kv/index.js";
+
+describe("kv command", () => {
+  describe("manifest", () => {
+    it("returns known KV keys from manifest", () => {
+      const keys = KvSyncService.getManifestKeys();
+      expect(keys.length).toBe(16);
+      expect(keys.some((k) => k.key === "trade:kill_switch")).toBe(true);
+      expect(keys.some((k) => k.key === "agent:openai_key")).toBe(true);
+      expect(keys.some((k) => k.key === "email:use_imap")).toBe(true);
+    });
+  });
+});

package/src/commands/config/kv-command.ts

@@ -0,0 +1,329 @@
+/**
+ * `hoox config kv` subcommand group — KV namespace key management.
+ *
+ * Subcommands:
+ *   list                           — List all keys
+ *   get <key>                      — Get a key's value
+ *   set <key> <value>              — Set a key's value
+ *   delete <key>                   — Delete a key
+ *   apply-manifest                 — Apply manifest defaults
+ *   manifest                       — Show expected manifest keys
+ */
+
+import { Command } from "commander";
+import { KvSyncService } from "../../services/kv/index.js";
+import {
+  formatSuccess,
+  formatError,
+  formatTable,
+  formatJson,
+} from "../../utils/formatters.js";
+import { CLIError, ExitCode } from "../../utils/errors.js";
+import { theme } from "../../utils/theme.js";
+import type { FormatOptions } from "../../utils/formatters.js";
+
+function formatOpts(cmd: Command): FormatOptions {
+  const opts = cmd.optsWithGlobals<{ json?: boolean; quiet?: boolean }>();
+  return { json: Boolean(opts.json), quiet: Boolean(opts.quiet) };
+}
+
+async function resolveNs(
+  cmd: Command,
+): Promise<string> {
+  const svc = new KvSyncService();
+  const opts = cmd.optsWithGlobals<{ namespaceId?: string }>();
+  return await svc.resolveNamespaceId(opts.namespaceId);
+}
+
+// ---------------------------------------------------------------------------
+// kv list
+// ---------------------------------------------------------------------------
+
+async function handleList(
+  opts: FormatOptions,
+  nsId: string,
+): Promise<void> {
+  const svc = new KvSyncService();
+  const keys = await svc.list(nsId);
+
+  if (opts.json) {
+    formatJson(keys, opts);
+  } else if (!opts.quiet) {
+    if (keys.length === 0) {
+      process.stdout.write("No keys found in KV namespace.\n");
+      return;
+    }
+    const rows = keys.map((k) => ({ Key: k.name }));
+    formatTable(rows, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// kv get
+// ---------------------------------------------------------------------------
+
+async function handleGet(
+  opts: FormatOptions,
+  nsId: string,
+  key: string,
+): Promise<void> {
+  const svc = new KvSyncService();
+  const value = await svc.get(nsId, key);
+
+  if (value === null) {
+    throw new CLIError(
+      `Key "${key}" not found in KV namespace`,
+      ExitCode.ERROR,
+    );
+  }
+
+  if (opts.json) {
+    formatJson({ key, value }, opts);
+  } else {
+    process.stdout.write(`${value}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// kv set
+// ---------------------------------------------------------------------------
+
+async function handleSet(
+  opts: FormatOptions,
+  nsId: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  const svc = new KvSyncService();
+  await svc.set(nsId, key, value);
+  formatSuccess(`Set "${key}" in KV namespace`, opts);
+}
+
+// ---------------------------------------------------------------------------
+// kv delete
+// ---------------------------------------------------------------------------
+
+async function handleDelete(
+  opts: FormatOptions,
+  nsId: string,
+  key: string,
+): Promise<void> {
+  const svc = new KvSyncService();
+  await svc.delete(nsId, key);
+  formatSuccess(`Deleted "${key}" from KV namespace`, opts);
+}
+
+// ---------------------------------------------------------------------------
+// kv apply-manifest
+// ---------------------------------------------------------------------------
+
+async function handleApplyManifest(
+  opts: FormatOptions,
+  nsId: string,
+): Promise<void> {
+  const svc = new KvSyncService();
+  const manifest = KvSyncService.getManifest();
+  let setCount = 0;
+  const errors: string[] = [];
+
+  for (const keyDef of manifest.keys) {
+    if (keyDef.default !== undefined && keyDef.default !== "") {
+      try {
+        await svc.set(nsId, keyDef.key, keyDef.default);
+        setCount++;
+      } catch (err) {
+        errors.push(
+          `${keyDef.key}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+
+  formatSuccess(
+    `Applied ${setCount}/${manifest.keys.length} manifest keys (${errors.length} errors)`,
+    opts,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// kv manifest
+// ---------------------------------------------------------------------------
+
+async function handleManifest(opts: FormatOptions): Promise<void> {
+  const manifest = KvSyncService.getManifest();
+
+  if (opts.json) {
+    formatJson(manifest, opts);
+  } else if (!opts.quiet) {
+    process.stdout.write(
+      `${theme.heading(`KV Manifest: ${manifest.namespace}`)}\n\n`,
+    );
+    const rows = manifest.keys.map((k) => ({
+      Key: k.key,
+      Type: k.type,
+      Default: k.default || "-",
+      Secret: k.secret ? "yes" : "no",
+      Description: k.description,
+    }));
+    formatTable(rows, opts);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerKvCommand(parentCmd: Command): void {
+  const kvCmd = parentCmd
+    .command("kv")
+    .summary("Manage KV namespace keys")
+    .description(
+      `Manage Cloudflare KV namespace keys and apply the key manifest.
+
+SUBCOMMANDS:
+  list              List all keys in the KV namespace
+  get <key>         Get a key's value
+  set <key> <value> Set a key's value
+  delete <key>      Delete a key
+  apply-manifest    Apply manifest key defaults to KV
+  manifest          Show expected KV keys from manifest
+
+OPTIONS:
+  --namespace-id <id>  KV namespace ID (auto-detected from wrangler if omitted)
+
+EXAMPLES:
+  hoox config kv list
+  hoox config kv set trade:kill_switch true
+  hoox config kv get trade:kill_switch
+  hoox config kv delete trade:kill_switch
+  hoox config kv apply-manifest
+  hoox config kv manifest`,
+    )
+    .option(
+      "--namespace-id <id>",
+      "KV namespace ID (auto-detected if omitted)",
+    );
+
+  // -- list
+  kvCmd
+    .command("list")
+    .description("List all keys in the KV namespace")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        const nsId = await resolveNs(cmd);
+        await handleList(opts, nsId);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  // -- get
+  kvCmd
+    .command("get <key>")
+    .description("Get a key's value from the KV namespace")
+    .action(async (key: string, _, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        const nsId = await resolveNs(cmd);
+        await handleGet(opts, nsId, key);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  // -- set
+  kvCmd
+    .command("set <key> <value>")
+    .description("Set a key's value in the KV namespace")
+    .action(
+      async (key: string, value: string, _, cmd: Command) => {
+        const opts = formatOpts(cmd);
+        try {
+          const nsId = await resolveNs(cmd);
+          await handleSet(opts, nsId, key, value);
+        } catch (err) {
+          formatError(
+            err instanceof Error ? err : String(err),
+            opts,
+          );
+          process.exit(
+            err instanceof CLIError ? err.code : ExitCode.ERROR,
+          );
+        }
+      },
+    );
+
+  // -- delete
+  kvCmd
+    .command("delete <key>")
+    .description("Delete a key from the KV namespace")
+    .action(async (key: string, _, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        const nsId = await resolveNs(cmd);
+        await handleDelete(opts, nsId, key);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  // -- apply-manifest
+  kvCmd
+    .command("apply-manifest")
+    .description(
+      "Apply manifest key defaults to the KV namespace",
+    )
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        const nsId = await resolveNs(cmd);
+        await handleApplyManifest(opts, nsId);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+
+  // -- manifest
+  kvCmd
+    .command("manifest")
+    .description("Show expected KV keys from manifest")
+    .action(async (_, cmd: Command) => {
+      const opts = formatOpts(cmd);
+      try {
+        await handleManifest(opts);
+      } catch (err) {
+        formatError(
+          err instanceof Error ? err : String(err),
+          opts,
+        );
+        process.exit(
+          err instanceof CLIError ? err.code : ExitCode.ERROR,
+        );
+      }
+    });
+}