From b702ff166dcfdbaf01408d7457e01dce09507bfd Mon Sep 17 00:00:00 2001 From: codeasier Date: Thu, 6 Aug 2026 19:19:16 +0800 Subject: [PATCH 1/3] feat: add pt-snap setup skill --- skills/pt-snap-setup/SKILL.md | 134 ++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 skills/pt-snap-setup/SKILL.md diff --git a/skills/pt-snap-setup/SKILL.md b/skills/pt-snap-setup/SKILL.md new file mode 100644 index 0000000..410dd75 --- /dev/null +++ b/skills/pt-snap-setup/SKILL.md @@ -0,0 +1,134 @@ +--- +name: pt-snap-setup +description: Use when installing or verifying pt-snap-cli in the current Python environment. Does not assume conda; for first-time install, PyPI, editable install, or pre-flight before fragmentation/leak analysis when pt-snap is missing. +--- + +# pt-snap-setup + +## Overview +Use this skill to verify whether `pt-snap-cli` is available in the current Python environment, or to guide a safe install into that same environment when it is missing. + +Use it when: +- Installing `pt-snap-cli` for the first time. +- Verifying whether the current shell is ready to run `pt-snap`. +- Doing pre-flight setup before fragmentation or leak analysis when `pt-snap` is missing. + +Do not assume conda, any fixed environment name, or that a different shell has the right Python. Work only with the environment that is active in the current shell unless the user explicitly changes it. + +## Required Inputs +No inputs are required. + +Optional inputs: +- ``: absolute or user-provided path to a local `pt-snap-cli` checkout for editable install. +- Install source preference: `editable` or `pypi`. +- Whether dev extras are wanted for a local editable install. + +Before running commands, substitute placeholders such as `` with actual values. + +## Mandatory Prerequisite Phase +Run these checks in order and report what you found. + +### 1. Identify the active Python environment +Run: +```bash +python -V +python -m pip --version +python -c "import sys; print(sys.executable)" +``` +Record the active Python version, the pip target environment, and the Python executable path. If any of these commands fails, stop and report the exact failure; do not attempt installation with an unverified interpreter. + +### 2. Check whether the CLI already works +Run: +```bash +pt-snap --help +``` +If this succeeds, report that `pt-snap` is available in the current shell. + +### 3. If the CLI is unavailable, check package importability and installation metadata +Run this check only if `pt-snap --help` failed in Step 2: +```bash +python -c "import pt_snap_cli; print(pt_snap_cli.__file__)" +``` +If the import succeeds, also run: +```bash +python -m pip show pt-snap-cli +``` +This distinguishes between: +- CLI available and ready. +- Package import works but `pt-snap` is not on the current shell `PATH`. +- Package import works from a source path, but the distribution is not installed in the active environment. +- Neither the CLI nor the package is available in the active Python environment. + +### 4. If both checks fail, ask for install source and confirm first +If `pt-snap --help` fails and the import check fails, stop and ask the user which install source they prefer. Confirm before running any install command. + +If the import succeeds but the CLI is missing, do not reinstall automatically. Report that the package is importable but the `pt-snap` entry point is unavailable, including whether `pip show pt-snap-cli` found an installed distribution. Ask whether the user wants to repair the installation or update `PATH`. + +Install choices: +- Editable install from this repository or another local checkout: + - Standard: `python -m pip install -e ""` + - With dev extras if requested: `python -m pip install -e "[dev]"` +- PyPI install: + - `python -m pip install pt-snap-cli` + +If the user wants a local editable install but has not provided ``, ask for it first. + +### 5. Run the chosen install into the active Python environment +Always use `python -m pip install ...` so the install targets the active Python environment. + +Examples: +```bash +python -m pip install -e "" +python -m pip install -e "[dev]" +python -m pip install pt-snap-cli +``` +Do not switch environments silently. Do not replace `python -m pip` with plain `pip` unless the user explicitly asks for that behavior. + +### 6. Re-verify after install +Run both checks again after any confirmed install command, even if Step 3 was the only check that failed earlier. Step 6 always re-runs both checks post-install by design: +```bash +pt-snap --help +python -c "import pt_snap_cli; print(pt_snap_cli.__file__)" +``` +Then report the final state using the same result categories as the output template: `ready`, `CLI missing but import works`, or `install failed`. + +If installation succeeds but `pt-snap --help` still fails while the import succeeds, report `CLI missing but import works` and explain that the executable directory is not on the current shell `PATH`. Do not run another install automatically. + +### 7. Stop if verification still fails +If verification still fails after the confirmed install command, stop and report the exact failure. Do not guess another environment, do not try a different interpreter automatically, and do not keep running more install commands without user confirmation. + +## Output Template +Report results in this structure: + +- Active Python info: + - `python -V`: `` + - `python -m pip --version`: `` + - `python -c "import sys; print(sys.executable)"`: `` +- Detected availability: + - `pt-snap --help`: `` + - `python -c "import pt_snap_cli; print(pt_snap_cli.__file__)"`: `` + - `python -m pip show pt-snap-cli`: `` +- Install command used: + - `` +- Install outcome: + - `` +- Final verification result: + - `` + +## Guardrails +- Do not assume conda or any fixed environment name. +- Do not silently switch the user's environment. +- Confirm with the user before any `pip install`. +- Use `python -m pip` so install targets the active Python environment. +- Do not write report files. +- Do not modify user config beyond what `pip install` requires. + +## Verification Checklist +- Active Python environment identified with `python -V`, `python -m pip --version`, and `python -c "import sys; print(sys.executable)"`. +- `pt-snap --help` checked in the current shell. +- `python -c "import pt_snap_cli; print(pt_snap_cli.__file__)"` checked if needed. +- `python -m pip show pt-snap-cli` checked when the package import succeeds but the CLI is unavailable. +- User confirmation obtained before any `python -m pip install ...` command. +- Exact install command recorded if one was run. +- Post-install verification re-run. +- If verification failed, failure reported without guessing another environment. From d08db8de9ad630168661a0420a3c65d0d4eaeee8 Mon Sep 17 00:00:00 2001 From: codeasier Date: Thu, 6 Aug 2026 21:35:30 +0800 Subject: [PATCH 2/3] fix: verify pt-snap setup environment ownership --- skills/pt-snap-setup/SKILL.md | 113 +++++++++++++++++++++++----------- 1 file changed, 76 insertions(+), 37 deletions(-) diff --git a/skills/pt-snap-setup/SKILL.md b/skills/pt-snap-setup/SKILL.md index 410dd75..954b82a 100644 --- a/skills/pt-snap-setup/SKILL.md +++ b/skills/pt-snap-setup/SKILL.md @@ -23,77 +23,99 @@ Optional inputs: - Install source preference: `editable` or `pypi`. - Whether dev extras are wanted for a local editable install. -Before running commands, substitute placeholders such as `` with actual values. +Before running commands, substitute placeholders such as ``, ``, and `` with actual values. ## Mandatory Prerequisite Phase Run these checks in order and report what you found. ### 1. Identify the active Python environment +Select one interpreter once, preferring `python` and falling back to `python3`: +```bash +if command -v python >/dev/null 2>&1; then command -v python; else command -v python3; fi +``` +If neither command exists, stop and report that no Python interpreter is available. Save the selected command path as ``, then resolve the interpreter itself: +```bash +"" -c "import os, sys; print(os.path.realpath(sys.executable))" +``` +Use this canonical path as `` for every later Python and pip command; do not switch between `python` and `python3`. + Run: ```bash -python -V -python -m pip --version -python -c "import sys; print(sys.executable)" +"" -V +"" -m pip --version +"" -c "import sys; print(sys.executable)" ``` -Record the active Python version, the pip target environment, and the Python executable path. If any of these commands fails, stop and report the exact failure; do not attempt installation with an unverified interpreter. +Record the active Python version, the pip target environment, and the canonical Python executable path. If any of these commands fails, stop and report the exact failure; do not attempt installation with an unverified interpreter. -### 2. Check whether the CLI already works +### 2. Check whether the CLI works and belongs to the selected Python Run: ```bash +command -v pt-snap pt-snap --help ``` -If this succeeds, report that `pt-snap` is available in the current shell. +If both commands succeed, save the first command's output as `` and inspect its shebang: +```bash +"" -c "from pathlib import Path; import sys; print(Path(sys.argv[1]).open(encoding='utf-8').readline().strip())" "" +``` +Resolve the shebang interpreter and compare its canonical path with ``. For an `/usr/bin/env ` shebang, resolve `` in the current `PATH` before comparing. Report `ready` only when `pt-snap --help` succeeds and both paths identify the same interpreter. + +If the shebang is missing or cannot be resolved, report `CLI ownership unverified`. If it points to another interpreter, report `CLI belongs to another Python environment`. Do not report the selected Python environment as ready and do not reinstall automatically. -### 3. If the CLI is unavailable, check package importability and installation metadata -Run this check only if `pt-snap --help` failed in Step 2: +### 3. If the CLI is unavailable or belongs elsewhere, check package availability +Run this check if `pt-snap --help` failed or Step 2 did not verify ownership: ```bash -python -c "import pt_snap_cli; print(pt_snap_cli.__file__)" +"" -c "import pt_snap_cli; print(pt_snap_cli.__file__)" ``` If the import succeeds, also run: ```bash -python -m pip show pt-snap-cli +"" -m pip show pt-snap-cli ``` This distinguishes between: - CLI available and ready. +- CLI resolves to another Python environment while the selected Python may or may not have the package. - Package import works but `pt-snap` is not on the current shell `PATH`. - Package import works from a source path, but the distribution is not installed in the active environment. - Neither the CLI nor the package is available in the active Python environment. -### 4. If both checks fail, ask for install source and confirm first -If `pt-snap --help` fails and the import check fails, stop and ask the user which install source they prefer. Confirm before running any install command. +### 4. If no matching CLI or package is available, ask before installing +If CLI ownership is not verified and the import check fails, report `not installed`, then ask which install source the user prefers. Confirm before running any install command. If the user declines, report `installation declined` and stop. If the import succeeds but the CLI is missing, do not reinstall automatically. Report that the package is importable but the `pt-snap` entry point is unavailable, including whether `pip show pt-snap-cli` found an installed distribution. Ask whether the user wants to repair the installation or update `PATH`. Install choices: - Editable install from this repository or another local checkout: - - Standard: `python -m pip install -e ""` - - With dev extras if requested: `python -m pip install -e "[dev]"` + - Standard: `"" -m pip install -e ""` + - With dev extras if requested: `"" -m pip install -e "[dev]"` - PyPI install: - - `python -m pip install pt-snap-cli` + - `"" -m pip install pt-snap-cli` If the user wants a local editable install but has not provided ``, ask for it first. ### 5. Run the chosen install into the active Python environment -Always use `python -m pip install ...` so the install targets the active Python environment. +Always use `"" -m pip install ...` so the install targets the selected Python environment. Examples: ```bash -python -m pip install -e "" -python -m pip install -e "[dev]" -python -m pip install pt-snap-cli +"" -m pip install -e "" +"" -m pip install -e "[dev]" +"" -m pip install pt-snap-cli ``` -Do not switch environments silently. Do not replace `python -m pip` with plain `pip` unless the user explicitly asks for that behavior. +Do not switch environments silently. Do not replace `"" -m pip` with plain `pip` unless the user explicitly asks for that behavior. ### 6. Re-verify after install -Run both checks again after any confirmed install command, even if Step 3 was the only check that failed earlier. Step 6 always re-runs both checks post-install by design: +Run the CLI path, help, ownership, import, and distribution checks again after any confirmed install command. Step 6 always re-runs all checks post-install by design: ```bash +command -v pt-snap pt-snap --help -python -c "import pt_snap_cli; print(pt_snap_cli.__file__)" +"" -c "import pt_snap_cli; print(pt_snap_cli.__file__)" +"" -m pip show pt-snap-cli ``` -Then report the final state using the same result categories as the output template: `ready`, `CLI missing but import works`, or `install failed`. +Repeat the shebang comparison from Step 2 when `command -v pt-snap` and `pt-snap --help` succeed. Then report the final state using the result categories in the output template. If installation succeeds but `pt-snap --help` still fails while the import succeeds, report `CLI missing but import works` and explain that the executable directory is not on the current shell `PATH`. Do not run another install automatically. +If `pt-snap` still resolves to another interpreter, report `CLI belongs to another Python environment`, even when the selected Python can import the package. Do not report `ready` until CLI ownership matches. + ### 7. Stop if verification still fails If verification still fails after the confirmed install command, stop and report the exact failure. Do not guess another environment, do not try a different interpreter automatically, and do not keep running more install commands without user confirmation. @@ -101,34 +123,51 @@ If verification still fails after the confirmed install command, stop and report Report results in this structure: - Active Python info: - - `python -V`: `` - - `python -m pip --version`: `` - - `python -c "import sys; print(sys.executable)"`: `` + - Selected command: `` + - ` -V`: `` + - ` -m pip --version`: `` + - ` -c "import sys; print(sys.executable)"`: `` - Detected availability: + - `command -v pt-snap`: `` - `pt-snap --help`: `` - - `python -c "import pt_snap_cli; print(pt_snap_cli.__file__)"`: `` - - `python -m pip show pt-snap-cli`: `` + - CLI shebang interpreter: `` + - CLI ownership: `` + - ` -c "import pt_snap_cli; print(pt_snap_cli.__file__)"`: `` + - ` -m pip show pt-snap-cli`: `` - Install command used: - - `` + - ` -m pip install ... command>` - Install outcome: - `` - Final verification result: - - `` + - `` + +Use these categories consistently before and after installation: +- `ready`: CLI help succeeds and the CLI shebang resolves to the selected Python. +- `CLI belongs to another Python environment`: CLI help succeeds, but its shebang resolves to a different interpreter. +- `CLI ownership unverified`: CLI help succeeds, but its shebang is missing or cannot be resolved. +- `CLI missing but import works`: the selected Python imports the package, but no matching CLI is available. +- `not installed`: neither a matching CLI nor a package import is available and no install was attempted. +- `installation declined`: installation was offered and the user declined it. +- `install failed`: a confirmed install command or its post-install package verification failed. ## Guardrails - Do not assume conda or any fixed environment name. - Do not silently switch the user's environment. - Confirm with the user before any `pip install`. -- Use `python -m pip` so install targets the active Python environment. +- Select `python` or `python3` once and use its absolute path for every Python and pip command. +- Verify that the resolved `pt-snap` shebang belongs to the selected Python before reporting `ready`. - Do not write report files. - Do not modify user config beyond what `pip install` requires. ## Verification Checklist -- Active Python environment identified with `python -V`, `python -m pip --version`, and `python -c "import sys; print(sys.executable)"`. -- `pt-snap --help` checked in the current shell. -- `python -c "import pt_snap_cli; print(pt_snap_cli.__file__)"` checked if needed. -- `python -m pip show pt-snap-cli` checked when the package import succeeds but the CLI is unavailable. -- User confirmation obtained before any `python -m pip install ...` command. +- `python` or `python3` selected once and its absolute path used consistently. +- Active Python environment identified with ` -V`, ` -m pip --version`, and `sys.executable`. +- `command -v pt-snap` and `pt-snap --help` checked in the current shell. +- Resolved CLI shebang interpreter compared with the selected Python before reporting `ready`. +- Package import checked if the CLI is unavailable or its ownership is not verified. +- ` -m pip show pt-snap-cli` checked when the package import succeeds but the CLI is unavailable or belongs elsewhere. +- User confirmation obtained before any ` -m pip install ...` command. - Exact install command recorded if one was run. - Post-install verification re-run. +- `not installed`, `installation declined`, and `install failed` reported as distinct states. - If verification failed, failure reported without guessing another environment. From da24329ff7eddf5421c2a1ef2620e5b627125b73 Mon Sep 17 00:00:00 2001 From: codeasier Date: Thu, 6 Aug 2026 23:00:00 +0800 Subject: [PATCH 3/3] fix: preserve virtualenv interpreter path --- skills/pt-snap-setup/SKILL.md | 15 ++++++----- tests/test_setup_skill.py | 48 +++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 7 deletions(-) create mode 100644 tests/test_setup_skill.py diff --git a/skills/pt-snap-setup/SKILL.md b/skills/pt-snap-setup/SKILL.md index 954b82a..e2866dc 100644 --- a/skills/pt-snap-setup/SKILL.md +++ b/skills/pt-snap-setup/SKILL.md @@ -35,9 +35,9 @@ if command -v python >/dev/null 2>&1; then command -v python; else command -v py ``` If neither command exists, stop and report that no Python interpreter is available. Save the selected command path as ``, then resolve the interpreter itself: ```bash -"" -c "import os, sys; print(os.path.realpath(sys.executable))" +"" -c "import sys; print(sys.executable)" ``` -Use this canonical path as `` for every later Python and pip command; do not switch between `python` and `python3`. +Preserve this path exactly as `` for every later Python and pip command; do not pass it through `realpath` or switch between `python` and `python3`. A virtual environment may use a symlink whose location is required for Python to discover that environment. Run: ```bash @@ -45,7 +45,7 @@ Run: "" -m pip --version "" -c "import sys; print(sys.executable)" ``` -Record the active Python version, the pip target environment, and the canonical Python executable path. If any of these commands fails, stop and report the exact failure; do not attempt installation with an unverified interpreter. +Record the active Python version, the pip target environment, and the Python executable path. If any of these commands fails, stop and report the exact failure; do not attempt installation with an unverified interpreter. ### 2. Check whether the CLI works and belongs to the selected Python Run: @@ -57,7 +57,7 @@ If both commands succeed, save the first command's output as `" -c "from pathlib import Path; import sys; print(Path(sys.argv[1]).open(encoding='utf-8').readline().strip())" "" ``` -Resolve the shebang interpreter and compare its canonical path with ``. For an `/usr/bin/env ` shebang, resolve `` in the current `PATH` before comparing. Report `ready` only when `pt-snap --help` succeeds and both paths identify the same interpreter. +Resolve the shebang interpreter and compare `realpath` values computed temporarily for the shebang interpreter and ``. For an `/usr/bin/env ` shebang, resolve `` in the current `PATH` before comparing. Never replace `` with its `realpath`; canonicalization is only for this ownership comparison. Report `ready` only when `pt-snap --help` succeeds and both comparison paths identify the same interpreter. If the shebang is missing or cannot be resolved, report `CLI ownership unverified`. If it points to another interpreter, report `CLI belongs to another Python environment`. Do not report the selected Python environment as ready and do not reinstall automatically. @@ -126,7 +126,7 @@ Report results in this structure: - Selected command: `` - ` -V`: `` - ` -m pip --version`: `` - - ` -c "import sys; print(sys.executable)"`: `` + - ` -c "import sys; print(sys.executable)"`: `` - Detected availability: - `command -v pt-snap`: `` - `pt-snap --help`: `` @@ -154,13 +154,14 @@ Use these categories consistently before and after installation: - Do not assume conda or any fixed environment name. - Do not silently switch the user's environment. - Confirm with the user before any `pip install`. -- Select `python` or `python3` once and use its absolute path for every Python and pip command. +- Select `python` or `python3` once and preserve its `sys.executable` path for every Python and pip command. +- Use canonical paths only for CLI ownership comparison, never to execute Python or pip. - Verify that the resolved `pt-snap` shebang belongs to the selected Python before reporting `ready`. - Do not write report files. - Do not modify user config beyond what `pip install` requires. ## Verification Checklist -- `python` or `python3` selected once and its absolute path used consistently. +- `python` or `python3` selected once and its uncanonicalized `sys.executable` path used consistently. - Active Python environment identified with ` -V`, ` -m pip --version`, and `sys.executable`. - `command -v pt-snap` and `pt-snap --help` checked in the current shell. - Resolved CLI shebang interpreter compared with the selected Python before reporting `ready`. diff --git a/tests/test_setup_skill.py b/tests/test_setup_skill.py new file mode 100644 index 0000000..80524a7 --- /dev/null +++ b/tests/test_setup_skill.py @@ -0,0 +1,48 @@ +from __future__ import annotations + +import os +import subprocess +import venv +from pathlib import Path + +import pytest + +SKILL_PATH = Path("skills/pt-snap-setup/SKILL.md") + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX venvs use interpreter symlinks") +def test_setup_skill_preserves_virtual_environment_interpreter_path(tmp_path: Path) -> None: + environment = tmp_path / "venv" + venv.EnvBuilder(with_pip=True, symlinks=True).create(environment) + candidate = environment / "bin" / "python" + child_env = os.environ.copy() + child_env.pop("__PYVENV_LAUNCHER__", None) + + executable = subprocess.run( + [candidate, "-c", "import sys; print(sys.executable)"], + check=True, + capture_output=True, + env=child_env, + text=True, + ).stdout.strip() + selected_prefix = subprocess.run( + [executable, "-c", "import sys; print(sys.prefix)"], + check=True, + capture_output=True, + env=child_env, + text=True, + ).stdout.strip() + base_prefix = subprocess.run( + [os.path.realpath(executable), "-c", "import sys; print(sys.prefix)"], + check=True, + capture_output=True, + env=child_env, + text=True, + ).stdout.strip() + + assert Path(selected_prefix) == environment + assert Path(base_prefix) != environment + + skill = SKILL_PATH.read_text() + assert '"" -c "import sys; print(sys.executable)"' in skill + assert "Never replace `` with its `realpath`" in skill