skillrepo 4.3.0 → 4.4.0

package/README.md

@@ -219,6 +219,109 @@ DELETEs from `/api/v1/library` and deletes the local directory. Requires
 a write-scoped access key. The local delete is immediate and does not
 wait for a follow-up sync.
 
+### `push` — upload a local skill directory to your account
+
+```sh
+skillrepo push <path> [--idempotency-key <key>] [--key <key>] [--url <url>] [--json]
+```
+
+Multipart `POST` to `/api/v1/library`. Walks `<path>`, packages
+`SKILL.md` plus every supporting file under `scripts/`, `references/`,
+and `assets/`, and uploads them as a single request. The server picks
+the outcome by SKILL.md frontmatter `name`:
+
+- **First push** of this name → creates a private skill and returns
+  `action: "created"`.
+- **Subsequent push with changed content** → releases a new version.
+  The server classifies the bump as major (if `description`,
+  `allowed-tools`, or `compatibility` changed) or minor otherwise, and
+  returns `action: "updated"` with the bump kind.
+- **Identical content** → no-op (SHA-matched). Returns
+  `action: "unchanged"`.
+
+`push` is the only CLI command that uploads local content; it does not
+write anything back to disk. Use `update` to pull canonical skills
+from the server to your local library.
+
+Limits: total multipart body ≤ 4.5 MB, per-file path depth ≤ 5
+segments, executable/archive extensions blocked (full list in
+`src/lib/skills/constants.ts`). Anti-abuse rate limit: 5/min and
+30/hr on Publisher; 30/min and 500/hr on Team.
+
+Flags:
+
+- `--idempotency-key <key>` — explicit key for safe retries. By default
+  the CLI generates a fresh UUID per invocation and uses it for the
+  in-process retry loop (transient 5xx/429 get up to 3 attempts with
+  exponential backoff and jitter). Pass an explicit key to share it
+  across separate shell invocations (CI step retries, manual reruns)
+  and replay the cached response. Cached responses live for 24 hours.
+- `--json` — emit a structured object (`action`, `bump`, `owner`,
+  `name`, `version`, `filesUploaded`).
+- `--key`, `--url` — standard auth / endpoint flags.
+
+Exit codes: `5` (validation — bad SKILL.md, blocked path, payload too
+large, `plan_limit`), `4` (scope — read-only key), `2` (auth), `1`
+(network/5xx after retries).
+
+### `publish` — make one of your skills visible in the public catalog
+
+```sh
+skillrepo publish <@owner/name> [--key <key>] [--url <url>] [--json]
+```
+
+`POST`s to `/api/v1/library/{owner}/{name}/publish` to flip the
+skill's visibility from `private` to `global`. Idempotent: calling
+`publish` on an already-global skill returns `200` with
+`action: "unchanged"` (the CLI prints "Already published").
+Requires a write-scoped access key.
+
+Permission model: admin+ members can always publish. Non-admin members
+can publish if their account-membership has `canPublish: true` (or the
+account-wide `memberCanPublish` default is enabled). Without either,
+the CLI exits `4 / scope` with `code: publish_not_permitted`. The same
+`canPublish` capability gates `unpublish` and `delete` symmetrically.
+
+Publish-only preconditions that surface as exit `5 / validation`:
+
+- `namespace_unset` — the account's name still equals its
+  auto-generated slug; customize the namespace first.
+- `analysis_pending` — safety analysis hasn't completed (only fires
+  where analysis is enabled).
+- `safety_grade_too_low` — the skill's safety grade is `F`.
+
+Flags:
+
+- `--json` — emit `{ action, owner, name }`. The CLI exits non-zero on error, so the presence of stdout JSON already implies success — there is no `ok` field.
+- `--key`, `--url` — standard auth / endpoint flags.
+
+### `unpublish` — remove one of your skills from the public catalog
+
+```sh
+skillrepo unpublish <@owner/name> [--key <key>] [--url <url>] [--json]
+```
+
+`POST`s to `/api/v1/library/{owner}/{name}/unpublish` to flip the
+skill's visibility from `global` to `private`. Pair to `publish`:
+same auth, same scope, same flag surface.
+
+**Subscribers keep their copy.** Accounts that already had your skill
+in their library retain the version they pulled — they just stop
+receiving future updates unless you republish. The CLI surfaces a
+one-line summary (e.g. "Notified 12 subscribers") so you know how
+many accounts the unpublish reached.
+
+Each affected subscriber account's owner-role member(s) receive a
+one-time notification email, debounced 24h per `(skill, account)`
+pair so a fast unpublish/republish/unpublish cycle doesn't spam the
+same recipient. The publisher's own account is excluded.
+Already-private skills (`action: "unchanged"`) trigger no emails.
+
+Flags:
+
+- `--json` — emit `{ action, owner, name, notifiedSubscriberCount }`. `notifiedSubscriberCount` is `0` when `action === "unchanged"`. No `ok` field — exit code carries success/failure.
+- `--key`, `--url` — standard auth / endpoint flags.
+
 ### `session-sync` — auto-sync on Claude Code session start
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -87,7 +87,7 @@ import {
   claudeSkillsProjectRoot,
   agentsSkillsProjectRoot,
 } from "../lib/paths.mjs";
