stata-code 0.6.2__tar.gz → 0.6.4__tar.gz

{stata_code-0.6.2 → stata_code-0.6.4}/CHANGELOG.md

@@ -6,6 +6,192 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## Unreleased
 
+## 0.6.4 — 2026-05-21
+
+### Added
+
+- **Claude Code plugin marketplace manifest.** `.claude-plugin/marketplace.json`
+  + `.claude-plugin/plugin.json` expose the repo as a single-plugin
+  marketplace, so users can install everything (MCP server config + agent
+  skill) with `claude plugin marketplace add brycewang-stanford/stata-code`
+  followed by `claude plugin install stata-code`.
+- **`stata-code` agent skill.** `skills/stata-code/SKILL.md` teaches Claude
+  the v1.0 RunResult schema, the 15 MCP tools, the token-economy defaults,
+  the 32-kind error taxonomy, and the diagnose-only vs. fix-and-rerun
+  workflows. The plugin manifest auto-installs it alongside the MCP
+  server.
+- **VS Code install-hint probe.** On activation the extension now resolves
+  the configured `stata-code-mcp` candidate list against `PATH` and any
+  workspace `.venv` / `venv`; if nothing matches, a one-time notification
+  offers to copy the `pip install "stata-code[mcp]"` command or open the
+  install docs. "Don't show again" pins the dismissal to the installed
+  extension version. Backed by a new pure module `serverProbe.ts` with
+  unit tests.
+- **README multi-client section.** Cursor, Claude Desktop, Cline,
+  Continue, Windsurf, and Antigravity now have their config-file paths
+  spelled out next to the shared `stata-code-mcp` JSON snippet, plus
+  guidance for project-venv absolute paths and `uvx` setups.
+- **README cell + section reference.** Documents that the VS Code
+  extension recognizes both `* %%` Jupyter-style cell markers and
+  `**#` … `**######` six-level section headings in `.do` files, and how
+  each interacts with the code-lens and Outline view.
+- **Open VSX publish step.** `vscode-release.yml` now publishes the VSIX
+  to Open VSX on every `vscode-v*` tag. The step is gated on
+  `OVSX_PAT` being set at runtime and runs with `continue-on-error: true`,
+  so a missing or expired token never blocks the primary VS Code
+  Marketplace publish.
+
+### Fixed
+
+- **Subprocess worker JSON protocol hardening.** Worker processes now keep
+  their private JSON protocol fds separate from real stdin/stdout and
+  redirect the real fd 0/1 pair to `os.devnull` before importing the
+  runner. The parent reader also ignores blank protocol noise while still
+  failing on non-empty non-JSON output. This prevents a pystata/Stata
+  initialization newline from surfacing as
+  `adapter_crash: worker emitted non-JSON: '\n'`.
+
+## 0.6.3 — 2026-05-10
+
+### Added
+
+- **`RefNotFound` exception** — `get_log` / `get_graph` / `get_matrix` now
+  raise a typed `RefNotFound` (subclass of `KeyError`) carrying the bad
+  ref and a stable `kind` token (`unknown_log_ref` / `unknown_graph_ref` /
+  `unknown_matrix_ref`). MCP dispatch maps it to a typed error response
+  without string-parsing.
+- **`NotebookError.kind` / `RunIndexError.kind`** — both classes now
+  expose a `kind` property so callers don't have to slice the message
+  prefix manually.
+- **`SessionPool.list_session_info_detailed`** — partial-failure-aware
+  variant of `list_session_info()` that surfaces per-worker `warnings`
+  alongside the aggregated `sessions` list. The MCP `list_sessions`
+  tool's output schema now includes the optional `warnings` field.
+- **`list_runs.requested_limit`** — echoes the original requested limit
+  when the server clamps it to `_LIMIT_MAX`, so a caller asking for
+  `limit=1000` can distinguish "scan was capped at 500 rows" from "the
+  manifest dir really has more than 500 rows".
+- **Server capabilities resource now includes prompts.** Reading
+  `stata://server/capabilities` returns tools, resource templates, AND
+  prompts in a single document — clients no longer need a follow-up
+  `list_prompts` round-trip just to enumerate the full surface.
+
+### Changed
+
+- **Test hygiene** — a `tests/conftest.py` snapshot/restores `_refs._store`
+  per test and shuts the default subprocess pool down at session end.
+  Closes a class of intermittent cross-test failures caused by ref-store
+  pollution from earlier MCP / pool tests.
+- **Subprocess cancellation race** — `SessionPool.execute()` now
+  re-checks `_cancel_pending` after `_get_or_spawn` so a `request_cancel`
+  that lands during worker spawn fires on the in-flight call instead of
+  the next one.
+- **`stata_info` edition casing is now consistent** — the top-level
+  `edition` field mirrors `stata.edition` (the enum value, e.g. `MP`)
+  verbatim. Previously the pool path lowercased it to `mp` while the
+  in-process path emitted `MP`, so the same payload could disagree with
+  itself.
+- **All MCP tool input schemas now declare `additionalProperties: false`.**
+  Typos like `originPath` (camelCase) or misspelled `log_lin_head` are
+  now rejected up-front with a typed validation error instead of silently
+  producing a wrong run.
+- **`cancel_session` and `reset_session` output schemas split.** Each
+  tool now advertises only the fields it actually returns; the previous
+  shared schema overpromised on one side and underpromised on the other.
+- **`list_resources` caps ref-backed entries at 256.** Long-lived
+  servers no longer return thousands of stale ref resources from
+  forgotten sessions — the most recently used 256 win.
+- **Pystata edition init now preserves the full error trail.** When all
+  three editions (MP / SE / BE) fail, the `PystataNotAvailable` message
+  lists each attempt's error rather than collapsing to the last one.
+
+### Fixed
+
+- **Jupyter kernel `implementation_version`** is now derived from
+  `stata_code.__version__` rather than a separate `0.2.0` literal.
+- **Jupyter kernel mypy `Invalid base class`** error — the dynamic
+  `Kernel if _HAS_IPYKERNEL else object` base class confused mypy.
+  Hidden behind a `TYPE_CHECKING` gate now; runtime behavior unchanged.
+- **`do_execute` / `do_inspect` signatures** are now LSP-compatible
+  with the latest `ipykernel.kernelbase.Kernel` (accepts `cell_meta`,
+  `cell_id`, `omit_sections`).
+- **Schema `$id` URL** corrected from `stata_code` to `stata-code`
+  (matches the actual GitHub repository name).
+- **VS Code MCP handshake** version is now read from `package.json`
+  via `resolveJsonModule`, removing the former fifth sync site.
+  `check_versions.py` still validates the literal form
+  when present, so reverting to a hardcoded string fails CI.
+- **Release tag glob tightened** — `v[0-9]*.[0-9]*.[0-9]*` instead of
+  `v[0-9]*` so stray tags without semver-style dot separators no longer
+  trigger the release workflow.
+- **Release pipeline now gates on ruff** so a direct push to `main`
+  cannot ship un-linted code.
+- **Mypy CI now covers `stata_code/mcp` and `stata_code/kernel`** in
+  addition to `core`, with the optional `mcp` / `kernel` extras
+  installed so `Server`, `Tool`, and `Kernel` symbols resolve.
+- **`COMMON_STATA_COMMANDS` deduplicated** — dropped the short forms
+  (`cap` / `qui` / `noi` / `mat` / `di`) that were producing
+  near-duplicate "did you mean" hits from `difflib`. The long forms
+  cover the same fuzzy-match neighbourhood.
+- **`_unique_dir` / `_unique_file`** fall back to a UUID suffix after
+  998 collisions instead of raising `FileExistsError`. The original
+  behaviour blocked the run on conditions that almost always indicate a
+  filesystem issue rather than a name clash.
+- **Dead code removed** — `_info_payload` (orphaned helper) in the MCP
+  server, `_truncate` in `notebook.py`, and the unused `index` / `source`
+  parameters on `_ensure_native_id`.
+
+## 0.6.2 — 2026-05-08
+
+Aggregated from the prior `Unreleased` section; covers 0.6.1 and 0.6.2.
+
+### Added
+
+- **Release version guard.** `scripts/check_versions.py` and the CI /
+  release workflows now verify that the Python package, MCP server, VS Code
+  package, VS Code MCP handshake, and release tag all use the same version.
+- **VS Code MCP launch tests.** The extension's server-launch candidate
+  builder is now a pure tested module covering local `.venv` / `venv`
+  discovery, configured Python interpreters, inline command parsing, and
+  environment construction.
+- **VS Code packaging smoke test.** The default CI now builds a VSIX artifact
+  with the same local `vsce` package command used by release packaging, so
+  package-manifest and `.vscodeignore` mistakes fail before release day.
+- **VS Code extension bundling.** The extension now bundles its TypeScript
+  entrypoint with `esbuild`, excluding `node_modules` and test/build support
+  files from the shipped VSIX.
+- **VS Code bundled dependency notices.** `THIRD_PARTY_NOTICES.md` now lists
+  the npm packages included in the bundled extension output and their license
+  terms.
+- **PyPI publish verification.** The release workflow now polls PyPI's
+  per-version JSON endpoint after the official publish job, so trusted
+  publisher failures surface as a failed release run instead of being hidden
+  by `continue-on-error`.
+
+### Changed
+
+- **Package-level Python API is subprocess-backed.** `stata_code.run()`,
+  `execute()`, and `is_available()` now go through the same worker pool as
+  the MCP server, preserving hard timeout behavior and avoiding caller-process
+  stdout redirection by `pystata`.
+- **CI treats core type errors as blocking.** `mypy stata_code/core` is now a
+  hard failure, and the default test workflow also compiles and tests the VS
+  Code extension.
+- **VS Code npm installs are locked.** The extension now ships
+  `package-lock.json`, and CI / release workflows use `npm ci` for reproducible
+  dependency installs.
+- **VS Code bundle target matches the extension host floor.** The esbuild
+  target is `node18`, keeping the published bundle aligned with the current
+  `engines.vscode` lower bound.
+- **Python 3.13 is in the support matrix.** CI now runs the no-Stata test
+  suite on Python 3.13, and package metadata advertises the 3.13 classifier.
+
+### Fixed
+
+- **Cancelled in-flight runs report incomplete logs.** If a live worker is
+  killed by `cancel_session`, the synthetic cancelled result now marks
+  `log.complete=false`, matching timeout and adapter-crash behavior.
+
 ## [0.6.0] — 2026-05-08
 
 ### Added

