@hogsend/cli 0.0.1 → 0.1.0

package/src/commands/setup.ts

@@ -0,0 +1,322 @@
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { confirm } from "@clack/prompts";
+import { color } from "../lib/output.js";
+import { bail } from "../lib/prompt.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend setup [--cwd <dir>] [--yes] [--json]
+
+Interactive local onboarding for a scaffolded Hogsend app. Mirrors the
+create-hogsend "next steps":
+
+  1. docker compose up -d              # Postgres + Redis + Hatchet-Lite
+  2. cp .env.example .env  (if missing)
+  3. generate a BETTER_AUTH_SECRET     (if still the placeholder)
+  4. pnpm db:migrate                   # engine track then client track
+
+Options:
+  --cwd <dir>    Project root to run in (defaults to the current directory).
+  --yes, -y      Skip confirmation prompts (assume yes). Implied by --json.
+  --json         Run non-interactively and emit a single JSON result document.
+  -h, --help     Show this help.
+
+Run ${color.cyan("hogsend doctor")} afterwards to verify the instance is healthy.`;
+
+/** Generate a 64-char hex secret (32 bytes) for BETTER_AUTH_SECRET. */
+function generateSecret(): string {
+  return randomBytes(32).toString("hex");
+}
+
+const SECRET_KEY = "BETTER_AUTH_SECRET";
+const PLACEHOLDER_PREFIX = "change-me";
+
+interface StepResult {
+  step: string;
+  status: "ok" | "skipped" | "failed";
+  detail: string;
+}
+
+/**
+ * Ensure a `.env` exists (copying `.env.example` when absent) and that
+ * BETTER_AUTH_SECRET holds a real generated value rather than the placeholder.
+ * Pure-ish: only touches the filesystem, returns a structured result.
+ */
+function ensureEnv(cwd: string): { copied: StepResult; secret: StepResult } {
+  const envPath = join(cwd, ".env");
+  const examplePath = join(cwd, ".env.example");
+
+  let copied: StepResult;
+  if (existsSync(envPath)) {
+    copied = {
+      step: "env",
+      status: "skipped",
+      detail: ".env already exists",
+    };
+  } else if (existsSync(examplePath)) {
+    copyFileSync(examplePath, envPath);
+    copied = {
+      step: "env",
+      status: "ok",
+      detail: "copied .env.example -> .env",
+    };
+  } else {
+    copied = {
+      step: "env",
+      status: "failed",
+      detail: "no .env and no .env.example to copy from",
+    };
+    return {
+      copied,
+      secret: {
+        step: "secret",
+        status: "skipped",
+        detail: "skipped — no .env",
+      },
+    };
+  }
+
+  // (Re)read the file we just ensured exists and refresh the secret if it is
+  // missing or still the scaffold placeholder. Never overwrite a real secret.
+  let raw: string;
+  try {
+    raw = readFileSync(envPath, "utf8");
+  } catch (err) {
+    return {
+      copied,
+      secret: {
+        step: "secret",
+        status: "failed",
+        detail: `could not read .env: ${err instanceof Error ? err.message : String(err)}`,
+      },
+    };
+  }
+
+  const lines = raw.split(/\r?\n/);
+  const idx = lines.findIndex((l) =>
+    l
+      .replace(/^export\s+/, "")
+      .trimStart()
+      .startsWith(`${SECRET_KEY}=`),
+  );
+  const existingLine = idx === -1 ? undefined : lines[idx];
+  const current =
+    existingLine === undefined
+      ? undefined
+      : existingLine.slice(existingLine.indexOf("=") + 1).trim();
+  const isPlaceholder =
+    current === undefined ||
+    current === "" ||
+    current.startsWith(PLACEHOLDER_PREFIX);
+
+  if (!isPlaceholder) {
+    return {
+      copied,
+      secret: {
+        step: "secret",
+        status: "skipped",
+        detail: `${SECRET_KEY} already set`,
+      },
+    };
+  }
+
+  const secret = generateSecret();
+  const newLine = `${SECRET_KEY}=${secret}`;
+  if (idx === -1) {
+    if (raw.length > 0 && !raw.endsWith("\n")) lines.push("");
+    lines.push(newLine);
+  } else {
+    lines[idx] = newLine;
+  }
+  writeFileSync(envPath, lines.join("\n"));
+
+  return {
+    copied,
+    secret: {
+      step: "secret",
+      status: "ok",
+      detail: `generated ${SECRET_KEY} (64-char hex)`,
+    },
+  };
+}
+
+/** Run a shell command, capturing exit status. */
+function runCmd(
+  cmd: string,
+  args: string[],
+  cwd: string,
+  json: boolean,
+): { status: number | null; ok: boolean } {
+  const result = spawnSync(cmd, args, {
+    cwd,
+    // In json mode stay silent (we report structured status); otherwise stream
+    // so the user sees docker / migration output inline.
+    stdio: json ? "ignore" : "inherit",
+  });
+  return { status: result.status, ok: result.status === 0 };
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const { values } = parseArgs({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      cwd: { type: "string" },
+      yes: { type: "boolean", short: "y", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const cwd = values.cwd ?? process.cwd();
+
+  if (!existsSync(join(cwd, "package.json"))) {
+    ctx.out.fail(
+      `no package.json in ${cwd} — run setup from a scaffolded Hogsend app (or pass --cwd).`,
+    );
+  }
+
+  const hasCompose =
+    existsSync(join(cwd, "docker-compose.yml")) ||
+    existsSync(join(cwd, "docker-compose.yaml")) ||
+    existsSync(join(cwd, "compose.yml")) ||
+    existsSync(join(cwd, "compose.yaml"));
+
+  // --json implies non-interactive; in TTY human mode we confirm first.
+  const skipConfirm = ctx.json || values.yes;
+
+  if (!ctx.json) {
+    ctx.out.intro(
+      `${color.bgMagenta(color.black(" hogsend "))} ${color.dim("local onboarding")}`,
+    );
+  }
+
+  if (ctx.out.interactive && !skipConfirm) {
+    const proceed = bail(
+      await confirm({
+        message: `Set up local infra in ${color.cyan(cwd)}? (docker compose up, .env, db:migrate)`,
+      }),
+    );
+    if (!proceed) {
+      ctx.out.outro(color.dim("Nothing changed."));
+      return;
+    }
+  }
+
+  const results: StepResult[] = [];
+
+  // 1. docker compose up -d
+  if (hasCompose) {
+    const docker = await ctx.out.step(
+      "Starting infra (docker compose up -d)",
+      async () => runCmd("docker", ["compose", "up", "-d"], cwd, ctx.json),
+    );
+    results.push({
+      step: "docker",
+      status: docker.ok ? "ok" : "failed",
+      detail: docker.ok
+        ? "Postgres + Redis + Hatchet-Lite up"
+        : `docker compose exited with code ${docker.status ?? "?"}`,
+    });
+  } else {
+    results.push({
+      step: "docker",
+      status: "skipped",
+      detail: "no docker-compose file found",
+    });
+  }
+
+  // 2 + 3. .env + secret (synchronous fs work, wrapped in a step for the spinner)
+  const env = await ctx.out.step("Preparing .env + auth secret", async () =>
+    ensureEnv(cwd),
+  );
+  results.push(env.copied, env.secret);
+
+  // 4. db:migrate (only attempt if docker didn't hard-fail; still try if skipped)
+  const dockerFailed = results.some(
+    (r) => r.step === "docker" && r.status === "failed",
+  );
+  if (dockerFailed) {
+    results.push({
+      step: "migrate",
+      status: "skipped",
+      detail:
+        "skipped — docker compose failed; bring infra up then run pnpm db:migrate",
+    });
+  } else {
+    const migrate = await ctx.out.step(
+      "Running migrations (pnpm db:migrate)",
+      async () => runCmd("pnpm", ["db:migrate"], cwd, ctx.json),
+    );
+    results.push({
+      step: "migrate",
+      status: migrate.ok ? "ok" : "failed",
+      detail: migrate.ok
+        ? "engine + client migrations applied"
+        : `pnpm db:migrate exited with code ${migrate.status ?? "?"}`,
+    });
+  }
+
+  const failed = results.filter((r) => r.status === "failed");
+  const ok = failed.length === 0;
+
+  if (ctx.json) {
+    ctx.out.json({
+      ok,
+      cwd,
+      steps: results,
+    });
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  // Human summary.
+  ctx.out.table(
+    results.map((r) => ({
+      step: r.step,
+      status:
+        r.status === "ok"
+          ? color.green("ok")
+          : r.status === "skipped"
+            ? color.dim("skipped")
+            : color.red("failed"),
+      detail: r.detail,
+    })),
+    ["step", "status", "detail"],
+  );
+
+  ctx.out.note(
+    [
+      `${color.cyan("pnpm dev")}          ${color.dim("# HTTP API on :3002")}`,
+      `${color.cyan("pnpm worker:dev")}   ${color.dim("# Hatchet worker, 2nd terminal")}`,
+      "",
+      `${color.dim("Verify with")} ${color.cyan("hogsend doctor")}${color.dim(".")}`,
+      `${color.dim("Grab HATCHET_CLIENT_TOKEN at")} ${color.cyan("http://localhost:8888")} ${color.dim("and set it in .env.")}`,
+    ].join("\n"),
+    "Next steps",
+  );
+
+  if (!ok) {
+    ctx.out.fail(
+      `${failed.length} step(s) failed — see the table above. Fix and re-run hogsend setup.`,
+    );
+  }
+
+  ctx.out.outro(
+    `${color.green("Done.")} ${color.dim("Local infra is up — go write a journey.")}`,
+  );
+}
+
+export const setupCommand: Command = {
+  name: "setup",
+  summary: "Local onboarding: docker compose up, gen secret, db:migrate",
+  usage,
+  run,
+};

package/src/commands/skills.ts

@@ -0,0 +1,268 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { multiselect } from "@clack/prompts";
+import { color } from "../lib/output.js";
+import { bail } from "../lib/prompt.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend skills <subcommand> [options]
+
+Manage the Claude Code skills bundled with @hogsend/cli. Bundled skills teach
+agents how to drive the hogsend CLI; \`add\` copies them into your project's
+./.claude/skills/<name>/ so Claude Code can discover them.
+
+Subcommands:
+  list                      List bundled skills + whether each is installed.
+  add [name] [--force]      Copy a bundled skill into ./.claude/skills/<name>/.
+                            Omit name for an interactive multiselect (human),
+                            or copy all bundled skills (--json / non-interactive).
+
+Options:
+  --force        Overwrite an already-installed skill.
+  --json         Emit machine-readable JSON only (implies non-interactive).
+  -h, --help     Show this help.
+
+Examples:
+  hogsend skills list
+  hogsend skills list --json
+  hogsend skills add
+  hogsend skills add hogsend-cli --force`;
+
+/**
+ * Resolve the directory holding the bundled skills shipped in the tarball.
+ * At runtime bin.js lives at <pkg>/dist/bin.js, so the skills dir (shipped via
+ * package.json files[]) is one level up at <pkg>/skills.
+ */
+function bundledSkillsDir(): string {
+  return fileURLToPath(new URL("../skills", import.meta.url));
+}
+
+/** Target directory for installed skills in the consumer project. */
+function installDir(cwd: string): string {
+  return join(cwd, ".claude", "skills");
+}
+
+interface BundledSkill {
+  name: string;
+  description: string;
+  installed: boolean;
+}
+
+/** A single line `key: value` reader for SKILL.md YAML frontmatter. */
+function readFrontmatterField(skillDir: string, field: string): string {
+  const skillFile = join(skillDir, "SKILL.md");
+  if (!existsSync(skillFile)) return "";
+  // Tiny frontmatter scan — avoids a YAML dep. Reads only the top block.
+  const raw = readFileSyncSafe(skillFile);
+  const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return "";
+  const block = fmMatch[1] ?? "";
+  for (const line of block.split("\n")) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (m && m[1] === field) {
+      return (m[2] ?? "").replace(/^["']|["']$/g, "").trim();
+    }
+  }
+  return "";
+}
+
+/** Read a file as utf8, returning "" on any error (never throws). */
+function readFileSyncSafe(path: string): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** Enumerate bundled skills (each is a subdir with a SKILL.md). */
+function listBundledSkills(cwd: string): BundledSkill[] {
+  const dir = bundledSkillsDir();
+  if (!existsSync(dir)) return [];
+  const target = installDir(cwd);
+  const entries = readdirSync(dir).filter((name) => {
+    const full = join(dir, name);
+    return statSync(full).isDirectory() && existsSync(join(full, "SKILL.md"));
+  });
+  return entries.sort().map((name) => ({
+    name,
+    description: readFrontmatterField(join(dir, name), "description"),
+    installed: existsSync(join(target, name)),
+  }));
+}
+
+function runList(ctx: CommandContext): void {
+  const skills = listBundledSkills(process.cwd());
+
+  if (ctx.json) {
+    ctx.out.json({
+      bundledSkillsDir: bundledSkillsDir(),
+      installDir: installDir(process.cwd()),
+      skills,
+    });
+    return;
+  }
+
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} skills`);
+  if (skills.length === 0) {
+    ctx.out.note(
+      "No bundled skills found in this package build.",
+      "skills list",
+    );
+    ctx.out.outro("Nothing to install.");
+    return;
+  }
+  ctx.out.table(
+    skills.map((s) => ({
+      name: s.name,
+      installed: s.installed ? color.green("yes") : color.dim("no"),
+      description:
+        s.description.length > 60
+          ? `${s.description.slice(0, 57)}...`
+          : s.description,
+    })),
+    ["name", "installed", "description"],
+  );
+  ctx.out.outro(
+    `Install with ${color.cyan("hogsend skills add <name>")} (or just ${color.cyan("hogsend skills add")}).`,
+  );
+}
+
+interface CopyResult {
+  name: string;
+  installed: boolean;
+  skipped: boolean;
+  path: string;
+}
+
+/** Copy one bundled skill into the project, honouring --force. */
+function copySkill(name: string, cwd: string, force: boolean): CopyResult {
+  const src = join(bundledSkillsDir(), name);
+  const dest = join(installDir(cwd), name);
+  const exists = existsSync(dest);
+  if (exists && !force) {
+    return { name, installed: false, skipped: true, path: dest };
+  }
+  mkdirSync(installDir(cwd), { recursive: true });
+  cpSync(src, dest, { recursive: true, force: true });
+  return { name, installed: true, skipped: false, path: dest };
+}
+
+async function runAdd(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      force: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const cwd = process.cwd();
+  const bundled = listBundledSkills(cwd);
+  if (bundled.length === 0) {
+    ctx.out.fail("no bundled skills found in this package build");
+  }
+
+  const requested = positionals[0];
+  const force = Boolean(values.force);
+
+  // Resolve which skills to install.
+  let names: string[];
+  if (requested) {
+    const match = bundled.find((s) => s.name === requested);
+    if (!match) {
+      ctx.out.fail(
+        `unknown skill "${requested}". Available: ${bundled.map((s) => s.name).join(", ")}`,
+      );
+    }
+    names = [requested];
+  } else if (ctx.out.interactive) {
+    const picked = bail(
+      await multiselect({
+        message: "Which skills do you want to install?",
+        options: bundled.map((s) => ({
+          value: s.name,
+          label: s.name,
+          hint: s.installed ? "installed" : undefined,
+        })),
+        required: true,
+      }),
+    ) as string[];
+    names = picked;
+  } else {
+    // Non-interactive (json or non-TTY) with no name => install all.
+    names = bundled.map((s) => s.name);
+  }
+
+  const results = names.map((name) => copySkill(name, cwd, force));
+
+  if (ctx.json) {
+    ctx.out.json({
+      installDir: installDir(cwd),
+      force,
+      results,
+    });
+    return;
+  }
+
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} skills add`);
+  for (const r of results) {
+    if (r.skipped) {
+      ctx.out.log(
+        `${color.yellow("skip")} ${r.name} ${color.dim("(already installed; use --force to overwrite)")}`,
+      );
+    } else {
+      ctx.out.log(`${color.green("✓")} ${r.name} ${color.dim(`-> ${r.path}`)}`);
+    }
+  }
+  const installedCount = results.filter((r) => r.installed).length;
+  const skippedCount = results.filter((r) => r.skipped).length;
+  ctx.out.outro(
+    `Installed ${installedCount} skill${installedCount === 1 ? "" : "s"}` +
+      (skippedCount > 0 ? `, skipped ${skippedCount}.` : "."),
+  );
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[0];
+
+  switch (sub) {
+    case "list":
+      runList(ctx);
+      return;
+    case "add":
+      await runAdd(ctx, ctx.argv.slice(1));
+      return;
+    case undefined:
+    case "-h":
+    case "--help":
+      ctx.out.log(usage);
+      return;
+    default:
+      ctx.out.fail(
+        `unknown skills subcommand "${sub}". Use: list | add. See hogsend skills --help.`,
+      );
+  }
+}
+
+export const skillsCommand: Command = {
+  name: "skills",
+  summary: "List + install bundled Claude Code skills into .claude/skills",
+  usage,
+  run,
+};

