sourcecode 1.31.29__tar.gz → 1.31.31__tar.gz

sourcecode-1.31.31/.continue-here.md

@@ -0,0 +1,89 @@
+# Handoff — Sesión 34 (2026-05-26)
+
+## Position
+
+**Project:** sourcecode (atlas-cli)  
+**Activity:** Post-audit bug fixing + new feature (MCP nudge)  
+**Branch:** master  
+**Last commit:** 11d23b0 — feat(mcp): add one-time MCP setup nudge after successful commands  
+**Tests:** 1601 passed, 3 skipped ✅
+
+---
+
+## Work Done This Session
+
+### Session 34 (this session)
+**New feature: one-time MCP setup nudge**
+
+**FEAT — `sourcecode mcp_nudge.py` (new module)**
+- `nudge_mcp_if_needed()`: fires after first successful analysis command when Claude Desktop/Cursor installed but sourcecode not yet in MCP config. Writes to stderr only. Creates `~/.sourcecode/nudge_shown` flag to fire at most once per session.
+- `clear_nudge_flag()`: called by `mcp init` on success — next run finds `is_installed=True` → no nudge.
+- Module-level imports for testability; `_IMPORTS_OK=False` stubs if onboarding package missing.
+
+**CLI hooks (4 call sites in `cli.py`):**
+| Command | Location |
+|---|---|
+| `sourcecode . --compact` | `main()` — after clipboard copy |
+| `sourcecode prepare-context` / `onboard` | `prepare_context_cmd()` — end |
+| `sourcecode endpoints` | `endpoints_cmd()` — end |
+| `sourcecode impact` | `impact_cmd()` — success path only (after not_found check) |
+
+**`mcp init` success** → `clear_nudge_flag()` called.
+
+**Tests:** `tests/test_mcp_nudge.py` — 11 tests, all pass.
+
+---
+
+## Remaining from Bug Audit Backlog
+
+### P1 backlog
+| # | Issue | File | Effort |
+|---|---|---|---|
+| P1-5 | `project_summary` quality — picks license/badges/marketing blurbs | `summarizer.py` | Medium |
+| P1-6 | `relevant_files.score` ranking quality audit (score exposed, ranking weak) | `ranking_engine.py` | Medium |
+
+### P2 unfixed
+| # | Issue | File | Effort |
+|---|---|---|---|
+| P2-13 | `--no-cache` flag inconsistent across subcommands | `cli.py` | Medium |
+| P2-14 | URLs in code_notes truncated (needs repro) | `code_notes_analyzer.py` | Low |
+| P2-16 | `entry_points.controllers.methods` mismatches `endpoints` count | `cli.py` | Medium |
+| P2-17 | `--compact --help` token claim stale (now runs arch analyzer too) | `cli.py` | Trivial |
+| P2-18 | `impact <file_path>` fails FQN resolution | `repository_ir.py` | Low |
+
+---
+
+## Key Files Modified (this session)
+
+```
+src/sourcecode/mcp_nudge.py         — NEW: nudge_mcp_if_needed, clear_nudge_flag
+src/sourcecode/cli.py               — 4 nudge call sites + clear_nudge_flag in mcp_init
+tests/test_mcp_nudge.py             — NEW: 11 tests
+```
+
+---
+
+## Decisions This Session
+
+| Decision | Rationale |
+|---|---|
+| Module-level imports in mcp_nudge.py (not lazy) | Enables `patch("sourcecode.mcp_nudge.detect_clients", ...)` in tests |
+| Flag at `~/.sourcecode/nudge_shown` | Reuses existing state root; simple touch file |
+| Nudge on impact only when resolution != not_found | not_found = exit 1 = failure; no nudge on failed commands |
+| `clear_nudge_flag()` in mcp_init success, not in detection | Separation: flag reset is explicit intent (user ran init), not a side effect of checking |
+
+---
+
+## Next Session
+
+**Recommended:** P2-17 (trivial) → P2-18 (low) → P2-14 (low, needs repro) → P1-5 (medium) → P1-6 (medium) → P2-13 (medium) → P2-16 (medium)
+
+**P2-17:** `--compact --help` says token count — verify claim still accurate after P2-10 fix (compact now runs ArchitectureAnalyzer). Update if stale.
+
+**P2-18:** `sourcecode impact <file_path>` — resolve file path to FQN before IR lookup. Currently passes raw path to `_resolve_target()`, fails to match.
+
+**P1-5:** Audit `summarizer.py`. Prefer: first real descriptive paragraph, architecture description, domain/stack. Exclude: 'Important:', license, badges, install snippets, TOC, link collections, sponsorship, release notes.
+
+**Resume command:** `/gsd:resume-work`
+
+**Test baseline:** `python3 -m pytest tests/ → 1601 passed, 3 skipped`

