truecourse 0.2.0 → 0.2.2

package/README.md

@@ -113,6 +113,7 @@ Once the server is running, `cd` into any repo and:
 npx truecourse add                    # Register repo without analyzing
 npx truecourse analyze                # Analyze current repo, show violations
 npx truecourse analyze --code-review  # Analyze with LLM code review (off by default)
+npx truecourse analyze --no-llm       # Deterministic checks only, skip all LLM calls
 npx truecourse analyze --diff         # Show new/resolved violations from uncommitted changes
 npx truecourse list                   # Show violations from latest analysis
 npx truecourse list --diff            # Show saved diff check results
@@ -177,6 +178,39 @@ All rules are visible in the **Rules** tab in the web UI. Custom rule generation
 | Rust | Planned |
 | PHP | Planned |
 
+## Telemetry
+
+TrueCourse collects anonymous usage data to help us understand adoption and improve the product. Telemetry is **enabled by default** and can be disabled at any time.
+
+### What is collected
+
+- Event type (`analyze` or `diff-check`)
+- Tool version
+- Languages detected (e.g., TypeScript, Python)
+- File count range (bucketed: 1-50, 50-200, etc.)
+- Service count
+- Analysis duration range (bucketed)
+- OS and architecture (e.g., `darwin-arm64`)
+- Random anonymous session ID (not tied to user identity)
+
+### What is NOT collected
+
+- Source code, file paths, repo names, or git URLs
+- Violation details, rule results, or LLM outputs
+- IP addresses, user identity, or machine hostname
+
+### Opt out
+
+```bash
+npx truecourse telemetry disable   # Disable telemetry
+npx truecourse telemetry enable    # Re-enable telemetry
+npx truecourse telemetry status    # Check current status
+```
+
+Telemetry is automatically disabled in CI environments (`CI=true`) and can also be disabled by setting `TRUECOURSE_TELEMETRY=0`.
+
+Data is sent to [PostHog](https://posthog.com) for aggregation.
+
 ## License
 
 MIT

package/cli.mjs

@@ -972,8 +972,8 @@ var require_command = __commonJS({
   "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/command.js"(exports) {
     var EventEmitter = __require("node:events").EventEmitter;
     var childProcess = __require("node:child_process");
-    var path9 = __require("node:path");
-    var fs8 = __require("node:fs");
+    var path10 = __require("node:path");
+    var fs9 = __require("node:fs");
     var process2 = __require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1905,11 +1905,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path9.resolve(baseDir, baseName);
-          if (fs8.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path9.extname(baseName))) return void 0;
+          const localBin = path10.resolve(baseDir, baseName);
+          if (fs9.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path10.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs8.existsSync(`${localBin}${ext}`)
+            (ext) => fs9.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -1921,21 +1921,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs8.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs9.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path9.resolve(
-            path9.dirname(resolvedScriptPath),
+          executableDir = path10.resolve(
+            path10.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path9.basename(
+            const legacyName = path10.basename(
               this._scriptPath,
-              path9.extname(this._scriptPath)
+              path10.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -1946,7 +1946,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path9.extname(executableFile));
+        launchWithNode = sourceExt.includes(path10.extname(executableFile));
         let proc;
         if (process2.platform !== "win32") {
           if (launchWithNode) {
@@ -2786,7 +2786,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path9.basename(filename, path9.extname(filename));
+        this._name = path10.basename(filename, path10.extname(filename));
         return this;
       }
       /**
@@ -2800,9 +2800,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path10) {
-        if (path10 === void 0) return this._executableDir;
-        this._executableDir = path10;
+      executableDir(path11) {
+        if (path11 === void 0) return this._executableDir;
+        this._executableDir = path11;
         return this;
       }
       /**
@@ -3766,7 +3766,7 @@ ${import_picocolors2.default.gray(m2)}  ${s}
 // node_modules/.pnpm/xmlhttprequest-ssl@2.1.2/node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js
 var require_XMLHttpRequest = __commonJS({
   "node_modules/.pnpm/xmlhttprequest-ssl@2.1.2/node_modules/xmlhttprequest-ssl/lib/XMLHttpRequest.js"(exports, module) {
-    var fs8 = __require("fs");
+    var fs9 = __require("fs");
     var Url = __require("url");
     var spawn3 = __require("child_process").spawn;
     module.exports = XMLHttpRequest3;
@@ -3924,7 +3924,7 @@ var require_XMLHttpRequest = __commonJS({
             throw new Error("XMLHttpRequest: Only GET method is supported");
           }
           if (settings.async) {
-            fs8.readFile(unescape(url2.pathname), function(error, data2) {
+            fs9.readFile(unescape(url2.pathname), function(error, data2) {
               if (error) {
                 self.handleError(error, error.errno || -1);
               } else {
@@ -3936,7 +3936,7 @@ var require_XMLHttpRequest = __commonJS({
             });
           } else {
             try {
-              this.response = fs8.readFileSync(unescape(url2.pathname));
+              this.response = fs9.readFileSync(unescape(url2.pathname));
               this.responseText = this.response.toString("utf8");
               this.status = 200;
               setState(self.DONE);
@@ -4062,15 +4062,15 @@ var require_XMLHttpRequest = __commonJS({
         } else {
           var contentFile = ".node-xmlhttprequest-content-" + process.pid;
           var syncFile = ".node-xmlhttprequest-sync-" + process.pid;
-          fs8.writeFileSync(syncFile, "", "utf8");
+          fs9.writeFileSync(syncFile, "", "utf8");
           var execString = "var http = require('http'), https = require('https'), fs = require('fs');var doRequest = http" + (ssl ? "s" : "") + ".request;var options = " + JSON.stringify(options) + ";var responseText = '';var responseData = Buffer.alloc(0);var req = doRequest(options, function(response) {response.on('data', function(chunk) {  var data = Buffer.from(chunk);  responseText += data.toString('utf8');  responseData = Buffer.concat([responseData, data]);});response.on('end', function() {fs.writeFileSync('" + contentFile + "', JSON.stringify({err: null, data: {statusCode: response.statusCode, headers: response.headers, text: responseText, data: responseData.toString('base64')}}), 'utf8');fs.unlinkSync('" + syncFile + "');});response.on('error', function(error) {fs.writeFileSync('" + contentFile + "', 'NODE-XMLHTTPREQUEST-ERROR:' + JSON.stringify(error), 'utf8');fs.unlinkSync('" + syncFile + "');});}).on('error', function(error) {fs.writeFileSync('" + contentFile + "', 'NODE-XMLHTTPREQUEST-ERROR:' + JSON.stringify(error), 'utf8');fs.unlinkSync('" + syncFile + "');});" + (data ? "req.write('" + JSON.stringify(data).slice(1, -1).replace(/'/g, "\\'") + "');" : "") + "req.end();";
           var syncProc = spawn3(process.argv[0], ["-e", execString]);
           var statusText;
-          while (fs8.existsSync(syncFile)) {
+          while (fs9.existsSync(syncFile)) {
           }
-          self.responseText = fs8.readFileSync(contentFile, "utf8");
+          self.responseText = fs9.readFileSync(contentFile, "utf8");
           syncProc.stdin.end();
-          fs8.unlinkSync(contentFile);
+          fs9.unlinkSync(contentFile);
           if (self.responseText.match(/^NODE-XMLHTTPREQUEST-ERROR:/)) {
             var errorObj = JSON.parse(self.responseText.replace(/^NODE-XMLHTTPREQUEST-ERROR:/, ""));
             self.handleError(errorObj, 503);
@@ -9762,12 +9762,12 @@ function parse2(str) {
   uri.queryKey = queryKey(uri, uri["query"]);
   return uri;
 }
-function pathNames(obj, path9) {
-  const regx = /\/{2,9}/g, names = path9.replace(regx, "/").split("/");
-  if (path9.slice(0, 1) == "/" || path9.length === 0) {
+function pathNames(obj, path10) {
+  const regx = /\/{2,9}/g, names = path10.replace(regx, "/").split("/");
+  if (path10.slice(0, 1) == "/" || path10.length === 0) {
     names.splice(0, 1);
   }
-  if (path9.slice(-1) == "/") {
+  if (path10.slice(-1) == "/") {
     names.splice(names.length - 1, 1);
   }
   return names;
@@ -10441,7 +10441,7 @@ var init_esm_debug = __esm({
 });
 
 // node_modules/.pnpm/socket.io-client@4.8.3/node_modules/socket.io-client/build/esm-debug/url.js
-function url(uri, path9 = "", loc) {
+function url(uri, path10 = "", loc) {
   let obj = uri;
   loc = loc || typeof location !== "undefined" && location;
   if (null == uri)
@@ -10475,7 +10475,7 @@ function url(uri, path9 = "", loc) {
   obj.path = obj.path || "/";
   const ipv6 = obj.host.indexOf(":") !== -1;
   const host = ipv6 ? "[" + obj.host + "]" : obj.host;
-  obj.id = obj.protocol + "://" + host + ":" + obj.port + path9;
+  obj.id = obj.protocol + "://" + host + ":" + obj.port + path10;
   obj.href = obj.protocol + "://" + host + (loc && loc.port === obj.port ? "" : ":" + obj.port);
   return obj;
 }
@@ -12146,8 +12146,8 @@ function lookup(uri, opts) {
   const parsed = url(uri, opts.path || "/socket.io");
   const source = parsed.source;
   const id = parsed.id;
-  const path9 = parsed.path;
-  const sameNamespace = cache[id] && path9 in cache[id]["nsps"];
+  const path10 = parsed.path;
+  const sameNamespace = cache[id] && path10 in cache[id]["nsps"];
   const newConnection = opts.forceNew || opts["force new connection"] || false === opts.multiplex || sameNamespace;
   let io;
   if (newConnection) {
@@ -12683,10 +12683,16 @@ function startConsoleMode(openBrowser) {
     process.execPath,
     [serverPath],
     {
-      stdio: "inherit",
+      stdio: ["ignore", "pipe", "pipe"],
       env: { ...process.env }
     }
   );
+  const forwardOutput = (data) => {
+    process.stdout.write("\r\x1B[K");
+    process.stderr.write(data);
+  };
+  serverProcess.stdout?.on("data", forwardOutput);
+  serverProcess.stderr?.on("data", forwardOutput);
   serverProcess.on("error", (error) => {
     v2.error(`Failed to start server: ${error.message}`);
     process.exit(1);
@@ -13364,9 +13370,9 @@ var {
 init_dist2();
 init_setup();
 init_start();
-import fs7 from "node:fs";
-import path8 from "node:path";
-import os6 from "node:os";
+import fs8 from "node:fs";
+import path9 from "node:path";
+import os7 from "node:os";
 
 // tools/cli/src/commands/add.ts
 init_dist2();
@@ -13415,9 +13421,73 @@ async function runAdd() {
 // tools/cli/src/commands/analyze.ts
 init_dist2();
 init_helpers();
+
+// tools/cli/src/telemetry.ts
+init_dist2();
+import fs7 from "node:fs";
+import path7 from "node:path";
+import os6 from "node:os";
+import crypto from "node:crypto";
+var DEFAULT_CONFIG2 = {
+  enabled: true,
+  anonymousId: "",
+  noticeShown: false
+};
+function getTelemetryConfigPath() {
+  return path7.join(os6.homedir(), ".truecourse", "telemetry.json");
+}
+function readTelemetryConfig() {
+  const configPath = getTelemetryConfigPath();
+  try {
+    const raw = fs7.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const config = { ...DEFAULT_CONFIG2, ...parsed };
+    if (!config.anonymousId) {
+      config.anonymousId = crypto.randomUUID();
+      writeTelemetryConfig(config);
+    }
+    return config;
+  } catch {
+    const config = {
+      enabled: true,
+      anonymousId: crypto.randomUUID(),
+      noticeShown: false
+    };
+    writeTelemetryConfig(config);
+    return config;
+  }
+}
+function writeTelemetryConfig(partial) {
+  const configPath = getTelemetryConfigPath();
+  const dir = path7.dirname(configPath);
+  fs7.mkdirSync(dir, { recursive: true });
+  let current;
+  try {
+    const raw = fs7.readFileSync(configPath, "utf-8");
+    current = { ...DEFAULT_CONFIG2, ...JSON.parse(raw) };
+  } catch {
+    current = { ...DEFAULT_CONFIG2 };
+  }
+  const merged = { ...current, ...partial };
+  fs7.writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+}
+function showFirstRunNotice() {
+  try {
+    const config = readTelemetryConfig();
+    if (!config.enabled || config.noticeShown) return;
+    v2.info(
+      "TrueCourse collects anonymous usage data to improve the product. Run `npx truecourse telemetry disable` to opt out."
+    );
+    writeTelemetryConfig({ noticeShown: true });
+  } catch {
+  }
+}
+
+// tools/cli/src/commands/analyze.ts
 var TIMEOUT_MS = 15 * 60 * 1e3;
-async function runAnalyze({ noAutostart = false, codeReview = false } = {}) {
+async function runAnalyze({ noAutostart = false, codeReview = false, deterministicOnly = false } = {}) {
   we("Analyzing repository");
+  showFirstRunNotice();
   if (noAutostart) {
     const url2 = getServerUrl();
     try {
@@ -13480,7 +13550,7 @@ async function runAnalyze({ noAutostart = false, codeReview = false } = {}) {
       fetch(`${serverUrl}/api/repos/${repo.id}/analyze`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ codeReview })
+        body: JSON.stringify({ codeReview, deterministicOnly })
       }).then((res2) => {
         if (!res2.ok) {
           clearTimeout(timeout);
@@ -13508,7 +13578,9 @@ async function runAnalyze({ noAutostart = false, codeReview = false } = {}) {
     }
     const violations = await res.json();
     renderViolationsSummary(violations);
-    v2.info("Code review running in background \u2014 results will appear in the dashboard");
+    if (!deterministicOnly) {
+      v2.info("Code review running in background \u2014 results will appear in the dashboard");
+    }
     const repoUrl = `${serverUrl}/repos/${repo.id}`;
     if (firstRun) {
       openInBrowser(repoUrl);
@@ -13533,6 +13605,7 @@ async function runAnalyze({ noAutostart = false, codeReview = false } = {}) {
 }
 async function runAnalyzeDiff({ noAutostart = false } = {}) {
   we("Running diff check");
+  showFirstRunNotice();
   if (noAutostart) {
     const url2 = getServerUrl();
     try {
@@ -13627,11 +13700,11 @@ init_dist2();
 init_platform();
 init_logs();
 init_helpers();
-import path7 from "node:path";
+import path8 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-var __dirname2 = path7.dirname(fileURLToPath3(import.meta.url));
+var __dirname2 = path8.dirname(fileURLToPath3(import.meta.url));
 function getServerPath2() {
-  return path7.join(__dirname2, "..", "server.mjs");
+  return path8.join(__dirname2, "..", "server.mjs");
 }
 async function healthcheck2() {
   const url2 = getServerUrl();
@@ -13786,7 +13859,7 @@ function registerServiceCommand(program3) {
 init_helpers();
 init_platform();
 var program2 = new Command();
-program2.name("truecourse").version("0.1.0").description("TrueCourse CLI - Setup and manage your TrueCourse instance");
+program2.name("truecourse").version("0.2.2").description("TrueCourse CLI - Setup and manage your TrueCourse instance");
 program2.command("setup").description("Run the setup wizard to configure TrueCourse").action(async () => {
   await runSetup();
 });
@@ -13796,11 +13869,11 @@ program2.command("start").description("Start TrueCourse services").action(async
 program2.command("add").description("Add the current directory as a repository").action(async () => {
   await runAdd();
 });
-program2.command("analyze").description("Analyze the current repository").option("--diff", "Run diff check against latest analysis").option("--code-review", "Include LLM code review (off by default)").option("--no-autostart", "Don't auto-start the server (for use from Claude Code skills)").action(async (options) => {
+program2.command("analyze").description("Analyze the current repository").option("--diff", "Run diff check against latest analysis").option("--code-review", "Include LLM code review (off by default)").option("--no-llm", "Skip all LLM calls, run only deterministic checks").option("--no-autostart", "Don't auto-start the server (for use from Claude Code skills)").action(async (options) => {
   if (options.diff) {
     await runAnalyzeDiff({ noAutostart: !options.autostart });
   } else {
-    await runAnalyze({ noAutostart: !options.autostart, codeReview: options.codeReview ?? false });
+    await runAnalyze({ noAutostart: !options.autostart, codeReview: options.codeReview ?? false, deterministicOnly: !options.llm });
   }
 });
 program2.command("code-review").description("Run LLM code review on the latest analysis").option("--diff", "Run on the latest diff analysis instead").option("--no-autostart", "Don't auto-start the server").action(async (options) => {
@@ -13832,10 +13905,29 @@ program2.command("stop").description("Stop the TrueCourse background service").a
     v2.info("Press Ctrl+C in the terminal where TrueCourse is running.");
   }
 });
+var telemetryCmd = program2.command("telemetry").description("Manage anonymous usage telemetry");
+telemetryCmd.command("enable").description("Enable anonymous usage telemetry").action(() => {
+  writeTelemetryConfig({ enabled: true });
+  v2.success("Telemetry enabled. Thank you for helping improve TrueCourse!");
+});
+telemetryCmd.command("disable").description("Disable anonymous usage telemetry").action(() => {
+  writeTelemetryConfig({ enabled: false });
+  v2.success("Telemetry disabled. No data will be collected.");
+});
+telemetryCmd.command("status").description("Show current telemetry status").action(() => {
+  const config = readTelemetryConfig();
+  if (process.env.CI === "true") {
+    v2.info("Telemetry is automatically disabled in CI environments.");
+  } else if (config.enabled) {
+    v2.info("Telemetry is enabled.");
+  } else {
+    v2.info("Telemetry is disabled.");
+  }
+});
 program2.action(async () => {
-  const configDir = path8.join(os6.homedir(), ".truecourse");
-  const envPath = path8.join(configDir, ".env");
-  const isFirstRun = !fs7.existsSync(envPath);
+  const configDir = path9.join(os7.homedir(), ".truecourse");
+  const envPath = path9.join(configDir, ".env");
+  const isFirstRun = !fs8.existsSync(envPath);
   if (isFirstRun) {
     await runSetup();
   }

package/db/migrations/0011_noisy_colleen_wing.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "analyses" ADD COLUMN "status" text DEFAULT 'completed' NOT NULL;
+-- Existing rows are completed analyses; new rows created at analysis start will explicitly set 'running'