sourcecode 1.35.36__py3-none-any.whl → 1.36.0__py3-none-any.whl

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/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/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/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/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/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/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/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.dist-info → sourcecode-1.36.0.dist-info}/METADATA

@@ -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.dist-info → sourcecode-1.36.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=ZxOECabDmAtGWQ7baAF8kAmS-2Kzj1Q5E1ciWq3lDi8,104
+sourcecode/__init__.py,sha256=j2Rx292C93M1gnbvMuKrqWMZXlDm3K85SxUiFzO4zac,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=liCwQmLgb5vplohy8arjYxs_HOIv5C9MjLh_gY6bc5Q,44115
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -7,7 +7,7 @@ sourcecode/cache.py,sha256=wAyPrXN5DqiGivnMpeEuun2xHDKfBer2_oBsh6kj_vc,30447
 sourcecode/canonical_ir.py,sha256=c_lYTVoegg-1W2dZ34_2s3tN8L0GVx7eiDRh9ghdSD8,24178
 sourcecode/cir_graphs.py,sha256=rZi8JV4ZrAa2WSCeyNa4JIEKQ_yZzDZTsrvVz2KfuKA,8919
 sourcecode/classifier.py,sha256=hKzg-nQ47htqqIUzSGvYxv15cXrA3KgICTwJmdqal0o,8095
-sourcecode/cli.py,sha256=5LrX0Fwp1Wqw7yE3hrXc26TOPf_A2vod7X6SG1s_0ag,247606
+sourcecode/cli.py,sha256=c8t9Jh68JjwcNyTZx9_hmoBLz1D0HOWu4snDFKtvang,249785
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -27,7 +27,7 @@ sourcecode/flow_analyzer.py,sha256=dSiuY4w49k29jW_EPXUOND9B5uVbuCA7kjnuHi-pIWA,2
 sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=DHR8fY69oU_Pi4SYaWboX6EoEFrctQKB9dsjpqwGMzw,62403
-sourcecode/license.py,sha256=iYtczUa4xh4-Y-2pMlfa6T7t1g-4nuld6-_PXT-Cq5Q,27299
+sourcecode/license.py,sha256=gHNXu4_yLiHCJLhIryBCCmtzF6wBoWplHMS8rmu7m24,28074
 sourcecode/mcp_nudge.py,sha256=5ELU_ixzh6uA83NXLOZT8h00OhL53okfQdji3jyKOjg,2917
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
 sourcecode/migrate_check.py,sha256=vowVIAxVaHU8vhZUEt-HrWrWM38m6a5INHJQGjEg5E0,55390
@@ -90,14 +90,14 @@ sourcecode/mcp/onboarding/applier.py,sha256=B9CneieWTpaDSDIyW3S5nrlRlBpvfqUcgi93
 sourcecode/mcp/onboarding/backup.py,sha256=ihqGOR8QTX8HASRSEDyfFyXr5bkXrygPHamv4p9KTmk,1452
 sourcecode/mcp/onboarding/detector.py,sha256=kDc0U6kXMuq_GivqwKrgJzIVLVeoLr3RQl63ksW10I8,3327
 sourcecode/mcp/onboarding/planner.py,sha256=Fopg5f72FDiPfldF7NOxYjcBA_w8hi_jBJpSz39lPb8,1332
-sourcecode/telemetry/__init__.py,sha256=M0eQZFNkmJiLbI_oNP4QEXwVju1dQ2d4P-E1-Bw8PxE,3116
-sourcecode/telemetry/config.py,sha256=Pir0WHp4z-9Qclnn2NDZ3vwitqsMkOAJckmwjUSxrk4,1795
+sourcecode/telemetry/__init__.py,sha256=rth1GuU9Tqt6BvbOe6q6sro1yCygiDW4dN3r1OvmvQM,3375
+sourcecode/telemetry/config.py,sha256=_MfMevIic1NTc8IRmCzQs96D8KPBLOWZ5cdhWrnHuwI,2639
 sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWnII,2237
-sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
-sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
-sourcecode/telemetry/transport.py,sha256=QSslxIwij8YkRWcVvxykODDrkiN_GAAEu3dUP7KIWeE,1651
-sourcecode-1.35.36.dist-info/METADATA,sha256=I2uv7cJb0-J0u-7RNSvPYjiExMkJIwjHqlLnOCcN618,30386
-sourcecode-1.35.36.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.35.36.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.35.36.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.35.36.dist-info/RECORD,,
+sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
+sourcecode/telemetry/filters.py,sha256=zFJfvmE7TT5ZYsXr3mh6kTe0adzzYqFZSx61wUJ8Rew,5849
+sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
+sourcecode-1.36.0.dist-info/METADATA,sha256=_SkuM5cooAYdgrd0BAhzvvKwy3f8i92t8XOMT2iwRtE,30383
+sourcecode-1.36.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.36.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.36.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.36.0.dist-info/RECORD,,