@hogsend/cli 0.0.1 → 0.1.0

package/dist/bin.js

@@ -1,10 +1,585 @@
 #!/usr/bin/env node
 
 // src/bin.ts
+import { createRequire as createRequire2 } from "module";
+
+// src/commands/contacts.ts
+import { parseArgs } from "util";
+
+// src/lib/http.ts
+function isHttpError(value) {
+  return value instanceof Error && "status" in value;
+}
+function makeHttpError(message, status, body) {
+  const err = new Error(message);
+  err.name = "HttpError";
+  err.status = status;
+  err.body = body;
+  return err;
+}
+function buildUrl(baseUrl, path, query) {
+  const url = new URL(path.startsWith("/") ? path : `/${path}`, `${baseUrl}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0) continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url.toString();
+}
+function bodyMessage(status, body) {
+  if (body && typeof body === "object" && "error" in body && typeof body.error === "string") {
+    return `${status}: ${body.error}`;
+  }
+  return `request failed with status ${status}`;
+}
+function createAdminClient(cfg) {
+  async function request(method, path, opts) {
+    if (opts.auth && !cfg.adminKey) {
+      throw makeHttpError(
+        "no admin key configured \u2014 pass --admin-key, or set HOGSEND_ADMIN_KEY / ADMIN_API_KEY",
+        0,
+        void 0
+      );
+    }
+    const headers = { Accept: "application/json" };
+    if (opts.auth && cfg.adminKey) {
+      headers.Authorization = `Bearer ${cfg.adminKey}`;
+    }
+    if (opts.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const url = buildUrl(cfg.baseUrl, path, opts.query);
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : void 0
+      });
+    } catch (cause) {
+      const msg = cause instanceof Error ? cause.message : String(cause);
+      throw makeHttpError(`cannot reach ${cfg.baseUrl} (${msg})`, 0, void 0);
+    }
+    const text = await res.text();
+    let parsed;
+    if (text.length > 0) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      throw makeHttpError(bodyMessage(res.status, parsed), res.status, parsed);
+    }
+    return parsed;
+  }
+  return {
+    cfg,
+    get: (path, query, extras) => request("GET", path, { query, auth: extras?.auth ?? true }),
+    patch: (path, body) => request("PATCH", path, { body, auth: true }),
+    post: (path, body) => request("POST", path, { body, auth: true })
+  };
+}
+
+// src/lib/output.ts
+import {
+  cancel,
+  intro as clackIntro,
+  note as clackNote,
+  outro as clackOutro,
+  spinner
+} from "@clack/prompts";
+import color from "picocolors";
+function renderTable(rows, columns) {
+  if (rows.length === 0) return color.dim("(no rows)");
+  const cols = columns ?? Array.from(
+    rows.reduce((set, row) => {
+      for (const key of Object.keys(row)) set.add(key);
+      return set;
+    }, /* @__PURE__ */ new Set())
+  );
+  const cell = (value) => {
+    if (value === null || value === void 0) return "";
+    if (typeof value === "object") return JSON.stringify(value);
+    return String(value);
+  };
+  const widths = cols.map(
+    (c) => Math.max(c.length, ...rows.map((r) => cell(r[c]).length))
+  );
+  const pad = (text, width) => text + " ".repeat(width - text.length);
+  const header = cols.map((c, i) => color.bold(pad(c, widths[i] ?? 0))).join("  ");
+  const sep3 = cols.map((_, i) => "-".repeat(widths[i] ?? 0)).join("  ");
+  const body = rows.map((r) => cols.map((c, i) => pad(cell(r[c]), widths[i] ?? 0)).join("  ")).join("\n");
+  return `${header}
+${color.dim(sep3)}
+${body}`;
+}
+function renderKv(obj) {
+  const keys = Object.keys(obj);
+  if (keys.length === 0) return color.dim("(empty)");
+  const width = Math.max(...keys.map((k) => k.length));
+  return keys.map((k) => {
+    const v = obj[k];
+    const str = v === null || v === void 0 ? "" : typeof v === "object" ? JSON.stringify(v) : String(v);
+    return `${color.dim(`${k}:`.padEnd(width + 1))} ${str}`;
+  }).join("\n");
+}
+function createOutput(opts) {
+  const isJson = opts.json;
+  const interactive = !isJson && Boolean(process.stdout.isTTY);
+  return {
+    interactive,
+    isJson,
+    intro(title) {
+      if (!interactive) return;
+      clackIntro(title);
+    },
+    async step(label, fn) {
+      if (interactive) {
+        const s = spinner();
+        s.start(label);
+        try {
+          const result = await fn();
+          s.stop(`${color.green("\u2713")} ${label}`);
+          return result;
+        } catch (err) {
+          s.stop(`${color.red("\u2717")} ${label}`);
+          throw err;
+        }
+      }
+      if (!isJson) console.log(`  ${label} ...`);
+      return fn();
+    },
+    note(body, title) {
+      if (isJson) return;
+      if (interactive) {
+        clackNote(body, title);
+        return;
+      }
+      if (title) console.log(`
+${title}`);
+      console.log(body);
+    },
+    table(rows, columns) {
+      if (isJson) return;
+      console.log(renderTable(rows, columns));
+    },
+    kv(obj, title) {
+      if (isJson) return;
+      if (title) console.log(color.bold(title));
+      console.log(renderKv(obj));
+    },
+    log(msg) {
+      if (isJson) return;
+      console.log(msg);
+    },
+    json(payload) {
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+    },
+    outro(msg) {
+      if (!interactive) return;
+      clackOutro(msg);
+    },
+    fail(message) {
+      if (isJson) {
+        process.stdout.write(`${JSON.stringify({ error: message })}
+`);
+      } else if (interactive) {
+        cancel(message);
+      } else {
+        process.stderr.write(`${color.red("error")} ${message}
+`);
+      }
+      process.exit(1);
+    }
+  };
+}
+
+// src/commands/contacts.ts
+var 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`;
+var badge = `${color.bgMagenta(color.black(" hogsend "))} contacts`;
+async function fetchOrFail(ctx, label, fn) {
+  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, argv) {
+  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(
+    ctx,
+    "Fetching contacts",
+    () => ctx.http.get("/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) \u2014 offset ${res.offset}, limit ${res.limit}`
+  );
+}
+async function runGet(ctx, argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+  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(
+    ctx,
+    "Fetching contact",
+    () => ctx.http.get(`/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, argv) {
+  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;
+  }
+  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(
+    ctx,
+    "Fetching timeline",
+    () => ctx.http.get(
+      `/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) \u2014 offset ${res.offset}, limit ${res.limit}`
+  );
+}
+function summarizeTimelineEntry(entry) {
+  const d = entry.data;
+  if (entry.type === "event") {
+    return String(d.event ?? "");
+  }
+  if (entry.type === "journey") {
+    return `${String(d.journeyId ?? "")} (${String(d.status ?? "")})`;
+  }
+  const subject = d.subject ? String(d.subject) : String(d.templateKey ?? "");
+  return `${subject} [${String(d.status ?? "")}]`;
+}
+async function run(ctx) {
+  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 void 0:
+      ctx.out.fail(
+        "contacts requires a subcommand: list, get, or timeline (see hogsend contacts --help)"
+      );
+      break;
+    default:
+      ctx.out.fail(
+        `unknown contacts subcommand "${sub}" \u2014 expected list, get, or timeline`
+      );
+  }
+}
+var contactsCommand = {
+  name: "contacts",
+  summary: "List, inspect, and trace contact activity",
+  usage,
+  run
+};
+
+// src/commands/doctor.ts
+import { parseArgs as parseArgs2 } from "util";
+var usage2 = `hogsend doctor [--url <baseUrl>] [--admin-key <key>] [--json]
+
+Probe a running Hogsend instance via GET /v1/health and report its health:
+component status (database, redis), two-track schema state (engine + client),
+and an overall verdict.
+
+The health route is unauthenticated, so doctor works without an admin key.
+
+Verdict:
+  ok                 service healthy, all components up, schema in sync
+  degraded           reachable but a component (database/redis) is down
+  migration_pending  reachable but a schema track is behind (pending migrations)
+  unreachable        the instance could not be reached at all
+
+Exit code: 0 when ok, 1 when unreachable / degraded / migration_pending.
+
+Options:
+  --url <baseUrl>    Target instance (default HOGSEND_API_URL / .env / :3002).
+  --admin-key <key>  Unused by doctor (health is unauthenticated).
+  --json             Emit machine-readable JSON only.
+  -h, --help         Show this help.`;
+function toVerdict(status) {
+  switch (status) {
+    case "healthy":
+      return "ok";
+    case "degraded":
+      return "degraded";
+    case "migration_pending":
+      return "migration_pending";
+  }
+}
+function componentSymbol(status) {
+  return status === "up" ? color.green("up") : color.red("down");
+}
+function trackLine(name, track) {
+  const sync = track.inSync ? color.green("in sync") : color.yellow(
+    `behind (${track.pending.length} pending: ${track.pending.length > 0 ? track.pending.join(", ") : "n/a"})`
+  );
+  const applied = track.applied ?? color.dim("none");
+  const required = track.required ?? color.dim("none");
+  return `${color.bold(name.padEnd(7))} applied ${applied} -> required ${required}  ${sync}`;
+}
+async function run2(ctx) {
+  const { values } = parseArgs2({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false }
+    },
+    // doctor takes no extra flags of its own; tolerate stray tokens.
+    strict: false
+  });
+  if (values.help) {
+    ctx.out.log(usage2);
+    return;
+  }
+  const { baseUrl } = ctx.http.cfg;
+  let health = null;
+  let reachError = null;
+  try {
+    health = await ctx.out.step(
+      `GET ${baseUrl}/v1/health`,
+      () => ctx.http.get("/v1/health", void 0, { auth: false })
+    );
+  } catch (error) {
+    if (isHttpError(error) && error.status === 0) {
+      reachError = error.message;
+    } else if (isHttpError(error)) {
+      reachError = error.message;
+    } else {
+      throw error;
+    }
+  }
+  if (!health) {
+    const verdict2 = "unreachable";
+    if (ctx.json) {
+      ctx.out.json({
+        ok: false,
+        verdict: verdict2,
+        baseUrl,
+        error: reachError ?? "unreachable"
+      });
+      process.exit(1);
+    }
+    ctx.out.note(
+      [
+        `${color.red("\u25CF")} ${color.bold("unreachable")}`,
+        "",
+        reachError ?? `could not reach ${baseUrl}`,
+        "",
+        color.dim("Is the instance running? Check --url / HOGSEND_API_URL.")
+      ].join("\n"),
+      "Doctor"
+    );
+    ctx.out.outro(color.red("doctor: unreachable"));
+    process.exit(1);
+  }
+  const verdict = toVerdict(health.status);
+  const ok = verdict === "ok";
+  if (ctx.json) {
+    ctx.out.json({
+      ok,
+      verdict,
+      baseUrl,
+      version: health.version,
+      uptime: health.uptime,
+      timestamp: health.timestamp,
+      components: health.components,
+      schema: health.schema
+    });
+    if (!ok) process.exit(1);
+    return;
+  }
+  const badge3 = `${color.bgMagenta(color.black(" hogsend "))} doctor`;
+  ctx.out.intro(badge3);
+  const verdictColor = verdict === "ok" ? color.green : verdict === "degraded" ? color.red : color.yellow;
+  const lines = [
+    `${verdictColor("\u25CF")} ${color.bold(verdict)}`,
+    color.dim(
+      `${baseUrl}  v${health.version}  up ${Math.round(health.uptime)}s`
+    ),
+    "",
+    color.bold("Components"),
+    `  database  ${componentSymbol(health.components.database.status)}${health.components.database.latencyMs !== void 0 ? color.dim(` ${health.components.database.latencyMs}ms`) : ""}`,
+    `  redis     ${componentSymbol(health.components.redis.status)}${health.components.redis.latencyMs !== void 0 ? color.dim(` ${health.components.redis.latencyMs}ms`) : ""}`,
+    "",
+    color.bold("Schema"),
+    `  ${trackLine("engine", health.schema.engine)}`,
+    `  ${trackLine("client", health.schema.client)}`
+  ];
+  ctx.out.note(lines.join("\n"), "Doctor");
+  if (ok) {
+    ctx.out.outro(color.green("doctor: ok"));
+    return;
+  }
+  ctx.out.outro(verdictColor(`doctor: ${verdict}`));
+  process.exit(1);
+}
+var doctorCommand = {
+  name: "doctor",
+  summary: "Probe a running instance's health (GET /v1/health)",
+  usage: usage2,
+  run: run2
+};
+
+// src/commands/eject.ts
 import { existsSync as existsSync2, realpathSync } from "fs";
 import { createRequire } from "module";
 import { dirname, join as join2, sep as sep2 } from "path";
-import { parseArgs } from "util";
+import { parseArgs as parseArgs3 } from "util";
 
 // src/eject.ts
 import { existsSync } from "fs";
@@ -117,30 +692,18 @@ async function countFiles(dir) {
   return count;
 }
 
-// src/bin.ts
-var USAGE = `hogsend \u2014 Hogsend project CLI
-
-Usage:
-  hogsend eject <package> [--force] [--cwd <dir>]
+// src/commands/eject.ts
+var usage3 = `hogsend eject <package> [--force] [--cwd <dir>]
 
-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.
+Copy a @hogsend/* package's source into vendor/<name> and rewrite the consumer
+dependency to file:./vendor/<name>. Every other dependency keeps upgrading.
 
 Options:
-  --force           Overwrite an existing vendor/<name>.
-  --cwd <dir>       Consumer repo root (defaults to the current directory).
-  -h, --help        Show this help.
+  --force        Overwrite an existing vendor/<name>.
+  --cwd <dir>    Consumer repo root (defaults to the current directory).
+  -h, --help     Show this help.
 
 After ejecting, run: pnpm install`;
-var RED = "\x1B[31m";
-var RESET = "\x1B[0m";
-function fail(message) {
-  process.stderr.write(`${RED}error${RESET} ${message}
-`);
-  process.exit(1);
-}
 function resolveSourceDir(pkg, consumerRoot) {
   const direct = join2(consumerRoot, "node_modules", pkg, "package.json");
   if (existsSync2(direct)) {
@@ -151,21 +714,16 @@ function resolveSourceDir(pkg, consumerRoot) {
     const entry = require2.resolve(pkg);
     let dir = dirname(entry);
     while (dir !== dirname(dir)) {
-      const candidate = join2(dir, "package.json");
-      if (existsSync2(candidate)) {
-        return dir;
-      }
+      if (existsSync2(join2(dir, "package.json"))) return dir;
       dir = dirname(dir);
     }
   } catch {
   }
-  fail(
-    `cannot resolve ${pkg} from ${consumerRoot}. Is it installed? Run pnpm install first.`
-  );
+  return null;
 }
-async function runEject(args) {
-  const { values, positionals } = parseArgs({
-    args,
+async function run3(ctx) {
+  const { values, positionals } = parseArgs3({
+    args: ctx.argv,
     allowPositionals: true,
     options: {
       force: { type: "boolean", default: false },
@@ -174,58 +732,1192 @@ async function runEject(args) {
     }
   });
   if (values.help) {
-    process.stdout.write(`${USAGE}
-`);
+    ctx.out.log(usage3);
     return;
   }
   const pkg = positionals[0];
   if (!pkg) {
-    fail("eject requires a package name, e.g. hogsend eject @hogsend/engine");
+    ctx.out.fail(
+      "eject requires a package name, e.g. hogsend eject @hogsend/engine"
+    );
   }
   const consumerRoot = values.cwd ?? process.cwd();
   const sourceDir = resolveSourceDir(pkg, consumerRoot);
+  if (!sourceDir) {
+    ctx.out.fail(
+      `cannot resolve ${pkg} from ${consumerRoot}. Is it installed? Run pnpm install first.`
+    );
+  }
   try {
-    const result = await eject({
-      pkg,
-      consumerRoot,
-      sourceDir,
-      force: values.force
-    });
-    process.stdout.write(
-      `Ejected ${result.pkg}
-  copied ${result.copiedFiles} files -> ${result.vendorPath}
-  dependency ${result.depSpecBefore} -> ${result.depSpecAfter}
-
-Now run: ${result.followUp}
-`
+    const result = await ctx.out.step(
+      `Ejecting ${pkg}`,
+      () => eject({ pkg, consumerRoot, sourceDir, force: values.force })
+    );
+    if (ctx.json) {
+      ctx.out.json(result);
+      return;
+    }
+    ctx.out.note(
+      [
+        `copied ${result.copiedFiles} files -> ${result.vendorPath}`,
+        `dependency ${result.depSpecBefore} -> ${color.cyan(result.depSpecAfter)}`,
+        "",
+        `Now run: ${color.cyan(result.followUp)}`
+      ].join("\n"),
+      `Ejected ${result.pkg}`
     );
   } catch (error) {
     if (error instanceof EjectError) {
-      fail(error.message);
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+}
+var ejectCommand = {
+  name: "eject",
+  summary: "Vendor a @hogsend/* package into vendor/<name>",
+  usage: usage3,
+  run: run3
+};
+
+// src/commands/events.ts
+import { parseArgs as parseArgs4 } from "util";
+var usage4 = `hogsend events <userId> [options]
+
+Stream the event history for a single user, newest first. Wraps
+GET /v1/admin/events?userId=<userId>.
+
+Arguments:
+  <userId>            The user (distinct) id to fetch events for. Required.
+
+Options:
+  --event <name>      Filter to a single event name.
+  --from <iso>        Only events at/after this ISO-8601 timestamp.
+  --to <iso>          Only events at/before this ISO-8601 timestamp.
+  --limit <n>         Max events to return (1-100, default 50).
+  --offset <n>        Pagination offset (default 0).
+  --json              Emit machine-readable JSON only.
+  -h, --help          Show this help.
+
+Examples:
+  hogsend events user_123
+  hogsend events user_123 --event signup --limit 10
+  hogsend events user_123 --from 2026-01-01T00:00:00Z --json`;
+async function run4(ctx) {
+  const { values, positionals } = parseArgs4({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      event: { type: "string" },
+      from: { type: "string" },
+      to: { type: "string" },
+      limit: { type: "string" },
+      offset: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage4);
+    return;
+  }
+  const userId = positionals[0];
+  if (!userId) {
+    ctx.out.fail("events requires a userId, e.g. hogsend events user_123");
+  }
+  const limit = parseNumber(values.limit, "limit", ctx);
+  const offset = parseNumber(values.offset, "offset", ctx);
+  const query = {
+    userId,
+    event: values.event,
+    from: values.from,
+    to: values.to,
+    limit,
+    offset
+  };
+  let data;
+  try {
+    data = await ctx.out.step(
+      `Fetching events for ${userId}`,
+      () => ctx.http.get("/v1/admin/events", query)
+    );
+  } catch (error) {
+    if (isHttpError(error)) {
+      ctx.out.fail(error.message);
     }
     throw error;
   }
+  if (ctx.json) {
+    ctx.out.json(data);
+    return;
+  }
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} events`);
+  if (data.events.length === 0) {
+    ctx.out.note(
+      `No events found for ${color.cyan(userId)}.`,
+      "Empty event stream"
+    );
+    ctx.out.outro(color.dim("Nothing to show."));
+    return;
+  }
+  const rows = data.events.map((e) => ({
+    occurredAt: e.occurredAt,
+    event: e.event,
+    properties: summarizeProps(e.properties),
+    id: e.id
+  }));
+  ctx.out.table(rows, ["occurredAt", "event", "properties", "id"]);
+  const shown = data.events.length;
+  const through = data.offset + shown;
+  ctx.out.outro(
+    `${color.green(String(shown))} event${shown === 1 ? "" : "s"} ` + color.dim(`(${data.offset + 1}-${through} of ${data.total})`)
+  );
+}
+function parseNumber(raw, name, ctx) {
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    ctx.out.fail(`--${name} must be a number, got "${raw}"`);
+  }
+  return n;
+}
+function summarizeProps(props) {
+  if (!props) return "";
+  const keys = Object.keys(props);
+  if (keys.length === 0) return "";
+  const preview = JSON.stringify(props);
+  return preview.length > 60 ? `${preview.slice(0, 57)}...` : preview;
+}
+var eventsCommand = {
+  name: "events",
+  summary: "Stream a single user's event history",
+  usage: usage4,
+  run: run4
+};
+
+// src/commands/journeys.ts
+import { parseArgs as parseArgs5 } from "util";
+var usage5 = `hogsend journeys <subcommand> [options]
+
+Inspect and toggle journeys via the admin API (/v1/admin/journeys).
+
+Subcommands:
+  list                       List journeys with status, trigger, and state counts.
+  get <id>                   Show one journey: trigger, exitOn, counts, recent states.
+  enable <id>                Enable a journey (PATCH { enabled: true }).
+  disable <id>               Disable a journey (PATCH { enabled: false }).
+
+Options:
+  list:
+    --enabled <true|false>   Filter by enabled state.
+    --limit <n>              Page size (1-100, default 50).
+    --offset <n>             Page offset (default 0).
+  --json                     Emit machine-readable JSON only.
+  -h, --help                 Show this help.
+
+Examples:
+  hogsend journeys list --enabled true
+  hogsend journeys get activation-welcome --json
+  hogsend journeys disable churn-prevention`;
+function badge2() {
+  return `${color.bgMagenta(color.black(" hogsend "))} journeys`;
+}
+function statusColor(enabled) {
+  return enabled ? color.green("enabled") : color.yellow("disabled");
+}
+async function runList2(ctx) {
+  const { values } = parseArgs5({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      enabled: { type: "string" },
+      limit: { type: "string" },
+      offset: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage5);
+    return;
+  }
+  if (values.enabled !== void 0 && !["true", "false"].includes(values.enabled)) {
+    ctx.out.fail("--enabled must be 'true' or 'false'");
+  }
+  const query = {
+    enabled: values.enabled,
+    limit: values.limit,
+    offset: values.offset
+  };
+  if (!ctx.json) ctx.out.intro(badge2());
+  const data = await ctx.out.step(
+    "Fetching journeys",
+    () => ctx.http.get("/v1/admin/journeys", query)
+  );
+  if (ctx.json) {
+    ctx.out.json(data);
+    return;
+  }
+  if (data.journeys.length === 0) {
+    ctx.out.note("No journeys matched.", "Journeys");
+  } else {
+    ctx.out.table(
+      data.journeys.map((j) => ({
+        id: j.id,
+        name: j.name,
+        status: statusColor(j.enabled),
+        trigger: j.trigger.event,
+        active: j.counts.active,
+        waiting: j.counts.waiting,
+        completed: j.counts.completed,
+        failed: j.counts.failed
+      })),
+      [
+        "id",
+        "name",
+        "status",
+        "trigger",
+        "active",
+        "waiting",
+        "completed",
+        "failed"
+      ]
+    );
+  }
+  ctx.out.outro(
+    `${data.journeys.length} of ${data.total} journey(s) \u2014 offset ${data.offset}, limit ${data.limit}`
+  );
+}
+async function runGet2(ctx, id) {
+  if (!id) {
+    ctx.out.fail(
+      "journeys get requires a journey id, e.g. hogsend journeys get activation-welcome"
+    );
+  }
+  if (!ctx.json) ctx.out.intro(badge2());
+  const data = await ctx.out.step(
+    `Fetching journey ${id}`,
+    () => ctx.http.get(
+      `/v1/admin/journeys/${encodeURIComponent(id)}`
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(data);
+    return;
+  }
+  const j = data.journey;
+  ctx.out.kv(
+    {
+      id: j.id,
+      name: j.name,
+      description: j.description ?? "",
+      status: statusColor(j.enabled),
+      trigger: j.trigger.event,
+      entryLimit: j.entryLimit,
+      exitOn: j.exitOn?.map((e) => e.event).join(", ") ?? "(none)"
+    },
+    "Journey"
+  );
+  ctx.out.kv(
+    {
+      active: j.counts.active,
+      waiting: j.counts.waiting,
+      completed: j.counts.completed,
+      failed: j.counts.failed,
+      exited: j.counts.exited
+    },
+    "Counts"
+  );
+  if (j.recentStates.length === 0) {
+    ctx.out.note("No recent journey instances.", "Recent states");
+  } else {
+    ctx.out.table(
+      j.recentStates.map((s) => ({
+        userId: s.userId,
+        email: s.userEmail,
+        status: s.status,
+        node: s.currentNodeId,
+        updatedAt: s.updatedAt
+      })),
+      ["userId", "email", "status", "node", "updatedAt"]
+    );
+  }
+  ctx.out.outro(`Journey ${j.id} is ${j.enabled ? "enabled" : "disabled"}.`);
+}
+async function runToggle(ctx, id, enabled) {
+  const verb = enabled ? "enable" : "disable";
+  if (!id) {
+    ctx.out.fail(
+      `journeys ${verb} requires a journey id, e.g. hogsend journeys ${verb} activation-welcome`
+    );
+  }
+  if (!ctx.json) ctx.out.intro(badge2());
+  const data = await ctx.out.step(
+    `${enabled ? "Enabling" : "Disabling"} ${id}`,
+    () => ctx.http.patch(
+      `/v1/admin/journeys/${encodeURIComponent(id)}`,
+      { enabled }
+    )
+  );
+  if (ctx.json) {
+    ctx.out.json(data);
+    return;
+  }
+  const j = data.journey;
+  ctx.out.note(
+    [
+      `${color.bold(j.name)} (${j.id})`,
+      `status: ${statusColor(j.enabled)}`,
+      `updated: ${j.updatedAt}`
+    ].join("\n"),
+    `Journey ${enabled ? "enabled" : "disabled"}`
+  );
+  ctx.out.outro(`${j.id} is now ${statusColor(j.enabled)}.`);
+}
+async function run5(ctx) {
+  const sub = ctx.argv[0];
+  const rest = ctx.argv.slice(1);
+  const subCtx = { ...ctx, argv: rest };
+  try {
+    switch (sub) {
+      case "list":
+        await runList2(subCtx);
+        return;
+      case "get": {
+        const id = rest.find((a) => !a.startsWith("-"));
+        if (rest.includes("--help") || rest.includes("-h")) {
+          ctx.out.log(usage5);
+          return;
+        }
+        await runGet2(subCtx, id);
+        return;
+      }
+      case "enable": {
+        if (rest.includes("--help") || rest.includes("-h")) {
+          ctx.out.log(usage5);
+          return;
+        }
+        await runToggle(
+          subCtx,
+          rest.find((a) => !a.startsWith("-")),
+          true
+        );
+        return;
+      }
+      case "disable": {
+        if (rest.includes("--help") || rest.includes("-h")) {
+          ctx.out.log(usage5);
+          return;
+        }
+        await runToggle(
+          subCtx,
+          rest.find((a) => !a.startsWith("-")),
+          false
+        );
+        return;
+      }
+      case void 0:
+        ctx.out.fail(
+          `journeys requires a subcommand (list|get|enable|disable). Run: hogsend journeys --help`
+        );
+        return;
+      default:
+        ctx.out.fail(
+          `unknown journeys subcommand '${sub}'. Expected list|get|enable|disable.`
+        );
+        return;
+    }
+  } catch (error) {
+    if (isHttpError(error)) {
+      if (error.status === 404) {
+        ctx.out.fail("journey not found");
+      }
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+}
+var journeysCommand = {
+  name: "journeys",
+  summary: "List, inspect, enable, and disable journeys",
+  usage: usage5,
+  run: run5
+};
+
+// src/commands/patch.ts
+import { spawnSync } from "child_process";
+import { parseArgs as parseArgs6 } from "util";
+var usage6 = `hogsend patch <package> [--cwd <dir>]
+
+Thin wrapper over pnpm's native patch flow. Runs \`pnpm patch <package>\`, which
+extracts the package into a temp dir and prints the path to edit. After editing,
+commit the patch with the command pnpm prints (\`pnpm patch-commit <dir>\`).
+
+This does NOT replace scripts/patch-check.sh (the patch re-apply contract).
+
+Options:
+  --cwd <dir>    Project root to run pnpm in (defaults to current directory).
+  -h, --help     Show this help.`;
+async function run6(ctx) {
+  const { values, positionals } = parseArgs6({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      cwd: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage6);
+    return;
+  }
+  const pkg = positionals[0];
+  if (!pkg) {
+    ctx.out.fail(
+      "patch requires a package name, e.g. hogsend patch @hogsend/engine"
+    );
+  }
+  const cwd = values.cwd ?? process.cwd();
+  const result = spawnSync("pnpm", ["patch", pkg], {
+    cwd,
+    stdio: ctx.json ? "ignore" : "inherit"
+  });
+  if (ctx.json) {
+    ctx.out.json({
+      package: pkg,
+      command: `pnpm patch ${pkg}`,
+      status: result.status,
+      ok: result.status === 0
+    });
+    if (result.status !== 0) process.exit(1);
+    return;
+  }
+  if (result.status !== 0) {
+    ctx.out.fail(`pnpm patch ${pkg} exited with code ${result.status ?? "?"}`);
+  }
+  ctx.out.note(
+    [
+      "pnpm extracted the package to a temp dir (printed above).",
+      "Edit the files, then commit the patch:",
+      "",
+      color.cyan("pnpm patch-commit <dir>")
+    ].join("\n"),
+    "Next steps"
+  );
+}
+var patchCommand = {
+  name: "patch",
+  summary: "Patch a package via pnpm's native patch flow",
+  usage: usage6,
+  run: run6
+};
+
+// src/commands/setup.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { randomBytes } from "crypto";
+import { copyFileSync, existsSync as existsSync3, readFileSync, writeFileSync } from "fs";
+import { join as join3 } from "path";
+import { parseArgs as parseArgs7 } from "util";
+import { confirm } from "@clack/prompts";
+
+// src/lib/prompt.ts
+import { cancel as cancel2, isCancel } from "@clack/prompts";
+function bail(value) {
+  if (isCancel(value)) {
+    cancel2("Cancelled.");
+    process.exit(0);
+  }
+  return value;
+}
+
+// src/commands/setup.ts
+var usage7 = `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.`;
+function generateSecret() {
+  return randomBytes(32).toString("hex");
+}
+var SECRET_KEY = "BETTER_AUTH_SECRET";
+var PLACEHOLDER_PREFIX = "change-me";
+function ensureEnv(cwd) {
+  const envPath = join3(cwd, ".env");
+  const examplePath = join3(cwd, ".env.example");
+  let copied;
+  if (existsSync3(envPath)) {
+    copied = {
+      step: "env",
+      status: "skipped",
+      detail: ".env already exists"
+    };
+  } else if (existsSync3(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 \u2014 no .env"
+      }
+    };
+  }
+  let raw;
+  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 ? void 0 : lines[idx];
+  const current = existingLine === void 0 ? void 0 : existingLine.slice(existingLine.indexOf("=") + 1).trim();
+  const isPlaceholder = current === void 0 || 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)`
+    }
+  };
+}
+function runCmd(cmd, args, cwd, json) {
+  const result = spawnSync2(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 run7(ctx) {
+  const { values } = parseArgs7({
+    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(usage7);
+    return;
+  }
+  const cwd = values.cwd ?? process.cwd();
+  if (!existsSync3(join3(cwd, "package.json"))) {
+    ctx.out.fail(
+      `no package.json in ${cwd} \u2014 run setup from a scaffolded Hogsend app (or pass --cwd).`
+    );
+  }
+  const hasCompose = existsSync3(join3(cwd, "docker-compose.yml")) || existsSync3(join3(cwd, "docker-compose.yaml")) || existsSync3(join3(cwd, "compose.yml")) || existsSync3(join3(cwd, "compose.yaml"));
+  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 = [];
+  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"
+    });
+  }
+  const env = await ctx.out.step(
+    "Preparing .env + auth secret",
+    async () => ensureEnv(cwd)
+  );
+  results.push(env.copied, env.secret);
+  const dockerFailed = results.some(
+    (r) => r.step === "docker" && r.status === "failed"
+  );
+  if (dockerFailed) {
+    results.push({
+      step: "migrate",
+      status: "skipped",
+      detail: "skipped \u2014 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;
+  }
+  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 \u2014 see the table above. Fix and re-run hogsend setup.`
+    );
+  }
+  ctx.out.outro(
+    `${color.green("Done.")} ${color.dim("Local infra is up \u2014 go write a journey.")}`
+  );
+}
+var setupCommand = {
+  name: "setup",
+  summary: "Local onboarding: docker compose up, gen secret, db:migrate",
+  usage: usage7,
+  run: run7
+};
+
+// src/commands/skills.ts
+import {
+  cpSync,
+  existsSync as existsSync4,
+  mkdirSync,
+  readdirSync,
+  readFileSync as readFileSync2,
+  statSync
+} from "fs";
+import { join as join4 } from "path";
+import { fileURLToPath } from "url";
+import { parseArgs as parseArgs8 } from "util";
+import { multiselect } from "@clack/prompts";
+var usage8 = `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`;
+function bundledSkillsDir() {
+  return fileURLToPath(new URL("../skills", import.meta.url));
+}
+function installDir(cwd) {
+  return join4(cwd, ".claude", "skills");
+}
+function readFrontmatterField(skillDir, field) {
+  const skillFile = join4(skillDir, "SKILL.md");
+  if (!existsSync4(skillFile)) return "";
+  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 "";
+}
+function readFileSyncSafe(path) {
+  try {
+    return readFileSync2(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function listBundledSkills(cwd) {
+  const dir = bundledSkillsDir();
+  if (!existsSync4(dir)) return [];
+  const target = installDir(cwd);
+  const entries = readdirSync(dir).filter((name) => {
+    const full = join4(dir, name);
+    return statSync(full).isDirectory() && existsSync4(join4(full, "SKILL.md"));
+  });
+  return entries.sort().map((name) => ({
+    name,
+    description: readFrontmatterField(join4(dir, name), "description"),
+    installed: existsSync4(join4(target, name))
+  }));
+}
+function runList3(ctx) {
+  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")}).`
+  );
+}
+function copySkill(name, cwd, force) {
+  const src = join4(bundledSkillsDir(), name);
+  const dest = join4(installDir(cwd), name);
+  const exists = existsSync4(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, argv) {
+  const { values, positionals } = parseArgs8({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      force: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage8);
+    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);
+  let names;
+  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" : void 0
+        })),
+        required: true
+      })
+    );
+    names = picked;
+  } else {
+    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("\u2713")} ${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 run8(ctx) {
+  const sub = ctx.argv[0];
+  switch (sub) {
+    case "list":
+      runList3(ctx);
+      return;
+    case "add":
+      await runAdd(ctx, ctx.argv.slice(1));
+      return;
+    case void 0:
+    case "-h":
+    case "--help":
+      ctx.out.log(usage8);
+      return;
+    default:
+      ctx.out.fail(
+        `unknown skills subcommand "${sub}". Use: list | add. See hogsend skills --help.`
+      );
+  }
+}
+var skillsCommand = {
+  name: "skills",
+  summary: "List + install bundled Claude Code skills into .claude/skills",
+  usage: usage8,
+  run: run8
+};
+
+// src/commands/stats.ts
+import { parseArgs as parseArgs9 } from "util";
+var usage9 = `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.`;
+function pct(rate) {
+  return `${(rate * 100).toFixed(2)}%`;
+}
+async function run9(ctx) {
+  const { values } = parseArgs9({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values.help) {
+    ctx.out.log(usage9);
+    return;
+  }
+  const metrics = await ctx.out.step(
+    "Fetching overview metrics",
+    () => ctx.http.get("/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));
+}
+var statsCommand = {
+  name: "stats",
+  summary: "Show system-wide overview metrics",
+  usage: usage9,
+  run: run9
+};
+
+// src/commands/index.ts
+var commands = [
+  doctorCommand,
+  journeysCommand,
+  contactsCommand,
+  statsCommand,
+  eventsCommand,
+  setupCommand,
+  skillsCommand,
+  ejectCommand,
+  patchCommand
+];
+
+// src/lib/config.ts
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
+import { join as join5 } from "path";
+import { parseArgs as parseArgs10 } from "util";
+var DEFAULT_BASE_URL = "http://localhost:3002";
+function parseGlobalFlags(argv) {
+  const { values, tokens } = parseArgs10({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+    options: {
+      url: { type: "string" },
+      "admin-key": { type: "string" },
+      json: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  const owned = /* @__PURE__ */ new Set(["url", "admin-key", "json", "help", "h"]);
+  const rest = [];
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      rest.push(token.value);
+    } else if (token.kind === "option") {
+      if (owned.has(token.name)) continue;
+      rest.push(token.rawName);
+      if (token.value !== void 0 && !token.inlineValue) {
+        rest.push(token.value);
+      } else if (token.inlineValue && token.value !== void 0) {
+        rest[rest.length - 1] = `${token.rawName}=${token.value}`;
+      }
+    }
+  }
+  return {
+    url: typeof values.url === "string" ? values.url : void 0,
+    adminKey: typeof values["admin-key"] === "string" ? values["admin-key"] : void 0,
+    json: values.json === true,
+    help: values.help === true,
+    rest
+  };
+}
+function loadDotEnv(cwd = process.cwd()) {
+  const out = {};
+  const file = join5(cwd, ".env");
+  if (!existsSync5(file)) return out;
+  let raw;
+  try {
+    raw = readFileSync3(file, "utf8");
+  } catch {
+    return out;
+  }
+  for (const rawLine of raw.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const withoutExport = line.startsWith("export ") ? line.slice("export ".length) : line;
+    const eq = withoutExport.indexOf("=");
+    if (eq === -1) continue;
+    const key = withoutExport.slice(0, eq).trim();
+    if (key === "") continue;
+    let value = withoutExport.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+function resolveConfig(flags, cwd = process.cwd()) {
+  const dotenv = loadDotEnv(cwd);
+  const baseUrlRaw = flags.url ?? process.env.HOGSEND_API_URL ?? dotenv.HOGSEND_API_URL ?? DEFAULT_BASE_URL;
+  const adminKey = flags.adminKey ?? process.env.HOGSEND_ADMIN_KEY ?? process.env.ADMIN_API_KEY ?? dotenv.HOGSEND_ADMIN_KEY ?? dotenv.ADMIN_API_KEY;
+  return {
+    baseUrl: baseUrlRaw.replace(/\/+$/, ""),
+    adminKey: adminKey && adminKey.length > 0 ? adminKey : void 0
+  };
+}
+
+// src/bin.ts
+function version() {
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const pkg = require2("../package.json");
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function rootUsage() {
+  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")} \u2014 the agent-native Hogsend CLI
+
+${color.dim("Usage:")} hogsend <command> [options]
+
+${color.dim("Commands:")}
+${list}
+
+${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
+
+Run ${color.cyan("hogsend <command> --help")} for command-specific options.`;
+}
+function findCommand(name) {
+  return commands.find((c) => c.name === name);
 }
 async function main() {
-  const [command, ...rest] = process.argv.slice(2);
-  if (!command || command === "--help" || command === "-h") {
-    process.stdout.write(`${USAGE}
+  const argv = process.argv.slice(2);
+  const [token, ...afterToken] = argv;
+  if (token === "-v" || token === "--version") {
+    process.stdout.write(`${version()}
 `);
     return;
   }
-  switch (command) {
-    case "eject":
-      await runEject(rest);
-      break;
-    default:
-      fail(`unknown command "${command}"
+  if (!token || token === "-h" || token === "--help") {
+    process.stdout.write(`${rootUsage()}
+`);
+    return;
+  }
+  const command = findCommand(token);
+  if (!command) {
+    process.stderr.write(
+      `${color.red("error")} unknown command "${token}"
 
-${USAGE}`);
+${rootUsage()}
+`
+    );
+    process.exit(1);
+  }
+  const flags = parseGlobalFlags(afterToken);
+  const out = createOutput({ json: flags.json });
+  if (flags.help) {
+    out.log(command.usage);
+    return;
   }
+  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)}
+  const msg = error instanceof Error ? error.message : String(error);
+  if (process.argv.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({ error: msg })}
+`);
+  } else {
+    process.stderr.write(`${color.red("error")} ${msg}
 `);
+  }
   process.exit(1);
 });
 //# sourceMappingURL=bin.js.map