@hogsend/cli 0.0.1 → 0.1.0

package/src/commands/types.ts

@@ -0,0 +1,41 @@
+import type { ResolvedConfig } from "../lib/config.js";
+import type { AdminClient } from "../lib/http.js";
+import type { Output } from "../lib/output.js";
+
+/**
+ * Per-invocation context handed to every command's `run()`. The router builds
+ * this once (after parsing global flags + resolving config) and passes it in,
+ * so command files never touch process.argv directly, never resolve config,
+ * and never construct an HTTP client themselves.
+ */
+export interface CommandContext {
+  /**
+   * The args AFTER the command token. e.g. for `hogsend journeys list --json`
+   * the router strips `journeys` and the global `--json`, leaving `["list"]`.
+   * Subcommand dispatch (list/get/...) is the command's own responsibility.
+   */
+  argv: string[];
+  /** Base URL + admin key, already resolved via flags > env > .env. */
+  cfg: ResolvedConfig;
+  /** Pre-built admin HTTP client, bound to `cfg`. */
+  http: AdminClient;
+  /** Output sink — human (TTY clack) vs json, already mode-selected. */
+  out: Output;
+  /** True when the global `--json` flag was passed. Mirrors `out.isJson`. */
+  json: boolean;
+}
+
+/**
+ * The descriptor every command file implements. The router matches `name`
+ * against the leading argv token and dispatches to `run()`.
+ */
+export interface Command {
+  /** Command token, e.g. "journeys", "eject". */
+  name: string;
+  /** One-line help shown in the root command list. */
+  summary: string;
+  /** Multiline usage block shown on `hogsend <name> --help`. */
+  usage: string;
+  /** Execute the command. Throw to fail (router renders + exits 1). */
+  run(ctx: CommandContext): Promise<void>;
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 // @hogsend/cli — programmatic entry. The `hogsend` bin lives in ./bin.ts.
+
+export type { Command, CommandContext } from "./commands/types.js";
 export {
   EjectError,
   type EjectOptions,

package/src/lib/config.ts

@@ -0,0 +1,147 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+
+/** Resolved target for the admin HTTP client. */
+export interface ResolvedConfig {
+  /** Base URL of the target instance, no trailing slash. */
+  baseUrl: string;
+  /** Admin bearer token, if resolvable. `doctor`/health works without it. */
+  adminKey: string | undefined;
+}
+
+/** Global flags parsed off the front of any command's argv. */
+export interface GlobalFlags {
+  url?: string;
+  adminKey?: string;
+  json: boolean;
+  help: boolean;
+  /** The remaining args after global flags are stripped. */
+  rest: string[];
+}
+
+const DEFAULT_BASE_URL = "http://localhost:3002";
+
+/**
+ * Parse the global flags that every command honours (`--url`, `--admin-key`,
+ * `--json`, `-h`/`--help`) off an argv slice, returning the parsed values plus
+ * the leftover `rest` (positionals + unknown flags) for the command to handle.
+ *
+ * `strict: false` so command-specific flags (e.g. `--enabled`, `--limit`) pass
+ * through untouched in `rest` rather than throwing here.
+ */
+export function parseGlobalFlags(argv: string[]): GlobalFlags {
+  const { values, tokens } = parseArgs({
+    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 },
+    },
+  });
+
+  // Rebuild `rest` from the token stream, dropping only the global flags we
+  // own (and their values). Everything else — positionals and unknown option
+  // tokens — is preserved verbatim for the command's own parser.
+  const owned = new Set(["url", "admin-key", "json", "help", "h"]);
+  const rest: string[] = [];
+  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 !== undefined && !token.inlineValue) {
+        rest.push(token.value);
+      } else if (token.inlineValue && token.value !== undefined) {
+        // already captured in rawName? no — rebuild as --name=value
+        rest[rest.length - 1] = `${token.rawName}=${token.value}`;
+      }
+    }
+  }
+
+  return {
+    url: typeof values.url === "string" ? values.url : undefined,
+    adminKey:
+      typeof values["admin-key"] === "string" ? values["admin-key"] : undefined,
+    json: values.json === true,
+    help: values.help === true,
+    rest,
+  };
+}
+
+/**
+ * Manually parse a `.env` file into a flat record. No dotenv dependency: a
+ * small, forgiving parser (KEY=VALUE per line, `#` comments, optional quotes,
+ * `export ` prefix tolerated). Never throws — a missing/unreadable file yields
+ * an empty record so config resolution stays robust in any cwd.
+ */
+export function loadDotEnv(
+  cwd: string = process.cwd(),
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const file = join(cwd, ".env");
+  if (!existsSync(file)) return out;
+  let raw: string;
+  try {
+    raw = readFileSync(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;
+}
+
+/**
+ * Resolve the target config with precedence flags > process.env > .env, falling
+ * back to the local-dev default base URL.
+ *
+ *   baseUrl: --url > HOGSEND_API_URL (env) > HOGSEND_API_URL (.env) > localhost:3002
+ *   adminKey: --admin-key > HOGSEND_ADMIN_KEY|ADMIN_API_KEY (env) > (.env equiv)
+ */
+export function resolveConfig(
+  flags: GlobalFlags,
+  cwd: string = process.cwd(),
+): ResolvedConfig {
+  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 : undefined,
+  };
+}

package/src/lib/http.ts

@@ -0,0 +1,145 @@
+import type { ResolvedConfig } from "./config.js";
+
+/** A non-2xx response (or transport failure) from the admin API. */
+export interface HttpError extends Error {
+  /** HTTP status code, or 0 for a transport-level failure (DNS/connect). */
+  status: number;
+  /** Parsed JSON body when available, else the raw text, else undefined. */
+  body: unknown;
+}
+
+/** Query params accepted by `get` — undefined values are dropped. */
+export type Query = Record<string, string | number | undefined>;
+
+/**
+ * Thin admin HTTP client over native fetch (Node 22). Hits `<base>/v1/...`,
+ * sends `Authorization: Bearer <adminKey>` on admin paths, parses JSON, and
+ * throws an {@link HttpError} on any non-2xx response.
+ *
+ * Path convention: pass the path AFTER the base URL, e.g. `/v1/admin/journeys`
+ * or `/v1/health`. The unauthenticated health route is reached via the same
+ * `get` — pass `{ auth: false }` so a missing admin key doesn't error.
+ */
+export interface AdminClient {
+  get<T = unknown>(
+    path: string,
+    query?: Query,
+    opts?: RequestExtras,
+  ): Promise<T>;
+  patch<T = unknown>(path: string, body: unknown): Promise<T>;
+  post<T = unknown>(path: string, body: unknown): Promise<T>;
+  /** The resolved config this client is bound to (for messages/JSON output). */
+  readonly cfg: ResolvedConfig;
+}
+
+/** Per-request overrides. */
+export interface RequestExtras {
+  /** Set false for unauthenticated routes (e.g. /v1/health). Default true. */
+  auth?: boolean;
+}
+
+function isHttpError(value: unknown): value is HttpError {
+  return value instanceof Error && "status" in value;
+}
+
+function makeHttpError(
+  message: string,
+  status: number,
+  body: unknown,
+): HttpError {
+  const err = new Error(message) as HttpError;
+  err.name = "HttpError";
+  err.status = status;
+  err.body = body;
+  return err;
+}
+
+function buildUrl(baseUrl: string, path: string, query?: Query): string {
+  const url = new URL(path.startsWith("/") ? path : `/${path}`, `${baseUrl}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined) continue;
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return url.toString();
+}
+
+function bodyMessage(status: number, body: unknown): string {
+  if (
+    body &&
+    typeof body === "object" &&
+    "error" in body &&
+    typeof (body as { error: unknown }).error === "string"
+  ) {
+    return `${status}: ${(body as { error: string }).error}`;
+  }
+  return `request failed with status ${status}`;
+}
+
+/** Build an {@link AdminClient} bound to the given resolved config. */
+export function createAdminClient(cfg: ResolvedConfig): AdminClient {
+  async function request<T>(
+    method: string,
+    path: string,
+    opts: { query?: Query; body?: unknown; auth: boolean },
+  ): Promise<T> {
+    if (opts.auth && !cfg.adminKey) {
+      throw makeHttpError(
+        "no admin key configured — pass --admin-key, or set HOGSEND_ADMIN_KEY / ADMIN_API_KEY",
+        0,
+        undefined,
+      );
+    }
+
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (opts.auth && cfg.adminKey) {
+      headers.Authorization = `Bearer ${cfg.adminKey}`;
+    }
+    if (opts.body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    const url = buildUrl(cfg.baseUrl, path, opts.query);
+
+    let res: Response;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+      });
+    } catch (cause) {
+      const msg = cause instanceof Error ? cause.message : String(cause);
+      throw makeHttpError(`cannot reach ${cfg.baseUrl} (${msg})`, 0, undefined);
+    }
+
+    const text = await res.text();
+    let parsed: unknown;
+    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 as T;
+  }
+
+  return {
+    cfg,
+    get: <T>(path: string, query?: Query, extras?: RequestExtras) =>
+      request<T>("GET", path, { query, auth: extras?.auth ?? true }),
+    patch: <T>(path: string, body: unknown) =>
+      request<T>("PATCH", path, { body, auth: true }),
+    post: <T>(path: string, body: unknown) =>
+      request<T>("POST", path, { body, auth: true }),
+  };
+}
+
+export { isHttpError };

package/src/lib/output.ts

@@ -0,0 +1,185 @@
+import {
+  cancel,
+  intro as clackIntro,
+  note as clackNote,
+  outro as clackOutro,
+  spinner,
+} from "@clack/prompts";
+import color from "picocolors";
+
+/**
+ * Unified output sink. Two modes:
+ *
+ *  - human: TTY clack chrome (intro badge, spinners, notes, outro) + tables.
+ *    Falls back to plain console.log lines when stdout is not a TTY.
+ *  - json (`--json`): ALL chrome is a no-op; the command emits exactly one
+ *    JSON document via `out.json(payload)`. Nothing else touches stdout, so a
+ *    --json run is always a single valid JSON document — safe for agents.
+ *
+ * `interactive` is true only when human mode AND stdout is a TTY; commands key
+ * spinner/prompt behaviour off it. `isJson` flips command control flow to the
+ * non-interactive branch.
+ */
+export interface Output {
+  /** True when human-mode AND stdout is a TTY (clack chrome is live). */
+  readonly interactive: boolean;
+  /** True when `--json` was passed. */
+  readonly isJson: boolean;
+  /** Session intro badge. No-op in json / non-TTY. */
+  intro(title: string): void;
+  /**
+   * Run an async step with a spinner in interactive mode; a plain awaited call
+   * otherwise. The label is logged (not spun) when non-interactive & not json.
+   */
+  step<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /** Boxed note. No-op in json / non-TTY (prints plain lines in non-TTY human). */
+  note(body: string, title?: string): void;
+  /** Render an array of records as a table (human only; no-op in json). */
+  table(rows: Record<string, unknown>[], columns?: string[]): void;
+  /** Render a key/value object (human only; no-op in json). */
+  kv(obj: Record<string, unknown>, title?: string): void;
+  /** Plain human/plain-text line. No-op in json. */
+  log(msg: string): void;
+  /** Emit the single JSON document. Only meaningful in json mode. */
+  json(payload: unknown): void;
+  /** Session outro. No-op in json / non-TTY. */
+  outro(msg: string): void;
+  /**
+   * Fail terminally. json: prints `{ "error": message }` to stdout, exit 1.
+   * human (TTY): clack cancel(message), exit 1. human (non-TTY): stderr, exit 1.
+   */
+  fail(message: string): never;
+}
+
+function renderTable(
+  rows: Record<string, unknown>[],
+  columns?: string[],
+): string {
+  if (rows.length === 0) return color.dim("(no rows)");
+  const cols =
+    columns ??
+    Array.from(
+      rows.reduce<Set<string>>((set, row) => {
+        for (const key of Object.keys(row)) set.add(key);
+        return set;
+      }, new Set<string>()),
+    );
+  const cell = (value: unknown): string => {
+    if (value === null || value === undefined) 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: string, width: number) =>
+    text + " ".repeat(width - text.length);
+  const header = cols
+    .map((c, i) => color.bold(pad(c, widths[i] ?? 0)))
+    .join("  ");
+  const sep = 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}\n${color.dim(sep)}\n${body}`;
+}
+
+function renderKv(obj: Record<string, unknown>): string {
+  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 === undefined
+          ? ""
+          : typeof v === "object"
+            ? JSON.stringify(v)
+            : String(v);
+      return `${color.dim(`${k}:`.padEnd(width + 1))} ${str}`;
+    })
+    .join("\n");
+}
+
+/** Build an {@link Output} for the given mode. */
+export function createOutput(opts: { json: boolean }): Output {
+  const isJson = opts.json;
+  const interactive = !isJson && Boolean(process.stdout.isTTY);
+
+  return {
+    interactive,
+    isJson,
+
+    intro(title) {
+      if (!interactive) return;
+      clackIntro(title);
+    },
+
+    async step<T>(label: string, fn: () => Promise<T>): Promise<T> {
+      if (interactive) {
+        const s = spinner();
+        s.start(label);
+        try {
+          const result = await fn();
+          s.stop(`${color.green("✓")} ${label}`);
+          return result;
+        } catch (err) {
+          s.stop(`${color.red("✗")} ${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(`\n${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) {
+      // Only stdout write in json mode; pretty-printed, single document.
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    },
+
+    outro(msg) {
+      if (!interactive) return;
+      clackOutro(msg);
+    },
+
+    fail(message): never {
+      if (isJson) {
+        process.stdout.write(`${JSON.stringify({ error: message })}\n`);
+      } else if (interactive) {
+        cancel(message);
+      } else {
+        process.stderr.write(`${color.red("error")} ${message}\n`);
+      }
+      process.exit(1);
+    },
+  };
+}
+
+export { color };

package/src/lib/prompt.ts

@@ -0,0 +1,17 @@
+import { cancel, isCancel } from "@clack/prompts";
+
+/**
+ * Guard a clack prompt result. clack returns a cancellation symbol when the
+ * user hits Ctrl-C / Esc; this unwraps the value or aborts the whole CLI
+ * cleanly (exit 0 — a deliberate cancel, not an error).
+ *
+ * Re-export clack's `text`/`select`/`confirm`/`multiselect` from
+ * `@clack/prompts` directly in command files; wrap each call in `bail()`.
+ */
+export function bail<T>(value: T | symbol): T {
+  if (isCancel(value)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return value as T;
+}