-import { promptWithBrowserOpen } from "../lib/prompt.mjs";
+import { promptWithBrowserOpen, confirm } from "../lib/prompt.mjs";
 import { promptMultiSelect } from "../lib/prompt-multiselect.mjs";
 import {
   CliError,
@@ -96,6 +96,10 @@ import {
   EXIT_AUTH,
 } from "../lib/errors.mjs";
 import { cliAuthUrl } from "../lib/constants.mjs";
+import {
+  reportInitFailure,
+  telemetryDisabledByEnv,
+} from "../lib/telemetry.mjs";
 
 /**
  * Format the user-visible "configured X, Y" line for the init step-4
@@ -288,6 +292,38 @@ export async function runInit(argv, io = {}, deps = {}) {
 
   p.blank();
 
+  // Determine the telemetry preference for THIS init run (#1539).
+  // Priority: SKILLREPO_NO_TELEMETRY env var (always wins) → existing
+  // config flag (if set explicitly) → opt-out default of `true`
+  // (enabled). The env-var check is the only opt-out path that fires
+  // BEFORE the very first user interaction; everything else assumes
+  // the user is willing to receive the prompt below.
+  let telemetryEnabledForRun;
+  if (telemetryDisabledByEnv()) {
+    telemetryEnabledForRun = false;
+  } else if (
+    existingConfig &&
+    typeof existingConfig.telemetry === "boolean"
+  ) {
+    telemetryEnabledForRun = existingConfig.telemetry;
+  } else if (yes || !process.stdin.isTTY) {
+    // Non-interactive: take the opt-out-friendly default. Users in
+    // CI / scripts can pin `SKILLREPO_NO_TELEMETRY=1` to override.
+    // The `!isTTY` check protects existing CI patterns like
+    // `init --key sk_live_...` (no --yes) that worked before this
+    // prompt was added — they would hang on `readline.question()`
+    // waiting for stdin that never arrives.
+    telemetryEnabledForRun = true;
+  } else {
+    // First-init prompt — only fires when no preference is recorded,
+    // the env var didn't already opt out, AND stdin is a TTY. Y/n
+    // with Y default, so a bare Enter keeps telemetry enabled.
+    telemetryEnabledForRun = await confirm(
+      "Send anonymous error reports to help improve setup?",
+      true,
+    );
+  }
+
   // ── Step 2: Validate against the server ──────────────────────
   p.step(2, 7, "Validating key");
   let accountCtx;
@@ -315,8 +351,27 @@ export async function runInit(argv, io = {}, deps = {}) {
       if (!apiKey || !apiKey.startsWith("sk_live_")) {
         throw validationError("Invalid access key format.");
       }
-      accountCtx = await validateAccessKey(serverUrl, apiKey, "init");
+      try {
+        accountCtx = await validateAccessKey(serverUrl, apiKey, "init");
+      } catch (retryErr) {
+        // The user re-pasted and validate still failed. This is the
+        // failure mode the diagnostic exercise surfaced — exactly the
+        // case telemetry exists for. Fire-and-forget; never throws.
+        void reportInitFailure({
+          serverUrl,
+          config: telemetryEnabledForRun ? { telemetry: true } : { telemetry: false },
+          stage: "post_paste_validate",
+          errorCode: retryErr instanceof CliError ? retryErr.exitCode : EXIT_AUTH,
+        });
+        throw retryErr;
+      }
     } else {
+      void reportInitFailure({
+        serverUrl,
+        config: telemetryEnabledForRun ? { telemetry: true } : { telemetry: false },
+        stage: "post_paste_validate",
+        errorCode: err instanceof CliError ? err.exitCode : EXIT_AUTH,
+      });
       throw err;
     }
   }
@@ -325,12 +380,15 @@ export async function runInit(argv, io = {}, deps = {}) {
 
   // ── Step 3: Write global config ──────────────────────────────
   p.step(3, 7, "Writing config");
+  // Persist the telemetry preference alongside the credentials so
+  // subsequent inits skip the prompt and honor the same choice (#1539).
   const configAction = writeConfig({
     apiKey,
     serverUrl,
     accountSlug: accountCtx.accountSlug,
     accountId: accountCtx.accountId,
     userId: accountCtx.userId,
+    telemetry: telemetryEnabledForRun,
   });
   p.success(`~/.claude/skillrepo/config.json ${configAction}`);
 

package/src/lib/config.mjs

@@ -174,6 +174,12 @@ export function writeConfig(config) {
   for (const key of ["accountSlug", "accountId", "userId"]) {
     if (config[key] !== undefined) merged[key] = config[key];
   }
+  // Telemetry opt-in/out flag (#1539). Persisted only when the caller
+  // explicitly sets it — omitting means "no preference recorded,"
+  // which the telemetry module treats as "enabled" (opt-out default).
+  if (typeof config.telemetry === "boolean") {
+    merged.telemetry = config.telemetry;
+  }
 
   // Atomic write via temp-file + rename. Matches the file-write.mjs
   // pattern: the config file is never in a half-written state, so

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", () => {

package/src/test/lib/config.test.mjs

@@ -206,6 +206,39 @@ describe("writeConfig", () => {
     assert.equal(mode, 0o600, `Expected 0o600, got ${mode.toString(8)}`);
   });
 
+  // Telemetry opt-in/out flag persistence (#1539). The field is only
+  // written when the caller explicitly sets it (boolean) — omitting
+  // means "no preference recorded" and the telemetry module treats
+  // that as the opt-out-friendly default of enabled.
+  it("persists telemetry=true when explicitly set", () => {
+    writeConfig({
+      apiKey: "sk_live_abc",
+      serverUrl: "https://example.com",
+      telemetry: true,
+    });
+    const raw = JSON.parse(readFileSync(globalConfigPath(), "utf-8"));
+    assert.equal(raw.telemetry, true);
+  });
+
+  it("persists telemetry=false when explicitly set", () => {
+    writeConfig({
+      apiKey: "sk_live_abc",
+      serverUrl: "https://example.com",
+      telemetry: false,
+    });
+    const raw = JSON.parse(readFileSync(globalConfigPath(), "utf-8"));
+    assert.equal(raw.telemetry, false);
+  });
+
+  it("does NOT write a telemetry field when omitted (preserves no-preference state)", () => {
+    writeConfig({
+      apiKey: "sk_live_abc",
+      serverUrl: "https://example.com",
+    });
+    const raw = JSON.parse(readFileSync(globalConfigPath(), "utf-8"));
+    assert.equal("telemetry" in raw, false);
+  });
+
   it("throws validationError on missing apiKey", () => {
     assert.throws(
       () => writeConfig({ serverUrl: "https://example.com" }),

package/src/test/lib/telemetry.test.mjs

@@ -0,0 +1,289 @@
+/**
+ * Unit tests for `packages/cli/src/lib/telemetry.mjs` (#1539).
+ *
+ * Covers:
+ *   - `telemetryDisabledByEnv` recognises `SKILLREPO_NO_TELEMETRY` and
+ *     the community `DO_NOT_TRACK` convention.
+ *   - `telemetryEnabled` honors env-disable, config-disable, and the
+ *     opt-out-friendly default of `true`.
+ *   - `reportInitFailure` is fire-and-forget — never throws, drops
+ *     payloads with out-of-enum `stage` values, builds the right
+ *     payload + URL, and honors the env/config opt-outs.
+ *
+ * The fetch is dependency-injected (no network).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  telemetryDisabledByEnv,
+  telemetryEnabled,
+  reportInitFailure,
+  INIT_STAGES,
+  TELEMETRY_TIMEOUT_MS,
+} from "../../lib/telemetry.mjs";
+
+let savedEnv;
+
+beforeEach(() => {
+  savedEnv = {
+    SKILLREPO_NO_TELEMETRY: process.env.SKILLREPO_NO_TELEMETRY,
+    DO_NOT_TRACK: process.env.DO_NOT_TRACK,
+  };
+  delete process.env.SKILLREPO_NO_TELEMETRY;
+  delete process.env.DO_NOT_TRACK;
+});
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+describe("telemetryDisabledByEnv", () => {
+  it("returns false when neither env var is set", () => {
+    assert.equal(telemetryDisabledByEnv(), false);
+  });
+
+  it("returns true when SKILLREPO_NO_TELEMETRY=1", () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "1";
+    assert.equal(telemetryDisabledByEnv(), true);
+  });
+
+  it("returns true for any truthy SKILLREPO_NO_TELEMETRY value", () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "yes";
+    assert.equal(telemetryDisabledByEnv(), true);
+  });
+
+  it("returns false when SKILLREPO_NO_TELEMETRY is '0'", () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "0";
+    assert.equal(telemetryDisabledByEnv(), false);
+  });
+
+  it("returns false when SKILLREPO_NO_TELEMETRY is 'false'", () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "false";
+    assert.equal(telemetryDisabledByEnv(), false);
+  });
+
+  it("returns true when DO_NOT_TRACK=1 (community convention)", () => {
+    process.env.DO_NOT_TRACK = "1";
+    assert.equal(telemetryDisabledByEnv(), true);
+  });
+
+  it("returns true when DO_NOT_TRACK=true (community convention)", () => {
+    process.env.DO_NOT_TRACK = "true";
+    assert.equal(telemetryDisabledByEnv(), true);
+  });
+
+  it("returns false when DO_NOT_TRACK has some other value", () => {
+    process.env.DO_NOT_TRACK = "no";
+    assert.equal(telemetryDisabledByEnv(), false);
+  });
+});
+
+describe("telemetryEnabled", () => {
+  it("is true with no config and no env var (opt-out default)", () => {
+    assert.equal(telemetryEnabled(null), true);
+    assert.equal(telemetryEnabled(undefined), true);
+    assert.equal(telemetryEnabled({}), true);
+  });
+
+  it("is true when config.telemetry === true", () => {
+    assert.equal(telemetryEnabled({ telemetry: true }), true);
+  });
+
+  it("is false when config.telemetry === false", () => {
+    assert.equal(telemetryEnabled({ telemetry: false }), false);
+  });
+
+  it("is false when env var opts out, regardless of config", () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "1";
+    assert.equal(telemetryEnabled({ telemetry: true }), false);
+    assert.equal(telemetryEnabled({}), false);
+    assert.equal(telemetryEnabled(null), false);
+  });
+});
+
+describe("INIT_STAGES", () => {
+  it("declares the closed set of init stages the server schema accepts", () => {
+    assert.deepEqual(
+      [...INIT_STAGES],
+      [
+        "pre_paste",
+        "post_paste_validate",
+        "config_write",
+        "library_sync",
+        "agent_detection",
+      ],
+    );
+  });
+});
+
+describe("reportInitFailure", () => {
+  function makeFetchSpy(response = new Response(null, { status: 204 })) {
+    const calls = [];
+    const fn = async (url, init) => {
+      calls.push({ url, init });
+      return response;
+    };
+    fn.calls = calls;
+    return fn;
+  }
+
+  it("does nothing when telemetry is disabled by env", async () => {
+    process.env.SKILLREPO_NO_TELEMETRY = "1";
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: null,
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 0);
+  });
+
+  it("does nothing when config opts out", async () => {
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: false },
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 0);
+  });
+
+  it("does nothing when stage is not in the closed enum", async () => {
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: null,
+      stage: "i_made_this_up",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 0);
+  });
+
+  it("POSTs the documented payload shape to /api/v1/cli/events", async () => {
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: true },
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 1);
+    const call = fetchSpy.calls[0];
+    assert.equal(call.url, "https://skillrepo.dev/api/v1/cli/events");
+    assert.equal(call.init.method, "POST");
+    assert.equal(call.init.headers["Content-Type"], "application/json");
+    assert.ok(call.init.headers["User-Agent"].startsWith("skillrepo-cli/"));
+    const body = JSON.parse(call.init.body);
+    assert.equal(body.stage, "post_paste_validate");
+    assert.equal(body.errorCode, 401);
+    assert.equal(body.serverUrlHost, "skillrepo.dev");
+    assert.equal(typeof body.cliVersion, "string");
+    assert.equal(typeof body.nodeVersion, "string");
+    assert.equal(typeof body.platform, "string");
+    // Privacy contract: no key material.
+    assert.equal(body.apiKey, undefined);
+    assert.equal(body.token, undefined);
+    assert.equal(body.secret, undefined);
+  });
+
+  it("strips trailing slashes from the server URL when building the endpoint", async () => {
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev///",
+      config: { telemetry: true },
+      stage: "config_write",
+      errorCode: 3,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls[0].url, "https://skillrepo.dev/api/v1/cli/events");
+  });
+
+  it("never throws — swallows network failures silently", async () => {
+    const fetchSpy = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: true },
+      stage: "post_paste_validate",
+      errorCode: 1,
+      deps: { fetch: fetchSpy },
+    });
+    // No assertion needed — if we reach this line, no throw happened.
+  });
+
+  it("never throws on a server 500 — swallows abnormal status silently", async () => {
+    const fetchSpy = makeFetchSpy(new Response("oops", { status: 500 }));
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: true },
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 1);
+  });
+
+  it("times out the fetch via AbortController", async () => {
+    // Verify the 1-second timeout fires by giving the fetch a slow
+    // promise and asserting the abort propagates. The fetch we
+    // provide observes the signal and rejects when aborted.
+    let abortObserved = false;
+    const fetchSpy = (url, init) =>
+      new Promise((_resolve, reject) => {
+        init.signal.addEventListener("abort", () => {
+          abortObserved = true;
+          reject(new DOMException("aborted", "AbortError"));
+        });
+      });
+    const start = Date.now();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: true },
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    const elapsed = Date.now() - start;
+    assert.equal(abortObserved, true);
+    // Give a generous tolerance — node:test machinery + CI variance
+    // can easily eat 200ms on a busy runner.
+    assert.ok(
+      elapsed >= TELEMETRY_TIMEOUT_MS - 50 && elapsed < TELEMETRY_TIMEOUT_MS + 2000,
+      `Elapsed ${elapsed}ms should be near TELEMETRY_TIMEOUT_MS (${TELEMETRY_TIMEOUT_MS})`,
+    );
+  });
+
+  it("does not fire on unsupported platforms (server would 400)", async () => {
+    // Simulate by swapping global fetch with a sentinel — we can't
+    // easily monkey `os.platform()`, so this verifies the symmetric
+    // contract: any platform string outside the closed set is dropped
+    // BEFORE fetch is called. The test runs on the host's actual
+    // platform (which is supported); the assertion is structural —
+    // that the platform check is in place.
+    //
+    // We assert by checking the FORWARD path: a supported platform
+    // (the host's) DOES fire, proving the gate isn't a global "skip
+    // everything" guard.
+    const fetchSpy = makeFetchSpy();
+    await reportInitFailure({
+      serverUrl: "https://skillrepo.dev",
+      config: { telemetry: true },
+      stage: "post_paste_validate",
+      errorCode: 401,
+      deps: { fetch: fetchSpy },
+    });
+    assert.equal(fetchSpy.calls.length, 1);
+  });
+});