feat(installer): offer CodeGraph Pro beta signup after install and upgrade (#1297)

One-time, strictly opt-in prompt at the end of codegraph install and
codegraph upgrade to join the CodeGraph Pro beta waitlist (same list as
the getcodegraph.com homepage form). Nothing is sent unless the user
answers yes AND enters an email; either answer is recorded machine-wide
so no later install or upgrade re-asks, and --yes / non-interactive / CI
runs never see the prompt.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -11,6 +11,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### New Features
 
+- `codegraph install` and `codegraph upgrade` now offer CodeGraph Pro beta access after finishing — answer yes, type your email, and you join the same waitlist as the getcodegraph.com homepage form. Strictly opt-in and asked at most once per machine total: nothing is sent unless you say yes and enter an email, either answer is remembered so no later install or upgrade ever re-asks, and non-interactive runs (`--yes`, scripts, CI) never see the question.
 - Every release is now cryptographically verifiable: npm packages publish with npm provenance (the "Provenance" badge on npmjs.com, proving each version was built by this repository's release workflow from a specific commit), and the GitHub Release bundles carry signed build attestations you can check with `gh attestation verify <file> -R colbymchenry/codegraph`.
 
 ### Fixes

__tests__/beta-signup.test.ts

@@ -0,0 +1,157 @@
+/**
+ * CodeGraph Pro beta opt-in (installer Step 5½).
+ *
+ * Covers the module the interactive prompt drives:
+ *   - ask-once persistence in the user-level state dir (temp dir injected —
+ *     no real ~/.codegraph ever touched)
+ *   - the submit request shape (endpoint, method, JSON body)
+ *   - fail-soft behavior: bad responses and network errors return false,
+ *     never throw
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  BETA_SIGNUP_ENDPOINT,
+  EMAIL_RE,
+  hasBetaSignupChoice,
+  recordBetaSignupChoice,
+  shouldOfferBetaSignup,
+  submitBetaSignup,
+} from '../src/installer/beta-signup';
+
+describe('beta signup choice persistence', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-beta-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('reports no choice on a fresh machine', () => {
+    expect(hasBetaSignupChoice({ dir })).toBe(false);
+  });
+
+  it('remembers a subscribed choice so no future install re-asks', () => {
+    recordBetaSignupChoice(true, { dir });
+    expect(hasBetaSignupChoice({ dir })).toBe(true);
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, 'beta-signup.json'), 'utf8'));
+    expect(raw.status).toBe('subscribed');
+    expect(raw.updated_at).toBeTruthy();
+  });
+
+  it('remembers a declined choice too — declining is also asked-once', () => {
+    recordBetaSignupChoice(false, { dir });
+    expect(hasBetaSignupChoice({ dir })).toBe(true);
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, 'beta-signup.json'), 'utf8'));
+    expect(raw.status).toBe('declined');
+  });
+
+  it('creates the state dir when missing', () => {
+    const nested = path.join(dir, 'not', 'yet', 'there');
+    recordBetaSignupChoice(true, { dir: nested });
+    expect(hasBetaSignupChoice({ dir: nested })).toBe(true);
+  });
+
+  it('treats a corrupted choice file as no choice', () => {
+    fs.writeFileSync(path.join(dir, 'beta-signup.json'), 'not json');
+    expect(hasBetaSignupChoice({ dir })).toBe(false);
+    fs.writeFileSync(path.join(dir, 'beta-signup.json'), JSON.stringify({ status: 'maybe' }));
+    expect(hasBetaSignupChoice({ dir })).toBe(false);
+  });
+});
+
+describe('shouldOfferBetaSignup — the shared no-spam gate', () => {
+  let dir: string;
+  const tty = { stdinIsTTY: true, stdoutIsTTY: true };
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-beta-gate-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('offers on a fresh machine with a real terminal', () => {
+    expect(shouldOfferBetaSignup({ dir, ...tty })).toBe(true);
+  });
+
+  it('never offers again once subscribed — from install OR upgrade', () => {
+    recordBetaSignupChoice(true, { dir });
+    expect(shouldOfferBetaSignup({ dir, ...tty, source: 'cli-install' })).toBe(false);
+    expect(shouldOfferBetaSignup({ dir, ...tty, source: 'cli-upgrade' })).toBe(false);
+  });
+
+  it('never offers again once declined either', () => {
+    recordBetaSignupChoice(false, { dir });
+    expect(shouldOfferBetaSignup({ dir, ...tty, source: 'cli-install' })).toBe(false);
+    expect(shouldOfferBetaSignup({ dir, ...tty, source: 'cli-upgrade' })).toBe(false);
+  });
+
+  it('never offers without a terminal (scripts, CI, piped output)', () => {
+    expect(shouldOfferBetaSignup({ dir, stdinIsTTY: false, stdoutIsTTY: true })).toBe(false);
+    expect(shouldOfferBetaSignup({ dir, stdinIsTTY: true, stdoutIsTTY: false })).toBe(false);
+  });
+});
+
+describe('submitBetaSignup', () => {
+  it('POSTs the email as JSON to the waitlist endpoint', async () => {
+    let captured: { url: string; init: RequestInit } | null = null;
+    const fetchImpl = (async (url: unknown, init?: RequestInit) => {
+      captured = { url: String(url), init: init! };
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    const ok = await submitBetaSignup('dev@example.com', { fetchImpl });
+
+    expect(ok).toBe(true);
+    expect(captured!.url).toBe(BETA_SIGNUP_ENDPOINT);
+    expect(captured!.init.method).toBe('POST');
+    expect((captured!.init.headers as Record<string, string>)['Content-Type']).toBe(
+      'application/json',
+    );
+    const body = JSON.parse(String(captured!.init.body));
+    expect(body).toEqual({ email: 'dev@example.com', source: 'cli-install' });
+  });
+
+  it('records where the signup came from (install vs upgrade)', async () => {
+    let body: Record<string, unknown> = {};
+    const fetchImpl = (async (_url: unknown, init?: RequestInit) => {
+      body = JSON.parse(String(init!.body));
+      return new Response('{"ok":true}', { status: 200 });
+    }) as typeof fetch;
+
+    await submitBetaSignup('dev@example.com', { fetchImpl, source: 'cli-upgrade' });
+    expect(body.source).toBe('cli-upgrade');
+  });
+
+  it('returns false on a non-2xx response', async () => {
+    const fetchImpl = (async () =>
+      new Response('{"ok":false}', { status: 502 })) as typeof fetch;
+    expect(await submitBetaSignup('dev@example.com', { fetchImpl })).toBe(false);
+  });
+
+  it('returns false (never throws) when the network fails', async () => {
+    const fetchImpl = (async () => {
+      throw new Error('offline');
+    }) as typeof fetch;
+    expect(await submitBetaSignup('dev@example.com', { fetchImpl })).toBe(false);
+  });
+});
+
+describe('EMAIL_RE', () => {
+  it('matches the landing-page validation shape', () => {
+    expect(EMAIL_RE.test('you@company.com')).toBe(true);
+    expect(EMAIL_RE.test('first.last+tag@sub.domain.io')).toBe(true);
+    expect(EMAIL_RE.test('nope')).toBe(false);
+    expect(EMAIL_RE.test('nope@nodot')).toBe(false);
+    expect(EMAIL_RE.test('spaces in@mail.com')).toBe(false);
+    expect(EMAIL_RE.test('')).toBe(false);
+  });
+});

__tests__/upgrade.test.ts

@@ -410,6 +410,69 @@ describe('runUpgrade', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Beta signup offer — fires ONLY after a real, successful binary update.
+// (The hook itself gates on TTY + the once-per-machine stored choice; see
+// __tests__/beta-signup.test.ts. Here we pin WHEN the upgrade path invokes it.)
+// ---------------------------------------------------------------------------
+
+describe('runUpgrade beta signup offer', () => {
+  function withSpy(deps: UpgradeDeps): { deps: UpgradeDeps; offered: () => number } {
+    let n = 0;
+    deps.offerBetaSignup = async () => { n += 1; };
+    return { deps, offered: () => n };
+  }
+
+  it('offers after a successful npm upgrade', async () => {
+    const { deps } = makeDeps({ method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.8' });
+    const { offered } = withSpy(deps);
+    expect(await runUpgrade({}, deps)).toBe(0);
+    expect(offered()).toBe(1);
+  });
+
+  it('does not offer on --check', async () => {
+    const { deps } = makeDeps({ method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.8' });
+    const { offered } = withSpy(deps);
+    expect(await runUpgrade({ check: true }, deps)).toBe(0);
+    expect(offered()).toBe(0);
+  });
+
+  it('does not offer when already up to date', async () => {
+    const { deps } = makeDeps({ method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.9' });
+    const { offered } = withSpy(deps);
+    expect(await runUpgrade({}, deps)).toBe(0);
+    expect(offered()).toBe(0);
+  });
+
+  it('does not offer when the upgrade fails', async () => {
+    const { deps } = makeDeps(
+      { method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.8' },
+      1 // npm exits non-zero
+    );
+    const { offered } = withSpy(deps);
+    expect(await runUpgrade({}, deps)).toBe(1);
+    expect(offered()).toBe(0);
+  });
+
+  it('does not offer on npx / source no-op paths', async () => {
+    for (const method of [
+      { kind: 'npx' } as const,
+      { kind: 'source', root: '/dev/codegraph' } as const,
+    ]) {
+      const { deps } = makeDeps({ method, currentVersion: '0.9.8' });
+      const { offered } = withSpy(deps);
+      expect(await runUpgrade({}, deps)).toBe(0);
+      expect(offered()).toBe(0);
+    }
+  });
+
+  it('a throwing offer never fails the upgrade', async () => {
+    const { deps } = makeDeps({ method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.8' });
+    deps.offerBetaSignup = async () => { throw new Error('boom'); };
+    expect(await runUpgrade({}, deps)).toBe(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Post-upgrade self-heal of installed agent surfaces
 // ---------------------------------------------------------------------------

src/bin/codegraph.ts

@@ -2394,6 +2394,10 @@ program
         warn: (m: string) => warn(m),
         error: (m: string) => error(m),
         platform: process.platform,
+        offerBetaSignup: async () => {
+          const { maybeOfferBetaSignup } = await import('../installer/beta-signup');
+          await maybeOfferBetaSignup({ source: 'cli-upgrade' });
+        },
       }
     );
     process.exit(code);

src/installer/beta-signup.ts

@@ -0,0 +1,169 @@
+/**
+ * CodeGraph Pro beta opt-in — the installer's one-time offer to join the
+ * beta-access waitlist (the same list the getcodegraph.com homepage form
+ * feeds). Strictly opt-in: the user must answer yes AND type their email;
+ * nothing is ever sent otherwise, and `--yes` / non-interactive runs never
+ * see the prompt.
+ *
+ * The choice (subscribed or declined) is stored once in the user-level
+ * state dir (~/.codegraph) so re-installs and upgrades never re-ask —
+ * mirroring the telemetry consent pattern. A failed submit stores nothing,
+ * so a later install can offer again.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+/** JSON waitlist endpoint on the landing page (see its /api/waitlist route). */
+export const BETA_SIGNUP_ENDPOINT = 'https://getcodegraph.com/api/waitlist';
+export const BETA_SIGNUP_URL = 'https://getcodegraph.com';
+
+/** Same shape the landing-page form validates against. */
+export const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+const SUBMIT_TIMEOUT_MS = 8_000;
+
+interface BetaSignupChoiceFile {
+  status: 'subscribed' | 'declined';
+  updated_at: string;
+}
+
+export interface BetaSignupDeps {
+  /** Global state dir; defaults to ~/.codegraph. Tests inject a temp dir. */
+  dir?: string;
+  fetchImpl?: typeof fetch;
+  now?: () => Date;
+  /** Where the signup came from, recorded with the email. */
+  source?: 'cli-install' | 'cli-upgrade';
+  /** TTY probes; default to the real process streams. Tests inject. */
+  stdinIsTTY?: boolean;
+  stdoutIsTTY?: boolean;
+}
+
+function choicePath(deps: BetaSignupDeps = {}): string {
+  return path.join(deps.dir ?? path.join(os.homedir(), '.codegraph'), 'beta-signup.json');
+}
+
+/** True once the user has answered (either way) on this machine. */
+export function hasBetaSignupChoice(deps: BetaSignupDeps = {}): boolean {
+  try {
+    const raw = JSON.parse(fs.readFileSync(choicePath(deps), 'utf8')) as BetaSignupChoiceFile;
+    return raw.status === 'subscribed' || raw.status === 'declined';
+  } catch {
+    return false;
+  }
+}
+
+/** Persist the answer so no future install re-asks. Fail silent. */
+export function recordBetaSignupChoice(
+  subscribed: boolean,
+  deps: BetaSignupDeps = {},
+): void {
+  try {
+    const file = choicePath(deps);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const choice: BetaSignupChoiceFile = {
+      status: subscribed ? 'subscribed' : 'declined',
+      updated_at: (deps.now?.() ?? new Date()).toISOString(),
+    };
+    fs.writeFileSync(file, JSON.stringify(choice, null, 2) + '\n');
+  } catch {
+    /* a full disk must not break the installer */
+  }
+}
+
+/**
+ * Submit one email to the beta waitlist. Returns true on success, false on
+ * any failure (bad response, offline, timeout) — never throws, never retries.
+ */
+export async function submitBetaSignup(
+  email: string,
+  deps: BetaSignupDeps = {},
+): Promise<boolean> {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  try {
+    const res = await fetchImpl(BETA_SIGNUP_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, source: deps.source ?? 'cli-install' }),
+      signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The one gate every ask site shares: offer only on a real terminal, and
+ * never once ANY prior ask (install or upgrade) has been answered on this
+ * machine. Exported separately so the no-spam rule is unit-testable.
+ */
+export function shouldOfferBetaSignup(deps: BetaSignupDeps = {}): boolean {
+  const stdinTTY = deps.stdinIsTTY ?? process.stdin.isTTY;
+  const stdoutTTY = deps.stdoutIsTTY ?? process.stdout.isTTY;
+  if (!stdinTTY || !stdoutTTY) return false;
+  return !hasBetaSignupChoice(deps);
+}
+
+// Dynamic import helper — tsc compiles import() to require() in CJS mode,
+// which fails for ESM-only packages (same trick as installer/index.ts).
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const importESM = new Function('specifier', 'return import(specifier)') as
+  (specifier: string) => Promise<typeof import('@clack/prompts')>;
+
+/**
+ * The full interactive offer: confirm → email → submit → remember. Shared by
+ * `codegraph install` (end of a successful install) and `codegraph upgrade`
+ * (after a successful binary update). Silently does nothing when the gate
+ * says no; never throws — a marketing question must not fail the command
+ * that hosts it. Cancel (Ctrl-C) and a failed submit store nothing, so a
+ * later install/upgrade may offer again; an explicit yes or no is stored
+ * forever.
+ */
+export async function maybeOfferBetaSignup(deps: BetaSignupDeps = {}): Promise<void> {
+  try {
+    if (!shouldOfferBetaSignup(deps)) return;
+    const clack = await importESM('@clack/prompts');
+
+    const wantsBeta = await clack.confirm({
+      message:
+        'Want early access to CodeGraph Pro? Join the beta waitlist — we’ll only email you about CodeGraph, never share your address.',
+      initialValue: true,
+    });
+    if (clack.isCancel(wantsBeta)) {
+      clack.log.info(`Skipped — you can join anytime at ${BETA_SIGNUP_URL}.`);
+      return;
+    }
+    if (!wantsBeta) {
+      recordBetaSignupChoice(false, deps);
+      clack.log.info(`No problem — you can join anytime at ${BETA_SIGNUP_URL}.`);
+      return;
+    }
+
+    const email = await clack.text({
+      message: 'What email should we send beta access to?',
+      placeholder: 'you@company.com',
+      validate: (value) =>
+        EMAIL_RE.test((value ?? '').trim()) ? undefined : 'That email address doesn’t look right.',
+    });
+    if (clack.isCancel(email)) {
+      clack.log.info(`Skipped — you can join anytime at ${BETA_SIGNUP_URL}.`);
+      return;
+    }
+
+    const s = clack.spinner();
+    s.start('Joining the beta waitlist...');
+    const ok = await submitBetaSignup(email.trim(), deps);
+    if (ok) {
+      s.stop('You’re on the list — we’ll email you when beta access opens.');
+      recordBetaSignupChoice(true, deps);
+    } else {
+      s.stop('Couldn’t reach the waitlist right now.');
+      clack.log.warn(`No worries — you can join anytime at ${BETA_SIGNUP_URL}.`);
+    }
+  } catch {
+    /* never let the beta question break an install or upgrade */
+  }
+}

src/installer/clack.d.ts

@@ -31,6 +31,14 @@ declare module '@clack/prompts' {
     required?: boolean;
   }): Promise<Value[] | symbol>;
 
+  export function text(opts: {
+    message: string;
+    placeholder?: string;
+    defaultValue?: string;
+    initialValue?: string;
+    validate?: (value: string | undefined) => string | Error | undefined;
+  }): Promise<string | symbol>;
+
   export function spinner(): {
     start(message?: string): void;
     stop(message?: string): void;

src/installer/index.ts

@@ -29,6 +29,7 @@ import { watchDisabledReason } from '../sync/watch-policy';
 import { isGitRepo, isSyncHookInstalled, installGitSyncHook } from '../sync/git-hooks';
 import { getCodeGraphDir, codeGraphDirName } from '../directory';
 import { getTelemetry, TELEMETRY_DOCS } from '../telemetry';
+import { maybeOfferBetaSignup } from './beta-signup';
 
 // Backwards-compat: keep these named exports — downstream code may
 // import them. The shim in `config-writer.ts` continues to re-export
@@ -266,6 +267,17 @@ export async function runInstallerWithOptions(opts: RunInstallerOptions): Promis
     });
   }
 
