@hogsend/cli 0.0.1 → 0.2.0

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,
+};