great-cto 2.69.0 → 2.70.1

package/dist/main.js

@@ -11,7 +11,7 @@
 //   7. bootstrap .great_cto/PROJECT.md
 //   8. print next steps
 import { resolve } from "node:path";
-import { banner, bold, cyan, dim, error, green, log, step, success, warn, yellow, confirm } from "./ui.js";
+import { banner, bold, cyan, dim, error, gray, green, log, step, success, warn, yellow, confirm } from "./ui.js";
 import { detect } from "./detect.js";
 import { pickArchetype, suggestCompliance } from "./archetypes.js";
 import { install, findInstalledVersions } from "./installer.js";
@@ -20,6 +20,7 @@ import { installAllCompanions } from "./companion.js";
 import { bootstrap } from "./bootstrap.js";
 import { compileFlow } from "./flow.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
+import { sendUsagePing, sendInstallPing, telemetrySubcommand, isTelemetryEnabled, computeAnonId } from "./telemetry.js";
 import { readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync, readdirSync, unlinkSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -96,6 +97,8 @@ function parseArgs(argv) {
             args.command = "board";
         else if (a === "console")
             args.command = "console";
+        else if (a === "telemetry")
+            args.command = "telemetry";
         else if (a === "register")
             args.command = "register";
         else if (a === "ci")
@@ -213,7 +216,13 @@ function findBoardServerPath() {
     const pluginBase = join(homedir(), ".claude", "plugins", "cache", "local", "great_cto");
     if (fsExistsSync(pluginBase)) {
         try {
-            const versions = readdirSync(pluginBase).filter(v => /^\d/.test(v)).sort().reverse();
+            // Numeric semver sort — a plain .sort() is lexicographic and would rank
+            // 2.99.0 above 2.100.0 (and once ranked 2.7.0 above 2.69.0).
+            const byVer = (a, b) => {
+                const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+                return (pb[0] - pa[0]) || (pb[1] - pa[1]) || (pb[2] - pa[2]) || 0;
+            };
+            const versions = readdirSync(pluginBase).filter(v => /^\d/.test(v)).sort(byVer);
             for (const v of versions.slice(0, 5)) {
                 candidates.push(join(pluginBase, v, "packages", "board", "server.mjs"));
             }
@@ -373,6 +382,13 @@ ${bold("Operator console (the second surface — invite-only, hostable):")}
   great-cto console --bind 0.0.0.0  Reachable beyond this machine (tunnel/hosting);
                                     operators sign in via invite links
 
+${bold("Telemetry (anonymous, opt-IN — OFF by default):")}
+  great-cto telemetry status   Show state + endpoint + your anon_id
+  great-cto telemetry on        Enable anonymous usage events (command, node, os — no PII)
+  great-cto telemetry off       Disable  ${dim("(also: DO_NOT_TRACK=1)")}
+  great-cto telemetry whoami    Print your anon_id (8 hex chars, not reversible)
+  ${dim("Privacy policy: docs/PRIVACY.md")}
+
 ${bold("Register:")}
   great-cto register           Add this repo to ~/.great_cto/projects.json
                                (auto-discovered after /audit or /start, but
@@ -892,6 +908,13 @@ async function runInit(args) {
     }
     // ── 6. install pre-push git hook ─────────────────────────
     installPrePushHook(args.dir);
+    // ── 7. opt-IN telemetry prompt (default OFF) ─────────────
+    await promoteTelemetryOptIn({ archetype: String(archetype), cliVersion: getCliVersion(), yes: args.yes });
+    // If already enabled (prior opt-in or env var), count this (re)install toward MAU.
+    if (isTelemetryEnabled()) {
+        await sendInstallPing({ cliVersion: getCliVersion(), archetype: String(archetype), consent: true })
+            .catch(() => { });
+    }
     // ── done ─────────────────────────────────────────────────
     log("");
     log(green(bold("✓ great_cto is ready.")));
@@ -907,6 +930,57 @@ async function runInit(args) {
     log("");
     return 0;
 }
+// ── Telemetry opt-IN prompt ────────────────────────────────────────────────
+// Shown after a successful init when interactive. Skipped if: --yes, non-TTY,
+// DO_NOT_TRACK=1, CI, or the user already decided (either way — no nagging).
+async function promoteTelemetryOptIn(opts) {
+    if (opts.yes)
+        return;
+    if (!process.stdin.isTTY)
+        return;
+    if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
+        return;
+    if (process.env.CI || process.env.GITHUB_ACTIONS)
+        return;
+    const cfgFile = join(homedir(), ".great_cto", "telemetry.json");
+    if (fsExistsSync(cfgFile)) {
+        try {
+            const cfg = JSON.parse(readFileSync(cfgFile, "utf8"));
+            if (cfg.enabled === true || cfg.enabled === false)
+                return; // already decided
+        }
+        catch { /* malformed — ask again */ }
+    }
+    log(dim("─".repeat(60)));
+    log(bold("Help improve great_cto with anonymous usage data?"));
+    log("");
+    log(dim("Default: OFF. One event per command — exactly this, nothing more:"));
+    log("");
+    log(gray(`  { "command": "init", "archetype": "${opts.archetype}", "version": "${opts.cliVersion}",`));
+    log(gray(`    "node": "${process.version.replace(/^v/, "")}", "os": "${process.platform}",`));
+    log(gray(`    "exit_code": 0, "duration_ms": 1234, "anon_id": "${computeAnonId()}" }`));
+    log("");
+    log(dim("No code, no repo names, no file paths, no IP, no PII. ") + dim("anon_id is sha256(user@host), not reversible."));
+    log(dim("Toggle anytime: " + cyan("npx great-cto telemetry off") + " · honors " + cyan("DO_NOT_TRACK=1")));
+    log(dim("Privacy: " + cyan("github.com/avelikiy/great_cto/blob/main/docs/PRIVACY.md")));
+    log("");
+    const yes = await confirm(bold("Enable anonymous telemetry?"), false);
+    log("");
+    try {
+        mkdirSync(join(homedir(), ".great_cto"), { recursive: true });
+        writeFileSync(cfgFile, JSON.stringify({ enabled: yes, decided_at: new Date().toISOString() }, null, 2) + "\n");
+    }
+    catch { /* best-effort */ }
+    if (yes) {
+        log(green("✓ Telemetry enabled. Thank you."));
+        log(dim(`  Your anon_id: ${cyan("npx great-cto telemetry whoami")}  ·  off anytime: ${cyan("npx great-cto telemetry off")}`));
+        log("");
+    }
+    else {
+        log(dim("No telemetry. (You can opt in later with " + cyan("npx great-cto telemetry on") + ".)"));
+        log("");
+    }
+}
 /**
  * Copy scripts/hooks/pre-push.sh from the installed plugin into the project's
  * .git/hooks/pre-push so that future pushes are scanned for private project
@@ -972,9 +1046,31 @@ async function runUpgrade(rawArgv) {
 async function main() {
     const rawArgv = process.argv.slice(2);
     const args = parseArgs(rawArgv);
+    // Anonymous, opt-IN usage telemetry (default OFF — see docs/PRIVACY.md). `finish`
+    // is the single exit funnel: it fires one fire-and-forget event (command + node + os
+    // + exit_code + duration, no PII) only when the user has opted in, then exits.
+    const __tStart = Date.now();
+    const finish = async (code) => {
+        try {
+            await sendUsagePing({
+                cliVersion: getCliVersion(),
+                subcommand: args.command,
+                exitCode: code,
+                durationMs: Date.now() - __tStart,
+            });
+        }
+        catch { /* telemetry never affects the exit */ }
+        process.exit(code);
+    };
+    // `great-cto telemetry <on|off|status|whoami>` — inspect / toggle, never sends.
+    if (args.command === "telemetry") {
+        const { exitCode, output } = telemetrySubcommand(args.positional[0]);
+        process.stdout.write(output);
+        process.exit(exitCode);
+    }
     if (args.command === "help") {
         printHelp();
-        process.exit(0);
+        await finish(0);
     }
     if (args.command === "unknown") {
         const tok = args.unknownToken ?? "<arg>";
@@ -986,7 +1082,7 @@ async function main() {
     if (args.command === "board") {
         try {
             const code = await runBoard(args);
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -996,7 +1092,7 @@ async function main() {
     if (args.command === "console") {
         try {
             const code = await runBoard(args, "console");
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1006,7 +1102,7 @@ async function main() {
     if (args.command === "register") {
         try {
             const code = await runRegister(args);
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1017,7 +1113,7 @@ async function main() {
         try {
             const { runCi, parseCiArgs } = await import("./ci.js");
             const code = await runCi(parseCiArgs(rawArgv));
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1031,7 +1127,7 @@ async function main() {
             const portArg = rawArgv.indexOf("--port");
             const port = portArg >= 0 ? parseInt(rawArgv[portArg + 1] ?? "8765", 10) : 8765;
             const code = await runMcp({ mode: sse ? "sse" : "stdio", port, version: getCliVersion() });
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1046,7 +1142,7 @@ async function main() {
                 dryRun: rawArgv.includes("--dry-run"),
                 cwd: args.dir,
             });
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1064,7 +1160,7 @@ async function main() {
                 noLog: rawArgv.includes("--no-log"),
                 insecure: rawArgv.includes("--insecure"),
             });
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1080,7 +1176,7 @@ async function main() {
                 process.exit(2);
             }
             const code = await runWebhookCli(parsed);
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1090,7 +1186,7 @@ async function main() {
     if (args.command === "upgrade") {
         try {
             const code = await runUpgrade(rawArgv);
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1121,7 +1217,7 @@ async function main() {
                 process.exit(2);
             }
             const code = await runReport(parsed);
-            process.exit(code);
+            await finish(code);
         }
         catch (e) {
             error(e.message);
@@ -1156,7 +1252,7 @@ async function main() {
     }
     try {
         const code = await runInit(args);
-        process.exit(code);
+        await finish(code);
     }
     catch (e) {
         error(e.message);

package/dist/telemetry.js

@@ -0,0 +1,217 @@
+// Anonymous opt-IN telemetry — default OFF.
+//
+// See docs/PRIVACY.md for the full policy. Short version:
+//   - Default: disabled (opt-in)
+//   - Honors DO_NOT_TRACK=1 (industry standard, https://consoledonottrack.com)
+//   - Skipped automatically in CI environments
+//   - No paths, no code, no PII — just {ts, version, command, archetype, node, os, exit, duration_ms, anon_id}
+//   - anon_id is sha256(user@hostname) truncated to 8 hex chars; not reversible
+//
+// Opt-in (any one):
+//   GREAT_CTO_TELEMETRY=on               (env var)
+//   ~/.great_cto/telemetry.json: { "enabled": true }
+//   npx great-cto telemetry on
+//
+// Opt-out (overrides everything):
+//   DO_NOT_TRACK=1                       (highest priority)
+//   GREAT_CTO_TELEMETRY=off
+//   GREAT_CTO_DISABLE_TELEMETRY=1        (legacy alias from v2.x)
+//   GREATCTO_NO_TELEMETRY=1              (legacy alias from v2.x)
+//   ~/.great_cto/telemetry.json: { "enabled": false }
+//
+// Endpoint:  https://telemetry.greatcto.systems/v1/event  (Cloudflare Worker → D1)
+// Worker:    workers/telemetry/index.ts
+// Schema v1: see docs/PRIVACY.md "What we collect"
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+const TELEMETRY_ENDPOINT = process.env.GREAT_CTO_TELEMETRY_ENDPOINT
+    || "https://great-cto-telemetry.alexander-velikiy.workers.dev/v1/event";
+// Note: workers.dev URL is the temporary default until telemetry.greatcto.systems
+// custom domain is bound. Override anytime with GREAT_CTO_TELEMETRY_ENDPOINT.
+const TELEMETRY_TIMEOUT_MS = 1000;
+// Allowlist — anything else is dropped client-side and server-side.
+const ALLOWED_COMMANDS = new Set([
+    "init", "ci", "board", "console", "register",
+    "adapt", "mcp", "report", "serve", "webhook", "upgrade",
+    "version", "help", "telemetry",
+]);
+// Allowlist for archetype field. Match the 25 documented + "none" + "unknown".
+const ALLOWED_ARCHETYPES = new Set([
+    "none", "unknown", "greenfield",
+    "enterprise-saas", "agent-product", "ai-system", "mlops",
+    "cli-tool", "cli", "library", "sdk", "devtools",
+    "fintech", "regulated", "compliance",
+    "iot-embedded", "web3", "marketplace", "cms", "edtech",
+    "gov-public", "insurance", "data-platform", "streaming",
+    "mobile-app", "infra", "web-service", "agent",
+]);
+function configPath() {
+    return path.join(os.homedir(), ".great_cto", "telemetry.json");
+}
+function readConfig() {
+    // ONLY the new opt-in file counts. We deliberately do NOT honor the legacy
+    // ~/.great_cto/config.json "telemetry" flag: that consent predates the v2.9.2
+    // zero-telemetry reset, so silently reactivating it would re-enable collection
+    // without a fresh, informed opt-in. Re-introduction requires a new decision.
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeConfig(cfg) {
+    const file = configPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+}
+/** Detect CI / automation environments — never send from these. */
+function isCI() {
+    const flags = ["CI", "GITHUB_ACTIONS", "GITLAB_CI", "CIRCLECI", "BUILDKITE",
+        "JENKINS_URL", "TF_BUILD", "DRONE", "TRAVIS", "APPVEYOR",
+        "BITBUCKET_BUILD_NUMBER", "TEAMCITY_VERSION", "CODEBUILD_BUILD_ID"];
+    return flags.some(f => process.env[f] != null && process.env[f] !== "");
+}
+/** Compute anon_id deterministically per machine, never reversible. */
+export function computeAnonId() {
+    const seed = `great_cto/${os.userInfo().username || "?"}/${os.hostname() || "?"}`;
+    return crypto.createHash("sha256").update(seed).digest("hex").slice(0, 8);
+}
+/** Resolve telemetry-enabled state. Pure function, no side effects. */
+export function isTelemetryEnabled(cliFlag = false) {
+    // Opt-out wins, in priority order:
+    if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
+        return false;
+    if (process.env.GREAT_CTO_TELEMETRY === "off")
+        return false;
+    if (process.env.GREAT_CTO_DISABLE_TELEMETRY === "1")
+        return false;
+    if (process.env.GREATCTO_NO_TELEMETRY === "1")
+        return false;
+    if (cliFlag)
+        return false;
+    if (isCI())
+        return false;
+    // Opt-in checks (explicit, fresh decision only):
+    if (process.env.GREAT_CTO_TELEMETRY === "on")
+        return true;
+    const cfg = readConfig();
+    if (cfg.enabled === true)
+        return true;
+    // Default: opt-out.
+    return false;
+}
+function sanitize(opts) {
+    const command = opts.command.toLowerCase();
+    if (!ALLOWED_COMMANDS.has(command))
+        return null;
+    const archetypeRaw = (opts.archetype || "none").toLowerCase().trim();
+    const archetype = ALLOWED_ARCHETYPES.has(archetypeRaw) ? archetypeRaw : "unknown";
+    return {
+        ts: new Date().toISOString(),
+        version: opts.cliVersion,
+        command,
+        archetype,
+        node: process.version.replace(/^v/, ""),
+        os: process.platform,
+        exit_code: typeof opts.exitCode === "number" ? opts.exitCode : 0,
+        duration_ms: typeof opts.durationMs === "number" ? Math.max(0, Math.round(opts.durationMs)) : 0,
+        anon_id: computeAnonId(),
+    };
+}
+/** Fire-and-forget POST. Never blocks. Never throws. Never logs unless DRYRUN. */
+async function send(evt) {
+    if (process.env.GREAT_CTO_TELEMETRY_DRYRUN === "1") {
+        process.stderr.write(`[telemetry] would-send: ${JSON.stringify(evt)}\n`);
+        return;
+    }
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), TELEMETRY_TIMEOUT_MS);
+        await fetch(TELEMETRY_ENDPOINT, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(evt),
+            signal: ctrl.signal,
+        }).catch(() => { });
+        clearTimeout(timer);
+    }
+    catch { /* best-effort */ }
+}
+// --- Public API ------------------------------------------------------------
+/** First-run/install ping. Sent only when enabled. Idempotent across runs. */
+export async function sendInstallPing(opts) {
+    if (!opts.consent)
+        return;
+    if (!isTelemetryEnabled())
+        return;
+    const evt = sanitize({ cliVersion: opts.cliVersion, command: "init", archetype: opts.archetype });
+    if (!evt)
+        return;
+    await send(evt);
+}
+/** Per-command usage ping. Sent only when enabled. Fire-and-forget. */
+export async function sendUsagePing(opts) {
+    if (!isTelemetryEnabled())
+        return;
+    const evt = sanitize({
+        cliVersion: opts.cliVersion,
+        command: opts.subcommand,
+        archetype: opts.archetype,
+        exitCode: opts.exitCode,
+        durationMs: opts.durationMs,
+    });
+    if (!evt)
+        return;
+    await send(evt);
+}
+/**
+ * Legacy shim — preserved for backwards compatibility with callers in main.ts
+ * that pass `--no-telemetry`. With opt-IN default, consent resolution is
+ * trivial: enabled iff isTelemetryEnabled() returns true.
+ */
+export function resolveTelemetryConsent(cliFlag) {
+    return isTelemetryEnabled(cliFlag);
+}
+// --- `npx great-cto telemetry <on|off|status|whoami>` subcommand -----------
+export function telemetrySubcommand(arg) {
+    const action = (arg || "status").toLowerCase();
+    switch (action) {
+        case "on": {
+            const cfg = readConfig();
+            cfg.enabled = true;
+            writeConfig(cfg);
+            return { exitCode: 0, output: `✓ telemetry enabled (config: ${configPath()})\n` +
+                    `  Anonymous events go to ${TELEMETRY_ENDPOINT}\n` +
+                    `  See docs/PRIVACY.md for the full data schema.\n` };
+        }
+        case "off": {
+            const cfg = readConfig();
+            cfg.enabled = false;
+            writeConfig(cfg);
+            return { exitCode: 0, output: `✓ telemetry disabled (config: ${configPath()})\n` };
+        }
+        case "status": {
+            const enabled = isTelemetryEnabled();
+            const reason = enabled
+                ? "enabled (sending events to " + TELEMETRY_ENDPOINT + ")"
+                : isCI()
+                    ? "disabled (CI environment detected)"
+                    : process.env.DO_NOT_TRACK === "1"
+                        ? "disabled (DO_NOT_TRACK=1)"
+                        : "disabled (default; run 'great-cto telemetry on' to enable)";
+            return { exitCode: 0, output: `telemetry: ${reason}\n` +
+                    `anon_id  : ${computeAnonId()}\n` +
+                    `endpoint : ${TELEMETRY_ENDPOINT}\n` +
+                    `config   : ${configPath()}\n` };
+        }
+        case "whoami": {
+            return { exitCode: 0, output: computeAnonId() + "\n" };
+        }
+        default: {
+            return { exitCode: 2, output: `usage: great-cto telemetry <on|off|status|whoami>\n` };
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.69.0",
+  "version": "2.70.1",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",