sourcecode 5.9.30__tar.gz → 5.9.31__tar.gz

{sourcecode-5.9.30 → sourcecode-5.9.31}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [5.9.31] — 2026-09-12
+
+*Patch release correcting MCP/CLI telemetry outcomes and the telemetry schema.*
+
+### Fixed
+
+- Successful Click exits no longer appear as failed `execution_completed` events.
+  Nonzero exits and unhandled exceptions retain `success=false` and emit only
+  the exception class as `error_kind`.
+- The telemetry schema now declares the MCP `tool` column used by the collector.
+
 ## [5.9.30] — 2026-09-02
 
 *A full pass over the open queue from the two 5.9.29 field audits. Nine rows

{sourcecode-5.9.30 → sourcecode-5.9.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 5.9.30
+Version: 5.9.31
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 Project-URL: Homepage, https://github.com/HarounDominique/sourcecode
 Project-URL: Repository, https://github.com/HarounDominique/sourcecode
@@ -59,7 +59,7 @@ Description-Content-Type: text/markdown
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.30-blue)
+![Version](https://img.shields.io/badge/version-5.9.31-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -290,7 +290,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.30 — and, on a build that has aged,
+ask version                    # ask 5.9.31 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.30 → sourcecode-5.9.31}/README.md

@@ -10,7 +10,7 @@
 > question. All analysis is local and deterministic; see [Privacy](#configuration--privacy)
 > before inspecting a repository whose telemetry policy you need to control.
 
-![Version](https://img.shields.io/badge/version-5.9.30-blue)
+![Version](https://img.shields.io/badge/version-5.9.31-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 Copyright (c) 2026 Dominique Haroun. All rights reserved. ASK Engine 5.7.0 and
@@ -241,7 +241,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 5.9.30 — and, on a build that has aged,
+ask version                    # ask 5.9.31 — and, on a build that has aged,
                                # how many releases have probably shipped since
 ```
 

{sourcecode-5.9.30 → sourcecode-5.9.31}/docs/USER_GUIDE.md

@@ -279,7 +279,7 @@ pipx install sourcecode   # isolated install, no venv needed
 
 # Verify
 ask version
-# ask 5.9.30
+# ask 5.9.31
 ```
 
 Requires Python 3.9+.

sourcecode-5.9.31/docs/investigations/2026-09-11-ask-mcp-telemetry.md

@@ -0,0 +1,117 @@
+# Investigación: resultados ASK por MCP del 11 de septiembre de 2026
+
+Investigado el 12 de septiembre de 2026. Código histórico: release 5.8.20,
+commit `0370f9c`. Contraste: checkout 5.9.30. Datos del incidente: las ocho filas
+aportadas por el usuario; no se ha accedido al despliegue ni a la base de datos.
+
+## Conclusión
+
+**Los cuatro `execution_completed success=false` no demuestran cuatro fallos.**
+La instrumentación confunde la salida normal de Click con una excepción de error.
+El defecto existe tanto en 5.8.20 como en el checkout 5.9.30 anterior a esta corrección.
+
+La lectura más compatible con el código es actividad MCP con tres resultados de
+herramienta marcados como correctos y uno como error, junto con cuatro ejecuciones
+CLI internas cuya medición de éxito está dañada. La atribución de las filas
+`command_executed / mcp` a herramientas requiere confirmar qué colector estaba
+desplegado: el colector antiguo transforma exactamente así los eventos MCP.
+No es posible emparejar inequívocamente cada fila interna con una herramienta.
+
+El final de la tabla no prueba abandono, desinstalación ni un cierre del servidor.
+Una instalación anónima tampoco identifica por sí sola a una persona.
+
+## Evidencia confirmada
+
+1. En `src/sourcecode/cli.py`, `_get_command_with_preprocessing()._cmd_main()`
+   captura `BaseException`, pone `success=False` y vuelve a lanzar la excepción.
+   Click termina las invocaciones correctas en modo standalone con `SystemExit(0)`.
+   `CliRunner` recoge esa salida como código 0, pero el evento ya se emitió como fallo.
+   Esto también ocurre dentro de `src/sourcecode/mcp/runner.py`.
+2. `cmd=analyze` es una familia amplia. El wrapper también usa ese valor para
+   `prepare-context`, `version` y otros comandos. El campo `command` aporta la
+   distinción si el colector lo conserva; no estaba incluido en la tabla recibida.
+3. En 5.8.20, `get_delta` invoca `prepare-context delta … --since REF`, mientras que
+   `get_compact_context(git_context=True)` invoca `… --compact --git-context`.
+   Por tanto, los flags encajan con llamadas MCP documentadas, sin indicar por sí
+   solos que el agente inventase argumentos o usase mal la CLI.
+4. El hook de MCP emite `mcp_tool_invoked`, con `cmd=mcp` y el resultado de la
+   herramienta. El cliente 5.8.20 permite ese evento. El colector antiguo
+   (`41c3e1a`) no lo permite y aplica `event: pick(p.event, EVENTS, "command_executed")`.
+   Conserva `cmd` y `success`, pero pierde `tool` y `command`.
+   El colector del repositorio actualizado (`44834aa`) sí permite ese evento.
+   **Colector desplegado desactualizado: inferencia fuerte, no comprobación remota.**
+5. El wrapper CLI no enviaba `error_kind` ni el número de archivos.
+   Así se explican `error_kind=null` y `repo_size=unknown` incluso con un análisis
+   correcto; no son evidencias de que el repositorio no llegase a abrirse.
+6. Los eventos se envían en hilos independientes, con timeout y sin reintentos.
+   `received_at` es recepción, no inicio de ejecución. Puede haber pérdidas y
+   cambios de orden; no permite reconstruir con certeza la secuencia de llamadas.
+
+## Reproducción
+
+Sobre el código histórico, un repositorio temporal con dos commits y el recorrido
+real `FastMCP Tool.run → herramienta → CliRunner` reproduce:
+
+| Llamada | Resultado visible al agente | Evento CLI | Evento MCP |
+|---|---|---|---|
+| `get_delta(since="HEAD~1")` | Correcto, `success=true` | `success=false`, flags `--since` | `success=true` |
+| `get_compact_context(git_context=True)` | Correcto, `success=true` | `success=false`, flags `--compact --git-context` | `success=true` |
+| `get_delta(since="MISSING_REF")` | Error, `isError=true`, `EXECUTION_FAILED` | `success=false`, flags `--since` | `success=false` |
+
+La reproducción local usa macOS y Python 3.14; el incidente es Linux/Python 3.12.
+Confirma el defecto de instrumentación compartido, pero no reproduce el entorno,
+repositorio ni argumentos exactos de aquella instalación.
+
+## Qué pudo causar el fallo real
+
+Una referencia Git no disponible reproduce un error real con los mismos flags.
+También es relevante la selección automática de `get_delta`: prueba `origin/main`,
+después `origin/master`, y finalmente usa `HEAD~1`. Ese último ref no existe en un
+repositorio con un solo commit o un clon superficial sin padre disponible. Una
+ruta errónea, permisos o una excepción interna son otras posibilidades.
+
+No se conserva el valor de `--since`, el repositorio ni stderr por diseño. No hay
+base para elegir una de esas causas como explicación del caso concreto. Tampoco
+hay evidencia específica de incompatibilidad con Python 3.12 o Linux.
+
+## Correcciones locales y comprobación operativa pendiente
+
+- El wrapper distingue `SystemExit(0/None)` de salidas fallidas y conserva intacto
+  el comportamiento de Click. Para fallos emite solo la clase de excepción.
+  `SystemExit` no permite conocer por sí solo el motivo de un error CLI manejado.
+- Cinco pruebas de regresión cubren salida correcta, ayuda, opción inválida,
+  excepción sin datos privados y resultado correcto por el runner MCP. Las cinco
+  fallaban antes de la corrección.
+- El SQL declara y migra de forma idempotente `tool`: el colector ya intentaba
+  insertarlo, pero el esquema versionado no lo declaraba. Sin esa columna, desplegar
+  ese colector puede impedir inserciones. No se conoce el esquema remoto real.
+- Estos cambios son locales: no se ha publicado una versión ni desplegado SQL o
+  función. Las instalaciones 5.8.20 seguirán enviando el indicador defectuoso.
+
+Antes de usar métricas de éxito, comprobar la revisión de la función desplegada y
+las columnas existentes; migrar el esquema antes de desplegar el colector actualizado.
+No reinterpretar masivamente los falsos negativos históricos como éxitos: contienen
+tanto ejecuciones correctas como errores reales. No sumar eventos CLI y MCP como
+acciones independientes.
+
+Consulta de solo lectura para ampliar las filas sin exigir que las columnas
+`command` y `tool` ya existan:
+
+```sql
+select received_at, client_ts, event, cmd,
+       to_jsonb(t)->>'command' as command,
+       to_jsonb(t)->>'tool' as tool,
+       flags, success, error_kind, duration, v
+from public.telemetry_events as t
+where received_at >= timestamptz '2026-09-11 00:00:00+00'
+  and received_at <  timestamptz '2026-09-12 00:00:00+00'
+  and session = '03ff2232'
+  and install_id = '62d2d283-7369-476f-8828-3cd9f57169b3'
+order by received_at;
+```
+
+Para versiones publicadas con la corrección, contar éxito mediante
+`event='execution_completed' AND success IS TRUE` para invocaciones CLI, o
+`event='mcp_tool_invoked' AND success IS TRUE` para herramientas MCP, manteniendo
+separados ambos indicadores. Hasta confirmar la versión desplegada del colector,
+`command_executed / mcp` debe tratarse como señal heredada, no como arranques del servidor.

{sourcecode-5.9.30 → sourcecode-5.9.31}/docs/privacy.md

@@ -65,6 +65,19 @@ When telemetry is enabled, these fields are sent per command invocation:
 | `tool` | `get_compact_context` | MCP tool name only, on `mcp_tool_invoked` events (see below) |
 | `session` | `a3f2c1b0` | 8-char random hex, ephemeral, never persisted |
 
+### Interpreting execution outcomes
+
+`execution_completed` means the CLI invocation ended. It is not itself a success
+event. Successful process exits (`SystemExit(0)` or `SystemExit(None)`) must record
+`success=true`; nonzero exits and unhandled exceptions record `success=false` and
+only the exception class in `error_kind`, never its message.
+
+Historical warning: ASK 5.8.20, and the unpatched 5.9.30 source, recorded successful
+Click exits as failures. Those `execution_completed.success=false` rows cannot be
+used to calculate a failure rate or retrospectively relabelled as successes.
+MCP tool outcomes are a separate event stream; do not count both streams as
+independent user actions. See [the September 11 investigation](investigations/2026-09-11-ask-mcp-telemetry.md).
+
 ### MCP tool invocations
 
 When ASK Engine runs as an MCP server (`ask mcp serve`), each tool call records one

{sourcecode-5.9.30 → sourcecode-5.9.31}/pyproject.toml

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

{sourcecode-5.9.30 → sourcecode-5.9.31}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "5.9.30"
+__version__ = "5.9.31"

{sourcecode-5.9.30 → sourcecode-5.9.31}/src/sourcecode/cli.py

@@ -4897,10 +4897,19 @@ def _get_command_with_preprocessing(typer_instance: Any) -> Any:
         started = time.monotonic()
         command = _telemetry_command(args)
         success = True
+        error_kind = None
         try:
             return _orig_cmd_main(args=args, **kwargs)
-        except BaseException:
+        except SystemExit as exc:
+            # Click uses SystemExit(0) even after successful CLI/MCP calls.
+            # Preserve its exit while recording the outcome, not the exception.
+            success = exc.code is None or exc.code == 0
+            if not success:
+                error_kind = type(exc).__name__
+            raise
+        except BaseException as exc:
             success = False
+            error_kind = type(exc).__name__
             raise
         finally:
             try:
@@ -4912,6 +4921,7 @@ def _get_command_with_preprocessing(typer_instance: Any) -> Any:
                     flags=_telemetry_flags(args),
                     duration_s=time.monotonic() - started,
                     success=success,
+                    error_kind=error_kind,
                 )
             except Exception:
                 pass

{sourcecode-5.9.30 → sourcecode-5.9.31}/src/sourcecode/release_info.py

@@ -27,7 +27,7 @@ from typing import Any, Optional
 #: The date `__version__` was released, from that version's CHANGELOG entry.
 #: `tests/test_release_info.py` fails the build if the two disagree, so this is
 #: a copy of a fact rather than a second authority for it.
-RELEASE_DATE = "2026-09-02"
+RELEASE_DATE = "2026-09-12"
 
 #: Releases per day, measured over the latest 30 CHANGELOG releases (the same
 #: computation the test re-runs). The nine-day interval before 5.9.0 lowers

{sourcecode-5.9.30 → sourcecode-5.9.31}/supabase/sql/telemetry_events.sql

@@ -18,6 +18,7 @@ create table if not exists public.telemetry_events (
   duration    text,            -- <1s | <5s | <15s | <60s | 60s+ | unknown
   success     boolean,
   error_kind  text,            -- exception class name only
+  tool        text,            -- MCP tool identifier only; never arguments
   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
@@ -26,6 +27,7 @@ create table if not exists public.telemetry_events (
 -- 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;
 alter table public.telemetry_events add column if not exists command text;
+alter table public.telemetry_events add column if not exists tool text;
 
 -- Common query axes: funnel by event, adoption by version, time series,
 -- and unique-install / conversion / retention by install_id.