{stata_code-0.6.2 → stata_code-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.6.2
+Version: 0.6.4
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
@@ -83,7 +84,7 @@ Description-Content-Type: text/markdown
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. Current test suite: 310 passing tests across schema, runner, MCP, kernel, notebook, and run-index modules. License: **MIT**.
+**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Two workflows v0.6 explicitly supports for end users:
 
@@ -145,6 +146,10 @@ See [`examples/`](examples/) for end-to-end cookbook entries: basic regression,
 
 ### As a Python Library
 
+The package-level `run()` / `execute()` API uses the same subprocess-backed
+runner as the MCP server, so long calls honor `timeout_ms` and `pystata`
+stdout redirection stays isolated from the caller process.
+
 ```python
 from stata_code import run
 
@@ -199,14 +204,34 @@ If you want the repair loop, say so explicitly. Otherwise, treat failed runs as
 If you prefer not to `pip install stata-code` globally, run it ephemerally through [`uv`](https://github.com/astral-sh/uv):
 
 ```bash
-claude mcp add stata-code --scope user -- uvx --from stata-code stata-code-mcp
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
 ```
 
 `uvx` will resolve and cache `stata-code` on first launch. Note: `pystata` is **not** on PyPI, so it still has to be locatable on the host. The runner adds the standard Stata install path (e.g. `/Applications/Stata/utilities/pystata` on macOS) to `sys.path` automatically; if your Stata lives elsewhere, set `PYTHONPATH` in the env block.
 
-#### Manual JSON config (Cursor / Claude Desktop / fallback)
+#### Claude Code via plugin marketplace
+
+This repository also ships a Claude Code plugin manifest (`.claude-plugin/`). Once you've added the marketplace to your Claude Code config, two commands wire up both the MCP server and the agent skill that teaches Claude the v1.0 result schema:
+
+```bash
+claude plugin marketplace add brycewang-stanford/stata-code
+claude plugin install stata-code
+```
+
+The plugin registers the `stata-code` MCP server and installs the [`stata-code` skill](skills/stata-code/SKILL.md) so Claude branches on `error.kind`, calls `get_log(ref)` lazily, and uses the notebook-edit tools without you re-explaining them every session.
+
+#### Other MCP clients (Cursor / Claude Desktop / Cline / Continue / Windsurf / Antigravity)
 
-For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/mcp.json`, Cursor settings, Claude Desktop `claude_desktop_config.json`, etc.):
+Most non-Claude-Code MCP clients accept the same JSON snippet. Drop it into the client's MCP config file:
+
+| Client | Config file |
+| --- | --- |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (user) or `<workspace>/.cursor/mcp.json` (project) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline (VS Code) | settings: `cline.mcpServers` |
+| Continue | `~/.continue/config.json` under `experimental.modelContextProtocolServers` |
+| Antigravity / generic | `~/.claude/mcp.json` or whatever the client documents |
 
 ```json
 {
@@ -218,12 +243,26 @@ For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/m
 }
 ```
 
