skillrepo 4.3.0 → 4.5.0

package/src/lib/telemetry.mjs

@@ -0,0 +1,201 @@
+/**
+ * Anonymous CLI telemetry (#1539).
+ *
+ * The CLI ships zero telemetry by default before this module: when
+ * `skillrepo init` fails on a user's machine — paste error, terminal
+ * corruption, wrong server URL — nothing reaches the server. The
+ * resulting blindspot was the single biggest reason the live diagnostic
+ * surfaced in the #1535 epic took days rather than minutes.
+ *
+ * This module is the OPT-OUT-FRIENDLY counterpart to the server-side
+ * `/api/v1/cli/events` endpoint. It does ONE thing — report an init
+ * failure — and is designed so that nothing it does can possibly
+ * interfere with the user's actual init flow:
+ *
+ *   1. **Fire-and-forget.** The HTTP call is started without `await`;
+ *      the calling site continues to the next line immediately.
+ *   2. **1-second hard timeout.** Even if the server hangs, the CLI
+ *      pays at most 1 second of wall-clock for the call.
+ *   3. **Never throws.** Every failure mode (network, DNS, timeout,
+ *      schema-rejection-by-server) is swallowed silently. The user's
+ *      init flow continues to its own error reporting unchanged.
+ *   4. **No key material.** The payload schema is documented at
+ *      `src/app/api/v1/cli/events/route.ts` — the server uses
+ *      `.strict()` so any extra field is rejected with 400, and this
+ *      module's `reportInitFailure` constructs the payload from a
+ *      closed set of allowed fields rather than spreading a context
+ *      object that could carry the user's key.
+ *
+ * Opt-out is honored from three sources, any one of which disables
+ * the call entirely:
+ *
+ *   - `SKILLREPO_NO_TELEMETRY=1` (or any non-empty value) in the env.
+ *     The simplest path for users who don't trust the CLI yet.
+ *   - `telemetry: false` in the global config (`~/.claude/skillrepo/
+ *     config.json`). Set interactively at first init, or by hand.
+ *   - The legacy `DO_NOT_TRACK` env var (community convention from
+ *     consoledonottrack.com). Honored for parity even though the
+ *     SkillRepo-specific var is the documented one.
+ *
+ * Self-hosting note: this module sends data ONLY to the server URL
+ * the user explicitly configured via `skillrepo init`. Self-hosters
+ * who point at their own SkillRepo instance receive their own
+ * telemetry; no traffic leaves their boundary.
+ */
+
+import { platform as nodePlatform } from "node:os";
+import { getCliVersion } from "./cli-version.mjs";
+
+/** Hard cap on how long the CLI waits for the telemetry call. */
+export const TELEMETRY_TIMEOUT_MS = 1000;
+
+/**
+ * Was telemetry explicitly disabled by env var? Independent of config
+ * so a user can disable telemetry without writing a config file (e.g.
+ * during the first-ever init, BEFORE the config file exists).
+ *
+ * Honors:
+ *   - `SKILLREPO_NO_TELEMETRY` (any truthy value)
+ *   - `DO_NOT_TRACK` (consoledonottrack.com convention; truthy = opt out)
+ *
+ * Exported for tests + for the init prompt to skip asking when the env
+ * var is already set.
+ */
+export function telemetryDisabledByEnv() {
+  const skillrepo = process.env.SKILLREPO_NO_TELEMETRY;
+  if (skillrepo && skillrepo !== "0" && skillrepo.toLowerCase() !== "false") {
+    return true;
+  }
+  const dnt = process.env.DO_NOT_TRACK;
+  if (dnt === "1" || dnt?.toLowerCase() === "true") {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Is telemetry enabled given the env + a config object? Pure function
+ * — takes the config explicitly so it's testable without touching disk.
+ * Default is enabled (opt-out, not opt-in) — the user is asked at first
+ * init and the prompt's "y" answer is what writes `telemetry: true` to
+ * config. Missing-config means brand-new install: the call is allowed
+ * (the init flow will land the config on success and persist whatever
+ * the user picked at the prompt).
+ */
+export function telemetryEnabled(config) {
+  if (telemetryDisabledByEnv()) return false;
+  // `telemetry: false` explicitly opts out. `telemetry: true` or
+  // missing both default to enabled.
+  if (config && config.telemetry === false) return false;
+  return true;
+}
+
+/**
+ * Closed set of init stages. Mirrors the server-side `CliEventBody`
+ * Zod schema — sending a value outside this set would be rejected by
+ * the server's `.strict()` validator and quietly swallowed by this
+ * module, so we constrain at the source.
+ */
+export const INIT_STAGES = Object.freeze([
+  "pre_paste",
+  "post_paste_validate",
+  "config_write",
+  "library_sync",
+  "agent_detection",
+]);
+
+/**
+ * Closed set of platforms (mirrors server-side Zod enum). Unknown
+ * Node.js `os.platform()` returns are mapped to the closest match or
+ * dropped from the payload — the server would reject 'sunos' etc.
+ */
+const SUPPORTED_PLATFORMS = new Set([
+  "darwin",
+  "linux",
+  "win32",
+  "freebsd",
+  "openbsd",
+  "aix",
+]);
+
+/**
+ * Extract the URL host from a server URL, with no path/query/userinfo.
+ * The server's Zod schema rejects anything with a slash or `@`, so a
+ * malformed input would fail validation and be silently swallowed —
+ * extracting the host on the CLI side keeps the payload clean and
+ * matches the privacy contract (no full URLs in payloads).
+ */
+function hostnameFrom(serverUrl) {
+  try {
+    return new URL(serverUrl).host;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Report an init failure to the server. Fire-and-forget — the returned
+ * promise is the abort/timeout housekeeping, NOT a result the caller
+ * should await. Tests await it to assert behavior; production call
+ * sites do `void reportInitFailure(...)` and continue immediately.
+ *
+ * @param {object} params
+ * @param {string} params.serverUrl - The SkillRepo server URL the user
+ *   was trying to init against (used to compute `serverUrlHost`).
+ * @param {object|null} params.config - The current global config
+ *   (or null if no config exists yet). Determines opt-out state.
+ * @param {string} params.stage - One of `INIT_STAGES`.
+ * @param {number} params.errorCode - CLI exit code or HTTP status.
+ * @param {object} [params.deps] - Test seam — inject `fetch` and `now`.
+ */
+export async function reportInitFailure({
+  serverUrl,
+  config,
+  stage,
+  errorCode,
+  deps,
+}) {
+  if (!telemetryEnabled(config)) return;
+  if (!INIT_STAGES.includes(stage)) return; // Closed enum: silently drop.
+
+  const platform = nodePlatform();
+  if (!SUPPORTED_PLATFORMS.has(platform)) return; // Server would 400.
+
+  const cliVersion = getCliVersion();
+  const payload = {
+    stage,
+    errorCode,
+    cliVersion,
+    nodeVersion: process.version,
+    platform,
+    serverUrlHost: hostnameFrom(serverUrl),
+  };
+
+  // Allow a test-injected fetch (jsdom doesn't have a global fetch by
+  // default in some setups, and we want to assert the call shape
+  // without hitting the network). Production uses Node's built-in
+  // fetch.
+  const fetchImpl = (deps && deps.fetch) || globalThis.fetch;
+  if (typeof fetchImpl !== "function") return; // Defensive — should never happen on Node ≥18.
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), TELEMETRY_TIMEOUT_MS);
+
+  try {
+    await fetchImpl(`${serverUrl.replace(/\/+$/, "")}/api/v1/cli/events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": `skillrepo-cli/${cliVersion} telemetry`,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+  } catch {
+    // Silent — telemetry must NEVER raise into the user's init flow.
+    // The user already sees the underlying init failure; piling a
+    // "telemetry call failed" warning on top would erode trust.
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/test/commands/init.test.mjs

@@ -233,6 +233,91 @@ describe("runInit — credential resolution", () => {
   });
 });
 
+// ── Telemetry consent wiring (#1539, #1535 round-1 audit) ──────────────
+//
+// The first-init consent prompt has four branches:
+//   1. SKILLREPO_NO_TELEMETRY env var → telemetryEnabledForRun=false
+//   2. existing config has explicit telemetry flag → use that
+//   3. --yes OR non-TTY stdin → opt-out-friendly default (true)
+//   4. interactive TTY → confirm() prompt
+//
+// All tests run under `--yes` (process.stdin.isTTY is falsy in node:test
+// regardless), so they exercise branches 1, 2, and 3. Branch 4 (TTY
+// interactive prompt) is integration-level — not unit-testable without
+// a pty harness.
+
+describe("runInit — telemetry consent (#1539)", () => {
+  let originalNoTelemetry;
+  let originalDoNotTrack;
+
+  beforeEach(async () => {
+    await setup();
+    originalNoTelemetry = process.env.SKILLREPO_NO_TELEMETRY;
+    originalDoNotTrack = process.env.DO_NOT_TRACK;
+    delete process.env.SKILLREPO_NO_TELEMETRY;
+    delete process.env.DO_NOT_TRACK;
+  });
+
+  afterEach(async () => {
+    if (originalNoTelemetry === undefined) {
+      delete process.env.SKILLREPO_NO_TELEMETRY;
+    } else {
+      process.env.SKILLREPO_NO_TELEMETRY = originalNoTelemetry;
+    }
+    if (originalDoNotTrack === undefined) {
+      delete process.env.DO_NOT_TRACK;
+    } else {
+      process.env.DO_NOT_TRACK = originalDoNotTrack;
+    }
+    await teardown();
+  });
+
+  it("--yes (no existing config, no env var) defaults telemetry to true", async () => {
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+    const cfg = readConfig();
+    assert.equal(cfg.telemetry, true);
+  });
+
+  it("SKILLREPO_NO_TELEMETRY=1 short-circuits to telemetry=false (even under --yes)", async () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "1";
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+    const cfg = readConfig();
+    assert.equal(cfg.telemetry, false);
+  });
+
+  it("DO_NOT_TRACK=1 (community convention) short-circuits to telemetry=false", async () => {
+    process.env.DO_NOT_TRACK = "1";
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+    const cfg = readConfig();
+    assert.equal(cfg.telemetry, false);
+  });
+
+  it("existing config.telemetry=false is preserved across re-init", async () => {
+    mkdirSync(join(process.env.HOME, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      join(process.env.HOME, ".claude", "skillrepo", "config.json"),
+      JSON.stringify({
+        schemaVersion: 1,
+        apiKey: VALID_KEY,
+        serverUrl,
+        telemetry: false,
+      }),
+    );
+    await runInit(["--yes"], { stdout, stderr });
+    const cfg = readConfig();
+    assert.equal(cfg.telemetry, false);
+  });
+});
+
 // ── Error paths ────────────────────────────────────────────────────────
 
 describe("runInit — error paths", () => {