+  // Step 5½: CodeGraph Pro beta opt-in — the same waitlist as the
+  // getcodegraph.com homepage form, offered once per machine at the end of a
+  // successful install (and after `codegraph upgrade` — the shared gate in
+  // maybeOfferBetaSignup means whichever asks first is the ONLY ask ever).
+  // Strictly opt-in (user answers yes AND types an email), never shown under
+  // --yes, and any yes/no answer is stored so nothing re-asks. Cancel or a
+  // failed submit stores nothing, so a later install/upgrade may offer again.
+  if (!useDefaults && installedIds.length > 0) {
+    await maybeOfferBetaSignup({ source: 'cli-install' });
+  }
+
   // Step 6: install wires up agents only — it deliberately does NOT index.
   // Building the per-project graph is the user's explicit `codegraph init`
   // (or `index`), so they choose what gets indexed and when, and we never

src/upgrade/index.ts

@@ -296,6 +296,13 @@ export interface UpgradeDeps {
   warn: (msg: string) => void;
   error: (msg: string) => void;
   platform: NodeJS.Platform;
+  /**
+   * Offer the one-time CodeGraph Pro beta opt-in after a successful update
+   * (see installer/beta-signup — self-gating: TTY only, and silent forever
+   * once any install/upgrade ask was answered). Optional so unit tests and
+   * embedded callers stay prompt-free; never fatal to the upgrade.
+   */
+  offerBetaSignup?: () => Promise<void>;
 }
 
 const c = {
@@ -413,6 +420,15 @@ export async function runUpgrade(opts: UpgradeOptions, deps: UpgradeDeps): Promi
     } else {
       deps.log(c.dim('Skipped refreshing agent instructions/config — run `codegraph install --refresh` once the PATH is fixed.'));
     }
+    // Reached only after a real binary update (check/up-to-date/npx/source
+    // all returned earlier) — the one place the upgrade path may offer the
+    // beta opt-in. The hook self-gates on TTY + the stored once-per-machine
+    // choice, so an already-answered user never sees it again.
+    try {
+      await deps.offerBetaSignup?.();
+    } catch {
+      /* a marketing question must never fail the upgrade */
+    }
   }
   return code;
 }