-Or run it as a module if the binary is not on `PATH`:
+Or, when the binary is not on `PATH`, run it as a module:
 
 ```bash
 python -m stata_code.mcp
 ```
 
+When `stata-code-mcp` lives inside a project virtualenv (recommended for reproducibility), point the client at the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "stata-code": {
+      "command": "/abs/path/to/.venv/bin/stata-code-mcp"
+    }
+  }
+}
+```
+
+For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -234,7 +273,7 @@ The MCP server registers 15 tools:
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `list_sessions` | Enumerate live sessions |
-| `cancel_session` | Cooperatively cancel the next `stata_run` for a session |
+| `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
 | `notebook_outline` | Compact per-cell index of a `.ipynb` (cell_id, type, preview) |
 | `notebook_get_cell` | One cell's full source plus a token-economic outputs summary |
@@ -299,7 +338,20 @@ The companion extension is on the Marketplace as [`brycewang-stanford.stata-code
 code --install-extension brycewang-stanford.stata-code-vscode
 ```
 
-Or open the **Extensions** sidebar in VS Code and search `stata-code`.
+Or open the **Extensions** sidebar in VS Code and search `stata-code`. The extension is also available from [Open VSX](https://open-vsx.org/) so Cursor, Windsurf, and other VS Code-compatible editors can install it without going through the Microsoft Marketplace.
+
+On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
+
+#### Cell and section conventions
+
+The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
+
+| Marker | Purpose | Example |
+| --- | --- | --- |
+| `* %% [title]` | Cell boundary. Each marker gets a **▶ Run Cell** code-lens; "Run Cell" submits the lines between this marker and the next one. Compatible with the Jupyter-style cell convention used by `kylebutts/vscode-stata`. | `* %% 02 model fit` |
+| `**# title` … `**###### title` | Section heading, 1–6 levels deep. Each heading gets a **▶ Run Section** code-lens and contributes to the Outline view. "Run Section" submits the heading through the next equal- or higher-level heading, matching the hierarchical execution model from `ZihaoVistonWang.stata-all-in-one`. | `**## DiD specification` |
+
+`program define … end` blocks are also surfaced in the Outline, nested under whichever section contains them.
 
 The extension still requires the MCP extra on your system Python (`pip install "stata-code[mcp]"`), so that `stata-code-mcp` resolves on `PATH` and can import the MCP SDK. Stata 17+ and a valid Stata license are required as for any other frontend.
 
@@ -348,14 +400,15 @@ stata_code/
 │   ├── _refs.py       # LRU ref store for log/graph/matrix payloads
 │   ├── schema.py      # Pydantic v2 models for the v1.0 result schema
 │   ├── errors.py      # rc → ErrorKind mapping + suggestion seeds
-│   └── runner.py      # the one execute(); collects everything via sfi
+│   ├── runner.py      # in-process execute(); collects everything via sfi
+│   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
 │   └── server.py      # MCP server (15 tools)
 └── kernel/
     └── kernel.py      # Jupyter kernel
 ```
 
-`runner.py` is the only place that touches Stata. The Jupyter kernel and MCP server both import from it and only translate results into their own transports.
+`runner.py` is the only place that directly talks to `pystata`. The public Python API and MCP server route calls through `_pool.py`, whose workers call `runner.execute()` in an isolated subprocess; the Jupyter kernel uses the in-process runner for notebook interactivity.
 
 ---
 
@@ -391,7 +444,7 @@ stata_code/
 - MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
-- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
@@ -401,8 +454,8 @@ stata_code/
 ### Next Up
 
 - Console fallback for Stata 11–16, re-implemented against the v1.0 schema
-- Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
-- Extra VS Code polish (esbuild bundle, lighter VSIX, command palette UX)
+- Decide whether to move the Jupyter kernel from the direct in-process runner to the subprocess pool, or keep documenting the current interactivity-first tradeoff
+- Extra VS Code polish: extension-host end-to-end tests, first-run diagnostics, and command palette UX
 - **v1.0** — Stable schema, broader Stata edition coverage
 
 See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
@@ -413,9 +466,9 @@ See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
 
 ```bash
 pip install -e ".[dev,mcp,kernel]"
-pytest                              # full suite (310 tests)
+pytest                              # full suite, including Stata tests when Stata is available
 pytest -m "not stata_required"      # CI subset; no Stata needed
-pytest -m "stata_required" -v       # Stata-only integration tests
+pytest -m "stata_required" -v       # real-Stata integration tests only
 ```
 
 The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.

{stata_code-0.6.2 → stata_code-0.6.4}/PUBLISHING.md

@@ -1,8 +1,9 @@
-# Publishing `stata-code` to PyPI
+# Publishing `stata-code` to TestPyPI and PyPI
 
-This project publishes to PyPI via **GitHub Actions Trusted Publishing** (OIDC).
-There are **no API tokens** stored in GitHub repository secrets — PyPI verifies
-the OIDC identity of the workflow run instead.
+This project publishes to TestPyPI and PyPI via **GitHub Actions Trusted
+Publishing** (OIDC). There are **no API tokens** stored in GitHub repository
+secrets — each package index verifies the OIDC identity of the workflow run
+instead.
 
 The release pipeline is in [`.github/workflows/release.yml`](.github/workflows/release.yml).
 
@@ -28,25 +29,34 @@ Trusted Publishing has two modes:
 
 Either path lands you in the same place after the first run.
 
-### 2. Configure the Trusted Publisher on PyPI
+### 2. Configure the Trusted Publishers
 
-On the PyPI publishing page, add a GitHub publisher with these values:
+PyPI and TestPyPI are separate package indexes, so configure both publisher
+records independently:
 
-| Field | Value |
-| --- | --- |
-| Owner | `brycewang-stanford` |
-| Repository name | `stata-code` |
-| Workflow filename | `release.yml` |
-| Environment name | `pypi` |
+| Site | Manage URL | Environment |
+| --- | --- | --- |
+| PyPI | <https://pypi.org/manage/project/stata-code/settings/publishing/> | `pypi` |
+| TestPyPI | <https://test.pypi.org/manage/project/stata-code/settings/publishing/> | `testpypi` |
+
+Use the same GitHub publisher values on both sites:
+
+- Owner: `brycewang-stanford`
+- Repository name: `stata-code`
+- Workflow filename: `release.yml`
+- Environment name: `pypi` or `testpypi`, matching the site above
 
 The environment name is **required** and must match the `environment.name`
-declared in `release.yml` (`pypi`). PyPI uses it as an extra constraint:
+declared in `release.yml`. PyPI / TestPyPI use it as an extra constraint:
 even a malicious workflow change in the repo cannot publish unless it runs
-under that exact environment.
+under the exact environment configured for that index.
+
+### 3. Create the GitHub Environments
 
-### 3. Create the GitHub Environment
+In the GitHub repo: **Settings → Environments → New environment**. Create both:
 
-In the GitHub repo: **Settings → Environments → New environment → name `pypi`**.
+- `testpypi`
+- `pypi`
 
 Recommended hardening (all in the environment settings page):
 
@@ -66,25 +76,38 @@ The environment doesn't need any secrets — Trusted Publishing handles auth.
 
 Once the one-time setup above is done, every release is just:
 
-1. **Bump the version** in `pyproject.toml` (`[project] version`).
-2. **Update `CHANGELOG.md`**: move the `[Unreleased]` entries under a new
+1. **Bump the version everywhere**:
+   - `pyproject.toml` → `[project] version`
+   - `stata_code/__init__.py` → `__version__`
+   - `stata_code/mcp/server.py` → `__version__`
+   - `vscode/package.json` → `version`
+   - `vscode/package-lock.json` → root package `version`
+2. **Run the version guard** before tagging:
+   ```bash
+   python scripts/check_versions.py
+   ```
+3. **Update `CHANGELOG.md`**: move the `[Unreleased]` entries under a new
    `## [X.Y.Z] - YYYY-MM-DD` heading, leaving an empty `[Unreleased]` shell
    on top.
-3. **Commit** the bump:
+4. **Commit** the bump:
    ```bash
-   git add pyproject.toml CHANGELOG.md
+   git add pyproject.toml stata_code/__init__.py stata_code/mcp/server.py vscode/package.json vscode/package-lock.json CHANGELOG.md
    git commit -m "release: vX.Y.Z"
    ```
-4. **Tag and push**:
+5. **Tag and push**:
    ```bash
    git tag vX.Y.Z
    git push origin main
    git push origin vX.Y.Z
    ```
-5. Watch the **`release` workflow** under the Actions tab. It will:
+6. Watch the **`release` workflow** under the Actions tab. It will:
    - build the sdist + wheel
    - run `twine check` on the artifacts
+   - publish to TestPyPI under the `testpypi` environment (no token needed)
    - publish to PyPI under the `pypi` environment (no token needed)
+   - poll PyPI's per-version JSON endpoint so a failed trusted-publisher
+     publish marks the workflow run failed even though the publish job itself
+     is `continue-on-error`
    - create a GitHub Release for the tag with the wheel + sdist attached and
      auto-generated release notes
 

{stata_code-0.6.2 → stata_code-0.6.4}/README.md

@@ -45,7 +45,7 @@
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. Current test suite: 310 passing tests across schema, runner, MCP, kernel, notebook, and run-index modules. License: **MIT**.
+**Status: v0.6 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
 Two workflows v0.6 explicitly supports for end users:
 
@@ -107,6 +107,10 @@ See [`examples/`](examples/) for end-to-end cookbook entries: basic regression,
 
 ### As a Python Library
 
+The package-level `run()` / `execute()` API uses the same subprocess-backed
+runner as the MCP server, so long calls honor `timeout_ms` and `pystata`
+stdout redirection stays isolated from the caller process.
+
 ```python
 from stata_code import run
 
@@ -161,14 +165,34 @@ If you want the repair loop, say so explicitly. Otherwise, treat failed runs as
 If you prefer not to `pip install stata-code` globally, run it ephemerally through [`uv`](https://github.com/astral-sh/uv):
 
 ```bash
-claude mcp add stata-code --scope user -- uvx --from stata-code stata-code-mcp
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
 ```
 
 `uvx` will resolve and cache `stata-code` on first launch. Note: `pystata` is **not** on PyPI, so it still has to be locatable on the host. The runner adds the standard Stata install path (e.g. `/Applications/Stata/utilities/pystata` on macOS) to `sys.path` automatically; if your Stata lives elsewhere, set `PYTHONPATH` in the env block.
 
-#### Manual JSON config (Cursor / Claude Desktop / fallback)
+#### Claude Code via plugin marketplace
+
+This repository also ships a Claude Code plugin manifest (`.claude-plugin/`). Once you've added the marketplace to your Claude Code config, two commands wire up both the MCP server and the agent skill that teaches Claude the v1.0 result schema:
+
+```bash
+claude plugin marketplace add brycewang-stanford/stata-code
+claude plugin install stata-code
+```
+
+The plugin registers the `stata-code` MCP server and installs the [`stata-code` skill](skills/stata-code/SKILL.md) so Claude branches on `error.kind`, calls `get_log(ref)` lazily, and uses the notebook-edit tools without you re-explaining them every session.
+
+#### Other MCP clients (Cursor / Claude Desktop / Cline / Continue / Windsurf / Antigravity)
 
-For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/mcp.json`, Cursor settings, Claude Desktop `claude_desktop_config.json`, etc.):
+Most non-Claude-Code MCP clients accept the same JSON snippet. Drop it into the client's MCP config file:
+
+| Client | Config file |
+| --- | --- |
+| Claude Desktop | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` (user) or `<workspace>/.cursor/mcp.json` (project) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline (VS Code) | settings: `cline.mcpServers` |
+| Continue | `~/.continue/config.json` under `experimental.modelContextProtocolServers` |
+| Antigravity / generic | `~/.claude/mcp.json` or whatever the client documents |
 
 ```json
 {
@@ -180,12 +204,26 @@ For clients without a `mcp add` CLI, edit the config file directly (`~/.claude/m
 }
 ```
 
-Or run it as a module if the binary is not on `PATH`:
+Or, when the binary is not on `PATH`, run it as a module:
 
 ```bash
 python -m stata_code.mcp
 ```
 
+When `stata-code-mcp` lives inside a project virtualenv (recommended for reproducibility), point the client at the absolute path:
+
+```json
+{
+  "mcpServers": {
+    "stata-code": {
+      "command": "/abs/path/to/.venv/bin/stata-code-mcp"
+    }
+  }
+}
+```
+
+For `uvx`-only setups, set `"command": "uvx"` and `"args": ["--from", "stata-code", "stata-code-mcp"]`.
+
 The MCP server registers 15 tools:
 
 | Tool | Purpose |
@@ -196,7 +234,7 @@ The MCP server registers 15 tools:
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `list_sessions` | Enumerate live sessions |
-| `cancel_session` | Cooperatively cancel the next `stata_run` for a session |
+| `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
 | `notebook_outline` | Compact per-cell index of a `.ipynb` (cell_id, type, preview) |
 | `notebook_get_cell` | One cell's full source plus a token-economic outputs summary |
@@ -261,7 +299,20 @@ The companion extension is on the Marketplace as [`brycewang-stanford.stata-code
 code --install-extension brycewang-stanford.stata-code-vscode
 ```
 
-Or open the **Extensions** sidebar in VS Code and search `stata-code`.
+Or open the **Extensions** sidebar in VS Code and search `stata-code`. The extension is also available from [Open VSX](https://open-vsx.org/) so Cursor, Windsurf, and other VS Code-compatible editors can install it without going through the Microsoft Marketplace.
+
+On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
+
+#### Cell and section conventions
+
+The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
+
+| Marker | Purpose | Example |
+| --- | --- | --- |
+| `* %% [title]` | Cell boundary. Each marker gets a **▶ Run Cell** code-lens; "Run Cell" submits the lines between this marker and the next one. Compatible with the Jupyter-style cell convention used by `kylebutts/vscode-stata`. | `* %% 02 model fit` |
+| `**# title` … `**###### title` | Section heading, 1–6 levels deep. Each heading gets a **▶ Run Section** code-lens and contributes to the Outline view. "Run Section" submits the heading through the next equal- or higher-level heading, matching the hierarchical execution model from `ZihaoVistonWang.stata-all-in-one`. | `**## DiD specification` |
+
+`program define … end` blocks are also surfaced in the Outline, nested under whichever section contains them.
 
 The extension still requires the MCP extra on your system Python (`pip install "stata-code[mcp]"`), so that `stata-code-mcp` resolves on `PATH` and can import the MCP SDK. Stata 17+ and a valid Stata license are required as for any other frontend.
 
@@ -310,14 +361,15 @@ stata_code/
 │   ├── _refs.py       # LRU ref store for log/graph/matrix payloads
 │   ├── schema.py      # Pydantic v2 models for the v1.0 result schema
 │   ├── errors.py      # rc → ErrorKind mapping + suggestion seeds
-│   └── runner.py      # the one execute(); collects everything via sfi
+│   ├── runner.py      # in-process execute(); collects everything via sfi
+│   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
 │   └── server.py      # MCP server (15 tools)
 └── kernel/
     └── kernel.py      # Jupyter kernel
 ```
 
-`runner.py` is the only place that touches Stata. The Jupyter kernel and MCP server both import from it and only translate results into their own transports.
+`runner.py` is the only place that directly talks to `pystata`. The public Python API and MCP server route calls through `_pool.py`, whose workers call `runner.execute()` in an isolated subprocess; the Jupyter kernel uses the in-process runner for notebook interactivity.
 
 ---
 
@@ -353,7 +405,7 @@ stata_code/
 - MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
-- Cooperative cancellation: `cancel(session_id)` / MCP `cancel_session`
+- Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok)
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
@@ -363,8 +415,8 @@ stata_code/
 ### Next Up
 
 - Console fallback for Stata 11–16, re-implemented against the v1.0 schema
-- Hard timeout / mid-Stata interrupt; design and tradeoffs in [`docs/design/hard_timeout.md`](docs/design/hard_timeout.md)
-- Extra VS Code polish (esbuild bundle, lighter VSIX, command palette UX)
+- Decide whether to move the Jupyter kernel from the direct in-process runner to the subprocess pool, or keep documenting the current interactivity-first tradeoff
+- Extra VS Code polish: extension-host end-to-end tests, first-run diagnostics, and command palette UX
 - **v1.0** — Stable schema, broader Stata edition coverage
 
 See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
@@ -375,9 +427,9 @@ See [SCHEMA.md §7](SCHEMA.md) for explicitly out-of-scope items.
 
 ```bash
 pip install -e ".[dev,mcp,kernel]"
-pytest                              # full suite (310 tests)
+pytest                              # full suite, including Stata tests when Stata is available
 pytest -m "not stata_required"      # CI subset; no Stata needed
-pytest -m "stata_required" -v       # Stata-only integration tests
+pytest -m "stata_required" -v       # real-Stata integration tests only
 ```
 
 The `stata_required` marker tags the real-Stata integration tests. CI uses `pytest -m "not stata_required"` so it does not collect them. Locally without Stata, those tests skip cleanly with the `"pystata / Stata 17+ not available"` message.