@hogsend/cli 0.20.0 → 0.21.0

package/package.json

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

package/src/__tests__/connect-flow.test.ts

@@ -103,6 +103,8 @@ function makeHarness(opts: {
   postResult?: unknown | Error;
   interactive?: boolean;
   confirmAnswer?: boolean;
+  /** Injected region resolver for the keyless (privateHost null) path. */
+  selectRegion?: () => Promise<string>;
 }): Harness {
   const sink: string[] = [];
   const calls: Harness["calls"] = {
@@ -209,6 +211,7 @@ function makeHarness(opts: {
       return true;
     },
     confirm: async () => opts.confirmAnswer ?? true,
+    ...(opts.selectRegion ? { selectRegion: opts.selectRegion } : {}),
     now: () => NOW,
   };
 
@@ -253,12 +256,9 @@ describe("runConnectPosthog — happy path", () => {
         expiresAt: "2026-06-13T04:00:00.000Z",
         tokenEndpoint: "https://eu.posthog.com/oauth/token/",
         clientId: POSTHOG_CLIENT_ID,
-        scopes: [
-          "person:read",
-          "person:write",
-          "project:read",
-          "hog_function:write",
-        ],
+        // The granted scopes are the front-loaded set the token response
+        // carries (TOKENS.scope === POSTHOG_SCOPES), split on whitespace.
+        scopes: POSTHOG_SCOPES.split(" "),
         scopedTeams: [123],
         scopedOrganizations: [],
       },
@@ -359,23 +359,21 @@ describe("runConnectPosthog — failure verdicts", () => {
 });
 
 describe("runConnectPosthog — provisioning outcomes", () => {
-  it("soft-skips when the webhook secret is unconfigured (note with recovery)", async () => {
+  it("proceeds to provision even when the webhook secret is unconfigured (server mints it)", async () => {
+    // webhookSecretConfigured:false no longer short-circuits — the server mints
+    // + persists the secret during provisioning, so the flow stores the
+    // credential AND POSTs provision-loop, landing on `connected`.
     const h = makeHarness({
       info: connectInfo({ webhookSecretConfigured: false }),
     });
     const result = await runConnectPosthog(h.deps, FLOW_DEFAULTS);
 
-    expect(result.verdict).toBe("connected_no_provision");
+    expect(result.verdict).toBe("connected");
     expect(h.calls.put).toHaveLength(1);
-    expect(h.calls.post).toHaveLength(0);
-    expect(result.provision).toEqual({
-      attempted: false,
-      skipped: "webhook_secret_missing",
-    });
-
-    const note = h.sink.find((s) => s.includes("POSTHOG_WEBHOOK_SECRET"));
-    expect(note).toBeDefined();
-    expect(note).toContain("--provision-only");
+    expect(h.calls.post).toEqual([
+      { path: "/v1/admin/analytics/provision-loop", body: {} },
+    ]);
+    expect(result.provision).toMatchObject({ attempted: true, ok: true });
   });
 
   it("soft-skips when API_PUBLIC_URL is loopback (PostHog can't reach it)", async () => {
@@ -466,15 +464,15 @@ describe("runConnectPosthog — --provision-only", () => {
     expect(h.calls.post).toHaveLength(0);
   });
 
-  it("hard-fails webhook_secret_missing BEFORE calling the route", async () => {
+  it("provisions even when the webhook secret is unconfigured (server mints it)", async () => {
+    // --provision-only no longer gates on webhookSecretConfigured — the server
+    // mints + persists the secret during provisioning, so the POST proceeds.
     const h = makeHarness({
       info: connectInfo({ webhookSecretConfigured: false }),
     });
-    await expectConnectError(
-      runConnectPosthog(h.deps, PROVISION_ONLY),
-      "webhook_secret_missing",
-    );
-    expect(h.calls.post).toHaveLength(0);
+    const result = await runConnectPosthog(h.deps, PROVISION_ONLY);
+    expect(result.verdict).toBe("connected");
+    expect(h.calls.post).toHaveLength(1);
   });
 
   it("any other non-2xx is provision_failed", async () => {
@@ -490,3 +488,72 @@ describe("runConnectPosthog — --provision-only", () => {
     );
   });
 });
+
+describe("runConnectPosthog — keyless / region resolution", () => {
+  it("resolves the region from --posthog-host on a keyless instance and proceeds", async () => {
+    // Server reports no PostHog config (privateHost null) — the CLI no longer
+    // hard-fails not_configured; it derives the region from the flag and runs
+    // the full OAuth handshake against it.
+    const h = makeHarness({ info: connectInfo({ privateHost: null }) });
+    const result = await runConnectPosthog(h.deps, {
+      ...FLOW_DEFAULTS,
+      posthogHost: "https://eu.posthog.com/",
+    });
+
+    expect(result.verdict).toBe("connected");
+    // Trailing slash stripped; discovery + the OAuth flow ran against it.
+    expect(h.calls.discover).toEqual(["https://eu.posthog.com"]);
+    expect(result.posthog?.privateHost).toBe("https://eu.posthog.com");
+    expect(h.calls.put).toHaveLength(1);
+  });
+
+  it("non-interactive keyless without a flag still fails not_configured", async () => {
+    const h = makeHarness({
+      info: connectInfo({ privateHost: null }),
+      interactive: false,
+    });
+    await expectConnectError(
+      runConnectPosthog(h.deps, FLOW_DEFAULTS),
+      "not_configured",
+    );
+    expect(h.calls.discover).toHaveLength(0);
+  });
+
+  it("interactive keyless uses the injected selectRegion prompt", async () => {
+    const selectRegion = async () => "https://us.posthog.com";
+    const h = makeHarness({
+      info: connectInfo({ privateHost: null }),
+      interactive: true,
+      selectRegion,
+    });
+    const result = await runConnectPosthog(h.deps, FLOW_DEFAULTS);
+
+    expect(result.verdict).toBe("connected");
+    expect(h.calls.discover).toEqual(["https://us.posthog.com"]);
+    expect(result.posthog?.privateHost).toBe("https://us.posthog.com");
+  });
+});
+
+describe("runConnectPosthog — scope downscope advisory", () => {
+  it("prints a note when PostHog grants fewer scopes than requested", async () => {
+    // Simulate a downscope: PostHog grants everything except two read scopes.
+    const granted = POSTHOG_SCOPES.split(" ")
+      .filter((s) => s !== "cohort:read" && s !== "query:read")
+      .join(" ");
+    const h = makeHarness({ tokens: { ...TOKENS, scope: granted } });
+    const result = await runConnectPosthog(h.deps, FLOW_DEFAULTS);
+
+    expect(result.verdict).toBe("connected");
+    const note = h.sink.find((s) => s.includes("PostHog granted"));
+    expect(note).toBeDefined();
+    expect(note).toContain("cohort:read");
+    expect(note).toContain("query:read");
+  });
+
+  it("prints no note when PostHog grants the full requested set", async () => {
+    // Default TOKENS.scope === POSTHOG_SCOPES — a full grant.
+    const h = makeHarness({});
+    await runConnectPosthog(h.deps, FLOW_DEFAULTS);
+    expect(h.sink.find((s) => s.includes("PostHog granted"))).toBeUndefined();
+  });
+});

package/src/commands/connect.ts

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { confirm } from "@clack/prompts";
+import { confirm, select, text } from "@clack/prompts";
 import { openBrowser } from "../lib/browser.js";
 import {
   ConnectError,
@@ -12,7 +12,7 @@ import { color } from "../lib/output.js";
 import { bail } from "../lib/prompt.js";
 import type { Command, CommandContext } from "./types.js";
 
-const usage = `hogsend connect <provider> [--provision-only] [--no-provision] [--no-browser] [--json]
+const usage = `hogsend connect <provider> [--posthog-host <url>] [--provision-only] [--no-provision] [--no-browser] [--json]
 
 Connect this Hogsend instance to an analytics provider via OAuth. Providers:
 
@@ -26,6 +26,10 @@ The browser consent must happen on THIS machine (the OAuth callback lands on
 this command from your laptop, not from an SSH session on the server.
 
 Options:
+  --posthog-host     PostHog app/private host to authorize against, e.g.
+                     https://eu.posthog.com or https://us.posthog.com (NOT the
+                     i. ingestion host). Required when the instance has no
+                     PostHog config and you're running non-interactively.
   --provision-only   Skip OAuth; (re-)provision the event loop using the
                      already-stored credential.
   --no-provision     Stop after storing the credential.
@@ -41,6 +45,7 @@ async function run(ctx: CommandContext): Promise<void> {
     allowPositionals: true,
     strict: false,
     options: {
+      "posthog-host": { type: "string" },
       "provision-only": { type: "boolean", default: false },
       "no-provision": { type: "boolean", default: false },
       "no-browser": { type: "boolean", default: false },
@@ -96,6 +101,26 @@ async function run(ctx: CommandContext): Promise<void> {
     exchangeCode,
     openBrowser,
     confirm: async (message) => bail(await confirm({ message })),
+    selectRegion: async () => {
+      const choice = bail(
+        await select({
+          message: "Which PostHog region should Hogsend authorize against?",
+          options: [
+            { value: "https://eu.posthog.com", label: "PostHog EU Cloud" },
+            { value: "https://us.posthog.com", label: "PostHog US Cloud" },
+            { value: "custom", label: "Custom / self-hosted" },
+          ],
+        }),
+      ) as string;
+      if (choice !== "custom") return choice;
+      return bail(
+        await text({
+          message:
+            "PostHog app/private host URL (e.g. https://posthog.example.com)",
+          placeholder: "https://posthog.example.com",
+        }),
+      );
+    },
     now: () => new Date(),
   };
 
@@ -104,6 +129,10 @@ async function run(ctx: CommandContext): Promise<void> {
       provisionOnly: Boolean(values["provision-only"]),
       noProvision: Boolean(values["no-provision"]),
       noBrowser: Boolean(values["no-browser"]),
+      posthogHost:
+        typeof values["posthog-host"] === "string"
+          ? values["posthog-host"]
+          : undefined,
     });
 
     if (ctx.json) {

package/src/lib/connect-flow.ts

@@ -34,6 +34,8 @@ export interface ConnectInfoResponse {
   personalKeyConfigured: boolean;
   webhookSecretConfigured: boolean;
   apiPublicUrl: string;
+  /** Expected OAuth scopes missing from the stored credential (advisory). */
+  scopeGap?: string[];
 }
 
 /** Loose mirror of POST /v1/admin/analytics/provision-loop's 200 (M10: any 2xx is success, no strict parse). */
@@ -51,7 +53,7 @@ export type ConnectVerdict =
   | "connected_no_provision"; // credential stored; provision skipped or failed
 
 export type ConnectFailure =
-  | "not_configured" // privateHost null (or US-cloud assumption declined)
+  | "not_configured" // privateHost null and no --posthog-host (non-interactive)
   | "oauth_unsupported" // discovery 404
   | "discovery_failed"
   | "port_unavailable"
@@ -61,8 +63,7 @@ export type ConnectFailure =
   | "exchange_failed"
   | "store_failed"
   | "no_credential" // --provision-only with nothing stored
-  | "webhook_secret_missing"
-  | "api_public_url_unreachable" // --provision-only without POSTHOG_WEBHOOK_SECRET
+  | "api_public_url_unreachable" // instance API_PUBLIC_URL is a loopback address
   | "provision_failed"; // --provision-only and the POST itself failed
 
 export class ConnectError extends Error {
@@ -101,10 +102,7 @@ export interface ConnectResult {
     | { attempted: true; ok: false; error: string }
     | {
         attempted: false;
-        skipped:
-          | "webhook_secret_missing"
-          | "no_provision_flag"
-          | "api_public_url_unreachable";
+        skipped: "no_provision_flag" | "api_public_url_unreachable";
       };
 }
 
@@ -128,6 +126,13 @@ export interface ConnectFlowDeps {
   openBrowser: (url: string) => boolean;
   /** bail-wrapped clack confirm; injected so tests never prompt. */
   confirm: (message: string) => Promise<boolean>;
+  /**
+   * Resolve the PostHog private/app host (e.g. https://eu.posthog.com) when the
+   * instance reports no region. Optional — when absent in interactive mode the
+   * flow falls back to {@link ConnectFlowDeps.confirm}. Injected (a bail-wrapped
+   * clack select + text) so tests never prompt.
+   */
+  selectRegion?: () => Promise<string>;
   now: () => Date;
 }
 
@@ -136,14 +141,22 @@ export interface ConnectFlowOptions {
   noProvision: boolean;
   noBrowser: boolean;
   timeoutMs?: number;
+  /** --posthog-host: the PostHog private/app host to authorize against. */
+  posthogHost?: string;
 }
 
 // --- §7 UX text — exact strings for failure modes / notes ------------------
 
 const 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.";
+  "Pass --posthog-host https://eu.posthog.com (or https://us.posthog.com, " +
+  "or your self-hosted app URL) to pick the region to authorize against. " +
+  "Alternatively set POSTHOG_HOST on the instance, redeploy, then re-run.";
+
+const POSTHOG_EU_HOST = "https://eu.posthog.com";
+const POSTHOG_US_HOST = "https://us.posthog.com";
+
+/** Strip a single trailing slash so origin checks stay exact. */
+const normalizeHost = (host: string): string => host.replace(/\/+$/, "");
 
 const hintOauthUnsupported = (privateHost: string): string =>
   `${privateHost} doesn't advertise an OAuth server (discovery returned 404).
@@ -193,13 +206,6 @@ Once deployed, wire the loop against the real instance:
 
   hogsend connect posthog --provision-only --url https://your-instance`;
 
-const WEBHOOK_SECRET_NOTE = `Credential stored — 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`;
-
 // ---------------------------------------------------------------------------
 
 const errMsg = (err: unknown): string =>
@@ -253,15 +259,8 @@ async function runProvisionOnly(
   info: ConnectInfoResponse,
   base: string,
 ): Promise<ConnectResult> {
-  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 — nothing to " +
-        "provision against",
-    );
-  }
-
+  // The server mints the webhook secret during provisioning, so we no longer
+  // gate on webhookSecretConfigured — just proceed to the provision route.
   if (isLoopbackUrl(info.apiPublicUrl)) {
     deps.out.note(LOOPBACK_URL_NOTE, "Instance not publicly reachable");
     throw new ConnectError(
@@ -325,6 +324,47 @@ function printProvisioned(out: Output, result: ProvisionLoopResponse): void {
   );
 }
 
+/**
+ * Resolve the PostHog private/app host to authorize against. The server's
+ * `connect-info` reports `privateHost` when it has a PostHog config; when it's
+ * null (keyless start) the CLI resolves the region client-side:
+ *
+ *  1. `--posthog-host` flag wins (trailing slash stripped).
+ *  2. interactive + a `selectRegion` dep → prompt (EU / US / custom).
+ *  3. interactive without `selectRegion` → US confirm, declined → EU.
+ *  4. non-interactive without the flag → throw not_configured.
+ */
+async function resolvePrivateHost(
+  deps: ConnectFlowDeps,
+  info: ConnectInfoResponse,
+  opts: ConnectFlowOptions,
+): Promise<string> {
+  if (info.privateHost !== null) {
+    return info.privateHost;
+  }
+
+  if (opts.posthogHost) {
+    return normalizeHost(opts.posthogHost);
+  }
+
+  if (deps.interactive) {
+    if (deps.selectRegion) {
+      return normalizeHost(await deps.selectRegion());
+    }
+    const useUs = await deps.confirm(
+      `Use PostHog US Cloud (${POSTHOG_US_HOST})? (No selects PostHog EU ` +
+        `Cloud, ${POSTHOG_EU_HOST})`,
+    );
+    return useUs ? POSTHOG_US_HOST : POSTHOG_EU_HOST;
+  }
+
+  throw new ConnectError(
+    "not_configured",
+    "this instance has no PostHog configuration",
+    HINT_NOT_CONFIGURED,
+  );
+}
+
 /**
  * Run the full connect flow (or the `--provision-only` shortcut). Resolves
  * with a {@link ConnectResult} whenever a credential is stored (even if
@@ -343,20 +383,19 @@ export async function runConnectPosthog(
       deps.http.get<ConnectInfoResponse>("/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) {
+  // a'. Resolve the region. The server tells us when it has no PostHog config
+  //     (privateHost null); the CLI then resolves it client-side from the flag
+  //     or an interactive prompt, so a fresh instance needs no PostHog env vars.
+  const privateHost = await resolvePrivateHost(deps, info, opts);
+
+  // When the server DID report a host but it wasn't explicit (US default),
+  // confirm the region. When privateHost was null we resolved it ourselves
+  // above, so this US-default reconciliation doesn't apply.
+  if (info.privateHost !== null && info.hostExplicit === false) {
     if (deps.interactive) {
       const proceed = await deps.confirm(
         "No POSTHOG_HOST set on the instance — assume PostHog US Cloud " +
@@ -533,6 +572,19 @@ export async function runConnectPosthog(
     credential: { stored: true, expiresAt },
   };
 
+  // Advise only when PostHog granted FEWER scopes than we requested THIS run
+  // (a downscope) — derived from the grant we just received, not the stale
+  // pre-run `info.scopeGap`, so a successful full re-auth prints nothing.
+  const requestedScopes = POSTHOG_SCOPES.split(" ");
+  const missingScopes = requestedScopes.filter((s) => !scopes.includes(s));
+  if (missingScopes.length > 0) {
+    deps.out.log(
+      `note: PostHog granted ${scopes.length}/${requestedScopes.length} ` +
+        `requested scope(s); missing: ${missingScopes.join(", ")}. Re-run ` +
+        "`hogsend connect posthog` to grant the full set.",
+    );
+  }
+
   // g. Provision the PostHog → Hogsend loop (soft: the credential is stored,
   //    so a provisioning failure never fails the command).
   if (opts.noProvision) {
@@ -543,15 +595,7 @@ export async function runConnectPosthog(
     };
   }
 
-  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" },
-    };
-  }
-
+  // The server mints the webhook secret during provisioning — no skip here.
   if (isLoopbackUrl(info.apiPublicUrl)) {
     deps.out.note(LOOPBACK_URL_NOTE, "Instance not publicly reachable");
     return {

package/src/lib/oauth.ts

@@ -24,10 +24,19 @@ export const POSTHOG_CLIENT_ID =
 
 /**
  * LOCKSTEP (M5): must match the `scope` field of the hosted CIMD document
- * (`apps/docs/public/.well-known/hogsend-posthog-client.json`).
+ * (`apps/docs/public/.well-known/hogsend-posthog-client.json`) AND the
+ * engine's `EXPECTED_POSTHOG_SCOPES`
+ * (`packages/engine/src/lib/posthog-scopes.ts`). Front-loaded beyond the
+ * webhook loop's needs (which is only `hog_function:write` + the minted
+ * secret) so future read/write features land without forcing a reconnect.
+ * Every name here is validated against PostHog's published
+ * `scopes_supported`. Grep all three places before changing.
  */
 export const POSTHOG_SCOPES =
-  "person:read person:write project:read hog_function:write";
+  "person:read person:write project:read organization:read " +
+  "hog_function:read hog_function:write feature_flag:read cohort:read " +
+  "cohort:write query:read insight:read event_definition:read " +
+  "property_definition:read";
 
 /**
  * LOCKSTEP (M5): the CIMD document's `redirect_uris` list EXACTLY