proxyctl 0.3.2__tar.gz → 0.4.0__tar.gz

{proxyctl-0.3.2 → proxyctl-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.3.2
+Version: 0.4.0
 Summary: Proxy configuration lifecycle management for macOS and Linux
 Project-URL: Homepage, https://github.com/crhan/proxyctl
 Project-URL: Issues, https://github.com/crhan/proxyctl/issues
@@ -63,7 +63,16 @@ PROXYCTL_AGENT=1 proxyctl <cmd>      # 一键 --json + 关色 + 非交互
 
 - envelope schema v2：`schema_version / cmd / ok / data / error / code / hints[] / warnings[] / doc / meta{{ts,elapsed_ms,proxyctl_version,request_id}}`
 - 退出码分语义：`0 OK / 2 USAGE / 3 NOT_FOUND / 4 PERMISSION / 5 ENGINE_DOWN / 6 CONFIG_ERR / 7 NETWORK_ERR / 8 LOCKED / 9 TIMEOUT / 10 DEPENDENCY_MISSING`
-- 写命令支持 `--dry-run` 输出结构化 plan；`audit/check` 支持 `--plain` TSV
+- 写命令支持 `--dry-run` 输出结构化 plan（`data.plan = [PlanStep, ...]`）；自 0.4.0 起
+  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读：
+  ```bash
+  proxyctl dns-unlock --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
+  # → launchctl bootout system/com.proxyctl.dns-lock
+  # → rm -f /Library/LaunchDaemons/com.proxyctl.dns-lock.plist
+  ```
+  PlanStep.action 枚举：`subprocess / system_op / fs_write / fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log / http_put`。
+  CI 层 contract test（`tests/integration/test_plan_exec_contract.py`）保证 plan ↔ exec 永不漂移。
+- `audit/check` 支持 `--plain` TSV
 - `proxyctl help <cmd>` 与 `<cmd> --help` 同源；错误带可执行 hints + explain topic
 - 非 TTY 自动关色；不读 stdin / 不 prompt；写操作 fcntl.flock 互斥
 - 从 0.2.x 升级见 [MIGRATION-0.3.md](MIGRATION-0.3.md)

{proxyctl-0.3.2 → proxyctl-0.4.0}/README.md

@@ -34,7 +34,16 @@ PROXYCTL_AGENT=1 proxyctl <cmd>      # 一键 --json + 关色 + 非交互
 
 - envelope schema v2：`schema_version / cmd / ok / data / error / code / hints[] / warnings[] / doc / meta{{ts,elapsed_ms,proxyctl_version,request_id}}`
 - 退出码分语义：`0 OK / 2 USAGE / 3 NOT_FOUND / 4 PERMISSION / 5 ENGINE_DOWN / 6 CONFIG_ERR / 7 NETWORK_ERR / 8 LOCKED / 9 TIMEOUT / 10 DEPENDENCY_MISSING`
-- 写命令支持 `--dry-run` 输出结构化 plan；`audit/check` 支持 `--plain` TSV
+- 写命令支持 `--dry-run` 输出结构化 plan（`data.plan = [PlanStep, ...]`）；自 0.4.0 起
+  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读：
+  ```bash
+  proxyctl dns-unlock --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
+  # → launchctl bootout system/com.proxyctl.dns-lock
+  # → rm -f /Library/LaunchDaemons/com.proxyctl.dns-lock.plist
+  ```
+  PlanStep.action 枚举：`subprocess / system_op / fs_write / fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log / http_put`。
+  CI 层 contract test（`tests/integration/test_plan_exec_contract.py`）保证 plan ↔ exec 永不漂移。
+- `audit/check` 支持 `--plain` TSV
 - `proxyctl help <cmd>` 与 `<cmd> --help` 同源；错误带可执行 hints + explain topic
 - 非 TTY 自动关色；不读 stdin / 不 prompt；写操作 fcntl.flock 互斥
 - 从 0.2.x 升级见 [MIGRATION-0.3.md](MIGRATION-0.3.md)

{proxyctl-0.3.2 → proxyctl-0.4.0}/man/proxyctl.1

@@ -1,4 +1,4 @@
-.TH PROXYCTL 1 "2026-05" "proxyctl 0.3.0" "User Commands"
+.TH PROXYCTL 1 "2026-05" "proxyctl 0.4.0" "User Commands"
 .SH NAME
 proxyctl \- Proxy configuration lifecycle management for macOS / Linux
 .SH SYNOPSIS
@@ -35,6 +35,12 @@ PlanStep 字段：step / action / target / reversible / requires_sudo /
 side_effects / summary。
 适用：mode / engine / fix / audit apply / config set / daemon /
 dns-lock / dns-unlock。
+.IP
+\fB自 0.4.0\fR：plan.target 全部真实化（无 \fI<...>\fR 占位符）；
+action=\fBsubprocess\fR 的 target.split() 可直接当 argv（run 时
+prepend sudo）。action 枚举：subprocess / system_op / fs_write /
+fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log /
+http_put。CI 层 contract test 保证 plan ↔ exec 永不漂移。
 .TP
 .BR --no-color
 关闭 ANSI 颜色（默认按 isatty / NO_COLOR / TERM=dumb / PROXYCTL_NO_COLOR 自动判断）。
@@ -53,8 +59,10 @@ dns-lock / dns-unlock。
 .SH COMMANDS
 .SS 自描述（Agent 入口）
 .TP
-.B proxyctl agent-guide
+\fBproxyctl agent-guide\fR [\fB--list-sections\fR | \fB--section\fR \fINAME\fR]
 输出给 LLM 的运行时入门 markdown（能力地图 / 引导路径 / 决策树 / envelope 字段表 / 锁文件位置 / footgun）。
+v0.3.3 新增：\fB--list-sections\fR 列出所有 ASCII slug 形式的 section 名；
+\fB--section <name>\fR 只输出该 section（模糊匹配 + did-you-mean），agent 按需取小块。
 .TP
 \fBproxyctl explain\fR [\fITOPIC\fR]
 无参输出"想改 X 去哪？"速查表；带 topic 输出卡片。
@@ -74,7 +82,8 @@ supports_dry_run / needs_sudo / interactive / exit_codes / examples。
 .B proxyctl doctor [--json]
 极简 5 项健康打分：engine_up / port_listen / dns_ok / system_proxy_ok /
 connectivity_ok。\fB--json\fR 额外含 informational 字段：
-engine / mode / port / config_path / engine_config_path / lock_held / lock_path。
+engine / mode / port / config_path / engine_config_path / lock_held / lock_path /
+\fBhealthy\fR (v0.3.3 新增 bool，agent 不必再算 score==max)。
 .TP
 .B proxyctl help [\fICOMMAND\fR]
 顶层帮助 / 单命令完整说明。等价 \fBproxyctl --help\fR / \fBproxyctl <cmd> --help\fR。

{proxyctl-0.3.2 → proxyctl-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxyctl"
-version = "0.3.2"
+version = "0.4.0"
 description = "Proxy configuration lifecycle management for macOS and Linux"
 readme = "README.md"
 requires-python = ">=3.10"

proxyctl-0.4.0/src/proxyctl/__init__.py

@@ -0,0 +1,8 @@
+"""proxyctl — Proxy configuration lifecycle management."""
+
+from importlib.metadata import PackageNotFoundError, version as _v
+
+try:
+    __version__ = _v("proxyctl")
+except PackageNotFoundError:  # editable / source tree without metadata
+    __version__ = "unknown"