{sourcecode-1.31.29 → sourcecode-1.31.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.29
+Version: 1.31.31
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.29-blue)
+![Version](https://img.shields.io/badge/version-1.31.31-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -263,7 +263,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.29
+# sourcecode 1.31.31
 ```
 
 ---

{sourcecode-1.31.29 → sourcecode-1.31.31}/README.md

@@ -2,7 +2,7 @@
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.29-blue)
+![Version](https://img.shields.io/badge/version-1.31.31-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -40,7 +40,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.29
+# sourcecode 1.31.31
 ```
 
 ---

{sourcecode-1.31.29 → sourcecode-1.31.31}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.31.29"
+version = "1.31.31"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.31.29 → sourcecode-1.31.31}/src/sourcecode/__init__.py

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

{sourcecode-1.31.29 → sourcecode-1.31.31}/src/sourcecode/cli.py

@@ -171,6 +171,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "repo-ir", "mcp", "endpoints", "impact",
         # Enterprise workflow commands
         "onboard", "modernize", "fix-bug", "review-pr",
+        # License
+        "activate",
     }
 )
 
@@ -253,6 +255,35 @@ def _emit_error_json(error: str, message: str, **context: object) -> None:
     _sys.stderr.flush()
 
 
+# H-06: Intercept Click-level UsageError (unknown options, bad args) and emit JSON.
+# Click's default show() writes "Error: No such option: --foo" as plain text.
+# Automation consumers need JSON on stderr regardless of how the error originated.
+try:
+    import click.exceptions as _click_exc
+
+    def _json_click_usage_error_show(self: Any, file: Any = None) -> None:  # type: ignore[override]
+        import json as _je
+        import sys as _jse
+        _code_map = {
+            "NoSuchOption": "invalid_option",
+            "BadOptionUsage": "invalid_option",
+            "BadParameter": "bad_parameter",
+            "MissingParameter": "missing_required",
+            "BadArgumentUsage": "bad_argument",
+        }
+        code = _code_map.get(type(self).__name__, "invalid_option")
+        payload: dict[str, object] = {"error": code, "message": self.format_message()}
+        _opt = getattr(self, "option_name", None) or getattr(self, "param_hint", None)
+        if _opt:
+            payload["flag"] = str(_opt).strip("'\"")
+        _jse.stderr.write(_je.dumps(payload, ensure_ascii=False) + "\n")
+        _jse.stderr.flush()
+
+    _click_exc.UsageError.show = _json_click_usage_error_show  # type: ignore[method-assign]
+except Exception:
+    pass  # click unavailable — plain-text fallback
+
+
 def _copy_to_clipboard(content: str) -> bool:
     """Copy text to system clipboard. Returns True on success, False otherwise (never raises)."""
     import subprocess
@@ -760,8 +791,11 @@ def main(
             err=True,
         )
 
