@hogsend/cli 0.0.1 → 0.1.0

package/src/commands/doctor.ts

@@ -0,0 +1,217 @@
+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 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.`;
+
+/** Subset of the engine /v1/health response we render. */
+interface HealthComponent {
+  status: "up" | "down";
+  latencyMs?: number;
+}
+interface HealthTrack {
+  applied: string | null;
+  required: string | null;
+  inSync: boolean;
+  pending: string[];
+}
+interface HealthResponse {
+  status: "healthy" | "degraded" | "migration_pending";
+  uptime: number;
+  timestamp: string;
+  version: string;
+  components: {
+    database: HealthComponent;
+    redis: HealthComponent;
+  };
+  schema: {
+    engine: HealthTrack;
+    client: HealthTrack;
+  };
+}
+
+type Verdict = "ok" | "degraded" | "migration_pending" | "unreachable";
+
+/** Map the server's status onto the CLI verdict vocabulary. */
+function toVerdict(status: HealthResponse["status"]): Verdict {
+  switch (status) {
+    case "healthy":
+      return "ok";
+    case "degraded":
+      return "degraded";
+    case "migration_pending":
+      return "migration_pending";
+  }
+}
+
+function componentSymbol(status: "up" | "down"): string {
+  return status === "up" ? color.green("up") : color.red("down");
+}
+
+function trackLine(name: string, track: HealthTrack): string {
+  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 run(ctx: CommandContext): Promise<void> {
+  const { values } = parseArgs({
+    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(usage);
+    return;
+  }
+
+  const { baseUrl } = ctx.http.cfg;
+
+  // Fetch health. A transport failure (status 0) means unreachable — we surface
+  // that as a first-class verdict rather than a hard error so agents get a
+  // structured answer. Any other HttpError (non-2xx) is genuinely exceptional.
+  let health: HealthResponse | null = null;
+  let reachError: string | null = null;
+  try {
+    health = await ctx.out.step(`GET ${baseUrl}/v1/health`, () =>
+      ctx.http.get<HealthResponse>("/v1/health", undefined, { auth: false }),
+    );
+  } catch (error) {
+    if (isHttpError(error) && error.status === 0) {
+      reachError = error.message;
+    } else if (isHttpError(error)) {
+      // A 4xx/5xx from /v1/health: the instance is up but answering badly.
+      // Treat as unreachable-for-health so the verdict stays meaningful.
+      reachError = error.message;
+    } else {
+      throw error;
+    }
+  }
+
+  if (!health) {
+    const verdict: Verdict = "unreachable";
+    if (ctx.json) {
+      ctx.out.json({
+        ok: false,
+        verdict,
+        baseUrl,
+        error: reachError ?? "unreachable",
+      });
+      process.exit(1);
+    }
+    ctx.out.note(
+      [
+        `${color.red("●")} ${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;
+  }
+
+  // Human render.
+  const badge = `${color.bgMagenta(color.black(" hogsend "))} doctor`;
+  ctx.out.intro(badge);
+
+  const verdictColor =
+    verdict === "ok"
+      ? color.green
+      : verdict === "degraded"
+        ? color.red
+        : color.yellow;
+
+  const lines = [
+    `${verdictColor("●")} ${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 !== undefined
+        ? color.dim(` ${health.components.database.latencyMs}ms`)
+        : ""
+    }`,
+    `  redis     ${componentSymbol(health.components.redis.status)}${
+      health.components.redis.latencyMs !== undefined
+        ? 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);
+}
+
+export const doctorCommand: Command = {
+  name: "doctor",
+  summary: "Probe a running instance's health (GET /v1/health)",
+  usage,
+  run,
+};

package/src/commands/eject.ts

@@ -0,0 +1,106 @@
+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 { color } from "../lib/output.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend eject <package> [--force] [--cwd <dir>]
+
+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.
+
+After ejecting, run: pnpm install`;
+
+/**
+ * Resolve the on-disk source directory for an installed package. Strategy 1:
+ * probe node_modules/<pkg>/package.json (following pnpm/workspace symlinks).
+ * Strategy 2: resolve the package entry via createRequire and walk up.
+ */
+function resolveSourceDir(pkg: string, consumerRoot: string): string | null {
+  const direct = join(consumerRoot, "node_modules", pkg, "package.json");
+  if (existsSync(direct)) {
+    return dirname(realpathSync(direct));
+  }
+  const require = createRequire(`${consumerRoot}${sep}`);
+  try {
+    const entry = require.resolve(pkg);
+    let dir = dirname(entry);
+    while (dir !== dirname(dir)) {
+      if (existsSync(join(dir, "package.json"))) return dir;
+      dir = dirname(dir);
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: ctx.argv,
+    allowPositionals: true,
+    options: {
+      force: { type: "boolean", default: false },
+      cwd: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const pkg = positionals[0];
+  if (!pkg) {
+    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 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) {
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+}
+
+export const ejectCommand: Command = {
+  name: "eject",
+  summary: "Vendor a @hogsend/* package into vendor/<name>",
+  usage,
+  run,
+};

package/src/commands/events.ts

@@ -0,0 +1,154 @@
+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 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`;
+
+interface UserEvent {
+  id: string;
+  userId: string;
+  event: string;
+  properties: Record<string, unknown> | null;
+  occurredAt: string;
+}
+
+interface EventsResponse {
+  events: UserEvent[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const { values, positionals } = parseArgs({
+    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(usage);
+    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: EventsResponse;
+  try {
+    data = await ctx.out.step(`Fetching events for ${userId}`, () =>
+      ctx.http.get<EventsResponse>("/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})`),
+  );
+}
+
+/**
+ * Parse an optional numeric flag. Returns undefined when absent (lets the
+ * server apply its default); fails on a non-numeric value.
+ */
+function parseNumber(
+  raw: string | undefined,
+  name: string,
+  ctx: CommandContext,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    ctx.out.fail(`--${name} must be a number, got "${raw}"`);
+  }
+  return n;
+}
+
+/** Compact a properties object into a single-line preview for the table. */
+function summarizeProps(props: Record<string, unknown> | null): string {
+  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;
+}
+
+export const eventsCommand: Command = {
+  name: "events",
+  summary: "Stream a single user's event history",
+  usage,
+  run,
+};

package/src/commands/index.ts

@@ -0,0 +1,32 @@
+import { contactsCommand } from "./contacts.js";
+import { doctorCommand } from "./doctor.js";
+import { ejectCommand } from "./eject.js";
+import { eventsCommand } from "./events.js";
+import { journeysCommand } from "./journeys.js";
+import { patchCommand } from "./patch.js";
+import { setupCommand } from "./setup.js";
+import { skillsCommand } from "./skills.js";
+import { statsCommand } from "./stats.js";
+import type { Command } from "./types.js";
+
+/**
+ * The command registry. The router (src/bin.ts) matches the leading argv token
+ * against each `command.name` and dispatches to `run()`.
+ *
+ * Order here is the order shown in root help. Data commands (agent-native,
+ * wrapping the engine's /v1/admin/* routes) come first, then the local
+ * scaffolding/maintenance commands (setup, skills, eject, patch).
+ */
+export const commands: Command[] = [
+  doctorCommand,
+  journeysCommand,
+  contactsCommand,
+  statsCommand,
+  eventsCommand,
+  setupCommand,
+  skillsCommand,
+  ejectCommand,
+  patchCommand,
+];
+
+export type { Command, CommandContext } from "./types.js";