@hogsend/cli 0.0.1 → 0.1.0

package/skills/hogsend-cli/references/query-stats.md

@@ -0,0 +1,66 @@
+# Query metrics, contacts, and events
+
+Read-only analysis over a running Hogsend instance. Always pass `--json` when
+parsing.
+
+## Overview metrics
+
+```bash
+hogsend stats --json
+```
+
+Wraps `GET /v1/admin/metrics/overview`. Returns (shape may vary slightly by
+version):
+
+```json
+{
+  "totalContacts": 1234,
+  "activeJourneys": 5,
+  "emailsSent24h": 88,
+  "emailsSent7d": 540,
+  "emailsSent30d": 2100,
+  "bounceRate30d": 0.012,
+  "unsubscribeRate": 0.004
+}
+```
+
+Use this for a one-shot snapshot. `bounceRate30d` / `unsubscribeRate` are
+fractions (multiply by 100 for a percentage). A rising bounce rate is the first
+signal of a deliverability problem.
+
+## Contacts
+
+```bash
+# List with search + pagination
+hogsend contacts list --search "@acme.com" --limit 50 --offset 0 --json
+
+# A single contact by internal id OR externalId
+hogsend contacts get user_123 --json
+
+# Merged activity timeline (events + emails + journeys) for one contact
+hogsend contacts timeline user_123 --json
+```
+
+Wraps `GET /v1/admin/contacts`, `GET /v1/admin/contacts/{id}`, and
+`GET /v1/admin/contacts/{id}/timeline`. `get` includes the contact record plus
+email preferences (subscribed / unsubscribed). The timeline is the fastest way
+to understand a single user's lifecycle history.
+
+## Raw event stream
+
+```bash
+hogsend events user_123 --json
+hogsend events user_123 --event "checkout.completed" --from 2026-01-01T00:00:00Z --to 2026-02-01T00:00:00Z --limit 100 --json
+```
+
+Wraps `GET /v1/admin/events?userId=<userId>`. Filter by `--event`, time window
+(`--from`/`--to`, ISO 8601), and paginate with `--limit`/`--offset`. Use this
+when the timeline isn't granular enough and you need the exact event payloads
+(e.g. to see which properties were present when a journey trigger fired).
+
+## Analysis pattern
+
+1. `hogsend stats --json` for the macro picture.
+2. `hogsend contacts list --search ... --json` to find the cohort.
+3. `hogsend contacts timeline <id> --json` to understand individual journeys.
+4. `hogsend events <id> --event <name> --json` to inspect exact payloads.

package/skills/hogsend-cli/references/setup-local.md

@@ -0,0 +1,52 @@
+# Set up a local Hogsend instance
+
+`hogsend setup` is interactive LOCAL onboarding — it mirrors the "next steps"
+that `create-hogsend` prints after scaffolding. It is NOT a Railway / cloud
+deploy flow.
+
+## Run it
+
+```bash
+hogsend setup
+```
+
+What it does (interactively, with clack prompts + spinners):
+
+1. `docker compose up -d` — starts TimescaleDB (Postgres), Redis, and
+   Hatchet-Lite locally.
+2. Generates a `BETTER_AUTH_SECRET`.
+3. Copies `.env.example` to `.env` if `.env` doesn't already exist (it won't
+   clobber an existing `.env`).
+4. Runs `db:migrate` to apply the database schema.
+
+Run it from your Hogsend project root (the directory with `docker-compose.yml`
+and `.env.example`).
+
+## Verify
+
+After setup, confirm the instance is healthy and the schema is in sync:
+
+```bash
+hogsend doctor --json
+```
+
+Expect a `ok` verdict with `database` and `redis` components healthy and
+`schema.inSync = true`. If you see `migration_pending`, re-run the migration
+step; if `unreachable`, the API isn't running yet — start it with `pnpm dev`
+(default port 3002), then re-run doctor.
+
+## Typical first session
+
+```bash
+hogsend setup            # docker up, secret, .env, migrate
+pnpm dev                 # start the API on :3002 (separate terminal)
+hogsend doctor --json    # confirm ok
+hogsend stats --json     # sanity-check metrics endpoint
+```
+
+## Notes
+
+- `setup` is interactive by design; in a non-interactive / agent context,
+  prefer running the underlying steps explicitly and then `hogsend doctor`.
+- The admin key for local reads comes from your `.env` (`ADMIN_API_KEY` or
+  `HOGSEND_ADMIN_KEY`); `doctor` itself needs no key.