-    # P0-2 FIX: --changed-only silently implies --compact; inform the user.
-    if changed_only and not compact and not agent:
+    # P1-2 FIX: --changed-only silently implies --compact; inform only on TTY.
+    # PowerShell 5.1 interprets any stderr write (even with exit 0) as NativeCommandError.
+    # Gate on isatty() so pipeline consumers never see informational noise on stderr.
+    import sys as _sys_tty
+    if changed_only and not compact and not agent and _sys_tty.stderr.isatty():
         typer.echo(
             "[info] --changed-only implies --compact (bounding output to changed files).",
             err=True,
@@ -2162,6 +2196,12 @@ def prepare_context_cmd(
         )
         raise typer.Exit(code=1)
 
+    # Pro gate: generate-tests and delta require an active Pro license.
+    _PRO_TASKS: frozenset[str] = frozenset({"generate-tests", "delta"})
+    if task in _PRO_TASKS:
+        from sourcecode.license import require_pro as _require_pro
+        _require_pro(task)
+
     # Validate --format: only "json" and "github-comment" are valid for prepare-context.
     # "yaml" is intentionally NOT supported here (use main command for yaml output).
     # Invalid values must error loudly — silently falling through to JSON is a lie.
@@ -2184,7 +2224,11 @@ def prepare_context_cmd(
 
     target = path.resolve()
     if not target.exists() or not target.is_dir():
-        typer.echo(f"Error: '{target}' is not a valid directory.", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+        )
         raise typer.Exit(code=1)
 
     if dry_run:
@@ -2215,7 +2259,49 @@ def prepare_context_cmd(
             _sys.stderr.flush()
     _t0 = _time.perf_counter()
     try:
-        output = builder.build(task, since=since, symptom=symptom, fast=fast, include_config=include_config, all_gaps=all_gaps)
+        # H-02: apply timeout for generate-tests — large repos can stall indefinitely.
+        # Mirrors SOURCECODE_TESTS_TIMEOUT_MS used by the MCP generate_tests_context tool.
+        if task == "generate-tests" and not fast:
+            import concurrent.futures as _cf
+            import os as _os_gt
+            _timeout_ms = int(_os_gt.environ.get("SOURCECODE_TESTS_TIMEOUT_MS", "30000"))
+            _timeout_s = _timeout_ms / 1000.0
+            _ex = _cf.ThreadPoolExecutor(max_workers=1)
+            _fut = _ex.submit(
+                builder.build, task,
+                since=since, symptom=symptom, fast=fast,
+                include_config=include_config, all_gaps=all_gaps,
+            )
+            _done_set, _nd_set = _cf.wait([_fut], timeout=_timeout_s)
+            _ex.shutdown(wait=False)
+            if _nd_set:
+                import sys as _sys_gt
+                if _sys_gt.stderr.isatty():
+                    _sys_gt.stderr.write(
+                        f"[generate-tests] timeout after {_timeout_ms}ms — returning partial result\n"
+                    )
+                    _sys_gt.stderr.flush()
+                from sourcecode.prepare_context import TaskOutput as _TO
+                output = _TO(
+                    task=task,
+                    goal=TASKS[task].goal,
+                    project_summary=None,
+                    architecture_summary=None,
+                    relevant_files=[],
+                    suspected_areas=[],
+                    improvement_opportunities=[],
+                    test_gaps=[],
+                    key_dependencies=[],
+                    code_notes_summary=None,
+                    limitations=[f"generate-tests timed out after {_timeout_ms}ms"],
+                    truncated=True,
+                    truncated_reason=f"timeout_{_timeout_ms}ms",
+                    confidence="low",
+                )
+            else:
+                output = _fut.result()
+        else:
+            output = builder.build(task, since=since, symptom=symptom, fast=fast, include_config=include_config, all_gaps=all_gaps)
     finally:
         _progress.finish()
     _t_total = (_time.perf_counter() - _t0) * 1000
@@ -2316,6 +2402,13 @@ def prepare_context_cmd(
         out["improvement_opportunities"] = output.improvement_opportunities
     if _task_include("test_gaps") and output.test_gaps:
         out["test_gaps"] = output.test_gaps
+    # P0-2: fast-mode truncation transparency — always emit when truncated, even if test_gaps is []
+    # Use `is True` (strict) so MagicMock objects in tests don't trigger this branch.
+    if getattr(output, "truncated", False) is True:
+        out["truncated"] = True
+        _tr = getattr(output, "truncated_reason", None)
+        if isinstance(_tr, str) and _tr:
+            out["truncated_reason"] = _tr
     if _task_include("code_notes_summary") and output.code_notes_summary:
         out["code_notes_summary"] = output.code_notes_summary
     if _task_include("changed_files") and output.changed_files:
@@ -2518,6 +2611,19 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
+    # H-01: fast-mode analysis transparency — consumer must not confuse "not analyzed"
+    # with "analyzed and found nothing". Fields that were never computed are absent or null,
+    # not zero. analysis_mode and skipped_analyzers make the omission explicit.
+    if fast:
+        out["analysis_mode"] = "fast"
+        _skipped: list[str] = ["deep_content_scan"]
+        _spec = TASKS.get(task)
+        if _spec and _spec.enable_code_notes:
+            _skipped.append("code_notes")
+        if task == "generate-tests":
+            _skipped.append("test_gap_discovery")
+        out["skipped_analyzers"] = _skipped
+
     # P0-1: Apply output budget per task — safety net for large repos.
     from sourcecode.output_budget import (
         trim_to_budget as _pc_trim,
@@ -2704,7 +2810,11 @@ def repo_ir_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     if files:
@@ -2846,6 +2956,9 @@ def impact_cmd(
       sourcecode impact org.keycloak.services.DefaultKeycloakSession /path/to/keycloak
       sourcecode impact UserService --depth 6 --output impact.json
     """
+    from sourcecode.license import require_pro as _require_pro
+    _require_pro("impact")
+
     import json as _json
     import sys as _sys
 
@@ -2856,7 +2969,11 @@ def impact_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     file_list = find_java_files(root)
@@ -2902,9 +3019,11 @@ def impact_cmd(
             if _copy_to_clipboard(output):
                 typer.echo("✓ copied to clipboard", err=True)
 
-    # Non-zero exit when target not found
+    # H-03: resolution=not_found is a valid structured answer, not an infra failure.
+    # Exit 0 so pipelines can parse the JSON without treating it as an error.
+    # Exit 1 is reserved for path-not-found, I/O failures, and real infra errors.
     if result.get("resolution") == "not_found":
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=0)
 
     from sourcecode.mcp_nudge import nudge_mcp_if_needed as _nudge
     _nudge()
@@ -2959,7 +3078,11 @@ def endpoints_cmd(
 
     target = path.resolve()
     if not target.exists() or not target.is_dir():
-        typer.echo(f"Error: '{target}' is not a valid directory.", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{target}' is not a valid directory.",
+            path=str(target),
+        )
         raise typer.Exit(code=1)
 
     data = _extract_java_endpoints(target)
@@ -3075,7 +3198,10 @@ def review_pr_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] PR review: blast radius, risk ranking, execution paths, security/txn impact.
+    """[Pro*] PR review: blast radius, risk ranking, execution paths, security/txn impact.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "What does this PR break and how risky is it?"
@@ -3135,7 +3261,10 @@ def fix_bug_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] Bug triage: risk-ranked files, suspected areas, related annotations.
+    """[Pro*] Bug triage: risk-ranked files, suspected areas, related annotations.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "Where in this codebase should I look to fix this symptom?"
@@ -3187,7 +3316,10 @@ def modernize_cmd(
         help="Copy output to clipboard after a successful run.",
     ),
 ) -> None:
-    """[Pro] Modernization planning: coupling, dead zones, risky modules, refactor candidates.
+    """[Pro*] Modernization planning: coupling, dead zones, risky modules, refactor candidates.
+
+    Note: [Pro*] label is reserved for a future licensing gate. This command currently
+    runs without authentication. Behavior may change in a future version.
 
     \b
     Answers: "Where should I refactor first, and what's safest to touch?"
@@ -3211,6 +3343,9 @@ def modernize_cmd(
       sourcecode onboard .         — Architecture overview first
       sourcecode impact <target>   — Verify impact before touching a hotspot
     """
+    from sourcecode.license import require_pro as _require_pro
+    _require_pro("modernize")
+
     import json as _json
     import sys as _sys
     from sourcecode.repository_ir import build_repo_ir, find_java_files, apply_ir_size_limits
@@ -3218,7 +3353,11 @@ def modernize_cmd(
 
     root = path.resolve()
     if not root.is_dir():
-        typer.echo(f"Error: {root} is not a directory", err=True)
+        _emit_error_json(
+            "invalid_path",
+            f"'{root}' is not a valid directory.",
+            path=str(root),
+        )
         raise typer.Exit(1)
 
     file_list = find_java_files(root)
@@ -3379,6 +3518,24 @@ def modernize_cmd(
 
 # ── version ───────────────────────────────────────────────────────────────────
 
+@app.command("activate")
+def activate_cmd(
+    license_key: str = typer.Argument(..., help="Your Pro license key"),
+) -> None:
+    """Activate a Pro license key.
+
+    \b
+    Validates the key against the license server and writes
+    ~/.sourcecode/license.json.
+
+    \b
+    Examples:
+      sourcecode activate SC-XXXX-XXXX-XXXX
+    """
+    from sourcecode.license import activate_license as _activate
+    _activate(license_key)
+
+
 @app.command("version")
 def version_cmd() -> None:
     """Show version and exit."""
@@ -3432,6 +3589,9 @@ def mcp_serve() -> None:
         }
       }
     """
+    from sourcecode.license import require_pro as _require_pro
+    _require_pro("mcp serve")
+
     import logging
     import sys as _sys
 
@@ -3443,6 +3603,24 @@ def mcp_serve() -> None:
     from sourcecode.mcp.server import mcp as _mcp
 
     log = logging.getLogger(__name__)
+
+    # P0-1: Strip UTF-8 BOM from stdin.buffer before the MCP server reads it.
+    # PowerShell 5.1 on Windows writes \xEF\xBB\xBF at the start of stdin,
+    # which breaks JSON parsing at line 1 column 1.
+    # peek(3) loads bytes into BufferedReader's internal buffer without consuming;
+    # read(3) discards only if the prefix is the UTF-8 BOM sequence.
+    # No-op on Linux/macOS/Git Bash where stdin never starts with a BOM.
+    # Guard: CliRunner / test stubs replace sys.stdin with StringIO (no .buffer).
+    try:
+        _stdin_buf = getattr(_sys.stdin, "buffer", None)
+        if _stdin_buf is not None and hasattr(_stdin_buf, "peek"):
+            _bom_prefix = _stdin_buf.peek(3)[:3]
+            if _bom_prefix == b"\xef\xbb\xbf":
+                _stdin_buf.read(3)
+                log.info("sourcecode-mcp stripped UTF-8 BOM from stdin (PowerShell 5.1 workaround)")
+    except Exception:
+        pass  # Never abort server startup over BOM detection
+
     log.info("sourcecode-mcp starting (stdio transport)")
     try:
         _mcp.run()

sourcecode-1.31.31/src/sourcecode/license.py

@@ -0,0 +1,166 @@
+"""License activation and enforcement for the sourcecode CLI.
+
+Flow:
+  1. Module imported → _init() loads ~/.sourcecode/license.json (if present)
+  2. is_pro set globally (True when plan == "pro")
+  3. Pro commands call require_pro(feature_name) at entry — exits 1 if not Pro
+  4. `sourcecode activate <key>` calls activate_license(key) — validates via
+     Supabase REST, writes ~/.sourcecode/license.json, exits 0 on success
+
+Supabase credentials:
+  SOURCECODE_SUPABASE_URL      — project REST endpoint
+  SOURCECODE_SUPABASE_ANON_KEY — public anon key (not a secret)
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Supabase endpoint config — override via env vars
+# ---------------------------------------------------------------------------
+_SUPABASE_URL: str = os.environ.get(
+    "SOURCECODE_SUPABASE_URL",
+    "https://YOUR_PROJECT.supabase.co",
+)
+_SUPABASE_ANON_KEY: str = os.environ.get(
+    "SOURCECODE_SUPABASE_ANON_KEY",
+    "",
+)
+
+_LICENSE_DIR: Path = Path.home() / ".sourcecode"
+_LICENSE_FILE: Path = _LICENSE_DIR / "license.json"
+
+# ---------------------------------------------------------------------------
+# Global license state — loaded once at import time
+# ---------------------------------------------------------------------------
+_license_data: Optional[dict] = None
+is_pro: bool = False
+
+
+def _load_license_file() -> Optional[dict]:
+    """Read ~/.sourcecode/license.json. Returns parsed dict or None."""
+    try:
+        if _LICENSE_FILE.exists():
+            raw = _LICENSE_FILE.read_text(encoding="utf-8")
+            return json.loads(raw)
+    except Exception:
+        pass
+    return None
+
+
+def _init() -> None:
+    global _license_data, is_pro
+    _license_data = _load_license_file()
+    is_pro = (
+        _license_data is not None
+        and _license_data.get("plan") == "pro"
+    )
+
+
+_init()
+
+
+# ---------------------------------------------------------------------------
+# Enforcement
+# ---------------------------------------------------------------------------
+
+def require_pro(feature_name: str) -> None:
+    """Exit with structured JSON error when not Pro.
+
+    Call at the very top of every Pro-gated command, before any work.
+
+    Example:
+        from sourcecode.license import require_pro
+        require_pro("impact")
+    """
+    if not is_pro:
+        payload = {
+            "error": "pro_required",
+            "feature": feature_name,
+            "message": "Run sourcecode activate <license_key>",
+        }
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+        sys.stdout.flush()
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Activation
+# ---------------------------------------------------------------------------
+
+def activate_license(license_key: str) -> None:
+    """Validate license_key via Supabase, write ~/.sourcecode/license.json.
+
+    Outputs JSON to stdout; exits 0 on success, 1 on any failure.
+    Never raises — all error paths emit JSON and call sys.exit(1).
+    """
+    import urllib.error
+    import urllib.request
+
+    # Bail early when Supabase isn't configured yet
+    if not _SUPABASE_ANON_KEY or _SUPABASE_URL == "https://YOUR_PROJECT.supabase.co":
+        _fail("configuration_error", "SOURCECODE_SUPABASE_URL / SOURCECODE_SUPABASE_ANON_KEY not configured.")
+
+    url = (
+        f"{_SUPABASE_URL}/rest/v1/users"
+        f"?license_key=eq.{license_key}"
+        f"&select=license_key,plan,email"
+    )
+    req = urllib.request.Request(url)
+    req.add_header("apikey", _SUPABASE_ANON_KEY)
+    req.add_header("Authorization", f"Bearer {_SUPABASE_ANON_KEY}")
+    req.add_header("Accept", "application/json")
+
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            body = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        _fail("network_error", f"Supabase returned HTTP {exc.code}")
+    except Exception as exc:
+        _fail("network_error", str(exc))
+
+    try:
+        rows = json.loads(body)
+    except Exception:
+        _fail("network_error", "Invalid JSON response from Supabase")
+
+    if not rows:
+        _fail("invalid_license", "License key not found")
+
+    user = rows[0]
+    if user.get("plan") != "pro":
+        _fail("not_pro", "This license is not Pro")
+
+    # Write license file
+    _LICENSE_DIR.mkdir(parents=True, exist_ok=True)
+    data = {
+        "license_key": license_key,
+        "plan": "pro",
+        "email": user.get("email", ""),
+        "activated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _LICENSE_FILE.write_text(
+        json.dumps(data, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+
+    result = {"status": "activated", "plan": "pro"}
+    sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+# ---------------------------------------------------------------------------
+# Internal helper
+# ---------------------------------------------------------------------------
+
+def _fail(error: str, message: str) -> None:
+    """Emit JSON error to stdout and exit 1. Never returns."""
+    payload = {"error": error, "message": message}
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+    sys.exit(1)