@hogsend/cli 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.12.1",
+    "@hogsend/studio": "^0.13.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -42,8 +42,8 @@
     "@clack/prompts": "^1.5.0",
     "better-auth": "^1.6.11",
     "picocolors": "^1.1.1",
-    "@hogsend/db": "^0.12.1",
-    "@hogsend/engine": "^0.12.1"
+    "@hogsend/db": "^0.13.0",
+    "@hogsend/engine": "^0.13.0"
   },
   "scripts": {
     "prebuild": "node scripts/bundle-studio.mjs",

package/skills/hogsend-database/references/migrations.md

@@ -31,7 +31,7 @@ export default defineConfig({
   dbCredentials: {
     url:
       process.env.DATABASE_URL ??
-      "postgresql://growthhog:growthhog@localhost:5434/growthhog",
+      "postgresql://hogsend:hogsend@localhost:5434/hogsend",
   },
 });
 ```

package/skills/hogsend-deploy/SKILL.md

@@ -33,6 +33,17 @@ This is the **consumer** deploy guide — for shipping the app you scaffolded wi
 - **Hatchet-Lite is your orchestration engine.** The worker connects to it over
   gRPC with `HATCHET_CLIENT_TOKEN` + `HATCHET_CLIENT_HOST_PORT`. Locally it runs
   via `docker-compose.yml`; in prod it's its own service.
+- **Mint `HATCHET_CLIENT_TOKEN` headlessly.** `hogsend hatchet token
+  --url <hatchet-url> --email <e> --password <p> [--tenant <slug>]` drives
+  hatchet-lite's REST API (register-or-login → ensure tenant → create token)
+  and prints ONLY the token to stdout — pipe it straight into
+  `railway variables --set "HATCHET_CLIENT_TOKEN=$(...)"`. No dashboard
+  copy-paste needed.
+- **Lock down a public hatchet-lite.** It ships with OPEN registration — anyone
+  who finds the public URL can create an account on your Hatchet dashboard. Set
+  `SERVER_ALLOW_SIGNUP=false` and seed a real admin via `ADMIN_EMAIL` /
+  `ADMIN_PASSWORD` (never leave the `admin@example.com` / `Admin123!!`
+  defaults). `hogsend hatchet token` then logs in with those credentials.
 - **Three required env vars, the rest optional.** `DATABASE_URL`,
   `BETTER_AUTH_SECRET`, `RESEND_API_KEY` are hard-required at boot; PostHog,
   webhook secrets, and the admin key are opt-in.

package/src/__tests__/hatchet-token.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it } from "vitest";
+import { HatchetTokenError, mintHatchetToken } from "../lib/hatchet-token.js";
+
+/**
+ * Unit tests for the headless HATCHET_CLIENT_TOKEN mint flow
+ * (register-or-login → ensure tenant → create API token) against a scripted
+ * fake of hatchet-lite's REST API. Covers:
+ *  - happy path: fresh register → seeded "default" tenant found → token
+ *  - locked-down instance: register 400 ("user signups are disabled") →
+ *    login fallback with the seeded admin credentials
+ *  - tenant missing from memberships → created with engineVersion V1
+ *  - bad credentials → HatchetTokenError mentioning login
+ *  - token is read from CreateAPITokenResponse.token verbatim
+ */
+
+interface Call {
+  url: string;
+  method: string;
+  body?: unknown;
+  cookie?: string;
+}
+
+type Route = (call: Call) => Response;
+
+function fakeHatchet(routes: Record<string, Route>): {
+  fetchImpl: typeof fetch;
+  calls: Call[];
+} {
+  const calls: Call[] = [];
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    const path = new URL(url).pathname;
+    const headers = new Headers(init?.headers);
+    const call: Call = {
+      url,
+      method: init?.method ?? "GET",
+      body: init?.body ? JSON.parse(String(init.body)) : undefined,
+      cookie: headers.get("cookie") ?? undefined,
+    };
+    calls.push(call);
+    const route = routes[`${call.method} ${path}`];
+    if (!route) {
+      return new Response(JSON.stringify({ errors: [] }), { status: 404 });
+    }
+    return route(call);
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const json = (body: unknown, init?: ResponseInit) =>
+  new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    ...init,
+  });
+
+const loginOk = () =>
+  json(
+    { metadata: { id: "u1" }, email: "a@b.co" },
+    { headers: { "set-cookie": "hatchet=sess-abc; Path=/; HttpOnly" } },
+  );
+
+const membershipsWith = (slug: string, id: string) =>
+  json({ rows: [{ tenant: { metadata: { id }, slug } }] });
+
+describe("mintHatchetToken", () => {
+  it("registers, finds the seeded default tenant, and mints the token", async () => {
+    const { fetchImpl, calls } = fakeHatchet({
+      "POST /api/v1/users/register": () => json({ metadata: { id: "u1" } }),
+      "POST /api/v1/users/login": loginOk,
+      "GET /api/v1/users/memberships": () =>
+        membershipsWith("default", "tenant-1"),
+      "POST /api/v1/tenants/tenant-1/api-tokens": () =>
+        json({ token: "jwt-token-123" }),
+    });
+
+    const result = await mintHatchetToken({
+      url: "https://hatchet.example.com/",
+      email: "admin@acme.com",
+      password: "Sup3rSecret!!",
+      fetchImpl,
+    });
+
+    expect(result).toEqual({
+      token: "jwt-token-123",
+      tenantId: "tenant-1",
+      tenantSlug: "default",
+      createdTenant: false,
+      registered: true,
+    });
+    // Authed calls carry the session cookie from login.
+    const tokenCall = calls.find((c) => c.url.includes("api-tokens"));
+    expect(tokenCall?.cookie).toBe("hatchet=sess-abc");
+    expect(tokenCall?.body).toEqual({ name: "hogsend" });
+  });
+
+  it("falls back to login when signups are disabled (SERVER_ALLOW_SIGNUP=false)", async () => {
+    const { fetchImpl } = fakeHatchet({
+      "POST /api/v1/users/register": () =>
+        json(
+          { errors: [{ description: "user signups are disabled" }] },
+          { status: 400 },
+        ),
+      "POST /api/v1/users/login": loginOk,
+      "GET /api/v1/users/memberships": () =>
+        membershipsWith("default", "tenant-1"),
+      "POST /api/v1/tenants/tenant-1/api-tokens": () =>
+        json({ token: "jwt-token-456" }),
+    });
+
+    const result = await mintHatchetToken({
+      url: "https://hatchet.example.com",
+      email: "admin@acme.com",
+      password: "Sup3rSecret!!",
+      fetchImpl,
+    });
+
+    expect(result.token).toBe("jwt-token-456");
+    expect(result.registered).toBe(false);
+  });
+
+  it("creates the tenant (engineVersion V1) when the slug has no membership", async () => {
+    const { fetchImpl, calls } = fakeHatchet({
+      "POST /api/v1/users/register": () =>
+        json({ errors: [] }, { status: 400 }),
+      "POST /api/v1/users/login": loginOk,
+      "GET /api/v1/users/memberships": () => json({ rows: [] }),
+      "POST /api/v1/tenants": () =>
+        json({ metadata: { id: "tenant-9" }, slug: "hogsend" }),
+      "POST /api/v1/tenants/tenant-9/api-tokens": () =>
+        json({ token: "jwt-token-789" }),
+    });
+
+    const result = await mintHatchetToken({
+      url: "https://hatchet.example.com",
+      email: "admin@acme.com",
+      password: "Sup3rSecret!!",
+      tenantSlug: "hogsend",
+      tokenName: "worker",
+      fetchImpl,
+    });
+
+    expect(result).toMatchObject({
+      token: "jwt-token-789",
+      tenantId: "tenant-9",
+      tenantSlug: "hogsend",
+      createdTenant: true,
+    });
+    const createCall = calls.find((c) => c.url.endsWith("/api/v1/tenants"));
+    expect(createCall?.body).toEqual({
+      name: "hogsend",
+      slug: "hogsend",
+      engineVersion: "V1",
+    });
+    expect(createCall?.cookie).toBe("hatchet=sess-abc");
+    const tokenCall = calls.find((c) => c.url.includes("api-tokens"));
+    expect(tokenCall?.body).toEqual({ name: "worker" });
+  });
+
+  it("throws a login error (with Hatchet's description) on bad credentials", async () => {
+    const { fetchImpl } = fakeHatchet({
+      "POST /api/v1/users/register": () =>
+        json({ errors: [] }, { status: 400 }),
+      "POST /api/v1/users/login": () =>
+        json(
+          { errors: [{ description: "invalid email or password" }] },
+          { status: 401 },
+        ),
+    });
+
+    await expect(
+      mintHatchetToken({
+        url: "https://hatchet.example.com",
+        email: "admin@acme.com",
+        password: "wrong",
+        fetchImpl,
+      }),
+    ).rejects.toThrowError(/login failed \(401\): invalid email or password/);
+  });
+
+  it("rejects an invalid base url and an invalid tenant slug without fetching", async () => {
+    const { fetchImpl, calls } = fakeHatchet({});
+
+    await expect(
+      mintHatchetToken({
+        url: "hatchet.example.com",
+        email: "a@b.co",
+        password: "x",
+        fetchImpl,
+      }),
+    ).rejects.toBeInstanceOf(HatchetTokenError);
+
+    await expect(
+      mintHatchetToken({
+        url: "https://hatchet.example.com",
+        email: "a@b.co",
+        password: "x",
+        tenantSlug: "Not A Slug",
+        fetchImpl,
+      }),
+    ).rejects.toThrowError(/invalid tenant slug/);
+
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/commands/hatchet.ts

@@ -0,0 +1,181 @@
+import { parseArgs } from "node:util";
+import { HatchetTokenError, mintHatchetToken } from "../lib/hatchet-token.js";
+import { color } from "../lib/output.js";
+import type { Command, CommandContext } from "./types.js";
+
+/**
+ * `hogsend hatchet token` — mint a HATCHET_CLIENT_TOKEN headlessly against a
+ * hatchet-lite instance (register-or-login → ensure tenant → create API token)
+ * so the Railway-template "copy the token out of the dashboard" step goes away.
+ *
+ * Output contract: on success the ONLY thing written to stdout is the token
+ * (+ newline) so it pipes cleanly into `railway variables --set` etc. All
+ * progress goes to stderr; --json swaps stdout for a single JSON document.
+ */
+
+const usage = `hogsend hatchet token [options]
+
+Mint a Hatchet API token (HATCHET_CLIENT_TOKEN) headlessly against a
+hatchet-lite instance. Registers the account if the instance still allows
+signups, otherwise logs in (e.g. with the seeded ADMIN_EMAIL/ADMIN_PASSWORD on
+a locked-down deployment), ensures the tenant exists, and creates the token.
+
+On success the token is the ONLY thing printed to stdout — pipe it straight
+into your platform's variable store. Progress and errors go to stderr.
+
+Options:
+  --url <hatchet-url>    Hatchet base URL (or HATCHET_URL), e.g. the
+                         hatchet-lite service's public https URL. Required —
+                         this command never falls back to HOGSEND_API_URL or
+                         the localhost default (those target your Hogsend
+                         API, not Hatchet). NOTE: for this command the global
+                         --url targets HATCHET, not your Hogsend API.
+  --email <e>            Account email (or HATCHET_ADMIN_EMAIL).
+  --password <p>         Account password (or HATCHET_ADMIN_PASSWORD). Prefer
+                         the env var — flags can leak into shell history.
+  --tenant <slug>        Tenant slug (default "default", the seeded tenant).
+                         Created (engine V1) if it doesn't exist yet.
+  --token-name <n>       Display name for the minted token (default "hogsend").
+  --json                 Emit { token, tenantId, ... } as one JSON document.
+  -h, --help             Show this help.
+
+Examples:
+  hogsend hatchet token --url https://hatchet-lite-production.up.railway.app \\
+    --email admin@example.com --password 'Admin123!!'
+  HATCHET_ADMIN_PASSWORD=... hogsend hatchet token --url https://... --email admin@acme.com
+  railway variables --service hogsend-worker \\
+    --set "HATCHET_CLIENT_TOKEN=$(hogsend hatchet token --url ... --email ... --password ...)"
+
+Lockdown note: hatchet-lite ships with OPEN registration — anyone who finds the
+public URL can create an account. On a public deployment set
+SERVER_ALLOW_SIGNUP=false (plus a real ADMIN_EMAIL/ADMIN_PASSWORD, which
+hatchet-lite seeds at boot); this command then logs in with those credentials.`;
+
+interface TokenFlags {
+  url?: string;
+  email?: string;
+  password?: string;
+  tenant?: string;
+  tokenName?: string;
+}
+
+function parseTokenFlags(argv: string[]): TokenFlags {
+  const { values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      url: { type: "string" },
+      email: { type: "string" },
+      password: { type: "string" },
+      tenant: { type: "string" },
+      "token-name": { type: "string" },
+    },
+  });
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined;
+  return {
+    url: str(values.url),
+    email: str(values.email),
+    password: str(values.password),
+    tenant: str(values.tenant),
+    tokenName: str(values["token-name"]),
+  };
+}
+
+/**
+ * Terminal failure that honors the stdout-is-only-the-token contract: human
+ * mode always writes to stderr (even in a TTY — clack's cancel would land on
+ * stdout); --json keeps the single-JSON-document contract via out.fail.
+ */
+function failToStderr(ctx: CommandContext, message: string): never {
+  if (ctx.json) {
+    ctx.out.fail(message);
+  }
+  process.stderr.write(`${color.red("error")} ${message}\n`);
+  process.exit(1);
+}
+
+async function runToken(ctx: CommandContext, argv: string[]): Promise<void> {
+  const flags = parseTokenFlags(argv);
+
+  // The router owns the global `--url` and resolves it into cfg.baseUrl before
+  // this command sees argv — an explicit `--url <hatchet-url>` arrives as
+  // cfg.baseUrl with cfg.urlExplicit set. We deliberately do NOT fall back to
+  // cfg.baseUrl otherwise: it ALWAYS resolves (HOGSEND_API_URL env/.env, then
+  // localhost:3002), which would silently POST the Hatchet admin credentials
+  // to the Hogsend API with a misleading login error. Without an explicit
+  // --url, HATCHET_URL is required and the missing-url error below fires. The
+  // local flag parse is kept first for safety should the router ever stop
+  // owning --url.
+  const url =
+    flags.url ??
+    (ctx.cfg.urlExplicit ? ctx.cfg.baseUrl : undefined) ??
+    process.env.HATCHET_URL;
+  const email = flags.email ?? process.env.HATCHET_ADMIN_EMAIL;
+  const password = flags.password ?? process.env.HATCHET_ADMIN_PASSWORD;
+
+  const missing: string[] = [];
+  if (!url) missing.push("--url (or HATCHET_URL)");
+  if (!email) missing.push("--email (or HATCHET_ADMIN_EMAIL)");
+  if (!password) missing.push("--password (or HATCHET_ADMIN_PASSWORD)");
+  if (missing.length > 0 || !url || !email || !password) {
+    failToStderr(ctx, `missing ${missing.join(", ")}`);
+  }
+
+  // Progress goes to stderr ONLY — stdout is reserved for the token.
+  const onProgress = ctx.json
+    ? undefined
+    : (msg: string) => process.stderr.write(`${color.dim(msg)}\n`);
+  onProgress?.(`hatchet: ${url}`);
+
+  try {
+    const result = await mintHatchetToken({
+      url,
+      email,
+      password,
+      tenantSlug: flags.tenant,
+      tokenName: flags.tokenName,
+      onProgress,
+    });
+
+    if (ctx.json) {
+      ctx.out.json(result);
+      return;
+    }
+    process.stdout.write(`${result.token}\n`);
+  } catch (err) {
+    if (err instanceof HatchetTokenError) {
+      failToStderr(ctx, err.message);
+    }
+    throw err;
+  }
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[0];
+  const rest = ctx.argv.slice(1);
+
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    ctx.out.log(usage);
+    return;
+  }
+  if (rest.includes("-h") || rest.includes("--help")) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  switch (sub) {
+    case "token":
+      return runToken(ctx, rest);
+    default:
+      failToStderr(ctx, `unknown subcommand "${sub}" — expected token`);
+  }
+}
+
+export const hatchetCommand: Command = {
+  name: "hatchet",
+  summary: "Hatchet helpers — mint a HATCHET_CLIENT_TOKEN headlessly",
+  usage,
+  run,
+};

package/src/commands/index.ts

@@ -6,6 +6,7 @@ import { domainCommand } from "./domain.js";
 import { ejectCommand } from "./eject.js";
 import { emailsCommand } from "./emails.js";
 import { eventsCommand } from "./events.js";
+import { hatchetCommand } from "./hatchet.js";
 import { journeysCommand } from "./journeys.js";
 import { patchCommand } from "./patch.js";
 import { setupCommand } from "./setup.js";
@@ -34,6 +35,7 @@ export const commands: Command[] = [
   campaignsCommand,
   webhooksCommand,
   domainCommand,
+  hatchetCommand,
   studioCommand,
   devCommand,
   setupCommand,

package/src/lib/config.ts

@@ -14,6 +14,13 @@ export interface ResolvedConfig {
    * to the admin key since `full-admin` implies `ingest`.
    */
   dataKey: string | undefined;
+  /**
+   * True when `baseUrl` came from an explicit `--url` flag (vs env / .env /
+   * the localhost default). Commands that target a DIFFERENT host than the
+   * Hogsend API (e.g. `hatchet token`) must only honor `baseUrl` when this is
+   * set, so a cwd `.env`'s HOGSEND_API_URL can't silently become their target.
+   */
+  urlExplicit: boolean;
 }
 
 /** Global flags parsed off the front of any command's argv. */
@@ -165,5 +172,6 @@ export function resolveConfig(
     baseUrl: baseUrlRaw.replace(/\/+$/, ""),
     adminKey: adminKey && adminKey.length > 0 ? adminKey : undefined,
     dataKey: dataKey && dataKey.length > 0 ? dataKey : undefined,
+    urlExplicit: flags.url !== undefined,
   };
 }