stata-code 0.14.0__tar.gz → 0.15.0__tar.gz

{stata_code-0.14.0 → stata_code-0.15.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
 ## [Unreleased]
 
+## 0.15.0 — 2026-10-03
+
+Variable labels can now be edited straight in a `.dta` file, by hand in the VS
+Code data viewer or in bulk by an agent, without Stata. Adds one MCP tool; the
+result schema is unchanged.
+
+### Added
+
+- **Edit variable labels without Stata.** A variable label is a fixed-width
+  field in every `.dta` format since Stata 8, so it can be replaced by
+  overwriting that field alone: no offset moves and the data, value labels,
+  notes, formats and characteristics keep their bytes. Two entry points share
+  that approach and the same Stata-written fixtures:
+  - **VS Code data viewer**: *Edit* beside a variable's label in the details
+    panel (or double-click the variable in the list), Enter to write it to the
+    file, Esc to cancel. Snapshots of in-memory data stay read-only.
+  - **MCP tool `set_variable_labels(path, labels?, dry_run?)`** (22 tools now):
+    a batch `{variable: label}` map for agents, e.g. to label an unlabeled
+    dataset after looking at it. Omit `labels` to read the current ones. The
+    reply lists `changed: [{name, before, after}]`, so `before` is the undo.
+    Python API: `stata_code.core.dta_labels`.
+
+  Every edit is validated before any byte is written. Limits are Stata's own
+  80 characters; files in formats older than 118 (Stata 13 or earlier) take
+  ASCII labels only, because those formats do not record their encoding.
+  Checked against Stata 18: the edited fixtures load, `describe` shows the new
+  labels, and `notes`, `label list` and `datasignature` are unchanged. Dataset
+  labels and value labels are variable-length and are not editable yet.
+
 ## 0.14.0 — 2026-10-03
 
 The `.dta` viewer added in 0.13 could only be scrolled. It can now be queried:

{stata_code-0.14.0 → stata_code-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stata-code
-Version: 0.14.0
+Version: 0.15.0
 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
@@ -362,7 +362,7 @@ claude mcp add stata-code --scope local -- stata-code-mcp
 claude mcp add stata-code --scope project -- stata-code-mcp
 ```
 
-Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 21 tools (`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
+Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 22 tools (`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `set_variable_labels`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
 
 #### Error Recovery in Agent Workflows
 
@@ -450,7 +450,7 @@ If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
 upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
 processes keep advertising the stale schema until they are restarted.
 
-The MCP server registers 21 tools:
+The MCP server registers 22 tools:
 
 | Tool | Purpose |
 | --- | --- |
@@ -464,6 +464,7 @@ The MCP server registers 21 tools:
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `inspect_data` | Run `describe` + `codebook` and return compact dataset metadata |
 | `lint_do` | Statically check do-file source (unbalanced braces, missing `end`, dangling `///`) before spending a run |
+| `set_variable_labels` | Write variable labels straight into a `.dta` file without Stata (the label fields are overwritten in place; data, value labels and notes keep their bytes); omit `labels` to read the current ones |
 | `install_package` | Install an SSC or explicit `net install` package and verify it resolves |
 | `list_sessions` | Enumerate live sessions |
 | `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
@@ -619,7 +620,7 @@ stata_code/
 │   ├── runner.py      # in-process execute(); collects everything via sfi
 │   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
-│   ├── server.py      # MCP server (21 tools)
+│   ├── server.py      # MCP server (22 tools)
 │   └── ...
 ├── core/console.py    # console (batch) backend — Stata 13+, no pystata
 └── kernel/
@@ -718,7 +719,7 @@ Rule of thumb:
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 34-kind error taxonomy with canonical suggestions and a machine-readable `recovery` verdict (retriable / needs-code-change / needs-user-input)
-- MCP server: 21 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), static linting (`lint_do`), and package installation (`install_package`)
+- MCP server: 22 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), static linting (`lint_do`), Stata-free variable-label editing (`set_variable_labels`), and package installation (`install_package`)
 - Command-safety guard: OS-escape / file-deletion commands (`shell`, `winexec`, `erase`, `rm`, `rmdir`, `!`) are blocked before Stata runs; configurable via `STATA_CODE_COMMAND_POLICY` / `STATA_CODE_POLICY_ALLOW` / `STATA_CODE_POLICY_BLOCK`
 - Bash / plain-terminal surface: `stata-code run` (a `.do` file, `-e` snippets, or stdin) prints the same structured `RunResult` any agent that can shell out can consume; `stata-code lint` runs the linter; `stata-code setup` writes MCP client configs
 - Console (batch) backend (`core/console.py`, `--backend console`, `run_console()`): drives the Stata command-line executable, parses the log into the same typed `RunResult`, and supports **Stata 13+ with no pystata**

{stata_code-0.14.0 → stata_code-0.15.0}/README.en.md

@@ -323,7 +323,7 @@ claude mcp add stata-code --scope local -- stata-code-mcp
 claude mcp add stata-code --scope project -- stata-code-mcp
 ```
 
-Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 21 tools (`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
+Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 22 tools (`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `set_variable_labels`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
 
 #### Error Recovery in Agent Workflows
 
@@ -411,7 +411,7 @@ If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
 upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
 processes keep advertising the stale schema until they are restarted.
 
-The MCP server registers 21 tools:
+The MCP server registers 22 tools:
 
 | Tool | Purpose |
 | --- | --- |
@@ -425,6 +425,7 @@ The MCP server registers 21 tools:
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
 | `inspect_data` | Run `describe` + `codebook` and return compact dataset metadata |
 | `lint_do` | Statically check do-file source (unbalanced braces, missing `end`, dangling `///`) before spending a run |
+| `set_variable_labels` | Write variable labels straight into a `.dta` file without Stata (the label fields are overwritten in place; data, value labels and notes keep their bytes); omit `labels` to read the current ones |
 | `install_package` | Install an SSC or explicit `net install` package and verify it resolves |
 | `list_sessions` | Enumerate live sessions |
 | `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
@@ -580,7 +581,7 @@ stata_code/
 │   ├── runner.py      # in-process execute(); collects everything via sfi
 │   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
-│   ├── server.py      # MCP server (21 tools)
+│   ├── server.py      # MCP server (22 tools)
 │   └── ...
 ├── core/console.py    # console (batch) backend — Stata 13+, no pystata
 └── kernel/
@@ -679,7 +680,7 @@ Rule of thumb:
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 34-kind error taxonomy with canonical suggestions and a machine-readable `recovery` verdict (retriable / needs-code-change / needs-user-input)
-- MCP server: 21 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), static linting (`lint_do`), and package installation (`install_package`)
+- MCP server: 22 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), static linting (`lint_do`), Stata-free variable-label editing (`set_variable_labels`), and package installation (`install_package`)
 - Command-safety guard: OS-escape / file-deletion commands (`shell`, `winexec`, `erase`, `rm`, `rmdir`, `!`) are blocked before Stata runs; configurable via `STATA_CODE_COMMAND_POLICY` / `STATA_CODE_POLICY_ALLOW` / `STATA_CODE_POLICY_BLOCK`
 - Bash / plain-terminal surface: `stata-code run` (a `.do` file, `-e` snippets, or stdin) prints the same structured `RunResult` any agent that can shell out can consume; `stata-code lint` runs the linter; `stata-code setup` writes MCP client configs
 - Console (batch) backend (`core/console.py`, `--backend console`, `run_console()`): drives the Stata command-line executable, parses the log into the same typed `RunResult`, and supports **Stata 13+ with no pystata**

{stata_code-0.14.0 → stata_code-0.15.0}/README.md

@@ -301,7 +301,7 @@ claude mcp add stata-code --scope local -- stata-code-mcp
 claude mcp add stata-code --scope project -- stata-code-mcp
 ```
 
-接着运行 `claude`，输入 `/mcp` 确认 `stata-code` 出现并带有 21 个工具（`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`）。
+接着运行 `claude`，输入 `/mcp` 确认 `stata-code` 出现并带有 22 个工具（`stata_run`, `stata_run_status`, `list_background_runs`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `lint_do`, `set_variable_labels`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`）。
 
 #### Agent 工作流里的报错恢复
 
@@ -381,7 +381,7 @@ client 配置里写绝对路径，例如 `/abs/path/to/.venv/bin/stata-code-mcp`
 `stata-code>=0.6.5`，然后重启 MCP client。旧 server 进程在重启前仍会继续
 暴露旧 schema。
 
-MCP server 注册了 21 个工具：
+MCP server 注册了 22 个工具：
 
 | 工具 | 用途 |
 | --- | --- |
@@ -395,6 +395,7 @@ MCP server 注册了 21 个工具：
 | `get_matrix` | 通过 `matrix://` ref 获取矩阵 `{rows, cols, values}` |
 | `inspect_data` | 运行 `describe` + `codebook`，返回紧凑的数据集元数据 |
 | `lint_do` | 在执行前静态检查 do 文件源代码（花括号不匹配、缺少 `end`、悬空 `///`） |
+| `set_variable_labels` | 不经过 Stata，直接改写 `.dta` 文件里的变量标签（原地覆写标签字段，数据、值标签、notes 逐字节不变）；不传 `labels` 时只读取现有标签 |
 | `install_package` | 安装 SSC 或显式 `net install` 包，并验证命令可解析 |
 | `list_sessions` | 列出 live sessions |
 | `cancel_session` | 取消某个 session；subprocess-backed 路径会终止运行中的 worker，也会短路尚未开始的运行 |
@@ -546,7 +547,7 @@ stata_code/
 │   ├── runner.py      # in-process execute(); collects everything via sfi
 │   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
-│   └── server.py      # MCP server (21 tools)
+│   └── server.py      # MCP server (22 tools)
 └── kernel/
     └── kernel.py      # Jupyter kernel
 ```
@@ -621,7 +622,7 @@ printf 'sysuse auto, clear\nsummarize mpg\nexit, clear\n' | stata-mp -q
 - 日志截断 + ref store
 - 警告抽取：5 类 + 通用 notes
 - 34 类错误分类法 + 标准化建议，以及机器可读的 `recovery` 判定（可重试 / 需改代码 / 需人工介入）
-- MCP server：21 个工具，覆盖执行、notebook 导航 / 检索 / 原子化编辑、运行索引（`list_runs`）、日志检索（`search_log`）、数据集检查（`inspect_data`）、静态检查（`lint_do`）和包安装（`install_package`）
+- MCP server：22 个工具，覆盖执行、notebook 导航 / 检索 / 原子化编辑、运行索引（`list_runs`）、日志检索（`search_log`）、数据集检查（`inspect_data`）、静态检查（`lint_do`）、无需 Stata 的变量标签编辑（`set_variable_labels`）和包安装（`install_package`）
 - 命令安全护栏：`shell`、`winexec`、`erase`、`rm`、`rmdir`、`!` 等 OS 逃逸 / 删除文件命令在执行前被拦截；可通过 `STATA_CODE_COMMAND_POLICY` / `STATA_CODE_POLICY_ALLOW` / `STATA_CODE_POLICY_BLOCK` 配置
 - Bash / 终端入口：`stata-code run`（`.do` 文件、`-e` 片段或 stdin）打印同一套结构化 `RunResult`，任何能调用 shell 的 agent 都可消费；`stata-code lint` 运行静态检查；`stata-code setup` 写入 MCP 客户端配置
 - Console（批处理）后端（`core/console.py`、`--backend console`、`run_console()`）：驱动 Stata 命令行、把日志解析成同一套带类型的 `RunResult`，支持 **Stata 13+ 且无需 pystata**

{stata_code-0.14.0 → stata_code-0.15.0}/docs/quickstart.zh.md

@@ -73,7 +73,7 @@ stata-code setup --claude        # 写入项目级 .mcp.json（会保留其它 s
 # 或： stata-code setup --cursor / --vscode / --all
 ```
 
-然后运行 `claude`，`/mcp` 里应能看到 `stata-code` 及其 21 个工具
+然后运行 `claude`，`/mcp` 里应能看到 `stata-code` 及其 22 个工具
 （`stata_run`、`lint_do`、`inspect_data`、`install_package` 等）。
 
 ---

{stata_code-0.14.0 → stata_code-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stata-code"
-version = "0.14.0"
+version = "0.15.0"
 description = "Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)"
 # The repo default README (README.md) is Chinese; keep the PyPI long description
 # English by pointing at README.en.md.

{stata_code-0.14.0 → stata_code-0.15.0}/stata_code/__init__.py

@@ -260,7 +260,7 @@ def is_available() -> bool:
     return True
 
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 __all__ = [
     # Primary entry points

stata_code-0.15.0/stata_code/core/dta_labels.py

@@ -0,0 +1,303 @@
+"""Read and edit variable labels in a ``.dta`` file without Stata.
+
+A variable label is a fixed-width, zero-terminated field in every ``.dta``
+format since Stata 8 (81 bytes through format 117, 321 bytes from 118 on; see
+``help dta``). Replacing one overwrites that field and nothing else: no offset
+moves, and the data, value labels, notes, characteristics and strLs keep their
+bytes. That is why :func:`set_variable_labels` patches the file in place
+rather than loading and re-saving it, which would need Stata (or would drop
+whatever the re-saving library does not model).
+
+Written against StataCorp's published format documentation, which
+LICENSE-POLICY.md §2.1 lists as an allowed reference. This is the Python
+counterpart of ``vscode/src/dtaWriter.ts`` and must accept and refuse the same
+labels; both are tested on the same Stata-written fixtures.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+__all__ = [
+    "MAX_VARIABLE_LABEL_CHARS",
+    "DtaLabelError",
+    "DtaLabels",
+    "LabelChange",
+    "read_variable_labels",
+    "set_variable_labels",
+]
+
+#: Stata's limit on a variable label, in characters.
+MAX_VARIABLE_LABEL_CHARS = 80
+
+_VARIABLE_LABELS_TAG = b"<variable_labels>"
+_VARNAMES_TAG = b"<varnames>"
+
+
+class DtaLabelError(ValueError):
+    """The file is not a supported ``.dta`` file, or a label cannot be stored."""
+
+
+@dataclass(frozen=True)
+class LabelChange:
+    name: str
+    before: str
+    after: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"name": self.name, "before": self.before, "after": self.after}
+
+
+@dataclass(frozen=True)
+class DtaLabels:
+    """Where the variable labels of one file live, and what they say."""
+
+    release: int
+    names: list[str]
+    labels: list[str]
+    #: File offset of the first label field.
+    offset: int
+    #: Width of each label field in bytes.
+    width: int
+
+    def as_dict(self) -> dict[str, str]:
+        return dict(zip(self.names, self.labels))
+
+
+def _zero_terminated(raw: bytes) -> bytes:
+    end = raw.find(b"\0")
+    return raw if end < 0 else raw[:end]
+
+
+def _decode(raw: bytes, release: int) -> str:
+    raw = _zero_terminated(raw)
+    if release >= 118:
+        return raw.decode("utf-8", errors="replace")
+    # Older formats do not record their encoding; mirror the viewer's "auto".
+    for encoding in ("utf-8", "gb18030"):
+        try:
+            return raw.decode(encoding)
+        except UnicodeDecodeError:
+            continue
+    return raw.decode("cp1252", errors="replace")
+
+
+def _read_exact(handle: BinaryIO, offset: int, length: int) -> bytes:
+    handle.seek(offset)
+    data = handle.read(length)
+    if len(data) != length:
+        raise DtaLabelError("malformed or truncated .dta file")
+    return data
+
+
+def _expect(data: bytes, pos: int, tag: bytes) -> int:
+    if data[pos : pos + len(tag)] != tag:
+        raise DtaLabelError(
+            f"malformed .dta file: expected {tag.decode('ascii')} at byte {pos}"
+        )
+    return pos + len(tag)
+
+
+def _locate_tagged(handle: BinaryIO, head: bytes, size: int) -> DtaLabels:
+    pos = _expect(head, 0, b"<stata_dta><header><release>")
+    try:
+        release = int(head[pos : pos + 3].decode("ascii"))
+    except ValueError:
+        raise DtaLabelError("malformed .dta file: unreadable release number") from None
+    if release not in (117, 118, 119, 120, 121):
+        raise DtaLabelError(f".dta format {release} is not supported")
+    pos = _expect(head, pos + 3, b"</release><byteorder>")
+    order = head[pos : pos + 3]
+    if order not in (b"LSF", b"MSF"):
+        raise DtaLabelError("malformed .dta file: unknown byte order")
+    endian = "<" if order == b"LSF" else ">"
+    pos = _expect(head, pos + 3, b"</byteorder><K>")
+    wide = release in (119, 121)  # more than 32,767 variables
+    if wide:
+        (n_vars,) = struct.unpack_from(endian + "I", head, pos)
+        pos += 4
+    else:
+        (n_vars,) = struct.unpack_from(endian + "H", head, pos)
+        pos += 2
+    pos = _expect(head, pos, b"</K><N>")
+    pos += 4 if release == 117 else 8
+    pos = _expect(head, pos, b"</N><label>")
+    if release == 117:
+        label_length = head[pos]
+        pos += 1
+    else:
+        (label_length,) = struct.unpack_from(endian + "H", head, pos)
+        pos += 2
+    pos = _expect(head, pos + label_length, b"</label><timestamp>")
+    pos = _expect(head, pos + 1 + head[pos], b"</timestamp></header><map>")
+    section = struct.unpack_from(endian + "14Q", head, pos)
+
+    name_width = 33 if release == 117 else 129
+    label_width = 81 if release == 117 else 321
+    names_at, labels_at = section[3], section[7]
+    names_bytes = n_vars * name_width
+    labels_bytes = n_vars * label_width
+    if (
+        names_at + len(_VARNAMES_TAG) + names_bytes > size
+        or labels_at + len(_VARIABLE_LABELS_TAG) + labels_bytes > size
+    ):
+        raise DtaLabelError("malformed or truncated .dta file: section map is out of range")
+
+    if _read_exact(handle, names_at, len(_VARNAMES_TAG)) != _VARNAMES_TAG:
+        raise DtaLabelError("malformed .dta file: <varnames> is not where the map says")
+    raw_names = _read_exact(handle, names_at + len(_VARNAMES_TAG), names_bytes)
+    if _read_exact(handle, labels_at, len(_VARIABLE_LABELS_TAG)) != _VARIABLE_LABELS_TAG:
+        raise DtaLabelError(
+            "malformed .dta file: <variable_labels> is not where the map says"
+        )
+    offset = labels_at + len(_VARIABLE_LABELS_TAG)
+    raw_labels = _read_exact(handle, offset, labels_bytes)
+    return DtaLabels(
+        release=release,
+        names=[
+            _decode(raw_names[i * name_width : (i + 1) * name_width], release)
+            for i in range(n_vars)
+        ],
+        labels=[
+            _decode(raw_labels[i * label_width : (i + 1) * label_width], release)
+            for i in range(n_vars)
+        ],
+        offset=offset,
+        width=label_width,
+    )
+
+
+def _locate_legacy(handle: BinaryIO, head: bytes, size: int) -> DtaLabels:
+    release = head[0]
+    if head[1] not in (1, 2):
+        raise DtaLabelError("malformed .dta file: unknown byte order")
+    endian = "<" if head[1] == 2 else ">"
+    (n_vars,) = struct.unpack_from(endian + "H", head, 4)
+    format_width = 12 if release == 113 else 49
+    names_at = 109 + n_vars
+    offset = names_at + n_vars * 33 + 2 * (n_vars + 1) + n_vars * (format_width + 33)
+    if offset + n_vars * 81 > size:
+        raise DtaLabelError("malformed or truncated .dta file")
+    raw_names = _read_exact(handle, names_at, n_vars * 33)
+    raw_labels = _read_exact(handle, offset, n_vars * 81)
+    return DtaLabels(
+        release=release,
+        names=[_decode(raw_names[i * 33 : (i + 1) * 33], release) for i in range(n_vars)],
+        labels=[_decode(raw_labels[i * 81 : (i + 1) * 81], release) for i in range(n_vars)],
+        offset=offset,
+        width=81,
+    )
+
+
+def _locate(handle: BinaryIO) -> DtaLabels:
+    size = os.fstat(handle.fileno()).st_size
+    handle.seek(0)
+    head = handle.read(4096)
+    if len(head) < 4:
+        raise DtaLabelError("not a Stata .dta file (file is too short)")
+    try:
+        if head[:1] == b"<":
+            return _locate_tagged(handle, head, size)
+        if 113 <= head[0] <= 115:
+            return _locate_legacy(handle, head, size)
+    except (struct.error, IndexError):
+        raise DtaLabelError("malformed or truncated .dta file") from None
+    if 102 <= head[0] <= 112:
+        raise DtaLabelError(
+            f".dta format {head[0]} (Stata 7 or older) is not supported; "
+            "open it in Stata and save it again to convert it"
+        )
+    raise DtaLabelError("not a Stata .dta file (unrecognized header)")
+
+
+def read_variable_labels(path: str | os.PathLike[str]) -> DtaLabels:
+    """Return the variable names and labels stored in the ``.dta`` file at ``path``."""
+    with Path(path).open("rb") as handle:
+        return _locate(handle)
+
+
+def _encode(label: str, release: int, width: int) -> bytes:
+    if len(label) > MAX_VARIABLE_LABEL_CHARS:
+        raise DtaLabelError(
+            f"label is {len(label)} characters; Stata allows at most "
+            f"{MAX_VARIABLE_LABEL_CHARS}"
+        )
+    for ch in label:
+        code = ord(ch)
+        if code < 0x20 or code == 0x7F:
+            raise DtaLabelError(
+                "label contains a control character (a line break or a tab?)"
+            )
+        if 0xD800 <= code <= 0xDFFF:
+            raise DtaLabelError(
+                "label contains an unpaired surrogate and is not valid Unicode"
+            )
+        if release < 118 and code > 0x7E:
+            # These formats predate UTF-8 and do not record which encoding they
+            # use, so no non-ASCII label would read the same everywhere.
+            raise DtaLabelError(
+                f"this is a format-{release} file (Stata 13 or older), which can "
+                "only take plain-ASCII labels here; save it again in Stata 14 or "
+                "newer to use other characters"
+            )
+    encoded = label.encode("utf-8")
+    if len(encoded) > width - 1:
+        raise DtaLabelError(
+            f"label takes {len(encoded)} bytes; this file format has room for {width - 1}"
+        )
+    return encoded.ljust(width, b"\0")
+
+
+def set_variable_labels(
+    path: str | os.PathLike[str],
+    labels: dict[str, str],
+    *,
+    dry_run: bool = False,
+) -> list[LabelChange]:
+    """Set variable labels in the ``.dta`` file at ``path``, in place.
+
+    ``labels`` maps variable name to the new label; ``""`` removes a label.
+    Every edit is validated before any byte is written, so a bad entry leaves
+    the file untouched. Returns the labels that actually changed (an entry that
+    already holds the requested text is not a change). With ``dry_run`` the
+    same validation runs and the same list comes back, but nothing is written.
+
+    Raises :class:`DtaLabelError` for an unsupported file, an unknown variable,
+    or a label Stata could not hold.
+    """
+    with Path(path).open("rb" if dry_run else "r+b") as handle:
+        found = _locate(handle)
+        index = {name: i for i, name in enumerate(found.names)}
+        patches: list[tuple[int, bytes, LabelChange]] = []
+        problems: list[str] = []
+        for name, label in labels.items():
+            i = index.get(name)
+            if i is None:
+                problems.append(f"{name}: no such variable")
+                continue
+            if not isinstance(label, str):
+                problems.append(f"{name}: label must be a string")
+                continue
+            if label == found.labels[i]:
+                continue
+            try:
+                field = _encode(label, found.release, found.width)
+            except DtaLabelError as exc:
+                problems.append(f"{name}: {exc}")
+                continue
+            patches.append(
+                (found.offset + i * found.width, field, LabelChange(name, found.labels[i], label))
+            )
+        if problems:
+            raise DtaLabelError("; ".join(problems))
+        if not dry_run and patches:
+            for offset, field, _ in patches:
+                handle.seek(offset)
+                handle.write(field)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return [change for _, _, change in patches]

{stata_code-0.14.0 → stata_code-0.15.0}/stata_code/mcp/server.py

@@ -65,6 +65,11 @@ except ImportError:  # pragma: no cover - environment without mcp installed
 from stata_code.core import _refs, jobs
 from stata_code.core._pool import get_default_pool, pool_execute, pool_stata_info
 from stata_code.core._runtime import PystataNotAvailable
+from stata_code.core.dta_labels import (
+    DtaLabelError,
+    read_variable_labels,
+    set_variable_labels,
+)
 from stata_code.core.lint import lint_code
 from stata_code.core.notebook import (
     NotebookError,
@@ -102,7 +107,7 @@ from stata_code.core.runner import (
 )
 from stata_code.core.schema import RunResult
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 SERVER_INSTRUCTIONS = (
     "Use stata-code for running and inspecting Stata code. Prefer structuredContent "
@@ -1498,6 +1503,59 @@ def _tool_definitions() -> list[Tool]:
                 openWorldHint=False,
             ),
         ),
+        Tool(
+            name="set_variable_labels",
+            title="Set Variable Labels in a .dta File",
+            description=(
+                "Stata-free: write variable labels straight into a .dta file on "
+                "disk, the on-disk equivalent of `label variable x \"...\"` + "
+                "`save, replace`. Pass `path` and `labels` ({variable name: "
+                "label}; \"\" removes a label). Only the label fields are "
+                "overwritten, so the data, value labels, notes, formats and "
+                "characteristics are byte-for-byte unchanged and no Stata "
+                "session or license is used. Omit `labels` to just read the "
+                "current names and labels (e.g. to find unlabeled variables "
+                "before proposing labels). All edits are validated first; if "
+                "any is invalid nothing is written. Limits: 80 characters per "
+                "label; files in formats older than 118 (Stata 13 or earlier) "
+                "take ASCII labels only. Returns {ok, path, release, changed:"
+                "[{name, before, after}], unchanged:[...]}; `before` is what to "
+                "pass back to undo. Use `dry_run` to validate without writing. "
+                "This edits the file, not a dataset already loaded in a "
+                "session: run `use` again to see the new labels there."
+            ),
+            inputSchema={
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["path"],
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the .dta file to edit.",
+                    },
+                    "labels": {
+                        "type": "object",
+                        "additionalProperties": {"type": "string"},
+                        "description": (
+                            "Variable name → new label. An empty string removes "
+                            "the label. Omit to read the current labels."
+                        ),
+                    },
+                    "dry_run": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Validate and report the changes without writing.",
+                    },
+                },
+            },
+            annotations=ToolAnnotations(
+                title="Set Variable Labels in a .dta File",
+                readOnlyHint=False,
+                destructiveHint=True,
+                idempotentHint=True,
+                openWorldHint=False,
+            ),
+        ),
     ]
 
 
@@ -2664,6 +2722,8 @@ async def _dispatch(name: str, arguments: dict[str, Any]) -> Any:
             return await asyncio.to_thread(_inspect_data_tool, arguments)
         if name == "lint_do":
             return _lint_do_tool(arguments)
+        if name == "set_variable_labels":
+            return _set_variable_labels_tool(arguments)
         return _error_result(f"Unknown tool: {name}", kind="unknown_tool")
     except NotebookError as exc:
         return _error_result(str(exc), kind=exc.kind)
@@ -3077,6 +3137,57 @@ def _lint_do_tool(arguments: dict[str, Any]) -> Any:
     return _json_result(payload)
 
 
+def _set_variable_labels_tool(arguments: dict[str, Any]) -> Any:
+    path = arguments.get("path")
+    labels = arguments.get("labels")
+    dry_run = arguments.get("dry_run", False)
+    if not isinstance(path, str) or not path:
+        return _error_result("path must be a non-empty string", kind="missing_argument")
+    if not isinstance(dry_run, bool):
+        return _error_result("dry_run must be a boolean", kind="invalid_request")
+    if labels is not None and (
+        not isinstance(labels, dict)
+        or not all(isinstance(k, str) and isinstance(v, str) for k, v in labels.items())
+    ):
+        return _error_result(
+            "labels must be an object mapping variable names to label strings",
+            kind="invalid_request",
+        )
+    try:
+        if labels is None:
+            found = read_variable_labels(path)
+            return _json_result(
+                {
+                    "ok": True,
+                    "path": path,
+                    "release": found.release,
+                    "labels": found.as_dict(),
+                    "changed": [],
+                    "unchanged": [],
+                    "dry_run": dry_run,
+                }
+            )
+        changes = set_variable_labels(path, labels, dry_run=dry_run)
+        release = read_variable_labels(path).release
+    except FileNotFoundError:
+        return _error_result(f"file not found: {path}", kind="file_not_found")
+    except DtaLabelError as exc:
+        return _error_result(str(exc), kind="invalid_request")
+    except OSError as exc:
+        return _error_result(f"could not edit {path}: {exc}", kind="file_io")
+    changed = {change.name for change in changes}
+    return _json_result(
+        {
+            "ok": True,
+            "path": path,
+            "release": release,
+            "changed": [change.to_dict() for change in changes],
+            "unchanged": [name for name in labels if name not in changed],
+            "dry_run": dry_run,
+        }
+    )
+
+
 def _inspect_data_tool(arguments: dict[str, Any]) -> Any:
     varlist = arguments.get("varlist")
     if varlist is not None and not isinstance(varlist, str):