feat(cli): report anonymous install telemetry

After a successful pgflow install, send one strict allowlisted contribution with the fixed package version, fresh/update/no-op result, and bucketed copied-migration count. CI, tests, DO_NOT_TRACK, and PGFLOW_TELEMETRY_DISABLED suppress the event; request failures never affect installation.

Reuse the existing telemetry worker and retention policy, extend its allowlist and tests, and expand the single telemetry reference page with an upfront no-identifiers guarantee, exact CLI payload, and both CLI and database opt-out controls. Raw migration timestamps, filenames, paths, errors, and project values never leave the machine.

Author: Agent

.changeset/quiet-install-signals.md

@@ -0,0 +1,5 @@
+---
+"pgflow": patch
+---
+
+Report anonymous fresh, update, or no-op install completion telemetry with the pgflow version and a bucketed migration count. CI, tests, `DO_NOT_TRACK`, and `PGFLOW_TELEMETRY_DISABLED` disable the event.

apps/telemetry-worker/src/index.test.ts

@@ -50,6 +50,24 @@ describe('telemetry ingest', () => {
     expect(points).toHaveLength(3);
   });
 
+  it.each([
+    'cli_install_fresh',
+    'cli_install_update',
+    'cli_install_noop',
+  ])('accepts the %s event with version and migration-count bucket', async (metric) => {
+    const { env, points } = makeEnv();
+    const res = await post({
+      schema: 1,
+      contributions: [{ metric, bucket: '0.18.0', count: '4-7' }],
+    }, env);
+    expect(res.status).toBe(204);
+    expect(points).toEqual([{
+      indexes: [metric],
+      blobs: ['0.18.0', '4-7'],
+      doubles: [1],
+    }]);
+  });
+
   it('stores the count bucket as a second blob', async () => {
     const { env, points } = makeEnv();
     await post(valid, env);

apps/telemetry-worker/src/index.ts

@@ -29,6 +29,9 @@ type BucketKind =
   | 'yes' | 'semver';
 
 const METRICS: Record<string, BucketKind> = {
+  cli_install_fresh: 'semver',
+  cli_install_update: 'semver',
+  cli_install_noop: 'semver',
   active_db_day: 'yes',
   workers_by_version: 'semver',
   version_changed: 'yes',

pkgs/cli/__tests__/commands/install/report-install-telemetry.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest';
+import { reportInstallTelemetry } from '../../../src/commands/install/report-install-telemetry';
+
+const result = { kind: 'update' as const, copied: 5 };
+
+describe('reportInstallTelemetry', () => {
+  it.each([
+    ['fresh', 12, '8-15'],
+    ['update', 5, '4-7'],
+    ['noop', 0, '0'],
+  ] as const)('reports a successful %s install', async (kind, copied, count) => {
+    const send = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
+
+    await reportInstallTelemetry(
+      { kind, copied },
+      { env: {}, version: '0.18.0', send },
+    );
+
+    expect(send).toHaveBeenCalledOnce();
+    const [url, request] = send.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://pgflow-telemetry.workers.dev/');
+    expect(request.method).toBe('POST');
+    expect(JSON.parse(request.body as string)).toEqual({
+      schema: 1,
+      contributions: [{
+        metric: `cli_install_${kind}`,
+        bucket: '0.18.0',
+        count,
+      }],
+    });
+  });
+
+  it.each([
+    { CI: 'true' },
+    { NODE_ENV: 'test' },
+    { DO_NOT_TRACK: '1' },
+    { PGFLOW_TELEMETRY_DISABLED: 'true' },
+  ])('does not report when disabled by $env', async (env) => {
+    const send = vi.fn();
+    await reportInstallTelemetry(result, { env, version: '0.18.0', send });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('does not report an invalid version', async () => {
+    const send = vi.fn();
+    await reportInstallTelemetry(result, { env: {}, version: 'unknown', send });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it('never fails installation when the request fails', async () => {
+    const send = vi.fn().mockRejectedValue(new Error('offline'));
+    await expect(
+      reportInstallTelemetry(result, { env: {}, version: '0.18.0', send }),
+    ).resolves.toBeUndefined();
+  });
+});

pkgs/cli/scripts/test-install

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -e
+export PGFLOW_TELEMETRY_DISABLED=1
 
 # Script to test pgflow CLI install functionality
 # Uses a temp directory to avoid conflicts with other tests

pkgs/cli/scripts/test-install-duplicates

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -e
+export PGFLOW_TELEMETRY_DISABLED=1
 
 # Script to test pgflow CLI install duplicate prevention
 # Uses a temp directory to avoid conflicts with other tests

pkgs/cli/src/commands/install/copy-migrations.ts

@@ -155,13 +155,18 @@ function generateNewTimestamp(
 // Find the migrations directory
 const sourcePath = findMigrationsDirectory();
 
+export type MigrationInstallResult = {
+  kind: 'fresh' | 'update' | 'noop';
+  copied: number;
+};
+
 export async function copyMigrations({
   supabasePath,
   autoConfirm = false,
 }: {
   supabasePath: string;
   autoConfirm?: boolean;
-}): Promise<boolean> {
+}): Promise<MigrationInstallResult | null> {
   const migrationsPath = path.join(supabasePath, 'migrations');
 
   if (!fs.existsSync(migrationsPath)) {
@@ -180,7 +185,7 @@ export async function copyMigrations({
     log.info(
       'If running in development mode, try building the core package first with: nx build core'
     );
-    return false;
+    return null;
   }
 
   // Get all existing migrations in user's directory
@@ -231,10 +236,10 @@ export async function copyMigrations({
     }
   }
 
-  // If no files to copy, show message and return false (no changes made)
+  // If no files need copying, this is a successful no-op install.
   if (filesToCopy.length === 0) {
     log.success('Migrations already up to date');
-    return false;
+    return { kind: 'noop', copied: 0 };
   }
 
   // Generate new timestamps for migrations to install
@@ -267,7 +272,7 @@ export async function copyMigrations({
 
     if (confirmResult !== true) {
       log.warn('Migration installation skipped');
-      return false;
+      return null;
     }
   }
 
@@ -281,5 +286,8 @@ export async function copyMigrations({
 
   log.success(`Installed ${filesToCopy.length} migration${filesToCopy.length !== 1 ? 's' : ''}`);
 
-  return true; // Return true to indicate migrations were copied
+  return {
+    kind: skippedFiles.length === 0 ? 'fresh' : 'update',
+    copied: filesToCopy.length,
+  };
 }

pkgs/cli/src/commands/install/index.ts

@@ -6,6 +6,7 @@ import { updateConfigToml } from './update-config-toml.js';
 import { createFlowsDirectory } from './create-flows-directory.js';
 import { createExampleWorker } from './create-example-worker.js';
 import { supabasePathPrompt } from './supabase-path-prompt.js';
+import { reportInstallTelemetry } from './report-install-telemetry.js';
 
 export default (program: Command) => {
   program
@@ -38,6 +39,14 @@ export default (program: Command) => {
         `  • Create ${chalk.cyan('supabase/functions/greet-user-worker/')} ${chalk.dim('(example worker)')}`,
         '',
         `  ${chalk.green('✓ Safe to re-run - completed steps will be skipped')}`,
+        '',
+        chalk.dim(
+          'Anonymous telemetry: after success, pgflow sends only this pgflow version, whether this was a fresh install, update, or no-op, and a bucketed count of copied migrations.'
+        ),
+        chalk.dim(
+          `No identifiers, paths, migration names, or exact project values. Set ${chalk.bold('PGFLOW_TELEMETRY_DISABLED=1')} to opt out.`
+        ),
+        chalk.blue.underline('https://pgflow.dev/reference/telemetry/'),
       ].join('\n');
 
       log.info(summaryMsg);
@@ -85,8 +94,10 @@ export default (program: Command) => {
 
       // Step 4: Show completion message
       const outroMessages: string[] = [];
+      const migrationsChanged =
+        migrations?.kind === 'fresh' || migrations?.kind === 'update';
 
-      if (migrations || configUpdate || flowsDirectory || exampleWorker) {
+      if (migrationsChanged || configUpdate || flowsDirectory || exampleWorker) {
         outroMessages.push(chalk.green.bold('✓ Installation complete!'));
       } else {
         outroMessages.push(
@@ -107,7 +118,7 @@ export default (program: Command) => {
         stepNumber++;
       }
 
-      if (migrations) {
+      if (migrationsChanged) {
         outroMessages.push(
           `  ${stepNumber}. Apply migrations: ${chalk.cyan('supabase migrations up')}`
         );
@@ -119,5 +130,9 @@ export default (program: Command) => {
       );
 
       outro(outroMessages.join('\n'));
+
+      if (migrations) {
+        await reportInstallTelemetry(migrations);
+      }
     });
 };

pkgs/cli/src/commands/install/report-install-telemetry.ts

@@ -0,0 +1,67 @@
+import { getVersion } from '../../utils/get-version.js';
+import type { MigrationInstallResult } from './copy-migrations.js';
+
+const ENDPOINT = 'https://pgflow-telemetry.workers.dev/';
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+type Environment = Record<string, string | undefined>;
+type Send = typeof globalThis.fetch;
+
+const isSet = (value: string | undefined) => {
+  const normalized = value?.toLowerCase();
+  return normalized !== undefined
+    && normalized !== ''
+    && normalized !== '0'
+    && normalized !== 'false';
+};
+
+function telemetryDisabled(env: Environment): boolean {
+  return env.NODE_ENV === 'test'
+    || isSet(env.CI)
+    || isSet(env.DO_NOT_TRACK)
+    || isSet(env.PGFLOW_TELEMETRY_DISABLED);
+}
+
+function bucketCount(value: number): string {
+  if (value === 0) return '0';
+  if (value === 1) return '1';
+  if (value <= 3) return '2-3';
+  if (value <= 7) return '4-7';
+  if (value <= 15) return '8-15';
+  if (value <= 31) return '16-31';
+  if (value <= 63) return '32-63';
+  if (value <= 127) return '64-127';
+  if (value <= 255) return '128-255';
+  return '256+';
+}
+
+export async function reportInstallTelemetry(
+  result: MigrationInstallResult,
+  {
+    env = process.env,
+    version = getVersion(),
+    send = globalThis.fetch,
+  }: { env?: Environment; version?: string; send?: Send } = {},
+): Promise<void> {
+  if (telemetryDisabled(env) || version.length > 32 || !SEMVER_RE.test(version)) {
+    return;
+  }
+
+  try {
+    await send(ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        schema: 1,
+        contributions: [{
+          metric: `cli_install_${result.kind}`,
+          bucket: version,
+          count: bucketCount(result.copied),
+        }],
+      }),
+      signal: AbortSignal.timeout(500),
+    });
+  } catch {
+    // Telemetry must never delay or fail installation.
+  }
+}