package/src/commands/stats.ts

@@ -0,0 +1,87 @@
+import { parseArgs } from "node:util";
+import { color } from "../lib/output.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend stats [--json]
+
+Show system-wide overview metrics from a running Hogsend instance.
+Wraps GET /v1/admin/metrics/overview.
+
+Fields:
+  totalContacts     Live (non-deleted) contacts.
+  activeJourneys    Journey states currently active or waiting.
+  emailsSent24h     Emails sent in the last 24 hours.
+  emailsSent7d      Emails sent in the last 7 days.
+  emailsSent30d     Emails sent in the last 30 days.
+  bounceRate30d     Bounced / sent over the last 30 days (0..1).
+  unsubscribeRate   Unsubscribed / total preferences (0..1).
+
+Options:
+  --url <baseUrl>      API base URL (default HOGSEND_API_URL or http://localhost:3002).
+  --admin-key <key>    Admin bearer key (default HOGSEND_ADMIN_KEY / ADMIN_API_KEY).
+  --json               Emit machine-readable JSON only.
+  -h, --help           Show this help.`;
+
+/** Shape returned by GET /v1/admin/metrics/overview. */
+interface OverviewMetrics {
+  totalContacts: number;
+  activeJourneys: number;
+  emailsSent24h: number;
+  emailsSent7d: number;
+  emailsSent30d: number;
+  bounceRate30d: number;
+  unsubscribeRate: number;
+}
+
+/** Render a 0..1 rate as a percentage with two decimals, e.g. 0.0123 -> "1.23%". */
+function pct(rate: number): string {
+  return `${(rate * 100).toFixed(2)}%`;
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const { values } = parseArgs({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const metrics = await ctx.out.step("Fetching overview metrics", () =>
+    ctx.http.get<OverviewMetrics>("/v1/admin/metrics/overview"),
+  );
+
+  if (ctx.json) {
+    ctx.out.json(metrics);
+    return;
+  }
+
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} stats`);
+
+  ctx.out.kv(
+    {
+      "Total contacts": metrics.totalContacts,
+      "Active journeys": metrics.activeJourneys,
+      "Emails sent (24h)": metrics.emailsSent24h,
+      "Emails sent (7d)": metrics.emailsSent7d,
+      "Emails sent (30d)": metrics.emailsSent30d,
+      "Bounce rate (30d)": pct(metrics.bounceRate30d),
+      "Unsubscribe rate": pct(metrics.unsubscribeRate),
+    },
+    "Overview",
+  );
+
+  ctx.out.outro(color.dim(ctx.http.cfg.baseUrl));
+}
+
+export const statsCommand: Command = {
+  name: "stats",
+  summary: "Show system-wide overview metrics",
+  usage,
+  run,
+};