package/src/bin.ts

@@ -1,140 +1,102 @@
 #!/usr/bin/env node
-import { existsSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, sep } from "node:path";
-import { parseArgs } from "node:util";
-import { EjectError, eject } from "./eject.js";
+import { commands } from "./commands/index.js";
+import type { Command } from "./commands/types.js";
+import { parseGlobalFlags, resolveConfig } from "./lib/config.js";
+import { createAdminClient } from "./lib/http.js";
+import { color, createOutput } from "./lib/output.js";
 
-const USAGE = `hogsend — Hogsend project CLI
-
-Usage:
-  hogsend eject <package> [--force] [--cwd <dir>]
+function version(): string {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require("../package.json") as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 
-Commands:
-  eject <package>   Copy a @hogsend/* package's source into vendor/<name> and
-                    rewrite the consumer dependency to file:./vendor/<name>.
-                    Every other dependency keeps upgrading via pnpm up.
+function rootUsage(): string {
+  const longest = commands.reduce((n, c) => Math.max(n, c.name.length), 0);
+  const list = commands
+    .map((c) => `  ${color.cyan(c.name.padEnd(longest))}  ${c.summary}`)
+    .join("\n");
+  return `${color.bold("hogsend")} — the agent-native Hogsend CLI
 
-Options:
-  --force           Overwrite an existing vendor/<name>.
-  --cwd <dir>       Consumer repo root (defaults to the current directory).
-  -h, --help        Show this help.
+${color.dim("Usage:")} hogsend <command> [options]
 
-After ejecting, run: pnpm install`;
+${color.dim("Commands:")}
+${list}
 
-const RED = "\x1b[31m";
-const RESET = "\x1b[0m";
+${color.dim("Global options:")}
+  --url <baseUrl>     Target instance (default HOGSEND_API_URL or http://localhost:3002)
+  --admin-key <key>   Admin bearer token (default HOGSEND_ADMIN_KEY / ADMIN_API_KEY)
+  --json              Emit machine-readable JSON only (for agents)
+  -h, --help          Show help (use after a command for command help)
+  -v, --version       Show version
 
-function fail(message: string): never {
-  process.stderr.write(`${RED}error${RESET} ${message}\n`);
-  process.exit(1);
+Run ${color.cyan("hogsend <command> --help")} for command-specific options.`;
 }
 
