@hogsend/cli 0.18.0 → 0.20.0

package/dist/bin.js

@@ -91,6 +91,10 @@ function createAdminClient(cfg) {
       body,
       auth: true
     }),
+    put: (path, body) => request(cfg.baseUrl, cfg.adminKey, missing, "PUT", path, {
+      body,
+      auth: true
+    }),
     del: (path, body) => request(cfg.baseUrl, cfg.adminKey, missing, "DELETE", path, {
       body,
       auth: true
@@ -459,16 +463,796 @@ async function run(ctx) {
       );
   }
 }
-var campaignsCommand = {
-  name: "campaigns",
-  summary: "Queue a broadcast to a list/bucket, or check its status",
-  usage,
-  run
+var campaignsCommand = {
+  name: "campaigns",
+  summary: "Queue a broadcast to a list/bucket, or check its status",
+  usage,
+  run
+};
+
+// src/commands/connect.ts
+import { parseArgs as parseArgs2 } from "util";
+import { confirm } from "@clack/prompts";
+
+// src/lib/browser.ts
+import { spawn } from "child_process";
+function openBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/loopback.ts
+import { createServer } from "http";
+
+// src/lib/oauth.ts
+import { createHash, randomBytes } from "crypto";
+var POSTHOG_CLIENT_ID = "https://hogsend.com/.well-known/hogsend-posthog-client.json";
+var POSTHOG_SCOPES = "person:read person:write project:read hog_function:write";
+var LOOPBACK_PORTS = [8423, 8424, 8425];
+var CALLBACK_PATH = "/callback";
+var CALLBACK_TIMEOUT_MS = 3e5;
+var REQUIRED_ACCESS_LEVEL = "team";
+var DISCOVERY_TIMEOUT_MS = 1e4;
+function computeChallenge(verifier) {
+  return createHash("sha256").update(verifier, "ascii").digest("base64url");
+}
+function generatePkce() {
+  const verifier = randomBytes(32).toString("base64url");
+  return { verifier, challenge: computeChallenge(verifier), method: "S256" };
+}
+function generateState() {
+  return randomBytes(16).toString("base64url");
+}
+async function discoverOAuthServer(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${opts.privateHost}/.well-known/oauth-authorization-server`;
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS)
+    });
+  } catch (cause) {
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    return { status: "error", message: `OAuth discovery failed: ${msg}` };
+  }
+  if (res.status === 404 || res.status === 410) {
+    return { status: "unsupported" };
+  }
+  if (!res.ok) {
+    return {
+      status: "error",
+      message: `OAuth discovery failed (HTTP ${res.status})`
+    };
+  }
+  let doc;
+  try {
+    doc = await res.json();
+  } catch {
+    return {
+      status: "error",
+      message: "malformed discovery document (not JSON)"
+    };
+  }
+  if (typeof doc !== "object" || doc === null || typeof doc.issuer !== "string" || typeof doc.authorization_endpoint !== "string" || typeof doc.token_endpoint !== "string") {
+    return {
+      status: "error",
+      message: "malformed discovery document (missing issuer / authorization_endpoint / token_endpoint)"
+    };
+  }
+  return { status: "ok", metadata: doc };
+}
+function buildAuthorizeUrl(opts) {
+  const url = new URL(opts.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", opts.clientId);
+  url.searchParams.set("redirect_uri", opts.redirectUri);
+  url.searchParams.set("scope", opts.scope);
+  url.searchParams.set("state", opts.state);
+  url.searchParams.set("code_challenge", opts.pkce.challenge);
+  url.searchParams.set("code_challenge_method", opts.pkce.method);
+  if (opts.requiredAccessLevel !== void 0) {
+    url.searchParams.set("required_access_level", opts.requiredAccessLevel);
+  }
+  return url.toString();
+}
+async function exchangeCode(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const res = await fetchImpl(opts.tokenEndpoint, {
+    method: "POST",
+    headers: {
+      // URLSearchParams sets this automatically; explicit for clarity.
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: opts.code,
+      redirect_uri: opts.redirectUri,
+      client_id: opts.clientId,
+      code_verifier: opts.codeVerifier
+    })
+  });
+  if (!res.ok) {
+    const text3 = await res.text().catch(() => "");
+    let detail = text3;
+    try {
+      const parsed = JSON.parse(text3);
+      if (typeof parsed === "object" && parsed !== null && typeof parsed.error === "string") {
+        detail = parsed.error;
+      }
+    } catch {
+    }
+    throw new Error(
+      `token exchange failed (${res.status})${detail ? `: ${detail}` : ""}`
+    );
+  }
+  const json2 = await res.json();
+  if (typeof json2.access_token !== "string" || json2.access_token === "") {
+    throw new Error("token response missing access_token");
+  }
+  if (typeof json2.refresh_token !== "string" || json2.refresh_token === "") {
+    throw new Error(
+      "token response missing refresh_token \u2014 cannot store a long-lived credential"
+    );
+  }
+  return json2;
+}
+
+// src/lib/loopback.ts
+var LoopbackError = class extends Error {
+  reason;
+  detail;
+  constructor(reason, message, detail) {
+    super(message);
+    this.name = "LoopbackError";
+    this.reason = reason;
+    this.detail = detail;
+  }
+};
+var page = (title, body) => `<!doctype html><html><head><meta charset="utf-8"><title>Hogsend</title><style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:6rem auto;padding:0 1rem;color:#1a1a1a}</style></head><body><h1>${title}</h1><p>${body}</p></body></html>`;
+var SUCCESS_HTML = page(
+  "Connected",
+  "You can close this tab and return to your terminal."
+);
+var DENIED_HTML = page(
+  "Not connected",
+  "Authorization was denied. Close this tab and re-run the command if that was a mistake."
+);
+var MISMATCH_HTML = page(
+  "Not connected",
+  "State mismatch. Close this tab and re-run the command."
+);
+var NO_CODE_HTML = page(
+  "Not connected",
+  "The callback carried no authorization code. Close this tab and re-run the command."
+);
+function tryListen(port, handler) {
+  return new Promise((resolve3, reject) => {
+    const server = createServer(handler);
+    const onError = (err) => {
+      server.close();
+      if (err.code === "EADDRINUSE") resolve3(null);
+      else reject(err);
+    };
+    server.once("error", onError);
+    server.listen({ host: "127.0.0.1", port }, () => {
+      server.removeListener("error", onError);
+      resolve3(server);
+    });
+  });
+}
+async function startLoopbackServer(opts) {
+  const callbackPath = opts.callbackPath ?? CALLBACK_PATH;
+  let settled = false;
+  let settleResolve;
+  let settleReject;
+  const settlePromise = new Promise((resolve3, reject) => {
+    settleResolve = resolve3;
+    settleReject = reject;
+  });
+  settlePromise.catch(() => {
+  });
+  const handler = (req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (url.pathname !== callbackPath) {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("Not found");
+      return;
+    }
+    if (settled) {
+      res.writeHead(410, { "content-type": "text/plain; charset=utf-8" });
+      res.end("This callback was already handled \u2014 return to your terminal.");
+      return;
+    }
+    settled = true;
+    const respond = (status, html) => {
+      res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
+      res.end(html);
+    };
+    const error = url.searchParams.get("error");
+    if (error !== null) {
+      respond(200, DENIED_HTML);
+      const detail = url.searchParams.get("error_description") ?? error;
+      settleReject(
+        error === "access_denied" ? new LoopbackError(
+          "consent_denied",
+          "authorization was denied in PostHog",
+          detail
+        ) : new LoopbackError(
+          "oauth_error",
+          `the OAuth callback returned an error: ${error}`,
+          detail
+        )
+      );
+      return;
+    }
+    const state = url.searchParams.get("state");
+    if (state === null || state !== opts.state) {
+      respond(400, MISMATCH_HTML);
+      settleReject(
+        new LoopbackError(
+          "state_mismatch",
+          "state mismatch on the OAuth callback \u2014 possible CSRF; retry the command"
+        )
+      );
+      return;
+    }
+    const code = url.searchParams.get("code");
+    if (code === null || code === "") {
+      respond(400, NO_CODE_HTML);
+      settleReject(
+        new LoopbackError(
+          "oauth_error",
+          "the OAuth callback carried no authorization code"
+        )
+      );
+      return;
+    }
+    respond(200, SUCCESS_HTML);
+    settleResolve({ code });
+  };
+  let server = null;
+  for (const port2 of opts.ports) {
+    server = await tryListen(port2, handler);
+    if (server) break;
+  }
+  if (!server) {
+    throw new LoopbackError(
+      "ports_busy",
+      `ports ${opts.ports.join(", ")} on 127.0.0.1 are all in use`
+    );
+  }
+  const address = server.address();
+  const port = address !== null && typeof address === "object" ? address.port : 0;
+  const bound = server;
+  return {
+    port,
+    redirectUri: `http://127.0.0.1:${port}${callbackPath}`,
+    waitForCallback(waitOpts) {
+      const timeoutMs = waitOpts?.timeoutMs ?? CALLBACK_TIMEOUT_MS;
+      let timer2;
+      const timeout = new Promise((_, reject) => {
+        timer2 = setTimeout(() => {
+          reject(
+            new LoopbackError(
+              "timeout",
+              "timed out waiting for the OAuth callback (5 minutes)"
+            )
+          );
+        }, timeoutMs);
+      });
+      return Promise.race([settlePromise, timeout]).finally(() => {
+        clearTimeout(timer2);
+      });
+    },
+    close() {
+      return new Promise((resolve3) => {
+        bound.closeAllConnections();
+        bound.close(() => resolve3());
+      });
+    }
+  };
+}
+
+// src/lib/connect-flow.ts
+var ConnectError = class extends Error {
+  verdict;
+  hint;
+  constructor(verdict, message, hint) {
+    super(message);
+    this.name = "ConnectError";
+    this.verdict = verdict;
+    this.hint = hint;
+  }
+};
+var HINT_NOT_CONFIGURED = "Set POSTHOG_API_KEY (and POSTHOG_HOST for EU/self-hosted) on the instance, redeploy, then re-run. The server's PostHog config tells the CLI which region to authorize against.";
+var hintOauthUnsupported = (privateHost) => `${privateHost} doesn't advertise an OAuth server (discovery returned 404).
+Self-hosted PostHog builds may not ship OAuth. Use a personal API key instead:
+
+  1. In PostHog: Settings -> User -> Personal API keys -> create a key scoped
+     person:read, person:write, project:read, hog_function:write
+  2. Set POSTHOG_PERSONAL_API_KEY=<key> on your Hogsend instance (api + worker)
+  3. Redeploy \u2014 person reads and loop provisioning use the key automatically.`;
+var HINT_PORTS = "Ports 8423-8425 on 127.0.0.1 are all in use \u2014 free one and re-run. The OAuth callback must land on one of these fixed ports; they are registered in Hogsend's OAuth client document.";
+var SSH_NOTE = `The consent page must open in a browser on THIS machine \u2014 the OAuth callback
+returns to 127.0.0.1 here. On a remote/SSH session this cannot complete: run
+the command from your laptop instead and point --url at the instance (the CLI
+never needs to run on the server).`;
+function isLoopbackUrl(publicUrl) {
+  try {
+    const host = new URL(publicUrl).hostname.toLowerCase();
+    return host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "[::1]" || host === "::1" || host.endsWith(".localhost");
+  } catch {
+    return false;
+  }
+}
+var LOOPBACK_URL_NOTE = `Credential stored \u2014 but this instance's API_PUBLIC_URL is a loopback
+address, so PostHog Cloud cannot deliver webhooks to it. Provisioning was
+skipped (a destination pointing at localhost would be unreachable).
+
+Once deployed, wire the loop against the real instance:
+
+  hogsend connect posthog --provision-only --url https://your-instance`;
+var WEBHOOK_SECRET_NOTE = `Credential stored \u2014 but the PostHog -> Hogsend event loop needs a shared
+webhook secret, and this instance doesn't have one yet. Finish the loop:
+
+  1. Generate a secret:        openssl rand -hex 32
+  2. Set it on the instance:   POSTHOG_WEBHOOK_SECRET=<secret>  (api AND worker)
+  3. Redeploy, then run:       hogsend connect posthog --provision-only`;
+var errMsg = (err) => err instanceof Error ? err.message : String(err);
+var httpErrorBody = (err) => {
+  if (!isHttpError(err)) return void 0;
+  const body = err.body;
+  if (body && typeof body === "object" && "error" in body && typeof body.error === "string") {
+    return body.error;
+  }
+  return void 0;
+};
+function fromLoopbackError(err) {
+  switch (err.reason) {
+    case "consent_denied":
+      return new ConnectError(
+        "consent_denied",
+        "authorization was denied in PostHog \u2014 re-run the command if that was a mistake"
+      );
+    case "state_mismatch":
+      return new ConnectError(
+        "state_mismatch",
+        "state mismatch on the OAuth callback \u2014 possible CSRF; retry the command"
+      );
+    case "timeout":
+      return new ConnectError(
+        "callback_timeout",
+        "timed out waiting for the OAuth callback (5 minutes) \u2014 re-run when you're ready to approve in the browser"
+      );
+    case "ports_busy":
+      return new ConnectError("port_unavailable", err.message, HINT_PORTS);
+    case "oauth_error":
+      return new ConnectError("exchange_failed", err.message);
+  }
+}
+async function runProvisionOnly(deps, info, base) {
+  if (info.webhookSecretConfigured === false) {
+    deps.out.note(WEBHOOK_SECRET_NOTE, "Webhook secret missing");
+    throw new ConnectError(
+      "webhook_secret_missing",
+      "POSTHOG_WEBHOOK_SECRET is not set on the instance \u2014 nothing to provision against"
+    );
+  }
+  if (isLoopbackUrl(info.apiPublicUrl)) {
+    deps.out.note(LOOPBACK_URL_NOTE, "Instance not publicly reachable");
+    throw new ConnectError(
+      "api_public_url_unreachable",
+      `API_PUBLIC_URL is ${info.apiPublicUrl} \u2014 PostHog cannot deliver webhooks to a loopback address`
+    );
+  }
+  let result;
+  try {
+    result = await deps.out.step(
+      `POST ${base}/v1/admin/analytics/provision-loop`,
+      () => deps.http.post(
+        "/v1/admin/analytics/provision-loop",
+        {}
+      )
+    );
+  } catch (err) {
+    if (isHttpError(err) && err.status === 409 && httpErrorBody(err) === "no_posthog_credential") {
+      throw new ConnectError(
+        "no_credential",
+        "no PostHog credential is stored on this instance",
+        "run `hogsend connect posthog` first"
+      );
+    }
+    throw new ConnectError("provision_failed", errMsg(err));
+  }
+  printProvisioned(deps.out, result);
+  return {
+    verdict: "connected",
+    providerId: "posthog",
+    instance: base,
+    posthog: null,
+    credential: { stored: false },
+    provision: {
+      attempted: true,
+      ok: true,
+      created: result.created === true,
+      hogFunctionId: result.hogFunctionId ?? "",
+      webhookUrl: result.webhookUrl ?? ""
+    }
+  };
+}
+function printProvisioned(out, result) {
+  out.note(
+    [
+      "PostHog -> Hogsend loop provisioned",
+      `  webhookUrl     ${result.webhookUrl ?? "(unknown)"}`,
+      `  hogFunctionId  ${result.hogFunctionId ?? "(unknown)"}`,
+      `  created        ${result.created === true ? "yes" : "no (existing function adopted)"}`
+    ].join("\n")
+  );
+}
+async function runConnectPosthog(deps, opts) {
+  const base = deps.http.cfg.baseUrl;
+  const info = await deps.out.step(
+    `GET ${base}/v1/admin/analytics/connect-info`,
+    () => deps.http.get("/v1/admin/analytics/connect-info")
+  );
+  const privateHost = info.privateHost;
+  if (privateHost === null) {
+    throw new ConnectError(
+      "not_configured",
+      "this instance has no PostHog configuration",
+      HINT_NOT_CONFIGURED
+    );
+  }
+  if (opts.provisionOnly) {
+    return runProvisionOnly(deps, info, base);
+  }
+  if (info.hostExplicit === false) {
+    if (deps.interactive) {
+      const proceed = await deps.confirm(
+        `No POSTHOG_HOST set on the instance \u2014 assume PostHog US Cloud (${privateHost})?`
+      );
+      if (!proceed) {
+        throw new ConnectError(
+          "not_configured",
+          "set POSTHOG_HOST on the instance to pick the right region"
+        );
+      }
+    } else {
+      deps.out.log(
+        `warning: no POSTHOG_HOST set on the instance \u2014 assuming PostHog US Cloud (${privateHost}).`
+      );
+    }
+  }
+  if (info.personalKeyConfigured === true) {
+    deps.out.log(
+      "note: POSTHOG_PERSONAL_API_KEY is set on the instance; the OAuth credential will take precedence once stored."
+    );
+  }
+  const metadata = await deps.out.step(
+    `OAuth discovery at ${privateHost}`,
+    async () => {
+      const result = await deps.discover({ privateHost });
+      if (result.status === "unsupported") {
+        throw new ConnectError(
+          "oauth_unsupported",
+          `${privateHost} doesn't advertise an OAuth server (discovery returned 404)`,
+          hintOauthUnsupported(privateHost)
+        );
+      }
+      if (result.status === "error") {
+        throw new ConnectError("discovery_failed", result.message);
+      }
+      return result.metadata;
+    }
+  );
+  try {
+    if (new URL(metadata.issuer).origin !== new URL(privateHost).origin) {
+      deps.out.log(
+        `warning: discovery issuer ${metadata.issuer} differs from ${privateHost} \u2014 continuing.`
+      );
+    }
+  } catch {
+  }
+  const pkce = generatePkce();
+  const state = generateState();
+  let server;
+  try {
+    server = await deps.startLoopback({ ports: LOOPBACK_PORTS, state });
+  } catch (err) {
+    if (err instanceof LoopbackError) throw fromLoopbackError(err);
+    throw err;
+  }
+  let code;
+  try {
+    const authorizeUrl = buildAuthorizeUrl({
+      authorizationEndpoint: metadata.authorization_endpoint,
+      clientId: POSTHOG_CLIENT_ID,
+      redirectUri: server.redirectUri,
+      scope: POSTHOG_SCOPES,
+      state,
+      pkce,
+      requiredAccessLevel: REQUIRED_ACCESS_LEVEL
+    });
+    deps.out.note(
+      [
+        "About to authorize Hogsend against PostHog",
+        `  instance   ${base}`,
+        `  posthog    ${privateHost}`,
+        `  scopes     ${POSTHOG_SCOPES}`,
+        `  callback   ${server.redirectUri}`
+      ].join("\n")
+    );
+    const opened = opts.noBrowser ? false : deps.openBrowser(authorizeUrl);
+    deps.out.log(
+      opened ? "Opening your browser. If nothing happens, open this URL yourself:" : "Open this URL in a browser on THIS machine:"
+    );
+    deps.out.log(`  ${authorizeUrl}`);
+    if (!opened) {
+      deps.out.note(SSH_NOTE);
+    }
+    const callback = await deps.out.step(
+      "Waiting for PostHog authorization (Ctrl-C aborts)",
+      () => server.waitForCallback({ timeoutMs: opts.timeoutMs })
+    );
+    code = callback.code;
+  } catch (err) {
+    if (err instanceof LoopbackError) throw fromLoopbackError(err);
+    throw err;
+  } finally {
+    await server.close();
+  }
+  const tokenEndpoint = metadata.token_endpoint;
+  let tokens;
+  try {
+    tokens = await deps.out.step(
+      `Exchanging code at ${tokenEndpoint}`,
+      () => deps.exchangeCode({
+        tokenEndpoint,
+        clientId: POSTHOG_CLIENT_ID,
+        code,
+        codeVerifier: pkce.verifier,
+        redirectUri: server.redirectUri
+      })
+    );
+  } catch (err) {
+    throw new ConnectError("exchange_failed", errMsg(err));
+  }
+  const expiresAt = new Date(
+    deps.now().getTime() + tokens.expires_in * 1e3
+  ).toISOString();
+  const scopes = (tokens.scope ?? POSTHOG_SCOPES).split(" ");
+  const scopedTeams = tokens.scoped_teams ?? [];
+  const scopedOrganizations = tokens.scoped_organizations ?? [];
+  try {
+    await deps.out.step(
+      `PUT ${base}/v1/admin/provider-credentials/posthog`,
+      () => deps.http.put("/v1/admin/provider-credentials/posthog", {
+        kind: "oauth",
+        payload: {
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          expiresAt,
+          tokenEndpoint,
+          clientId: POSTHOG_CLIENT_ID,
+          scopes,
+          scopedTeams,
+          scopedOrganizations
+        }
+      })
+    );
+  } catch (err) {
+    throw new ConnectError("store_failed", errMsg(err));
+  }
+  const stored = {
+    providerId: "posthog",
+    instance: base,
+    posthog: {
+      privateHost,
+      issuer: metadata.issuer,
+      scopes: scopes.join(" "),
+      scopedTeams,
+      scopedOrganizations
+    },
+    credential: { stored: true, expiresAt }
+  };
+  if (opts.noProvision) {
+    return {
+      verdict: "connected_no_provision",
+      ...stored,
+      provision: { attempted: false, skipped: "no_provision_flag" }
+    };
+  }
+  if (info.webhookSecretConfigured === false) {
+    deps.out.note(WEBHOOK_SECRET_NOTE, "Webhook secret missing");
+    return {
+      verdict: "connected_no_provision",
+      ...stored,
+      provision: { attempted: false, skipped: "webhook_secret_missing" }
+    };
+  }
+  if (isLoopbackUrl(info.apiPublicUrl)) {
+    deps.out.note(LOOPBACK_URL_NOTE, "Instance not publicly reachable");
+    return {
+      verdict: "connected_no_provision",
+      ...stored,
+      provision: { attempted: false, skipped: "api_public_url_unreachable" }
+    };
+  }
+  try {
+    const result = await deps.out.step(
+      `POST ${base}/v1/admin/analytics/provision-loop`,
+      () => deps.http.post(
+        "/v1/admin/analytics/provision-loop",
+        {}
+      )
+    );
+    printProvisioned(deps.out, result);
+    return {
+      verdict: "connected",
+      ...stored,
+      provision: {
+        attempted: true,
+        ok: true,
+        created: result.created === true,
+        hogFunctionId: result.hogFunctionId ?? "",
+        webhookUrl: result.webhookUrl ?? ""
+      }
+    };
+  } catch (err) {
+    const message = errMsg(err);
+    deps.out.log(
+      `The credential is stored, but provisioning the event loop failed: ${message}. Re-run with: hogsend connect posthog --provision-only`
+    );
+    return {
+      verdict: "connected_no_provision",
+      ...stored,
+      provision: { attempted: true, ok: false, error: message }
+    };
+  }
+}
+
+// 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/connect.ts
+var usage2 = `hogsend connect <provider> [--provision-only] [--no-provision] [--no-browser] [--json]
+
+Connect this Hogsend instance to an analytics provider via OAuth. Providers:
+
+  posthog    Authorize Hogsend against your PostHog region (PKCE, loopback
+             callback on 127.0.0.1), store the refresh token on the instance,
+             then provision the PostHog -> Hogsend event loop (a PostHog
+             destination posting to /v1/webhooks/posthog).
+
+The browser consent must happen on THIS machine (the OAuth callback lands on
+127.0.0.1). The target instance can be anywhere \u2014 point --url at it and run
+this command from your laptop, not from an SSH session on the server.
+
+Options:
+  --provision-only   Skip OAuth; (re-)provision the event loop using the
+                     already-stored credential.
+  --no-provision     Stop after storing the credential.
+  --no-browser       Don't spawn a browser; just print the authorize URL.
+  --url, --admin-key, --json, -h, --help   Global flags as usual.
+
+Exit code: 0 when a credential is stored (even if provisioning was skipped),
+1 otherwise.`;
+async function run2(ctx) {
+  const { values: values2, positionals } = parseArgs2({
+    args: ctx.argv,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      "provision-only": { type: "boolean", default: false },
+      "no-provision": { type: "boolean", default: false },
+      "no-browser": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (values2.help) {
+    ctx.out.log(usage2);
+    return;
+  }
+  const provider = positionals[0];
+  if (!provider) {
+    ctx.out.fail("missing provider \u2014 try: hogsend connect posthog");
+  }
+  if (provider !== "posthog") {
+    ctx.out.fail(`unknown provider "${provider}" \u2014 supported: posthog`);
+  }
+  if (values2["provision-only"] && values2["no-provision"]) {
+    ctx.out.fail("--provision-only and --no-provision are mutually exclusive");
+  }
+  try {
+    const target = new URL(ctx.cfg.baseUrl);
+    if (target.protocol === "http:" && target.hostname !== "localhost" && target.hostname !== "127.0.0.1") {
+      ctx.out.log(
+        color.yellow(
+          `warning: ${ctx.cfg.baseUrl} is plain http \u2014 OAuth tokens will be sent to it unencrypted; use https for remote instances.`
+        )
+      );
+    }
+  } catch {
+  }
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} connect`);
+  const deps = {
+    http: ctx.http,
+    out: ctx.out,
+    interactive: ctx.out.interactive,
+    discover: discoverOAuthServer,
+    startLoopback: startLoopbackServer,
+    exchangeCode,
+    openBrowser,
+    confirm: async (message) => bail(await confirm({ message })),
+    now: () => /* @__PURE__ */ new Date()
+  };
+  try {
+    const result = await runConnectPosthog(deps, {
+      provisionOnly: Boolean(values2["provision-only"]),
+      noProvision: Boolean(values2["no-provision"]),
+      noBrowser: Boolean(values2["no-browser"])
+    });
+    if (ctx.json) {
+      ctx.out.json({ ok: true, ...result });
+      return;
+    }
+    ctx.out.outro(
+      color.green(
+        `connect: posthog ${result.verdict === "connected" ? "connected" : "connected (loop not provisioned)"}`
+      )
+    );
+  } catch (error) {
+    if (error instanceof ConnectError) {
+      if (ctx.json) {
+        ctx.out.json({
+          ok: false,
+          verdict: error.verdict,
+          error: error.message,
+          hint: error.hint
+        });
+        process.exit(1);
+      }
+      ctx.out.note(
+        error.hint ? `${error.message}
+
+${error.hint}` : error.message
+      );
+      ctx.out.outro(color.red(`connect: ${error.verdict}`));
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+var connectCommand = {
+  name: "connect",
+  summary: "Connect an analytics provider via OAuth (posthog)",
+  usage: usage2,
+  run: run2
 };
 
 // src/commands/contacts.ts
-import { parseArgs as parseArgs2 } from "util";
-var usage2 = `hogsend contacts <subcommand> [options]
+import { parseArgs as parseArgs3 } from "util";
+var usage3 = `hogsend contacts <subcommand> [options]
 
 Inspect contacts via the admin API (/v1/admin/contacts) and upsert them via the
 data plane (PUT /v1/contacts).
@@ -573,7 +1357,7 @@ async function fetchOrFail(ctx, label, fn) {
   }
 }
 async function runList(ctx, argv) {
-  const { values: values2 } = parseArgs2({
+  const { values: values2 } = parseArgs3({
     args: argv,
     allowPositionals: true,
     options: {
@@ -584,7 +1368,7 @@ async function runList(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage2);
+    ctx.out.log(usage3);
     return;
   }
   const query = {
@@ -616,7 +1400,7 @@ async function runList(ctx, argv) {
   );
 }
 async function runGet(ctx, argv) {
-  const { values: values2, positionals } = parseArgs2({
+  const { values: values2, positionals } = parseArgs3({
     args: argv,
     allowPositionals: true,
     options: {
@@ -624,7 +1408,7 @@ async function runGet(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage2);
+    ctx.out.log(usage3);
     return;
   }
   const id = positionals[1];
@@ -671,7 +1455,7 @@ async function runGet(ctx, argv) {
   ctx.out.outro(`Contact ${color.cyan(contact.externalId)}`);
 }
 async function runTimeline(ctx, argv) {
-  const { values: values2, positionals } = parseArgs2({
+  const { values: values2, positionals } = parseArgs3({
     args: argv,
     allowPositionals: true,
     options: {
@@ -682,7 +1466,7 @@ async function runTimeline(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage2);
+    ctx.out.log(usage3);
     return;
   }
   const id = positionals[1];
@@ -736,7 +1520,7 @@ function summarizeTimelineEntry(entry) {
   return `${subject} [${String(d.status ?? "")}]`;
 }
 async function runUpsert(ctx, argv) {
-  const { values: values2 } = parseArgs2({
+  const { values: values2 } = parseArgs3({
     args: argv,
     allowPositionals: true,
     options: {
@@ -750,7 +1534,7 @@ async function runUpsert(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage2);
+    ctx.out.log(usage3);
     return;
   }
   const email = values2.email;
@@ -790,7 +1574,7 @@ async function runUpsert(ctx, argv) {
   const verb = res.created ? "created" : "updated";
   ctx.out.outro(`Contact ${color.cyan(res.id)} ${verb}.`);
 }
-async function run2(ctx) {
+async function run3(ctx) {
   const sub = ctx.argv[0];
   switch (sub) {
     case "list":
@@ -815,21 +1599,21 @@ async function run2(ctx) {
 var contactsCommand = {
   name: "contacts",
   summary: "List, inspect, trace, and upsert contacts",
-  usage: usage2,
-  run: run2
+  usage: usage3,
+  run: run3
 };
 
 // src/commands/dev.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { join as join3, resolve } from "path";
-import { parseArgs as parseArgs5 } from "util";
+import { parseArgs as parseArgs6 } from "util";
 
 // src/lib/proc.ts
-import { spawn } from "child_process";
+import { spawn as spawn2 } from "child_process";
 import { createInterface } from "readline";
 function spawnManaged(opts) {
-  const child = spawn(opts.cmd, opts.args, {
+  const child = spawn2(opts.cmd, opts.args, {
     cwd: opts.cwd,
     env: { ...process.env, FORCE_COLOR: "1", ...opts.env },
     stdio: ["ignore", "pipe", "pipe"],
@@ -930,7 +1714,7 @@ async function waitForHttp(url, timeoutMs) {
 
 // src/lib/setup-steps.ts
 import { spawnSync } from "child_process";
-import { randomBytes } from "crypto";
+import { randomBytes as randomBytes2 } from "crypto";
 import { copyFileSync, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { connect } from "net";
 import { join as join2 } from "path";
@@ -938,10 +1722,10 @@ import { join as join2 } from "path";
 // src/lib/config.ts
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-import { parseArgs as parseArgs3 } from "util";
+import { parseArgs as parseArgs4 } from "util";
 var DEFAULT_BASE_URL = "http://localhost:3002";
 function parseGlobalFlags(argv) {
-  const { values: values2, tokens } = parseArgs3({
+  const { values: values2, tokens } = parseArgs4({
     args: argv,
     allowPositionals: true,
     strict: false,
@@ -1022,7 +1806,7 @@ var SECRET_KEY = "BETTER_AUTH_SECRET";
 var PLACEHOLDER_PREFIX = "change-me";
 var PLACEHOLDER_PREFIXES = [PLACEHOLDER_PREFIX, "REPLACE_ME"];
 function generateSecret() {
-  return randomBytes(32).toString("hex");
+  return randomBytes2(32).toString("hex");
 }
 var COMPOSE_FILES = [
   "docker-compose.yml",
@@ -1215,8 +1999,8 @@ async function detectRunningInfra(cwd) {
 }
 
 // src/commands/events.ts
-import { parseArgs as parseArgs4 } from "util";
-var usage3 = `hogsend events <userId> [options]
+import { parseArgs as parseArgs5 } from "util";
+var usage4 = `hogsend events <userId> [options]
 hogsend events send <name> [options]
 
 Read a single user's event history (admin API), or send an event into the data
@@ -1262,14 +2046,14 @@ Examples:
   hogsend events user_123 --from 2026-01-01T00:00:00Z --json
   hogsend events send signup --user-id user_123 --prop plan=pro
   hogsend events send purchase --email a@b.com --props '{"amount":49}' --json`;
-async function run3(ctx) {
+async function run4(ctx) {
   if (ctx.argv[0] === "send") {
     return runSend2(ctx, ctx.argv.slice(1));
   }
   return runRead(ctx, ctx.argv);
 }
 async function runRead(ctx, argv) {
-  const { values: values2, positionals } = parseArgs4({
+  const { values: values2, positionals } = parseArgs5({
     args: argv,
     allowPositionals: true,
     options: {
@@ -1282,7 +2066,7 @@ async function runRead(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage3);
+    ctx.out.log(usage4);
     return;
   }
   const userId = positionals[0];
@@ -1338,7 +2122,7 @@ async function runRead(ctx, argv) {
   );
 }
 async function runSend2(ctx, argv) {
-  const { values: values2, positionals } = parseArgs4({
+  const { values: values2, positionals } = parseArgs5({
     args: argv,
     allowPositionals: true,
     options: {
@@ -1356,7 +2140,7 @@ async function runSend2(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage3);
+    ctx.out.log(usage4);
     return;
   }
   const name = positionals[0];
@@ -1494,12 +2278,12 @@ function summarizeProps(props) {
 var eventsCommand = {
   name: "events",
   summary: "Stream a user's event history, or send an event",
-  usage: usage3,
-  run: run3
+  usage: usage4,
+  run: run4
 };
 
 // src/commands/dev.ts
-var usage4 = `hogsend dev [options]
+var usage5 = `hogsend dev [options]
 hogsend dev --fire <event> [event-send options]
 
 Run the full local stack for a Hogsend app from one command:
@@ -1582,7 +2366,7 @@ function extractFire(argv) {
 }
 async function runFire(ctx, event, rest) {
   if (rest.includes("-h") || rest.includes("--help")) {
-    ctx.out.log(usage4);
+    ctx.out.log(usage5);
     return;
   }
   try {
@@ -1690,7 +2474,7 @@ async function prepareInfra(ctx, cwd, pkg) {
     ctx.out.log(color.dim("  no db:migrate script \u2014 skipping migrations"));
   }
 }
-async function run4(ctx) {
+async function run5(ctx) {
   const fire = extractFire(ctx.argv);
   if (fire && "error" in fire) {
     ctx.out.fail(fire.error);
@@ -1699,7 +2483,7 @@ async function run4(ctx) {
     await runFire(ctx, fire.event, fire.rest);
     return;
   }
-  const { values: values2 } = parseArgs5({
+  const { values: values2 } = parseArgs6({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -1710,7 +2494,7 @@ async function run4(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage4);
+    ctx.out.log(usage5);
     return;
   }
   const cwd = resolve(values2.cwd ?? process.cwd());
@@ -1817,12 +2601,12 @@ ${color.dim("Shutting down\u2026")}`);
 var devCommand = {
   name: "dev",
   summary: "Run the full local stack: infra, API + worker, health, URLs",
-  usage: usage4,
-  run: run4
+  usage: usage5,
+  run: run5
 };
 
 // src/commands/doctor.ts
-import { parseArgs as parseArgs6 } from "util";
+import { parseArgs as parseArgs7 } from "util";
 
 // src/lib/skills.ts
 import {
@@ -1954,7 +2738,26 @@ function skillsNudge(ctx) {
     "Skills out of date"
   );
 }
-var usage5 = `hogsend doctor [--url <baseUrl>] [--admin-key <key>] [--json]
+function analyticsNudge(ctx) {
+  if (ctx.json) return;
+  const dotenv = loadDotEnv(process.cwd());
+  const captureKey = process.env.POSTHOG_API_KEY ?? dotenv.POSTHOG_API_KEY;
+  const personalKey = process.env.POSTHOG_PERSONAL_API_KEY ?? dotenv.POSTHOG_PERSONAL_API_KEY;
+  if (!captureKey || personalKey) return;
+  ctx.out.note(
+    [
+      "POSTHOG_API_KEY is set without POSTHOG_PERSONAL_API_KEY \u2014 person",
+      "property READS are disabled (the phc_ project key is write-only by",
+      "PostHog's design), so per-user timezone resolution falls back to",
+      "contact properties. Capture and person WRITES are unaffected.",
+      "",
+      `Fix: create a personal API key scoped ${color.cyan("person:read")} and set ${color.cyan("POSTHOG_PERSONAL_API_KEY")}.`,
+      `Docs: ${color.cyan("https://hogsend.com/docs/guides/analytics-access")}`
+    ].join("\n"),
+    "PostHog person reads disabled"
+  );
+}
+var usage6 = `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),
@@ -1996,8 +2799,8 @@ function trackLine(name, track) {
   const required = track.required ?? color.dim("none");
   return `${color.bold(name.padEnd(7))} applied ${applied} -> required ${required}  ${sync}`;
 }
-async function run5(ctx) {
-  const { values: values2 } = parseArgs6({
+async function run6(ctx) {
+  const { values: values2 } = parseArgs7({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -2007,7 +2810,7 @@ async function run5(ctx) {
     strict: false
   });
   if (values2.help) {
-    ctx.out.log(usage5);
+    ctx.out.log(usage6);
     return;
   }
   const { baseUrl } = ctx.http.cfg;
@@ -2087,6 +2890,7 @@ async function run5(ctx) {
   ];
   ctx.out.note(lines.join("\n"), "Doctor");
   skillsNudge(ctx);
+  analyticsNudge(ctx);
   if (ok) {
     ctx.out.outro(color.green("doctor: ok"));
     return;
@@ -2097,13 +2901,13 @@ async function run5(ctx) {
 var doctorCommand = {
   name: "doctor",
   summary: "Probe a running instance's health (GET /v1/health)",
-  usage: usage5,
-  run: run5
+  usage: usage6,
+  run: run6
 };
 
 // src/commands/domain.ts
-import { parseArgs as parseArgs7 } from "util";
-import { confirm } from "@clack/prompts";
+import { parseArgs as parseArgs8 } from "util";
+import { confirm as confirm2 } from "@clack/prompts";
 
 // src/lib/dns.ts
 import { resolveNs as nodeResolveNs } from "dns/promises";
@@ -2397,18 +3201,8 @@ async function applyRecords(opts) {
   return applyVercel(opts, fetchImpl);
 }
 
-// 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/domain.ts
-var usage6 = `hogsend domain <subcommand> [options]
+var usage7 = `hogsend domain <subcommand> [options]
 
 Manage the sending domain through the RUNNING instance's admin routes
 (/v1/admin/domain) \u2014 provider API keys never touch the CLI. Requires an admin
@@ -2516,7 +3310,7 @@ function renderStatus(ctx, status) {
   }
 }
 async function runAdd(ctx, argv) {
-  const { values: values2, positionals } = parseArgs7({
+  const { values: values2, positionals } = parseArgs8({
     args: argv,
     allowPositionals: true,
     options: {
@@ -2526,7 +3320,7 @@ async function runAdd(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage6);
+    ctx.out.log(usage7);
     return;
   }
   const domain = positionals[0];
@@ -2552,7 +3346,7 @@ async function runAdd(ctx, argv) {
   const autoAvailable = canAutoApply(host.id, process.env);
   if (autoAvailable && records.length > 0) {
     const doApply = values2.apply ? true : values2["no-apply"] ? false : ctx.out.interactive ? bail(
-      await confirm({
+      await confirm2({
         message: `Apply these records via the ${host.label} API?`,
         initialValue: true
       })
@@ -2601,7 +3395,7 @@ async function runAdd(ctx, argv) {
   );
 }
 async function runCheck(ctx, argv) {
-  const { values: values2, positionals } = parseArgs7({
+  const { values: values2, positionals } = parseArgs8({
     args: argv,
     allowPositionals: true,
     options: {
@@ -2611,7 +3405,7 @@ async function runCheck(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage6);
+    ctx.out.log(usage7);
     return;
   }
   const timeoutSecs = Number(values2.timeout);
@@ -2683,7 +3477,7 @@ async function runCheck(ctx, argv) {
   }
 }
 async function runStatus2(ctx, argv) {
-  const { values: values2 } = parseArgs7({
+  const { values: values2 } = parseArgs8({
     args: argv,
     allowPositionals: false,
     options: {
@@ -2692,7 +3486,7 @@ async function runStatus2(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage6);
+    ctx.out.log(usage7);
     return;
   }
   const status = await getStatus(ctx, { refresh: values2.refresh });
@@ -2712,11 +3506,11 @@ async function runStatus2(ctx, argv) {
   }
   ctx.out.outro("Done.");
 }
-async function run6(ctx) {
+async function run7(ctx) {
   const sub = ctx.argv[0];
   const rest = ctx.argv.slice(1);
   if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
-    ctx.out.log(usage6);
+    ctx.out.log(usage7);
     return;
   }
   switch (sub) {
@@ -2735,15 +3529,15 @@ async function run6(ctx) {
 var domainCommand = {
   name: "domain",
   summary: "Set up + verify the sending domain (DNS records, auto-apply)",
-  usage: usage6,
-  run: run6
+  usage: usage7,
+  run: run7
 };
 
 // src/commands/eject.ts
 import { existsSync as existsSync6, realpathSync } from "fs";
 import { createRequire as createRequire2 } from "module";
 import { dirname, join as join6, sep as sep2 } from "path";
-import { parseArgs as parseArgs8 } from "util";
+import { parseArgs as parseArgs9 } from "util";
 
 // src/eject.ts
 import { existsSync as existsSync5 } from "fs";
@@ -2857,7 +3651,7 @@ async function countFiles(dir) {
 }
 
 // src/commands/eject.ts
-var usage7 = `hogsend eject <package> [--force] [--cwd <dir>]
+var usage8 = `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.
@@ -2885,8 +3679,8 @@ function resolveSourceDir(pkg, consumerRoot) {
   }
   return null;
 }
-async function run7(ctx) {
-  const { values: values2, positionals } = parseArgs8({
+async function run8(ctx) {
+  const { values: values2, positionals } = parseArgs9({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -2896,7 +3690,7 @@ async function run7(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage7);
+    ctx.out.log(usage8);
     return;
   }
   const pkg = positionals[0];
@@ -2940,13 +3734,13 @@ async function run7(ctx) {
 var ejectCommand = {
   name: "eject",
   summary: "Vendor a @hogsend/* package into vendor/<name>",
-  usage: usage7,
-  run: run7
+  usage: usage8,
+  run: run8
 };
 
 // src/commands/emails.ts
-import { parseArgs as parseArgs9 } from "util";
-var usage8 = `hogsend emails <subcommand> [options]
+import { parseArgs as parseArgs10 } from "util";
+var usage9 = `hogsend emails <subcommand> [options]
 
 Send a transactional email through the data plane (POST /v1/emails). The send
 runs through the full preferences + tracking pipeline (link-click + open).
@@ -3024,7 +3818,7 @@ function statusColor2(status) {
   }
 }
 async function runSend3(ctx, argv) {
-  const { values: values2, positionals } = parseArgs9({
+  const { values: values2, positionals } = parseArgs10({
     args: argv,
     allowPositionals: true,
     options: {
@@ -3042,7 +3836,7 @@ async function runSend3(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage8);
+    ctx.out.log(usage9);
     return;
   }
   const template = positionals[0];
@@ -3098,7 +3892,7 @@ async function runSend3(ctx, argv) {
   );
   ctx.out.outro(`${template} \u2192 ${statusColor2(res.status)}.`);
 }
-async function run8(ctx) {
+async function run9(ctx) {
   const sub = ctx.argv[0];
   switch (sub) {
     case "send":
@@ -3115,12 +3909,12 @@ async function run8(ctx) {
 var emailsCommand = {
   name: "emails",
   summary: "Send a transactional email through the data plane",
-  usage: usage8,
-  run: run8
+  usage: usage9,
+  run: run9
 };
 
 // src/commands/hatchet.ts
-import { parseArgs as parseArgs10 } from "util";
+import { parseArgs as parseArgs11 } from "util";
 
 // src/lib/hatchet-token.ts
 var SLUG_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
@@ -3291,7 +4085,7 @@ async function mintHatchetToken(opts) {
 }
 
 // src/commands/hatchet.ts
-var usage9 = `hogsend hatchet token [options]
+var usage10 = `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
@@ -3329,7 +4123,7 @@ 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.`;
 function parseTokenFlags(argv) {
-  const { values: values2 } = parseArgs10({
+  const { values: values2 } = parseArgs11({
     args: argv,
     allowPositionals: true,
     strict: false,
@@ -3395,15 +4189,15 @@ async function runToken(ctx, argv) {
     throw err;
   }
 }
-async function run9(ctx) {
+async function run10(ctx) {
   const sub = ctx.argv[0];
   const rest = ctx.argv.slice(1);
   if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
-    ctx.out.log(usage9);
+    ctx.out.log(usage10);
     return;
   }
   if (rest.includes("-h") || rest.includes("--help")) {
-    ctx.out.log(usage9);
+    ctx.out.log(usage10);
     return;
   }
   switch (sub) {
@@ -3416,13 +4210,13 @@ async function run9(ctx) {
 var hatchetCommand = {
   name: "hatchet",
   summary: "Hatchet helpers \u2014 mint a HATCHET_CLIENT_TOKEN headlessly",
-  usage: usage9,
-  run: run9
+  usage: usage10,
+  run: run10
 };
 
 // src/commands/journeys.ts
-import { parseArgs as parseArgs11 } from "util";
-var usage10 = `hogsend journeys <subcommand> [options]
+import { parseArgs as parseArgs12 } from "util";
+var usage11 = `hogsend journeys <subcommand> [options]
 
 Inspect and toggle journeys via the admin API (/v1/admin/journeys).
 
@@ -3451,7 +4245,7 @@ function statusColor3(enabled) {
   return enabled ? color.green("enabled") : color.yellow("disabled");
 }
 async function runList2(ctx) {
-  const { values: values2 } = parseArgs11({
+  const { values: values2 } = parseArgs12({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -3462,7 +4256,7 @@ async function runList2(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage10);
+    ctx.out.log(usage11);
     return;
   }
   if (values2.enabled !== void 0 && !["true", "false"].includes(values2.enabled)) {
@@ -3598,7 +4392,7 @@ async function runToggle(ctx, id, enabled) {
   );
   ctx.out.outro(`${j.id} is now ${statusColor3(j.enabled)}.`);
 }
-async function run10(ctx) {
+async function run11(ctx) {
   const sub = ctx.argv[0];
   const rest = ctx.argv.slice(1);
   const subCtx = { ...ctx, argv: rest };
@@ -3610,7 +4404,7 @@ async function run10(ctx) {
       case "get": {
         const id = rest.find((a) => !a.startsWith("-"));
         if (rest.includes("--help") || rest.includes("-h")) {
-          ctx.out.log(usage10);
+          ctx.out.log(usage11);
           return;
         }
         await runGet2(subCtx, id);
@@ -3618,7 +4412,7 @@ async function run10(ctx) {
       }
       case "enable": {
         if (rest.includes("--help") || rest.includes("-h")) {
-          ctx.out.log(usage10);
+          ctx.out.log(usage11);
           return;
         }
         await runToggle(
@@ -3630,7 +4424,7 @@ async function run10(ctx) {
       }
       case "disable": {
         if (rest.includes("--help") || rest.includes("-h")) {
-          ctx.out.log(usage10);
+          ctx.out.log(usage11);
           return;
         }
         await runToggle(
@@ -3664,14 +4458,14 @@ async function run10(ctx) {
 var journeysCommand = {
   name: "journeys",
   summary: "List, inspect, enable, and disable journeys",
-  usage: usage10,
-  run: run10
+  usage: usage11,
+  run: run11
 };
 
 // src/commands/patch.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { parseArgs as parseArgs12 } from "util";
-var usage11 = `hogsend patch <package> [--cwd <dir>]
+import { parseArgs as parseArgs13 } from "util";
+var usage12 = `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,
@@ -3682,8 +4476,8 @@ 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 run11(ctx) {
-  const { values: values2, positionals } = parseArgs12({
+async function run12(ctx) {
+  const { values: values2, positionals } = parseArgs13({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -3692,7 +4486,7 @@ async function run11(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage11);
+    ctx.out.log(usage12);
     return;
   }
   const pkg = positionals[0];
@@ -3732,16 +4526,16 @@ async function run11(ctx) {
 var patchCommand = {
   name: "patch",
   summary: "Patch a package via pnpm's native patch flow",
-  usage: usage11,
-  run: run11
+  usage: usage12,
+  run: run12
 };
 
 // src/commands/setup.ts
 import { existsSync as existsSync7 } from "fs";
 import { join as join7 } from "path";
-import { parseArgs as parseArgs13 } from "util";
-import { confirm as confirm2 } from "@clack/prompts";
-var usage12 = `hogsend setup [--cwd <dir>] [--yes] [--json]
+import { parseArgs as parseArgs14 } from "util";
+import { confirm as confirm3 } from "@clack/prompts";
+var usage13 = `hogsend setup [--cwd <dir>] [--yes] [--json]
 
 Interactive local onboarding for a scaffolded Hogsend app. Mirrors the
 create-hogsend "next steps":
@@ -3758,8 +4552,8 @@ Options:
   -h, --help     Show this help.
 
 Run ${color.cyan("hogsend doctor")} afterwards to verify the instance is healthy.`;
-async function run12(ctx) {
-  const { values: values2 } = parseArgs13({
+async function run13(ctx) {
+  const { values: values2 } = parseArgs14({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -3769,7 +4563,7 @@ async function run12(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage12);
+    ctx.out.log(usage13);
     return;
   }
   const cwd = values2.cwd ?? process.cwd();
@@ -3787,7 +4581,7 @@ async function run12(ctx) {
   }
   if (ctx.out.interactive && !skipConfirm) {
     const proceed = bail(
-      await confirm2({
+      await confirm3({
         message: `Set up local infra in ${color.cyan(cwd)}? (docker compose up, .env, db:migrate)`
       })
     );
@@ -3884,16 +4678,16 @@ async function run12(ctx) {
 var setupCommand = {
   name: "setup",
   summary: "Local onboarding: docker compose up, gen secret, db:migrate",
-  usage: usage12,
-  run: run12
+  usage: usage13,
+  run: run13
 };
 
 // src/commands/skills.ts
 import { existsSync as existsSync8 } from "fs";
 import { join as join8 } from "path";
-import { parseArgs as parseArgs14 } from "util";
+import { parseArgs as parseArgs15 } from "util";
 import { multiselect } from "@clack/prompts";
-var usage13 = `hogsend skills <subcommand> [options]
+var usage14 = `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
@@ -3954,7 +4748,7 @@ function runList3(ctx) {
   );
 }
 async function runAdd2(ctx, argv) {
-  const { values: values2, positionals } = parseArgs14({
+  const { values: values2, positionals } = parseArgs15({
     args: argv,
     allowPositionals: true,
     options: {
@@ -3964,7 +4758,7 @@ async function runAdd2(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage13);
+    ctx.out.log(usage14);
     return;
   }
   const cwd = process.cwd();
@@ -4032,7 +4826,7 @@ async function runAdd2(ctx, argv) {
     `Installed ${installedCount} skill${installedCount === 1 ? "" : "s"}` + (skippedCount > 0 ? `, skipped ${skippedCount}.` : ".")
   );
 }
-async function run13(ctx) {
+async function run14(ctx) {
   const sub = ctx.argv[0];
   switch (sub) {
     case "list":
@@ -4044,7 +4838,7 @@ async function run13(ctx) {
     case void 0:
     case "-h":
     case "--help":
-      ctx.out.log(usage13);
+      ctx.out.log(usage14);
       return;
     default:
       ctx.out.fail(
@@ -4055,13 +4849,13 @@ async function run13(ctx) {
 var skillsCommand = {
   name: "skills",
   summary: "List + install bundled Claude Code skills into .claude/skills",
-  usage: usage13,
-  run: run13
+  usage: usage14,
+  run: run14
 };
 
 // src/commands/stats.ts
-import { parseArgs as parseArgs15 } from "util";
-var usage14 = `hogsend stats [--json]
+import { parseArgs as parseArgs16 } from "util";
+var usage15 = `hogsend stats [--json]
 
 Show system-wide overview metrics from a running Hogsend instance.
 Wraps GET /v1/admin/metrics/overview.
@@ -4083,8 +4877,8 @@ Options:
 function pct(rate) {
   return `${(rate * 100).toFixed(2)}%`;
 }
-async function run14(ctx) {
-  const { values: values2 } = parseArgs15({
+async function run15(ctx) {
+  const { values: values2 } = parseArgs16({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -4092,7 +4886,7 @@ async function run14(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage14);
+    ctx.out.log(usage15);
     return;
   }
   const metrics = await ctx.out.step(
@@ -4121,20 +4915,19 @@ async function run14(ctx) {
 var statsCommand = {
   name: "stats",
   summary: "Show system-wide overview metrics",
-  usage: usage14,
-  run: run14
+  usage: usage15,
+  run: run15
 };
 
 // src/commands/studio.ts
-import { spawn as spawn2 } from "child_process";
 import { createReadStream, existsSync as existsSync9, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
-import { createServer } from "http";
+import { createServer as createServer2 } from "http";
 import { extname, join as join9, normalize, resolve as resolve2, sep as sep3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import { parseArgs as parseArgs17 } from "util";
+import { parseArgs as parseArgs18 } from "util";
 
 // src/commands/studio-admin.ts
-import { parseArgs as parseArgs16 } from "util";
+import { parseArgs as parseArgs17 } from "util";
 import { password as passwordPrompt, text as text2 } from "@clack/prompts";
 
 // ../../node_modules/.pnpm/postgres@3.4.9/node_modules/postgres/src/index.js
@@ -13322,6 +14115,7 @@ __export(schema_exports, {
   memberRelations: () => memberRelations,
   organization: () => organization,
   organizationRelations: () => organizationRelations,
+  providerCredentials: () => providerCredentials,
   session: () => session,
   sessionRelations: () => sessionRelations,
   trackedLinks: () => trackedLinks,
@@ -14024,6 +14818,30 @@ var linkClicks = pgTable(
   ]
 );
 
+// ../db/src/schema/provider-credentials.ts
+var providerCredentials = pgTable(
+  "provider_credentials",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    // e.g. "posthog" — matches an AnalyticsProvider meta.id by convention,
+    // but deliberately NOT foreign-keyed: providers are code-defined.
+    providerId: text("provider_id").notNull(),
+    // "oauth" today; "api_key" is the anticipated future kind.
+    kind: text("kind").notNull().default("oauth"),
+    // Encrypted JSON: base64url(iv || ciphertext || gcmTag).
+    payload: text("payload").notNull(),
+    ...timestamps
+  },
+  (table) => [
+    // unique-per-kind: one oauth credential per provider; a future api_key
+    // credential for the same provider coexists.
+    uniqueIndex("provider_credentials_provider_kind_idx").on(
+      table.providerId,
+      table.kind
+    )
+  ]
+);
+
 // ../db/src/schema/user-events.ts
 var userEvents = pgTable(
   "user_events",
@@ -14519,7 +15337,7 @@ Examples:
 Security: passwords are written ONLY via better-auth (scrypt) \u2014 never raw SQL,
 never plaintext at rest, never logged. Prefer the masked prompt over --password.`;
 function parseAdminFlags(argv) {
-  const { values: values2 } = parseArgs16({
+  const { values: values2 } = parseArgs17({
     args: argv,
     allowPositionals: true,
     strict: false,
@@ -14720,7 +15538,7 @@ async function runStudioAdmin(ctx, argv) {
 }
 
 // src/commands/studio.ts
-var usage15 = `hogsend studio [options]
+var usage16 = `hogsend studio [options]
 
 Subcommands:
   admin create | reset | list   Shell-gated Studio admin recovery (DB + secret).
@@ -14798,24 +15616,12 @@ function indexHtml(distPath, baseUrl) {
   }
   return `${inject}${raw}`;
 }
-function openBrowser(url) {
-  const platform = process.platform;
-  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-  try {
-    const child = spawn2(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {
-    });
-    child.unref();
-  } catch {
-  }
-}
-async function run15(ctx) {
+async function run16(ctx) {
   if (ctx.argv[0] === "admin") {
     await runStudioAdmin(ctx, ctx.argv.slice(1));
     return;
   }
-  const { values: values2, positionals } = parseArgs17({
+  const { values: values2, positionals } = parseArgs18({
     args: ctx.argv,
     allowPositionals: true,
     strict: false,
@@ -14828,7 +15634,7 @@ async function run15(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage15);
+    ctx.out.log(usage16);
     return;
   }
   const port = Number(values2.port ?? "3333");
@@ -14846,7 +15652,7 @@ async function run15(ctx) {
   }
   const cleanBase = baseUrl ? baseUrl.replace(/\/+$/, "") : void 0;
   const index2 = indexHtml(distPath, cleanBase);
-  const server = createServer((req, res) => {
+  const server = createServer2((req, res) => {
     const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0] ?? "/");
     const rel = urlPath.replace(/^\/studio/, "");
     if (rel === "" || rel === "/") {
@@ -14914,17 +15720,17 @@ async function run15(ctx) {
 var studioCommand = {
   name: "studio",
   summary: "Serve the bundled Hogsend Studio admin SPA locally",
-  usage: usage15,
-  run: run15
+  usage: usage16,
+  run: run16
 };
 
 // src/commands/upgrade.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { existsSync as existsSync10, readFileSync as readFileSync6 } from "fs";
 import { join as join10 } from "path";
-import { parseArgs as parseArgs18 } from "util";
-import { confirm as confirm3 } from "@clack/prompts";
-var usage16 = `hogsend upgrade [--cwd <dir>] [--pm <pnpm|npm|yarn|bun>] [options]
+import { parseArgs as parseArgs19 } from "util";
+import { confirm as confirm4 } from "@clack/prompts";
+var usage17 = `hogsend upgrade [--cwd <dir>] [--pm <pnpm|npm|yarn|bun>] [options]
 
 Upgrade a scaffolded Hogsend app in one step:
   1. bump every @hogsend/* dependency to latest (or --to <version>), then
@@ -14960,8 +15766,8 @@ function hogsendDeps(cwd) {
 function addArgs(pm, specs) {
   return [pm === "npm" ? "install" : "add", ...specs];
 }
-async function run16(ctx) {
-  const { values: values2 } = parseArgs18({
+async function run17(ctx) {
+  const { values: values2 } = parseArgs19({
     args: ctx.argv,
     allowPositionals: true,
     options: {
@@ -14975,7 +15781,7 @@ async function run16(ctx) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage16);
+    ctx.out.log(usage17);
     return;
   }
   if (values2["deps-only"] && values2["skills-only"]) {
@@ -15019,7 +15825,7 @@ async function run16(ctx) {
       doSkills ? "refresh .claude/skills" : null
     ].filter(Boolean).join(" + ");
     const proceed = bail(
-      await confirm3({ message: `Upgrade ${color.cyan(cwd)}: ${plan}?` })
+      await confirm4({ message: `Upgrade ${color.cyan(cwd)}: ${plan}?` })
     );
     if (!proceed) {
       ctx.out.outro(color.dim("Nothing changed."));
@@ -15100,12 +15906,12 @@ async function run16(ctx) {
 var upgradeCommand = {
   name: "upgrade",
   summary: "Bump @hogsend/* deps to latest + refresh vendored skills",
-  usage: usage16,
-  run: run16
+  usage: usage17,
+  run: run17
 };
 
 // src/commands/webhooks.ts
-import { parseArgs as parseArgs19 } from "util";
+import { parseArgs as parseArgs20 } from "util";
 var WEBHOOK_EVENT_TYPES = [
   "contact.created",
   "contact.updated",
@@ -15122,7 +15928,7 @@ var WEBHOOK_EVENT_TYPES = [
   "bucket.entered",
   "bucket.left"
 ];
-var usage17 = `hogsend webhooks <subcommand> [options]
+var usage18 = `hogsend webhooks <subcommand> [options]
 
 Manage outbound webhook endpoints \u2014 the Svix-style signed event stream Hogsend
 emits to your URLs. Wraps the admin routes (/v1/admin/webhooks), so this command
@@ -15212,7 +16018,7 @@ ${color.bold(secret)}`,
   );
 }
 async function runList5(ctx, argv) {
-  const { values: values2 } = parseArgs19({
+  const { values: values2 } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: {
@@ -15223,7 +16029,7 @@ async function runList5(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const query = {
@@ -15272,13 +16078,13 @@ function renderEndpoint(ctx, ep, title) {
   );
 }
 async function runGet3(ctx, argv) {
-  const { values: values2, positionals } = parseArgs19({
+  const { values: values2, positionals } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: { help: { type: "boolean", short: "h", default: false } }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const id = positionals[0];
@@ -15303,7 +16109,7 @@ async function runGet3(ctx, argv) {
   ctx.out.outro(`${res.url} \u2192 ${res.status}`);
 }
 async function runCreate2(ctx, argv) {
-  const { values: values2 } = parseArgs19({
+  const { values: values2 } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: {
@@ -15316,7 +16122,7 @@ async function runCreate2(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const url = values2.url;
@@ -15350,7 +16156,7 @@ async function runCreate2(ctx, argv) {
   ctx.out.outro(`${color.green("Created")} ${res.id} \u2192 ${res.url}`);
 }
 async function runUpdate(ctx, argv) {
-  const { values: values2, positionals } = parseArgs19({
+  const { values: values2, positionals } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: {
@@ -15364,7 +16170,7 @@ async function runUpdate(ctx, argv) {
     }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const id = positionals[0];
@@ -15405,13 +16211,13 @@ async function runUpdate(ctx, argv) {
   ctx.out.outro(`${color.green("Updated")} ${res.id} \u2192 ${res.status}`);
 }
 async function runDelete(ctx, argv) {
-  const { values: values2, positionals } = parseArgs19({
+  const { values: values2, positionals } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: { help: { type: "boolean", short: "h", default: false } }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const id = positionals[0];
@@ -15435,13 +16241,13 @@ async function runDelete(ctx, argv) {
   ctx.out.outro(`${color.green("Deleted")} ${id}`);
 }
 async function runRotate(ctx, argv) {
-  const { values: values2, positionals } = parseArgs19({
+  const { values: values2, positionals } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: { help: { type: "boolean", short: "h", default: false } }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const id = positionals[0];
@@ -15470,13 +16276,13 @@ async function runRotate(ctx, argv) {
   );
 }
 async function runTest(ctx, argv) {
-  const { values: values2, positionals } = parseArgs19({
+  const { values: values2, positionals } = parseArgs20({
     args: argv,
     allowPositionals: true,
     options: { help: { type: "boolean", short: "h", default: false } }
   });
   if (values2.help) {
-    ctx.out.log(usage17);
+    ctx.out.log(usage18);
     return;
   }
   const id = positionals[0];
@@ -15502,7 +16308,7 @@ async function runTest(ctx, argv) {
     `${color.green("Enqueued")} a ${color.cyan(res.eventType)} delivery to ${id}.`
   );
 }
-async function run17(ctx) {
+async function run18(ctx) {
   const sub = ctx.argv[0];
   switch (sub) {
     case "list":
@@ -15533,8 +16339,8 @@ async function run17(ctx) {
 var webhooksCommand = {
   name: "webhooks",
   summary: "Manage outbound webhook endpoints (create, rotate, test)",
-  usage: usage17,
-  run: run17
+  usage: usage18,
+  run: run18
 };
 
 // src/commands/index.ts
@@ -15548,6 +16354,7 @@ var commands = [
   campaignsCommand,
   webhooksCommand,
   domainCommand,
+  connectCommand,
   hatchetCommand,
   studioCommand,
   devCommand,