sourcecode 1.35.36__tar.gz → 1.36.0__tar.gz

{sourcecode-1.35.36 → sourcecode-1.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.35.36
+Version: 1.36.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.35.36-blue)
+![Version](https://img.shields.io/badge/version-1.36.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -114,7 +114,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.35.36
+# sourcecode 1.36.0
 ```
 
 ---

{sourcecode-1.35.36 → sourcecode-1.36.0}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.35.36-blue)
+![Version](https://img.shields.io/badge/version-1.36.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -76,7 +76,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.35.36
+# sourcecode 1.36.0
 ```
 
 ---

{sourcecode-1.35.36 → sourcecode-1.36.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.35.36"
+version = "1.36.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.35.36"
+__version__ = "1.36.0"

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/cli.py

@@ -653,6 +653,38 @@ def version_callback(value: bool) -> None:
         raise typer.Exit()
 
 
+def _print_welcome() -> None:
+    """Branded quickstart shown only on a bare invocation at a human terminal.
+
+    Agents and pipes never reach here: they either pass args/flags or stdout is
+    not a TTY, so the JSON machine contract is completely unchanged.
+    """
+    try:
+        from sourcecode import license as _lic
+        tier = "Pro" if _lic.is_pro else "Free"
+    except Exception:
+        tier = "Free"
+
+    lines = [
+        "",
+        f"  sourcecode {__version__}   ·   {tier}",
+        "",
+        "  Structural context for AI coding agents — analyze a repo, get",
+        "  LLM-ready JSON in milliseconds.",
+        "",
+        "  Get started:",
+        "    sourcecode --compact                high-signal summary of this repo",
+        "    sourcecode prepare-context onboard  full onboarding context",
+        "    sourcecode mcp init                 connect Claude / Cursor",
+        "",
+        "  sourcecode --help           all commands",
+    ]
+    if tier != "Pro":
+        lines.append("  sourcecode activate <key>   unlock Pro (large repos)")
+    lines.append("")
+    typer.echo("\n".join(lines))
+
+
 @app.callback(invoke_without_command=True)
 def main(
     ctx: typer.Context,
@@ -902,6 +934,13 @@ def main(
     if ctx.invoked_subcommand is not None:
         return
 
+    # Bare invocation at a human terminal → branded quickstart instead of
+    # dumping a large JSON blob. Agents/pipes are untouched: any arg/flag, or a
+    # non-TTY stdout (piped), falls through to the normal analysis + JSON.
+    if len(sys.argv) <= 1 and sys.stdout.isatty():
+        _print_welcome()
+        raise typer.Exit()
+
     _t0 = time.monotonic()
     no_tree: bool = False  # set True by --agent; --no-tree flag removed
 
@@ -2797,6 +2836,17 @@ def prepare_context_cmd(
             _cached_pctx = _pctx_cache.read(target, _pctx_cache_key)
             if _cached_pctx is not None:
                 _emit_command_output(_cached_pctx, output_path, copy)
+                try:
+                    from sourcecode import telemetry as _tel
+                    _tel.record(
+                        "execution_completed",
+                        cmd="prepare-context",
+                        feature=task,
+                        output_fmt=format,
+                        duration_s=0.0,
+                    )
+                except Exception:
+                    pass
                 return
 
     builder = TaskContextBuilder(target)
@@ -3192,6 +3242,18 @@ def prepare_context_cmd(
 
     _emit_command_output(_pc_content, output_path, copy)
 
+    try:
+        from sourcecode import telemetry as _tel
+        _tel.record(
+            "execution_completed",
+            cmd="prepare-context",
+            feature=task,
+            output_fmt=format,
+            duration_s=_time.perf_counter() - _t0,
+        )
+    except Exception:
+        pass
+
     from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
     _nudge()
 

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/license.py

@@ -416,6 +416,15 @@ _init()
 # Entitlement helpers
 # ---------------------------------------------------------------------------
 
+def _emit_telemetry(event: str, **kw: object) -> None:
+    """Best-effort telemetry emit. Respects opt-in; never raises or blocks."""
+    try:
+        from sourcecode import telemetry as _tel
+        _tel.record(event, **kw)  # type: ignore[arg-type]
+    except Exception:
+        pass
+
+
 def can_use(feature_name: str) -> bool:
     """Return True if the current plan has access to feature_name.
 
@@ -510,6 +519,7 @@ def require_feature(
     }
     if extra_fields:
         payload.update(extra_fields)
+    _emit_telemetry("gate_blocked", feature=feature_name, success=False)
     _emit_upgrade_and_exit(
         f"'{display}' is a Pro feature.",
         [info.get("description", ""), info.get("value", "")],
@@ -560,6 +570,7 @@ def require_repo_or_pro(
     }
     if extra_fields:
         payload.update(extra_fields)
+    _emit_telemetry("gate_blocked", feature=feature_name, repo_size="large", success=False)
     _emit_upgrade_and_exit(headline, body, payload)
 
 
@@ -610,6 +621,7 @@ def _finish_device_auth(result: dict) -> None:
     _write_license_file(data)
     _license_data = data
     is_pro = plan == "pro" and plan_status != "inactive"
+    _emit_telemetry("activation", feature="device_flow", success=is_pro)
 
     sys.stderr.write(f"\n  Authenticated as {email}.  Plan: {plan}\n\n")
     sys.stderr.flush()
@@ -693,9 +705,11 @@ def activate_license(license_key: str) -> None:
         _fail("network_error", "Could not reach license server. Check your internet connection.")
 
     if not result.get("valid"):
+        _emit_telemetry("activation", feature="key", success=False, error_kind="InvalidLicense")
         _fail("invalid_license", result.get("error", "License key is not valid or subscription is inactive."))
 
     if result.get("plan") != "pro":
+        _emit_telemetry("activation", feature="key", success=False, error_kind="NotPro")
         _fail("not_pro", "This license is not a Pro license.")
 
     _LICENSE_DIR.mkdir(parents=True, exist_ok=True)
@@ -709,6 +723,7 @@ def activate_license(license_key: str) -> None:
         "validated_at": now,
     }
     _write_license_file(data)
+    _emit_telemetry("activation", feature="key", success=True)
 
     output = {"status": "activated", "plan": "pro", "features": data["features"]}
     sys.stdout.write(json.dumps(output, ensure_ascii=False) + "\n")

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/telemetry/__init__.py

@@ -19,7 +19,7 @@ import sys
 import uuid
 from typing import Any, Optional
 
-from sourcecode.telemetry.config import is_enabled
+from sourcecode.telemetry.config import get_install_id, is_enabled
 from sourcecode.telemetry.events import (
     TelemetryEvent,
     duration_bucket,
@@ -77,6 +77,8 @@ def record(
     duration_s: Optional[float] = None,
     success: bool = True,
     error_kind: Optional[str] = None,
+    feature: Optional[str] = None,
+    repo_size: Optional[str] = None,
 ) -> None:
     """Record a telemetry event. Fire-and-forget — never blocks or raises.
 
@@ -96,10 +98,16 @@ def record(
             cmd=cmd,
             flags=flags or [],
             output_fmt=output_fmt,
-            repo_size=file_count_bucket(file_count) if file_count is not None else "unknown",
+            repo_size=(
+                repo_size if repo_size is not None
+                else file_count_bucket(file_count) if file_count is not None
+                else "unknown"
+            ),
             duration=duration_bucket(duration_s) if duration_s is not None else "unknown",
             success=success,
             error_kind=error_kind,
+            feature=feature,
+            install=get_install_id(),
             session=_SESSION,
         )
         payload = sanitize(ev)

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/telemetry/config.py

@@ -63,5 +63,28 @@ def mark_asked() -> None:
     _save(data)
 
 
+def get_install_id() -> str:
+    """Stable anonymous install id — a random UUID v4.
+
+    Created lazily on first opted-in event. NOT derived from hardware, email,
+    hostname or any identifier — it only says "the same install across runs",
+    which is what enables unique-user, conversion and retention metrics.
+    Returns "" if it cannot be persisted (telemetry then degrades to events
+    without a stable id, never an error).
+    """
+    data = _load()
+    tel = data.setdefault("telemetry", {})
+    iid = tel.get("install_id")
+    if not iid:
+        import uuid
+        iid = str(uuid.uuid4())
+        tel["install_id"] = iid
+        _save(data)
+        # If the write failed, re-read to avoid handing out a non-persisted id
+        if not _load().get("telemetry", {}).get("install_id"):
+            return ""
+    return str(iid)
+
+
 def config_file_path() -> Path:
     return _CONFIG_FILE

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/telemetry/events.py

@@ -59,6 +59,9 @@ class TelemetryEvent:
         duration    — <1s | <5s | <15s | <60s | 60s+
         success     — True/False
         error_kind  — exception class name only (no message, no traceback)
+        feature     — gated feature / task name (closed categorical set) or None
+        install     — stable anonymous install UUID (random, no PII); enables
+                      unique-user / conversion / retention metrics
         session     — 8-char random hex, ephemeral, NOT persisted
     """
 
@@ -75,4 +78,6 @@ class TelemetryEvent:
     duration: str = "unknown"
     success: bool = True
     error_kind: Optional[str] = None
+    feature: Optional[str] = None
+    install: str = ""
     session: str = ""

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/telemetry/filters.py

@@ -63,6 +63,19 @@ _SAFE_EVENTS: frozenset[str] = frozenset({
     "execution_failed",
     "telemetry_enabled",
     "telemetry_disabled",
+    "gate_blocked",
+    "activation",
+})
+# Closed set of gated features / task names. Used to learn which capability
+# drives Pro demand. All values are fixed product identifiers — no user data.
+_SAFE_FEATURES: frozenset[str] = frozenset({
+    # gated features (license._FEATURE_INFO keys)
+    "impact", "modernize", "fix-bug", "review-pr", "delta", "generate-tests",
+    "--full", "git-history", "multi-repo", "export-rich", "team-snapshots",
+    # prepare-context task names not already above
+    "explain", "onboard", "refactor",
+    # activation outcomes
+    "key", "device_flow",
 })
 _SAFE_SIZES: frozenset[str] = frozenset({"tiny", "small", "medium", "large", "huge", "unknown"})
 _SAFE_DURATIONS: frozenset[str] = frozenset({"<1s", "<5s", "<15s", "<60s", "60s+", "unknown"})
@@ -103,6 +116,14 @@ def _safe_session(value: str) -> str:
     return ""
 
 
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def _safe_install(value: str) -> str:
+    """Install id must be a canonical UUID — nothing else can pass."""
+    return value if value and _UUID_RE.match(value) else ""
+
+
 def sanitize(event: TelemetryEvent) -> dict[str, Any]:
     """Apply privacy filter to event and return a safe dict for transmission.
 
@@ -127,6 +148,13 @@ def sanitize(event: TelemetryEvent) -> dict[str, Any]:
     if event.error_kind:
         safe["error_kind"] = _safe_error_kind(event.error_kind)
 
+    if event.feature:
+        safe["feature"] = _safe_str(event.feature, _SAFE_FEATURES, "other")
+
+    install = _safe_install(event.install)
+    if install:
+        safe["install"] = install
+
     session = _safe_session(event.session)
     if session:
         safe["session"] = session

{sourcecode-1.35.36 → sourcecode-1.36.0}/src/sourcecode/telemetry/transport.py

@@ -15,7 +15,7 @@ import os
 import threading
 from typing import Any
 
-_DEFAULT_ENDPOINT = "https://t.sourcecode.dev/v1/event"
+_DEFAULT_ENDPOINT = "https://qkndlmyekvujjdgthtmz.supabase.co/functions/v1/telemetry"
 _TIMEOUT_S = 3
 
 

{sourcecode-1.35.36 → sourcecode-1.36.0}/supabase/functions/README.md

@@ -9,9 +9,13 @@ Backend for the Pro license flow. The CLI side lives in
 |----------|---------|-----|
 | `get-license` | Validates a license key for `sourcecode activate` and the 30-min revalidation. Returns `{valid, plan, status, features, email}`. | `--no-verify-jwt` |
 | `lemonsqueezy-webhook` | Lemon Squeezy purchase/subscription webhook. Stores the LS native key, sets plan/status, handles revocation. | `--no-verify-jwt` |
+| `telemetry` | Collects opt-in anonymous usage events (no PII). Inserts into `telemetry_events`. CLI side: `src/sourcecode/telemetry/`. | `--no-verify-jwt` |
 
-Both deploy with JWT verification OFF: the CLI authenticates with the public
-publishable key (not a JWT), and the webhook authenticates via HMAC signature.
+All deploy with JWT verification OFF: the CLI authenticates with the public
+publishable key (not a JWT), the webhook authenticates via HMAC signature, and
+telemetry is unauthenticated public ingest.
+
+The `telemetry` table is created from `supabase/sql/telemetry_events.sql`.
 
 ## Secrets (Supabase dashboard -> Edge Functions -> Secrets)
 

sourcecode-1.36.0/supabase/functions/telemetry/index.ts

@@ -0,0 +1,72 @@
+import { serve } from "https://deno.land/std@0.177.0/http/server.ts";
+import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
+
+// Opt-in anonymous usage telemetry collector. The CLI sends privacy-filtered
+// events (no PII, no paths) fire-and-forget — see src/sourcecode/telemetry/.
+// Deploy with --no-verify-jwt: events are public, low-value, and the client
+// sends no auth header. This endpoint only INSERTS into telemetry_events.
+const SUPABASE_URL = Deno.env.get("SUPABASE_URL")!;
+const SUPABASE_SERVICE_ROLE_KEY = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;
+
+// Server-side defense in depth — mirror the client allowlists. Anything
+// unexpected is coerced to a safe default so a tampered payload cannot inject.
+const EVENTS = new Set([
+  "command_executed", "execution_completed", "execution_failed",
+  "telemetry_enabled", "telemetry_disabled", "gate_blocked", "activation",
+]);
+const SIZES = new Set(["tiny", "small", "medium", "large", "huge", "unknown"]);
+const DURATIONS = new Set(["<1s", "<5s", "<15s", "<60s", "60s+", "unknown"]);
+const OSES = new Set(["linux", "macos", "windows", "other"]);
+const ARCHES = new Set(["x64", "arm64", "other"]);
+const FMTS = new Set(["json", "yaml"]);
+
+const pick = (v: unknown, allowed: Set<string>, fb: string) =>
+  typeof v === "string" && allowed.has(v) ? v : fb;
+const short = (v: unknown, n = 32) =>
+  typeof v === "string" && v.length <= n && !/[/\\\s]/.test(v) ? v : null;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const uuid = (v: unknown) =>
+  typeof v === "string" && UUID_RE.test(v) ? v : null;
+
+serve(async (req: Request) => {
+  if (req.method !== "POST") return new Response("ok", { status: 405 });
+
+  let p: Record<string, unknown>;
+  try {
+    p = await req.json();
+  } catch {
+    return new Response("ok", { status: 200 }); // never error loudly on telemetry
+  }
+
+  const row = {
+    event: pick(p.event, EVENTS, "command_executed"),
+    client_ts: short(p.ts, 20),
+    v: short(p.v, 16),
+    py: short(p.py, 8),
+    os: pick(p.os, OSES, "other"),
+    arch: pick(p.arch, ARCHES, "other"),
+    cmd: short(p.cmd, 24),
+    flags: Array.isArray(p.flags) ? p.flags.filter((f) => short(f, 32)).slice(0, 40) : [],
+    output_fmt: pick(p.output_fmt, FMTS, "json"),
+    repo_size: pick(p.repo_size, SIZES, "unknown"),
+    duration: pick(p.duration, DURATIONS, "unknown"),
+    success: typeof p.success === "boolean" ? p.success : null,
+    error_kind: short(p.error_kind, 64),
+    feature: short(p.feature, 32),
+    install_id: uuid(p.install),
+    session: short(p.session, 16),
+  };
+
+  try {
+    const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY);
+    await supabase.from("telemetry_events").insert(row);
+  } catch (e) {
+    console.error("telemetry insert failed", e);
+    // still return 200 — never penalize the CLI for our DB hiccup
+  }
+
+  return new Response(JSON.stringify({ received: true }), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+});

sourcecode-1.36.0/supabase/sql/telemetry_events.sql

@@ -0,0 +1,36 @@
+-- Anonymous, opt-in usage telemetry. No PII, no paths — every column is a
+-- bounded categorical or bucket. Populated by the `telemetry` edge function.
+create table if not exists public.telemetry_events (
+  id          uuid primary key default gen_random_uuid(),
+  received_at timestamptz not null default now(),
+  event       text not null,
+  client_ts   text,
+  v           text,            -- sourcecode version
+  py          text,            -- python major.minor
+  os          text,            -- linux | macos | windows | other
+  arch        text,            -- x64 | arm64 | other
+  cmd         text,            -- analyze | prepare-context | telemetry | unknown
+  flags       jsonb default '[]'::jsonb,
+  output_fmt  text,            -- json | yaml
+  repo_size   text,            -- tiny | small | medium | large | huge | unknown
+  duration    text,            -- <1s | <5s | <15s | <60s | 60s+ | unknown
+  success     boolean,
+  error_kind  text,            -- exception class name only
+  feature     text,            -- gated feature / task name (closed set)
+  install_id  uuid,            -- stable anonymous install id (random, no PII)
+  session     text             -- ephemeral 8-char hex, NOT a stable user id
+);
+
+-- If the table already exists from an earlier deploy, add the column:
+alter table public.telemetry_events add column if not exists install_id uuid;
+
+-- Common query axes: funnel by event, adoption by version, time series,
+-- and unique-install / conversion / retention by install_id.
+create index if not exists telemetry_events_event_idx      on public.telemetry_events (event);
+create index if not exists telemetry_events_received_at_idx on public.telemetry_events (received_at);
+create index if not exists telemetry_events_feature_idx     on public.telemetry_events (feature);
+create index if not exists telemetry_events_install_idx     on public.telemetry_events (install_id);
+
+-- RLS on, no policies: only the service role (edge function) can write/read.
+-- The public anon/publishable key cannot touch this table.
+alter table public.telemetry_events enable row level security;