@tanstack/cli 0.62.5 → 0.63.0

package/dist/telemetry-config.js

@@ -0,0 +1,140 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const TELEMETRY_NOTICE_VERSION = 1;
+function createDefaultTelemetryConfig() {
+    return {
+        distinctId: randomUUID(),
+        enabled: true,
+        noticeVersion: 0,
+    };
+}
+function getHomeDirectory() {
+    return process.env.HOME || homedir();
+}
+function isTelemetryConfig(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    return (typeof record.distinctId === 'string' &&
+        typeof record.enabled === 'boolean' &&
+        typeof record.noticeVersion === 'number');
+}
+function getDisabledByEnvironment() {
+    if (process.env.DO_NOT_TRACK === '1') {
+        return 'env';
+    }
+    if (process.env.TANSTACK_CLI_TELEMETRY_DISABLED === '1') {
+        return 'env';
+    }
+    if (process.env.CI) {
+        return 'ci';
+    }
+    return undefined;
+}
+export function getTelemetryConfigPath() {
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME?.trim();
+    if (xdgConfigHome) {
+        return join(xdgConfigHome, 'tanstack', 'cli.json');
+    }
+    const homeDirectory = getHomeDirectory().trim();
+    if (homeDirectory) {
+        return join(homeDirectory, '.config', 'tanstack', 'cli.json');
+    }
+    return join(process.cwd(), '.tanstack', 'cli.json');
+}
+async function readTelemetryConfigFile(configPath) {
+    if (!existsSync(configPath)) {
+        return undefined;
+    }
+    try {
+        const raw = await readFile(configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isTelemetryConfig(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeTelemetryConfigFile(configPath, config) {
+    await mkdir(dirname(configPath), { recursive: true });
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+}
+async function readOrCreateTelemetryConfig(createIfMissing) {
+    const configPath = getTelemetryConfigPath();
+    const existingConfig = await readTelemetryConfigFile(configPath);
+    if (existingConfig || !createIfMissing) {
+        return {
+            config: existingConfig,
+            configPath,
+        };
+    }
+    const createdConfig = createDefaultTelemetryConfig();
+    await writeTelemetryConfigFile(configPath, createdConfig);
+    return {
+        config: createdConfig,
+        configPath,
+    };
+}
+export async function getTelemetryStatus(opts) {
+    const disabledBy = getDisabledByEnvironment();
+    const { config, configPath } = await readOrCreateTelemetryConfig(opts?.createIfMissing ?? !disabledBy);
+    if (!config) {
+        return {
+            configPath,
+            disabledBy,
+            distinctId: undefined,
+            enabled: false,
+            noticeVersion: 0,
+        };
+    }
+    if (disabledBy) {
+        return {
+            configPath,
+            disabledBy,
+            distinctId: config.distinctId,
+            enabled: false,
+            noticeVersion: config.noticeVersion,
+        };
+    }
+    if (!config.enabled) {
+        return {
+            configPath,
+            disabledBy: 'config',
+            distinctId: config.distinctId,
+            enabled: false,
+            noticeVersion: config.noticeVersion,
+        };
+    }
+    return {
+        configPath,
+        distinctId: config.distinctId,
+        enabled: true,
+        noticeVersion: config.noticeVersion,
+    };
+}
+export async function markTelemetryNoticeSeen() {
+    const { config, configPath } = await readOrCreateTelemetryConfig(true);
+    if (!config || config.noticeVersion >= TELEMETRY_NOTICE_VERSION) {
+        return;
+    }
+    await writeTelemetryConfigFile(configPath, {
+        ...config,
+        noticeVersion: TELEMETRY_NOTICE_VERSION,
+    });
+}
+export async function setTelemetryEnabled(enabled) {
+    const { config, configPath } = await readOrCreateTelemetryConfig(true);
+    const nextConfig = {
+        ...(config || createDefaultTelemetryConfig()),
+        enabled,
+    };
+    await writeTelemetryConfigFile(configPath, nextConfig);
+    return nextConfig;
+}

package/dist/telemetry.js

@@ -0,0 +1,195 @@
+import { version as nodeVersion } from 'node:process';
+import { getTelemetryStatus, markTelemetryNoticeSeen, TELEMETRY_NOTICE_VERSION, } from './telemetry-config.js';
+const POSTHOG_API_HOST = 'https://us.i.posthog.com';
+const POSTHOG_CAPTURE_ENDPOINT = `${POSTHOG_API_HOST}/capture/`;
+const POSTHOG_PROJECT_TOKEN = 'phc_xJ2VBahJBzy3BShLhuGpw7EyoSuQtgwXXvhE9BYtHuKQ';
+const TELEMETRY_NOTICE = 'TanStack CLI sends anonymous usage telemetry by default. It never sends project names, paths, raw search text, template URLs, add-on config values, or raw error messages. Disable it with `tanstack telemetry disable` or `TANSTACK_CLI_TELEMETRY_DISABLED=1`.';
+const TELEMETRY_TIMEOUT_MS = 1200;
+let telemetryStatusPromise;
+function getNodeMajorVersion() {
+    return Number.parseInt(nodeVersion.replace(/^v/, '').split('.')[0] || '0', 10);
+}
+function cleanProperties(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => cleanProperties(entry))
+            .filter((entry) => entry !== undefined);
+    }
+    if (value && typeof value === 'object') {
+        const cleanedEntries = Object.entries(value)
+            .map(([key, entry]) => [key, cleanProperties(entry)])
+            .filter(([, entry]) => entry !== undefined);
+        return Object.fromEntries(cleanedEntries);
+    }
+    if (value === undefined) {
+        return undefined;
+    }
+    return value;
+}
+function getErrorCode(error) {
+    if (!error || typeof error !== 'object') {
+        return 'unknown_error';
+    }
+    const message = String(error.message || '').toLowerCase();
+    if (message.includes('cancel')) {
+        return 'cancelled';
+    }
+    if (message.includes('invalid')) {
+        return 'invalid_input';
+    }
+    if (message.includes('not found')) {
+        return 'not_found';
+    }
+    if (message.includes('timed out')) {
+        return 'timeout';
+    }
+    if (message.includes('fetch') ||
+        message.includes('network') ||
+        message.includes('econn')) {
+        return 'network_error';
+    }
+    if (message.includes('permission') || message.includes('eacces')) {
+        return 'permission_error';
+    }
+    return 'unknown_error';
+}
+async function fetchTelemetryStatus() {
+    telemetryStatusPromise ?? (telemetryStatusPromise = getTelemetryStatus());
+    return telemetryStatusPromise;
+}
+async function postEvent(event, distinctId, properties) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, TELEMETRY_TIMEOUT_MS);
+    try {
+        await fetch(POSTHOG_CAPTURE_ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                api_key: POSTHOG_PROJECT_TOKEN,
+                distinct_id: distinctId,
+                event,
+                properties,
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        // Telemetry must never affect CLI behavior.
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export class TelemetryClient {
+    constructor(status) {
+        this.commandProperties = {};
+        this.pendingSteps = new Map();
+        this.completedSteps = [];
+        this.disabledBy = status.disabledBy;
+        this.distinctId = status.distinctId;
+        this.enabled = status.enabled && Boolean(status.distinctId);
+    }
+    mergeProperties(properties) {
+        this.commandProperties = {
+            ...this.commandProperties,
+            ...properties,
+        };
+    }
+    startStep(info) {
+        if (!this.enabled) {
+            return;
+        }
+        this.pendingSteps.set(info.id, {
+            startedAt: Date.now(),
+            type: info.type,
+        });
+    }
+    finishStep(id) {
+        if (!this.enabled) {
+            return;
+        }
+        const step = this.pendingSteps.get(id);
+        if (!step) {
+            return;
+        }
+        this.pendingSteps.delete(id);
+        this.completedSteps.push({
+            durationMs: Math.max(Date.now() - step.startedAt, 0),
+            id,
+            type: step.type,
+        });
+    }
+    async captureCommandStarted(command, properties) {
+        this.mergeProperties(properties);
+        if (!this.enabled || !this.distinctId) {
+            return;
+        }
+        void postEvent('command_started', this.distinctId, cleanProperties({
+            ...this.baseProperties(),
+            ...this.commandProperties,
+            command,
+        }));
+    }
+    async captureCommandCompleted(command, durationMs) {
+        if (!this.enabled || !this.distinctId) {
+            return;
+        }
+        await postEvent('command_completed', this.distinctId, cleanProperties({
+            ...this.baseProperties(),
+            ...this.commandProperties,
+            command,
+            duration_ms: durationMs,
+            result: 'success',
+            steps: this.completedSteps.map((step) => ({
+                duration_ms: step.durationMs,
+                id: step.id,
+                type: step.type,
+            })),
+        }));
+    }
+    async captureCommandFailed(command, durationMs, error) {
+        if (!this.enabled || !this.distinctId) {
+            return;
+        }
+        await postEvent('command_failed', this.distinctId, cleanProperties({
+            ...this.baseProperties(),
+            ...this.commandProperties,
+            command,
+            duration_ms: durationMs,
+            error_code: getErrorCode(error),
+            result: 'failed',
+            steps: this.completedSteps.map((step) => ({
+                duration_ms: step.durationMs,
+                id: step.id,
+                type: step.type,
+            })),
+        }));
+    }
+    baseProperties() {
+        return {
+            $lib: 'tanstack-cli',
+            disabled_by: this.disabledBy,
+            node_major: getNodeMajorVersion(),
+            os_arch: process.arch,
+            os_platform: process.platform,
+        };
+    }
+}
+export async function createTelemetryClient(opts) {
+    const status = await fetchTelemetryStatus();
+    if (status.enabled &&
+        status.noticeVersion < TELEMETRY_NOTICE_VERSION &&
+        !opts?.json) {
+        console.error(TELEMETRY_NOTICE);
+        await markTelemetryNoticeSeen();
+        telemetryStatusPromise = undefined;
+    }
+    return new TelemetryClient(await fetchTelemetryStatus());
+}
+export function resetTelemetryStateForTests() {
+    telemetryStatusPromise = undefined;
+}

package/dist/types/telemetry-config.d.ts

@@ -0,0 +1,47 @@
+export interface TelemetryConfig {
+    distinctId: string;
+    enabled: boolean;
+    noticeVersion: number;
+}
+export interface TelemetryStatus {
+    configPath: string;
+    disabledBy?: 'ci' | 'config' | 'env';
+    distinctId?: string;
+    enabled: boolean;
+    noticeVersion: number;
+}
+export declare const TELEMETRY_NOTICE_VERSION = 1;
+export declare function getTelemetryConfigPath(): string;
+export declare function getTelemetryStatus(opts?: {
+    createIfMissing?: boolean;
+}): Promise<{
+    configPath: string;
+    disabledBy: "ci" | "env" | undefined;
+    distinctId: undefined;
+    enabled: false;
+    noticeVersion: number;
+} | {
+    configPath: string;
+    disabledBy: "ci" | "env";
+    distinctId: string;
+    enabled: false;
+    noticeVersion: number;
+} | {
+    configPath: string;
+    disabledBy: "config";
+    distinctId: string;
+    enabled: false;
+    noticeVersion: number;
+} | {
+    configPath: string;
+    distinctId: string;
+    enabled: true;
+    noticeVersion: number;
+    disabledBy?: undefined;
+}>;
+export declare function markTelemetryNoticeSeen(): Promise<void>;
+export declare function setTelemetryEnabled(enabled: boolean): Promise<{
+    enabled: boolean;
+    distinctId: string;
+    noticeVersion: number;
+}>;

package/dist/types/telemetry.d.ts

@@ -0,0 +1,24 @@
+import { getTelemetryStatus } from './telemetry-config.js';
+import type { StatusEvent } from '@tanstack/create';
+type TelemetryProperties = Record<string, unknown>;
+export declare class TelemetryClient {
+    private commandProperties;
+    private pendingSteps;
+    private completedSteps;
+    private readonly disabledBy?;
+    private readonly distinctId?;
+    readonly enabled: boolean;
+    constructor(status: Awaited<ReturnType<typeof getTelemetryStatus>>);
+    mergeProperties(properties: TelemetryProperties): void;
+    startStep(info: StatusEvent): void;
+    finishStep(id: string): void;
+    captureCommandStarted(command: string, properties: TelemetryProperties): Promise<void>;
+    captureCommandCompleted(command: string, durationMs: number): Promise<void>;
+    captureCommandFailed(command: string, durationMs: number, error: unknown): Promise<void>;
+    private baseProperties;
+}
+export declare function createTelemetryClient(opts?: {
+    json?: boolean;
+}): Promise<TelemetryClient>;
+export declare function resetTelemetryStateForTests(): void;
+export {};

package/dist/types/types.d.ts

@@ -14,6 +14,8 @@ export interface CliOptions {
     templateId?: string;
     targetDir?: string;
     interactive?: boolean;
+    nonInteractive?: boolean;
+    yes?: boolean;
     devWatch?: string;
     runDev?: boolean;
     install?: boolean;

package/dist/types/ui-environment.d.ts

@@ -1,2 +1,3 @@
 import type { Environment } from '@tanstack/create';
-export declare function createUIEnvironment(appName: string, silent: boolean): Environment;
+import type { TelemetryClient } from './telemetry.js';
+export declare function createUIEnvironment(appName: string, silent: boolean, getTelemetry?: () => TelemetryClient | undefined): Environment;

package/dist/ui-environment.js

@@ -1,7 +1,7 @@
 import { cancel, confirm, intro, isCancel, log, outro, spinner, } from '@clack/prompts';
 import chalk from 'chalk';
 import { createDefaultEnvironment } from '@tanstack/create';
-export function createUIEnvironment(appName, silent) {
+export function createUIEnvironment(appName, silent, getTelemetry) {
     const defaultEnvironment = createDefaultEnvironment();
     let newEnvironment = {
         ...defaultEnvironment,
@@ -46,6 +46,23 @@ export function createUIEnvironment(appName, silent) {
                     },
                 };
             },
+            startStep: (info) => {
+                getTelemetry?.()?.startStep(info);
+            },
+            finishStep: (id, _finalMessage) => {
+                getTelemetry?.()?.finishStep(id);
+            },
+        };
+    }
+    else {
+        newEnvironment = {
+            ...newEnvironment,
+            startStep: (info) => {
+                getTelemetry?.()?.startStep(info);
+            },
+            finishStep: (id, _finalMessage) => {
+                getTelemetry?.()?.finishStep(id);
+            },
         };
     }
     return newEnvironment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cli",
-  "version": "0.62.5",
+  "version": "0.63.0",
   "description": "TanStack CLI",
   "type": "module",
   "main": "./dist/index.js",