bestax-migrate 2.0.1 → 2.1.0

package/README.md

@@ -84,6 +84,19 @@ A codemod rewrites your source in place, so how it is built and published matter
 
 Full detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)
 
+## Telemetry
+
+`bestax-migrate` can send one **anonymous** usage event after a successful
+run — only if you opt in when asked (once, on an interactive terminal). The
+event is just the run's shape — source library, CSS mode, the dry/deps flags, a
+capped changed-file count, and per-rule TODO counts — plus the CLI version,
+Node major version, and OS platform name. Never file paths, file contents,
+code, names, IPs, or machine IDs, and no identifier exists that could link two
+events together. Opt out any time with `--no-telemetry`,
+`BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.
+
+Full disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)
+
 ## License
 
 MIT © Alex Smith

package/dist/cli.d.ts

@@ -3,6 +3,7 @@
  *
  *   bestax-migrate <source> <paths...> [--dry] [--print] [--extensions ...]
  *                  [--css bestax|bulma|keep] [--no-deps]
+ *                  [--telemetry|--no-telemetry]
  *
  * Walks the given files/directories, routes each file by type (JS/TSX →
  * jscodeshift transform, .scss/.sass → the source's stylesheet transform),
@@ -10,7 +11,10 @@
  * (unless --dry), and prints the run report. TODO annotations are expected
  * output — the exit code is 0 whenever the run itself succeeds.
  */
+import { createInterface } from 'node:readline/promises';
+import type { Readable, Writable } from 'node:stream';
 import { Command } from 'commander';
+import { type MigrateRunStats } from './telemetry.js';
 export declare function collectFiles(targets: string[], extensions: string[]): string[];
 /** Nearest package.json for each target, walking up to the filesystem root. */
 export declare function findPackageJsons(targets: string[]): string[];
@@ -18,5 +22,20 @@ export interface CliIo {
     log: (message: string) => void;
     error: (message: string) => void;
 }
+/**
+ * One-question consent prompt (readline — this package carries no interactive
+ * prompt dependency). Returns null when the question is cancelled (Ctrl-C /
+ * Ctrl-D): a cancel is not an answer and nothing is persisted. The streams are
+ * injectable so tests can drive the question without a TTY.
+ */
+export declare function promptTelemetryConsent(io: CliIo, input?: Readable, output?: Writable, makeInterface?: typeof createInterface): Promise<boolean | null>;
+/**
+ * Consent + beacon after a successful run. Only success events are reported,
+ * the beacon is awaited (so no error path can kill an in-flight request), and
+ * nothing in here may throw or alter the exit code. The prompt is skipped
+ * without a TTY on both ends, under an explicit flag, or with DO_NOT_TRACK
+ * set (the non-interactive path must never hang).
+ */
+export declare function handleTelemetry(stats: MigrateRunStats, flag: boolean | undefined, io: CliIo, promptConsent?: (io: CliIo) => Promise<boolean | null>): Promise<void>;
 export declare function createCLI(io?: CliIo): Command;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CAkBV;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkB5D;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AA+HD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAkD,GACrD,OAAO,CA0FT"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAqBxE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EAAE,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CAkBV;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAkB5D;AAED,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AA2ID;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,KAAK,EACT,KAAK,GAAE,QAAwB,EAC/B,MAAM,GAAE,QAAyB,EAGjC,aAAa,GAAE,OAAO,eAAiC,GACtD,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAyBzB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,EAAE,EAAE,KAAK,EACT,aAAa,GAAE,CAAC,EAAE,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAA0B,GAC7E,OAAO,CAAC,IAAI,CAAC,CAqBf;AAYD,wBAAgB,SAAS,CACvB,EAAE,GAAE,KAAkD,GACrD,OAAO,CAkHT"}

package/dist/cli.js

@@ -3,6 +3,7 @@
  *
  *   bestax-migrate <source> <paths...> [--dry] [--print] [--extensions ...]
  *                  [--css bestax|bulma|keep] [--no-deps]
+ *                  [--telemetry|--no-telemetry]
  *
  * Walks the given files/directories, routes each file by type (JS/TSX →
  * jscodeshift transform, .scss/.sass → the source's stylesheet transform),
@@ -12,11 +13,13 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { Command } from 'commander';
 import { Reporter } from './report.js';
 import { runTransform } from './runner.js';
 import { getSource, sourceNames } from './sources/registry.js';
+import { reportMigrateRun } from './telemetry.js';
 const SKIP_DIRS = new Set([
     'node_modules',
     '.git',
@@ -172,6 +175,91 @@ function migrateDependencies(source, targets, reporter, io, options, bulmaRefere
         }
     }
 }
+const TELEMETRY_NOTICE = 'Help improve bestax-migrate — share anonymous usage stats?\n' +
+    "Sends only the run's shape (source library, CSS mode, dry/deps flags,\n" +
+    'changed-file count, rule names and counts) plus CLI version, Node major,\n' +
+    'and OS name. Never file paths, file contents, or code.\n' +
+    '  Details & opt-out: https://bestax.io/docs/guides/telemetry\n' +
+    '  Feedback welcome:  https://github.com/allxsmith/bestax/issues';
+const TELEMETRY_ACK_ON = 'Thanks! Opt out anytime with --no-telemetry.';
+const TELEMETRY_ACK_OFF = "No problem — we won't ask again.";
+const TELEMETRY_ACK_UNSAVED = "Couldn't save your choice (config dir not writable) — you may be asked again.";
+/**
+ * One-question consent prompt (readline — this package carries no interactive
+ * prompt dependency). Returns null when the question is cancelled (Ctrl-C /
+ * Ctrl-D): a cancel is not an answer and nothing is persisted. The streams are
+ * injectable so tests can drive the question without a TTY.
+ */
+export async function promptTelemetryConsent(io, input = process.stdin, output = process.stdout, 
+// Injectable for tests: SIGINT is only emitted by real TTY input, so a test
+// captures the interface through this factory and emits it directly.
+makeInterface = createInterface) {
+    io.log('');
+    io.log(chalk.gray(TELEMETRY_NOTICE));
+    const rl = makeInterface({ input, output });
+    const cancelled = new AbortController();
+    // Ctrl-C emits SIGINT on the interface and Ctrl-D closes it; both must
+    // reject the pending question instead of leaving it hanging forever.
+    rl.once('SIGINT', () => {
+        // Honor the interrupt instead of swallowing it into a zero exit: the run
+        // itself already succeeded, so no abrupt kill — but the ^C must be
+        // visible to callers. 130 = 128 + SIGINT, the shell convention.
+        process.exitCode = 130;
+        rl.close();
+    });
+    rl.once('close', () => cancelled.abort());
+    try {
+        const answer = await rl.question('Share anonymous usage stats? (y/N) ', {
+            signal: cancelled.signal,
+        });
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Consent + beacon after a successful run. Only success events are reported,
+ * the beacon is awaited (so no error path can kill an in-flight request), and
+ * nothing in here may throw or alter the exit code. The prompt is skipped
+ * without a TTY on both ends, under an explicit flag, or with DO_NOT_TRACK
+ * set (the non-interactive path must never hang).
+ */
+export async function handleTelemetry(stats, flag, io, promptConsent = promptTelemetryConsent) {
+    try {
+        await reportMigrateRun(stats, flag, {
+            interactive: process.stdin.isTTY === true && process.stdout.isTTY === true,
+            promptConsent: () => promptConsent(io),
+            onDecided: (enabled, persisted) => {
+                // Worded on whether the write actually stuck: promising "we won't
+                // ask again" after a swallowed write failure would be false.
+                if (!persisted) {
+                    io.log(chalk.dim(TELEMETRY_ACK_UNSAVED));
+                }
+                else if (enabled) {
+                    io.log(chalk.dim(TELEMETRY_ACK_ON));
+                }
+                else {
+                    io.log(chalk.dim(TELEMETRY_ACK_OFF));
+                }
+            },
+        });
+    }
+    catch {
+        // Telemetry must never affect the migration's outcome.
+    }
+}
+/** Post-run "star us" nudge — TTY only, so piped output stays parseable. */
+function displayStarNudge(io) {
+    if (process.stdout.isTTY !== true)
+        return;
+    io.log('');
+    io.log(chalk.yellow('★ If you enjoy using bestax-bulma, please star us on GitHub!'));
+    io.log(chalk.dim('   https://github.com/allxsmith/bestax'));
+}
 export function createCLI(io = { log: console.log, error: console.error }) {
     const program = new Command();
     program
@@ -184,7 +272,9 @@ export function createCLI(io = { log: console.log, error: console.error }) {
         .option('-e, --extensions <list>', 'comma-separated file extensions to include', 'js,jsx,ts,tsx,scss,sass')
         .option('--css <mode>', `stylesheet target: ${CSS_MODES.join(', ')}`, 'bestax')
         .option('--no-deps', 'skip updating package.json dependencies')
-        .action((sourceName, targets, options) => {
+        .option('--telemetry', 'enable anonymous usage telemetry (https://bestax.io/docs/guides/telemetry)')
+        .option('--no-telemetry', 'disable anonymous usage telemetry')
+        .action(async (sourceName, targets, options) => {
         const source = getSource(sourceName);
         if (!source) {
             io.error(`${chalk.red('Unknown source')} "${sourceName}". Available sources: ${sourceNames().join(', ')}`);
@@ -220,6 +310,19 @@ export function createCLI(io = { log: console.log, error: console.error }) {
         reportUnsupportedFiles(source, targets, reporter, extensions);
         migrateDependencies(source, targets, reporter, io, runOptions, bulmaReferenced);
         io.log(reporter.render(source.label + (runOptions.dry ? ' (dry run)' : '')));
+        displayStarNudge(io);
+        // Success path only: rule names and counts, never file/line/message.
+        const stats = {
+            source: source.name,
+            cssMode: runOptions.cssMode,
+            dry: runOptions.dry,
+            deps: runOptions.deps,
+            changedCount: reporter.changedCount,
+            todosByRule: reporter
+                .todosByRule()
+                .map(({ rule, entries }) => ({ rule, count: entries.length })),
+        };
+        await handleTelemetry(stats, options.telemetry, io);
     });
     return program;
 }

package/dist/index.js

@@ -9,5 +9,5 @@ if (major < 22) {
     process.exit(1);
 }
 const { createCLI } = await import('./cli.js');
-createCLI().parse();
+await createCLI().parseAsync(process.argv);
 export {};

package/dist/telemetry-core.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared CLI telemetry kernel (disclosure: https://bestax.io/docs/guides/telemetry).
+ *
+ * Copied byte-for-byte into create-bestax and bestax-migrate — both publish
+ * standalone, so this cannot be a workspace package. `check:conformance
+ * --only=telemetry-core` fails if the copies diverge. Edit this file in
+ * create-bestax and copy it over the migrate one.
+ *
+ * No identifier of any kind is generated. Undecided means off. Every failure
+ * here is silent: telemetry must never affect the CLI's outcome.
+ */
+export type TelemetryDecision = 'on' | 'off' | 'undecided';
+export type TelemetrySource = 'flag' | 'dnt' | 'env' | 'config' | 'default';
+export interface ResolvedTelemetry {
+    decision: TelemetryDecision;
+    source: TelemetrySource;
+}
+/** Shared across the bestax CLI family so consent is asked at most once. */
+export declare function telemetryConfigPath(): string;
+/**
+ * Precedence: flag (persisted by the caller) → DO_NOT_TRACK → BESTAX_TELEMETRY
+ * (per-run, never persisted) → config file → undecided (off).
+ */
+export declare function resolveTelemetry(flag?: boolean): Promise<ResolvedTelemetry>;
+/**
+ * Returns whether the decision was actually written: callers word their
+ * acknowledgement on it, because promising "we won't ask again" after a
+ * swallowed write failure would be false on every future run.
+ */
+export declare function persistTelemetryDecision(enabled: boolean, decidedBy: string): Promise<boolean>;
+export declare function sendTelemetry(payload: unknown): Promise<void>;
+export declare function getToolVersion(): string;
+export interface ReportRunOptions {
+    /** True only when a consent question could actually be answered. */
+    interactive: boolean;
+    /** Owns the consent UI up to the answer (notice, question); null = cancelled. */
+    promptConsent: () => Promise<boolean | null>;
+    /**
+     * Called after a prompted answer has been (attempted to be) saved, so the
+     * acknowledgement can tell the truth about whether it will stick.
+     */
+    onDecided?: (enabled: boolean, persisted: boolean) => void;
+}
+export declare function reportRun(flag: boolean | undefined, toolName: string, options: ReportRunOptions, payload: unknown): Promise<void>;
+//# sourceMappingURL=telemetry-core.d.ts.map

package/dist/telemetry-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-core.d.ts","sourceRoot":"","sources":["../src/telemetry-core.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,KAAK,GAAG,WAAW,CAAC;AAE3D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;CACzB;AAYD,4EAA4E;AAC5E,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AA6BD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,iBAAiB,CAAC,CAyB5B;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAWnE;AAED,wBAAgB,cAAc,IAAI,MAAM,CAUvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC7C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5D;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/telemetry-core.js

@@ -0,0 +1,141 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync } from 'fs';
+const DEFAULT_ENDPOINT = 'https://bestax.io/api/t';
+const TIMEOUT_MS = 1500;
+/** Shared across the bestax CLI family so consent is asked at most once. */
+export function telemetryConfigPath() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(base, 'bestax', 'telemetry.json');
+}
+async function readConfig() {
+    try {
+        const parsed = JSON.parse(await readFile(telemetryConfigPath(), 'utf-8'));
+        // Consent fails closed: only a well-formed v1 record is trusted. A bare
+        // {"enabled":true}, an array, or an unknown future schema version reads
+        // as "never asked" (prompt again) — never as an opt-in.
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed) &&
+            parsed.version === 1) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt config reads as "never asked".
+    }
+    return null;
+}
+function doNotTrack() {
+    const dnt = process.env.DO_NOT_TRACK;
+    return dnt !== undefined && dnt !== '' && dnt !== '0';
+}
+/**
+ * Precedence: flag (persisted by the caller) → DO_NOT_TRACK → BESTAX_TELEMETRY
+ * (per-run, never persisted) → config file → undecided (off).
+ */
+export async function resolveTelemetry(flag) {
+    if (flag !== undefined) {
+        return {
+            decision: flag ? 'on' : 'off',
+            source: 'flag',
+        };
+    }
+    if (doNotTrack()) {
+        return { decision: 'off', source: 'dnt' };
+    }
+    const env = process.env.BESTAX_TELEMETRY;
+    if (env === '0' || env === '1') {
+        return {
+            decision: env === '1' ? 'on' : 'off',
+            source: 'env',
+        };
+    }
+    const config = await readConfig();
+    if (config && typeof config.enabled === 'boolean') {
+        return {
+            decision: config.enabled ? 'on' : 'off',
+            source: 'config',
+        };
+    }
+    return { decision: 'undecided', source: 'default' };
+}
+/**
+ * Returns whether the decision was actually written: callers word their
+ * acknowledgement on it, because promising "we won't ask again" after a
+ * swallowed write failure would be false on every future run.
+ */
+export async function persistTelemetryDecision(enabled, decidedBy) {
+    try {
+        const config = {
+            version: 1,
+            enabled,
+            decidedAt: new Date().toISOString(),
+            decidedBy,
+        };
+        const filePath = telemetryConfigPath();
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        return true;
+    }
+    catch {
+        // An unwritable config dir must not break the CLI.
+        return false;
+    }
+}
+export async function sendTelemetry(payload) {
+    try {
+        await fetch(process.env.BESTAX_TELEMETRY_ENDPOINT || DEFAULT_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Fire-and-forget: the response (or its absence) is never surfaced.
+    }
+}
+export function getToolVersion() {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const packageJson = JSON.parse(readFileSync(join(dir, '..', 'package.json'), 'utf-8'));
+        return packageJson.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export async function reportRun(flag, toolName, options, payload) {
+    const resolved = await resolveTelemetry(flag);
+    let decision = resolved.decision;
+    if (resolved.source === 'flag') {
+        // Flags are the scripted equivalent of the prompt: decided once,
+        // remembered — EXCEPT under DO_NOT_TRACK, where the flag still applies to
+        // this one run (an explicit ask on the command line wins) but is never
+        // written down, so a copied command containing --telemetry cannot enable
+        // telemetry beyond the run it was typed for.
+        if (!doNotTrack()) {
+            const persisted = await persistTelemetryDecision(decision === 'on', `${toolName}@${getToolVersion()}`);
+            // A silently unsaved flag is worse than an unsaved answer: with an
+            // opposite value already in the shared config, --no-telemetry would
+            // apply to this run only and the next family run would re-enable.
+            if (!persisted) {
+                options.onDecided?.(decision === 'on', false);
+            }
+        }
+    }
+    else if (decision === 'undecided' && options.interactive) {
+        const answer = await options.promptConsent();
+        if (answer !== null) {
+            const persisted = await persistTelemetryDecision(answer, `${toolName}@${getToolVersion()}`);
+            decision = answer ? 'on' : 'off';
+            options.onDecided?.(answer, persisted);
+        }
+    }
+    if (decision === 'on') {
+        await sendTelemetry(payload);
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,53 @@
+import type { ReportRunOptions } from './telemetry-core.js';
+/**
+ * bestax-migrate payload + reporter. The kernel lives in telemetry-core.ts
+ * (copied from create-bestax; `check:conformance --only=telemetry-core`).
+ *
+ * Envelope and props are closed enums, versions, or bounded integers.
+ * `todosByRule` slugs are migrate's own rule names (including `prop:<jsxProp>`),
+ * never file paths, messages, or code.
+ */
+/**
+ * Client half of the wire-contract caps. The worker's schema.ts / validate.ts
+ * (telemetry-worker) hold the other half; scripts/telemetry-contract.test.mjs
+ * pins each pair equal (TODO_RULES_CAP === MAX_TODO_RULES, TODO_COUNT_CAP ===
+ * MAX_CHANGED_COUNT, CHANGED_COUNT_CAP === CHANGED_COUNT_DOUBLE_CAP).
+ */
+export declare const TODO_RULES_CAP = 20;
+export declare const TODO_COUNT_CAP = 100000;
+export declare const CHANGED_COUNT_CAP = 10000;
+export interface MigrateRunStats {
+    /** Registry source name, e.g. 'react-bulma-components'. */
+    source: string;
+    /** 'bestax' | 'bulma' | 'keep'. */
+    cssMode: string;
+    dry: boolean;
+    deps: boolean;
+    changedCount: number;
+    todosByRule: Array<{
+        rule: string;
+        count: number;
+    }>;
+}
+export interface MigratePayload {
+    v: 1;
+    tool: 'bestax-migrate';
+    event: 'migrate';
+    toolVersion: string;
+    nodeMajor: number;
+    platform: string;
+    props: {
+        source: string;
+        cssMode: string;
+        dry: boolean;
+        deps: boolean;
+        changedCount: number;
+    };
+    todosByRule?: Array<{
+        rule: string;
+        count: number;
+    }>;
+}
+export declare function buildMigratePayload(stats: MigrateRunStats): MigratePayload;
+export declare function reportMigrateRun(stats: MigrateRunStats, flag: boolean | undefined, options: ReportRunOptions): Promise<void>;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,eAAO,MAAM,cAAc,SAAS,CAAC;AACrC,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE;QACL,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,OAAO,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QAGd,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,WAAW,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,cAAc,CAuB1E;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,GAAG,SAAS,EACzB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/dist/telemetry.js

@@ -0,0 +1,45 @@
+import { getToolVersion, reportRun } from './telemetry-core.js';
+/**
+ * bestax-migrate payload + reporter. The kernel lives in telemetry-core.ts
+ * (copied from create-bestax; `check:conformance --only=telemetry-core`).
+ *
+ * Envelope and props are closed enums, versions, or bounded integers.
+ * `todosByRule` slugs are migrate's own rule names (including `prop:<jsxProp>`),
+ * never file paths, messages, or code.
+ */
+/**
+ * Client half of the wire-contract caps. The worker's schema.ts / validate.ts
+ * (telemetry-worker) hold the other half; scripts/telemetry-contract.test.mjs
+ * pins each pair equal (TODO_RULES_CAP === MAX_TODO_RULES, TODO_COUNT_CAP ===
+ * MAX_CHANGED_COUNT, CHANGED_COUNT_CAP === CHANGED_COUNT_DOUBLE_CAP).
+ */
+export const TODO_RULES_CAP = 20;
+export const TODO_COUNT_CAP = 100000;
+export const CHANGED_COUNT_CAP = 10000;
+export function buildMigratePayload(stats) {
+    const todosByRule = stats.todosByRule
+        .slice(0, TODO_RULES_CAP)
+        .map(({ rule, count }) => ({
+        rule,
+        count: Math.min(count, TODO_COUNT_CAP),
+    }));
+    return {
+        v: 1,
+        tool: 'bestax-migrate',
+        event: 'migrate',
+        toolVersion: getToolVersion(),
+        nodeMajor: Number(process.versions.node.split('.')[0]),
+        platform: process.platform,
+        props: {
+            source: stats.source,
+            cssMode: stats.cssMode,
+            dry: stats.dry,
+            deps: stats.deps,
+            changedCount: Math.min(stats.changedCount, CHANGED_COUNT_CAP),
+        },
+        ...(todosByRule.length > 0 ? { todosByRule } : {}),
+    };
+}
+export async function reportMigrateRun(stats, flag, options) {
+    await reportRun(flag, 'bestax-migrate', options, buildMigratePayload(stats));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bestax-migrate",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Codemods for migrating existing React apps from other Bulma libraries to @allxsmith/bestax-bulma",
   "type": "module",
   "bin": {
@@ -51,7 +51,7 @@
     "react-dom": "^19.2.8",
     "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",
-    "@allxsmith/bestax-bulma": "^5.11.1"
+    "@allxsmith/bestax-bulma": "^5.11.2"
   },
   "publishConfig": {
     "access": "public"
@@ -70,5 +70,5 @@
     "clean": "rimraf dist",
     "release": "npx semantic-release"
   },
-  "readme": "# bestax-migrate\n\n[![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/bestax-migrate)](https://socket.dev/npm/package/bestax-migrate/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nCodemods that migrate existing React apps to [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — the actively maintained React component library for **Bulma v1**.\n\nCurrently supported source libraries:\n\n| Source                                                                           | Status                                                            |\n| -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |\n| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs) |\n\n## Requirements\n\n**Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the CLI\nexits immediately with an explicit upgrade message.\n\nThis applies only to the Node version the codemod itself runs on. It places no requirement on\nthe app being migrated — the source is read as text and is never executed.\n\n## Usage\n\n```bash\n# Preview what would change (no writes)\npnpm dlx bestax-migrate react-bulma-components src/ --dry\n\n# Apply the migration\npnpm dlx bestax-migrate react-bulma-components src/\n```\n\nnpm and yarn work too: `npx bestax-migrate …` / `yarn dlx bestax-migrate …`.\n\nThe codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:\n\n- rewrite `react-bulma-components` imports to `@allxsmith/bestax-bulma` (including `const { Input } = Form` destructuring and namespace imports)\n- rename components and compound sub-components (`Form.Textarea` → `TextArea`, `Card.Footer.Item` → `Card.FooterItem`, `Hero.Footer` → `Hero.Foot`, …)\n- convert props (`renderAs` → `as`, `loading` → `isLoading`, numeric spacing/text sizes → string unions, `textAlign=\"center\"` → `textAlign=\"centered\"`, …)\n- flatten responsive breakpoint objects (`mobile={{ size: 4 }}` → `sizeMobile={4}`)\n- restructure patterns bestax models differently (`Table.Container`, Navbar dropdowns, `Form.Help`, icon-font children → `<Icon name=…>`)\n- migrate stylesheets: CSS imports converge on `@allxsmith/bestax-bulma/bestax.css`, and SCSS files move from Bulma 0.9's `@import` + `$var !default` overrides to `@use 'bulma/sass' with (…)` plus `@use '@allxsmith/bestax-bulma/scss/extras'`\n- update `package.json`: remove `react-bulma-components`, add `@allxsmith/bestax-bulma`, bump `bulma` to `^1`, and swap the dead `node-sass` for dart `sass` (no install is ever run)\n\nAnything without a safe automatic conversion is left in place with a `// TODO(bestax-migrate): …` comment, and the run ends with a report of every TODO by file and line. TODOs are expected output, not errors — resolve them with the [migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components), or let the [`bestax-migrate` Agent Skill](https://bestax.io/docs/skills/intro) walk them for you:\n\n```bash\nnpx skills add https://github.com/allxsmith/bestax --skill bestax-migrate\n```\n\n## Options\n\n| Flag                 | Description                                                    |\n| -------------------- | -------------------------------------------------------------- |\n| `--dry`, `-d`        | Report what would change without writing files                 |\n| `--print`, `-p`      | Print transformed sources to stdout                            |\n| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`) |\n| `--css <mode>`       | Stylesheet target: `bestax` (default), `bulma`, or `keep`      |\n| `--no-deps`          | Skip updating package.json dependencies                        |\n\n## After the codemod\n\n1. Run your package manager's install (the codemod rewrote `package.json` but never installs)\n2. Search for `TODO(bestax-migrate)` and resolve each comment\n3. Typecheck/build and review the rendered app\n\nFull walkthrough: [react-bulma-components migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components).\n\n## Hardened by default\n\nA codemod rewrites your source in place, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/bestax-migrate#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **The libraries this tool migrates away from are never installed here** — source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## License\n\nMIT © Alex Smith\n"
+  "readme": "# bestax-migrate\n\n[![npm version](https://img.shields.io/npm/v/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![npm downloads](https://img.shields.io/npm/dm/bestax-migrate.svg)](https://www.npmjs.com/package/bestax-migrate)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Socket Badge](https://socket.dev/api/badge/npm/package/bestax-migrate)](https://socket.dev/npm/package/bestax-migrate/overview)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/allxsmith/bestax/badge)](https://scorecard.dev/viewer/?uri=github.com/allxsmith/bestax)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-3fb950.svg)](https://www.npmjs.com/package/bestax-migrate#provenance)\n[![Security policy](https://img.shields.io/badge/security-policy-blue.svg)](https://github.com/allxsmith/bestax/blob/main/SECURITY.md)\n\nCodemods that migrate existing React apps to [`@allxsmith/bestax-bulma`](https://www.npmjs.com/package/@allxsmith/bestax-bulma) — the actively maintained React component library for **Bulma v1**.\n\nCurrently supported source libraries:\n\n| Source                                                                           | Status                                                            |\n| -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |\n| [`react-bulma-components`](https://github.com/couds/react-bulma-components) (v4) | ✅ All 32 components mapped (a few patterns are flagged as TODOs) |\n\n## Requirements\n\n**Node.js 22 or newer.** Node 18 and 20 are both past end-of-life. On an older runtime the CLI\nexits immediately with an explicit upgrade message.\n\nThis applies only to the Node version the codemod itself runs on. It places no requirement on\nthe app being migrated — the source is read as text and is never executed.\n\n## Usage\n\n```bash\n# Preview what would change (no writes)\npnpm dlx bestax-migrate react-bulma-components src/ --dry\n\n# Apply the migration\npnpm dlx bestax-migrate react-bulma-components src/\n```\n\nnpm and yarn work too: `npx bestax-migrate …` / `yarn dlx bestax-migrate …`.\n\nThe codemod uses [jscodeshift](https://github.com/facebook/jscodeshift) to:\n\n- rewrite `react-bulma-components` imports to `@allxsmith/bestax-bulma` (including `const { Input } = Form` destructuring and namespace imports)\n- rename components and compound sub-components (`Form.Textarea` → `TextArea`, `Card.Footer.Item` → `Card.FooterItem`, `Hero.Footer` → `Hero.Foot`, …)\n- convert props (`renderAs` → `as`, `loading` → `isLoading`, numeric spacing/text sizes → string unions, `textAlign=\"center\"` → `textAlign=\"centered\"`, …)\n- flatten responsive breakpoint objects (`mobile={{ size: 4 }}` → `sizeMobile={4}`)\n- restructure patterns bestax models differently (`Table.Container`, Navbar dropdowns, `Form.Help`, icon-font children → `<Icon name=…>`)\n- migrate stylesheets: CSS imports converge on `@allxsmith/bestax-bulma/bestax.css`, and SCSS files move from Bulma 0.9's `@import` + `$var !default` overrides to `@use 'bulma/sass' with (…)` plus `@use '@allxsmith/bestax-bulma/scss/extras'`\n- update `package.json`: remove `react-bulma-components`, add `@allxsmith/bestax-bulma`, bump `bulma` to `^1`, and swap the dead `node-sass` for dart `sass` (no install is ever run)\n\nAnything without a safe automatic conversion is left in place with a `// TODO(bestax-migrate): …` comment, and the run ends with a report of every TODO by file and line. TODOs are expected output, not errors — resolve them with the [migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components), or let the [`bestax-migrate` Agent Skill](https://bestax.io/docs/skills/intro) walk them for you:\n\n```bash\nnpx skills add https://github.com/allxsmith/bestax --skill bestax-migrate\n```\n\n## Options\n\n| Flag                 | Description                                                    |\n| -------------------- | -------------------------------------------------------------- |\n| `--dry`, `-d`        | Report what would change without writing files                 |\n| `--print`, `-p`      | Print transformed sources to stdout                            |\n| `--extensions`, `-e` | File extensions to include (default `js,jsx,ts,tsx,scss,sass`) |\n| `--css <mode>`       | Stylesheet target: `bestax` (default), `bulma`, or `keep`      |\n| `--no-deps`          | Skip updating package.json dependencies                        |\n\n## After the codemod\n\n1. Run your package manager's install (the codemod rewrote `package.json` but never installs)\n2. Search for `TODO(bestax-migrate)` and resolve each comment\n3. Typecheck/build and review the rendered app\n\nFull walkthrough: [react-bulma-components migration guide](https://bestax.io/docs/guides/getting-started/migration/react-bulma-components).\n\n## Hardened by default\n\nA codemod rewrites your source in place, so how it is built and published matters:\n\n- **Signed provenance** — every release carries a sigstore attestation linking the tarball to the exact commit and CI run that built it. Check the **Provenance** section on the [npm page](https://www.npmjs.com/package/bestax-migrate#provenance), or run `npm audit signatures`.\n- **npm OIDC trusted publishing** — short-lived, per-run credentials; no long-lived `NPM_TOKEN` exists to be stolen. Release commits and tags are GPG-signed.\n- **Socket.dev scans every PR** for malware, install scripts, obfuscated code, and privilege escalation before it can reach `main`.\n- **The libraries this tool migrates away from are never installed here** — source fixtures are read as text only, so no unmaintained third-party package enters the dependency tree.\n- **Dependencies are a deliberate act** — install scripts are blocked unless individually allow-listed, freshly published versions are refused for 3 days, and CI installs only what the reviewed lockfile resolves.\n- **Every GitHub Action is pinned to a full commit SHA**, and CodeQL, Dependency Review, and Dependabot run continuously alongside a high-severity `pnpm audit` gate.\n- **Layered AI review before merge** — [CodeRabbit](https://coderabbit.ai) plus an independent adversarial Claude review (a different model from the one writing AI-authored changes), on top of required green CI, an approving review, and a human merge.\n\nFull detail: [`SECURITY.md`](https://github.com/allxsmith/bestax/blob/main/SECURITY.md) · [Security guide](https://bestax.io/docs/guides/security)\n\n## Telemetry\n\n`bestax-migrate` can send one **anonymous** usage event after a successful\nrun — only if you opt in when asked (once, on an interactive terminal). The\nevent is just the run's shape — source library, CSS mode, the dry/deps flags, a\ncapped changed-file count, and per-rule TODO counts — plus the CLI version,\nNode major version, and OS platform name. Never file paths, file contents,\ncode, names, IPs, or machine IDs, and no identifier exists that could link two\nevents together. Opt out any time with `--no-telemetry`,\n`BESTAX_TELEMETRY=0`, or `DO_NOT_TRACK=1`.\n\nFull disclosure of every field and control: [Telemetry guide](https://bestax.io/docs/guides/telemetry)\n\n## License\n\nMIT © Alex Smith\n"
 }