-/**
- * Resolves the on-disk source directory for an installed package from the
- * consumer root. Works for pnpm's `.pnpm` layout and workspace symlinks.
- *
- * Strategy 1 (primary): probe `<consumerRoot>/node_modules/<pkg>/package.json`
- * directly, following the symlink to its real location. This is the common
- * layout and — unlike `require.resolve("<pkg>/package.json")` — is NOT blocked
- * by the package's `exports` map (most packages don't expose `./package.json`).
- *
- * Strategy 2 (fallback): resolve the package's main entry via `createRequire`
- * and walk up to the nearest directory that contains a package.json whose
- * `name` matches.
- */
-function resolveSourceDir(pkg: string, consumerRoot: string): string {
-  const direct = join(consumerRoot, "node_modules", pkg, "package.json");
-  if (existsSync(direct)) {
-    // realpath follows pnpm/workspace symlinks to the actual source dir.
-    return dirname(realpathSync(direct));
-  }
-
-  const require = createRequire(`${consumerRoot}${sep}`);
-  try {
-    // Resolving the entry point works even when `./package.json` is not an
-    // exported subpath; we then walk up to the package root.
-    const entry = require.resolve(pkg);
-    let dir = dirname(entry);
-    while (dir !== dirname(dir)) {
-      const candidate = join(dir, "package.json");
-      if (existsSync(candidate)) {
-        return dir;
-      }
-      dir = dirname(dir);
-    }
-  } catch {
-    // fall through to the failure below
-  }
-
-  fail(
-    `cannot resolve ${pkg} from ${consumerRoot}. Is it installed? Run pnpm install first.`,
-  );
+function findCommand(name: string): Command | undefined {
+  return commands.find((c) => c.name === name);
 }
 
-async function runEject(args: string[]): Promise<void> {
-  const { values, positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-    options: {
-      force: { type: "boolean", default: false },
-      cwd: { type: "string" },
-      help: { type: "boolean", short: "h", default: false },
-    },
-  });
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const [token, ...afterToken] = argv;
 
-  if (values.help) {
-    process.stdout.write(`${USAGE}\n`);
+  // Version is a top-level concern (before flag parsing).
+  if (token === "-v" || token === "--version") {
+    process.stdout.write(`${version()}\n`);
     return;
   }
 
-  const pkg = positionals[0];
-  if (!pkg) {
-    fail("eject requires a package name, e.g. hogsend eject @hogsend/engine");
+  // No command, or a root-level help request.
+  if (!token || token === "-h" || token === "--help") {
+    process.stdout.write(`${rootUsage()}\n`);
+    return;
   }
 
-  const consumerRoot = values.cwd ?? process.cwd();
-  const sourceDir = resolveSourceDir(pkg, consumerRoot);
-
-  try {
-    const result = await eject({
-      pkg,
-      consumerRoot,
-      sourceDir,
-      force: values.force,
-    });
-    process.stdout.write(
-      `Ejected ${result.pkg}\n` +
-        `  copied ${result.copiedFiles} files -> ${result.vendorPath}\n` +
-        `  dependency ${result.depSpecBefore} -> ${result.depSpecAfter}\n` +
-        `\nNow run: ${result.followUp}\n`,
+  const command = findCommand(token);
+  if (!command) {
+    // Unknown command: report on stderr and show usage. Not json-gated since
+    // there's no resolved Output yet.
+    process.stderr.write(
+      `${color.red("error")} unknown command "${token}"\n\n${rootUsage()}\n`,
     );
-  } catch (error) {
-    if (error instanceof EjectError) {
-      fail(error.message);
-    }
-    throw error;
+    process.exit(1);
   }
-}
 
-async function main(): Promise<void> {
-  const [command, ...rest] = process.argv.slice(2);
+  // Parse global flags off the post-token argv; the rest is the command's argv.
+  const flags = parseGlobalFlags(afterToken);
+  const out = createOutput({ json: flags.json });
 
-  if (!command || command === "--help" || command === "-h") {
-    process.stdout.write(`${USAGE}\n`);
+  // `hogsend <cmd> --help` short-circuits to the command's usage block.
+  if (flags.help) {
+    out.log(command.usage);
     return;
   }
 
-  switch (command) {
-    case "eject":
-      await runEject(rest);
-      break;
-    default:
-      fail(`unknown command "${command}"\n\n${USAGE}`);
-  }
+  const cfg = resolveConfig(flags);
+  const http = createAdminClient(cfg);
+
+  await command.run({
+    argv: flags.rest,
+    cfg,
+    http,
+    out,
+    json: flags.json,
+  });
 }
 
-main().catch((error) => {
-  process.stderr.write(`${RED}error${RESET} ${String(error)}\n`);
+main().catch((error: unknown) => {
+  const msg = error instanceof Error ? error.message : String(error);
+  // Best-effort json detection for top-level failures (Output may not exist).
+  if (process.argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({ error: msg })}\n`);
+  } else {
+    process.stderr.write(`${color.red("error")} ${msg}\n`);
+  }
   process.exit(1);
 });

package/src/commands/contacts.ts

@@ -0,0 +1,316 @@
+import { parseArgs } from "node:util";
+import { isHttpError } from "../lib/http.js";
+import { color } from "../lib/output.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend contacts <subcommand> [options]
+
+Inspect contacts via the running app's admin API (/v1/admin/contacts).
+
+Subcommands:
+  list                  List contacts (newest activity first).
+  get <id>              Get one contact (by id or externalId) + preferences.
+  timeline <id>        Merged event/email/journey activity for a contact.
+
+list options:
+  --search <q>          Filter by email/externalId substring.
+  --limit <n>           Page size (1-100, default 50).
+  --offset <n>          Page offset (default 0).
+
+timeline options:
+  --type <t>            Restrict to one of: event | journey | email.
+  --limit <n>           Page size (1-100, default 50).
+  --offset <n>          Page offset (default 0).
+
+Global options (handled by the router): --url, --admin-key, --json, -h/--help.
+
+Examples:
+  hogsend contacts list --search acme@ --json
+  hogsend contacts get user_123
+  hogsend contacts timeline user_123 --type email --json`;
+
+type ContactRecord = {
+  id: string;
+  externalId: string;
+  email: string | null;
+  properties: Record<string, unknown>;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type Preferences = {
+  id: string;
+  userId: string;
+  email: string;
+  unsubscribedAll: boolean;
+  suppressed: boolean;
+  bounceCount: number;
+  categories: Record<string, boolean>;
+} | null;
+
+type ListResponse = {
+  contacts: ContactRecord[];
+  total: number;
+  limit: number;
+  offset: number;
+};
+
+type GetResponse = {
+  contact: ContactRecord;
+  preferences: Preferences;
+};
+
+type TimelineEntry = {
+  type: "event" | "journey" | "email";
+  timestamp: string;
+  data: Record<string, unknown>;
+};
+
+type TimelineResponse = {
+  timeline: TimelineEntry[];
+  total: number;
+  limit: number;
+  offset: number;
+};
+
+const badge = `${color.bgMagenta(color.black(" hogsend "))} contacts`;
+
+/** Run an HTTP call, mapping HttpError into a clean ctx.out.fail message. */
+async function fetchOrFail<T>(
+  ctx: CommandContext,
+  label: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await ctx.out.step(label, fn);
+  } catch (err) {
+    if (isHttpError(err)) {
+      if (err.status === 404) {
+        ctx.out.fail(err.message || "contact not found");
+      }
+      ctx.out.fail(err.message);
+    }
+    throw err;
+  }
+}
+
+async function runList(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      search: { type: "string" },
+      limit: { type: "string" },
+      offset: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const query = {
+    search: values.search,
+    limit: values.limit,
+    offset: values.offset,
+  };
+
+  if (!ctx.json) ctx.out.intro(`${badge} list`);
+
+  const res = await fetchOrFail<ListResponse>(ctx, "Fetching contacts", () =>
+    ctx.http.get<ListResponse>("/v1/admin/contacts", query),
+  );
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  ctx.out.table(
+    res.contacts.map((cnt) => ({
+      id: cnt.id,
+      externalId: cnt.externalId,
+      email: cnt.email ?? color.dim("(none)"),
+      lastSeenAt: cnt.lastSeenAt,
+    })),
+    ["id", "externalId", "email", "lastSeenAt"],
+  );
+  ctx.out.outro(
+    `${res.contacts.length} of ${res.total} contact(s) — offset ${res.offset}, limit ${res.limit}`,
+  );
+}
+
+async function runGet(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  // positionals[0] is the "get" subcommand token; the id follows it.
+  const id = positionals[1];
+  if (!id) {
+    ctx.out.fail(
+      "contacts get requires an id, e.g. hogsend contacts get user_123",
+    );
+  }
+
+  if (!ctx.json) ctx.out.intro(`${badge} get`);
+
+  const res = await fetchOrFail<GetResponse>(ctx, "Fetching contact", () =>
+    ctx.http.get<GetResponse>(`/v1/admin/contacts/${encodeURIComponent(id)}`),
+  );
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  const { contact, preferences } = res;
+  ctx.out.kv(
+    {
+      id: contact.id,
+      externalId: contact.externalId,
+      email: contact.email ?? color.dim("(none)"),
+      firstSeenAt: contact.firstSeenAt,
+      lastSeenAt: contact.lastSeenAt,
+      properties: contact.properties,
+    },
+    "Contact",
+  );
+
+  if (preferences) {
+    ctx.out.kv(
+      {
+        unsubscribedAll: preferences.unsubscribedAll,
+        suppressed: preferences.suppressed,
+        bounceCount: preferences.bounceCount,
+        categories: preferences.categories,
+      },
+      "Preferences",
+    );
+  } else {
+    ctx.out.log(color.dim("No email preferences on record."));
+  }
+
+  ctx.out.outro(`Contact ${color.cyan(contact.externalId)}`);
+}
+
+async function runTimeline(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      type: { type: "string" },
+      limit: { type: "string" },
+      offset: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  // positionals[0] is the "timeline" subcommand token; the id follows it.
+  const id = positionals[1];
+  if (!id) {
+    ctx.out.fail(
+      "contacts timeline requires an id, e.g. hogsend contacts timeline user_123",
+    );
+  }
+
+  if (values.type && !["event", "journey", "email"].includes(values.type)) {
+    ctx.out.fail("--type must be one of: event, journey, email");
+  }
+
+  const query = {
+    type: values.type,
+    limit: values.limit,
+    offset: values.offset,
+  };
+
+  if (!ctx.json) ctx.out.intro(`${badge} timeline`);
+
+  const res = await fetchOrFail<TimelineResponse>(
+    ctx,
+    "Fetching timeline",
+    () =>
+      ctx.http.get<TimelineResponse>(
+        `/v1/admin/contacts/${encodeURIComponent(id)}/timeline`,
+        query,
+      ),
+  );
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  ctx.out.table(
+    res.timeline.map((entry) => ({
+      timestamp: entry.timestamp,
+      type: entry.type,
+      summary: summarizeTimelineEntry(entry),
+    })),
+    ["timestamp", "type", "summary"],
+  );
+  ctx.out.outro(
+    `${res.timeline.length} of ${res.total} entry(s) — offset ${res.offset}, limit ${res.limit}`,
+  );
+}
+
+/** One-line human description of a timeline entry, by type. */
+function summarizeTimelineEntry(entry: TimelineEntry): string {
+  const d = entry.data;
+  if (entry.type === "event") {
+    return String(d.event ?? "");
+  }
+  if (entry.type === "journey") {
+    return `${String(d.journeyId ?? "")} (${String(d.status ?? "")})`;
+  }
+  // email
+  const subject = d.subject ? String(d.subject) : String(d.templateKey ?? "");
+  return `${subject} [${String(d.status ?? "")}]`;
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[0];
+
+  switch (sub) {
+    case "list":
+      return runList(ctx, ctx.argv);
+    case "get":
+      return runGet(ctx, ctx.argv);
+    case "timeline":
+      return runTimeline(ctx, ctx.argv);
+    case undefined:
+      ctx.out.fail(
+        "contacts requires a subcommand: list, get, or timeline (see hogsend contacts --help)",
+      );
+      break;
+    default:
+      ctx.out.fail(
+        `unknown contacts subcommand "${sub}" — expected list, get, or timeline`,
+      );
+  }
+}
+
+export const contactsCommand: Command = {
+  name: "contacts",
+  summary: "List, inspect, and trace contact activity",
+  usage,
+  run,
+};