skit-cli 0.0.1__tar.gz → 0.2.0__tar.gz

skit_cli-0.0.1/README.md → skit_cli-0.2.0/PKG-INFO

@@ -1,3 +1,33 @@
+Metadata-Version: 2.4
+Name: skit-cli
+Version: 0.2.0
+Summary: Script launcher and parameter manager: all your scripts in one menu, their flags, input() calls, and constants auto-extracted into a run form — no more opening an IDE just to tweak a value.
+Keywords: script,launcher,uv,tui,pep723,script-manager,script-runner,automation,ai-agent,agent-skills
+Author: Yi-Ting Chiu
+Author-email: Yi-Ting Chiu <mytim710@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Dist: typer>=0.26,<1
+Requires-Dist: platformdirs>=4.10,<5
+Requires-Dist: tomli-w>=1.2,<2
+Requires-Dist: textual>=8.2,<9
+Requires-Dist: rich>=15,<16
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/t41372/skit
+Project-URL: Issues, https://github.com/t41372/skit/issues
+Description-Content-Type: text/markdown
+
 ![skit — script launcher and parameter manager](https://raw.githubusercontent.com/t41372/skit/main/docs/assets/banner.png)
 
 [![CI](https://github.com/t41372/skit/actions/workflows/ci.yml/badge.svg)](https://github.com/t41372/skit/actions/workflows/ci.yml)
@@ -17,7 +47,11 @@ skit stores your Python scripts in one place and makes them painless to launch.
 
 **AI writes the scripts. skit gives them a home.**
 
-<video src="https://github.com/user-attachments/assets/65c9eed8-d6fa-4a16-836c-7017eb08bb9c" controls></video>
+And it's a home you share with your agent: the library you drive from a menu, AI agents
+drive through a deterministic CLI — checking it before writing yet another one-off
+script, and (with your OK) saving the good ones back, so they outlive the chat.
+
+<video src="https://github.com/user-attachments/assets/d27121fe-5855-4270-91b0-b0ee9e5d11ee" controls></video>
 
 ## What it does
 
@@ -27,6 +61,7 @@ skit stores your Python scripts in one place and makes them painless to launch.
 - **No environment mess.** skit declares each script's dependencies in the script itself (PEP 723) and runs it through uv in an isolated, cached environment — no venvs to manage, nothing installed globally.
 - **Mouse or keyboard.** Plain `skit` opens the full TUI; every key hint on screen is also a clickable button.
 - **Automation-ready.** Every TUI action is also a CLI command with `--json` output and meaningful exit codes — for shell scripts, CI, and AI agents.
+- **Your agent's script library too.** The official [Agent Skill](https://agentskills.io) teaches Claude Code, Codex, Cursor, Gemini CLI, and friends the whole drill: discover scripts with `skit list`, read a parameter schema with `skit show`, run with `skit run --set … --no-input`. One `skit agent install` away — see [Works with your AI agent](#works-with-your-ai-agent).
 - **Speaks your language.** English, 繁體中文, and 简体中文, with more to come. See [Languages](#languages).
 
 | Problem | What skit does |
@@ -34,6 +69,7 @@ skit stores your Python scripts in one place and makes them painless to launch.
 | Scripts scattered all over the place | One central menu, with search |
 | Scripts with weird external dependencies | An isolated environment per script — dependencies declared in the file (PEP 723), resolved by uv |
 | CLI flags you forget ten minutes later, `input()` prompts, hard-coded constants meant to be edited by hand | Static analysis extracts them all into an interactive form — no code changes. Last-used values come prefilled; favorites save as presets. |
+| The weird script an AI wrote for you dies with the chat session | Agents check the library first, reuse what's there, and save the keepers — one-off scripts become permanent, parameterized tools |
 
 Nothing to set up per script — no refactoring, no config to maintain. The script an AI wrote last week and the one you barely remember from last year launch the same way.
 
@@ -72,6 +108,15 @@ uv tool install git+https://github.com/t41372/skit          # latest development
 uvx --from git+https://github.com/t41372/skit skit --help   # try it without installing
 ```
 
+## Update
+
+```bash
+uv tool upgrade skit-cli   # update to the latest release — also how you "check": it says up to date if you are
+skit --version             # the version you're on
+```
+
+`uv tool upgrade` follows whatever source you installed from: PyPI installs track PyPI releases, `git+…` installs re-fetch the main branch.
+
 ## Uninstall
 
 ```bash
@@ -119,12 +164,29 @@ The rest of the CLI exists for automation and AI agents — every TUI action, sc
 ```bash
 skit run my_script -p fast    # run with a saved preset
 skit run my_script --dry-run  # print the exact command, don't run it
+skit run my_script --set width=800 --no-input   # set values explicitly, never prompt
+skit show my_script --json    # one script's full parameter schema, machine-readable
 skit params my_script         # show managed parameters and last-used values
 skit list --json              # machine-readable listing
 skit config                   # settings: language, editor, mirror, form style
 skit --help                   # everything else
 ```
 
+## Works with your AI agent
+
+skit is a script repository for humans *and* AI agents: one library — you get the
+forms, agents get a deterministic CLI. The official [Agent Skill](https://agentskills.io)
+teaches compatible agents (Claude Code, Codex, Cursor, Gemini CLI, and many more) to
+check your library before writing yet another one-off script, to inspect and run what's
+already there, and to offer to save the useful scripts they write — so they outlive the
+session that created them.
+
+```bash
+skit agent install            # pick one of the agent directories found on your machine
+skit agent install claude     # or name it: claude / codex / agents (--project for this repo only)
+npx skills add t41372/skit    # or install through skills.sh into 70+ agents
+```
+
 ## Languages
 
 | Language | Status |

skit_cli-0.0.1/PKG-INFO → skit_cli-0.2.0/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: skit-cli
-Version: 0.0.1
-Summary: Script launcher and parameter manager: pick a script, fill in a form, run — no more opening an IDE just to tweak constants.
-Keywords: script,launcher,uv,tui,pep723,script-manager
-Author: Yi-Ting Chiu
-Author-email: Yi-Ting Chiu <mytim710@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Environment :: Console :: Curses
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Topic :: Utilities
-Requires-Dist: typer>=0.26,<1
-Requires-Dist: platformdirs>=4.10,<5
-Requires-Dist: tomli-w>=1.2,<2
-Requires-Dist: textual>=8.2,<9
-Requires-Dist: rich>=15,<16
-Requires-Python: >=3.12
-Project-URL: Repository, https://github.com/t41372/skit
-Project-URL: Issues, https://github.com/t41372/skit/issues
-Description-Content-Type: text/markdown
-
 ![skit — script launcher and parameter manager](https://raw.githubusercontent.com/t41372/skit/main/docs/assets/banner.png)
 
 [![CI](https://github.com/t41372/skit/actions/workflows/ci.yml/badge.svg)](https://github.com/t41372/skit/actions/workflows/ci.yml)
@@ -47,7 +17,11 @@ skit stores your Python scripts in one place and makes them painless to launch.
 
 **AI writes the scripts. skit gives them a home.**
 
-<video src="https://github.com/user-attachments/assets/65c9eed8-d6fa-4a16-836c-7017eb08bb9c" controls></video>
+And it's a home you share with your agent: the library you drive from a menu, AI agents
+drive through a deterministic CLI — checking it before writing yet another one-off
+script, and (with your OK) saving the good ones back, so they outlive the chat.
+
+<video src="https://github.com/user-attachments/assets/d27121fe-5855-4270-91b0-b0ee9e5d11ee" controls></video>
 
 ## What it does
 
@@ -57,6 +31,7 @@ skit stores your Python scripts in one place and makes them painless to launch.
 - **No environment mess.** skit declares each script's dependencies in the script itself (PEP 723) and runs it through uv in an isolated, cached environment — no venvs to manage, nothing installed globally.
 - **Mouse or keyboard.** Plain `skit` opens the full TUI; every key hint on screen is also a clickable button.
 - **Automation-ready.** Every TUI action is also a CLI command with `--json` output and meaningful exit codes — for shell scripts, CI, and AI agents.
+- **Your agent's script library too.** The official [Agent Skill](https://agentskills.io) teaches Claude Code, Codex, Cursor, Gemini CLI, and friends the whole drill: discover scripts with `skit list`, read a parameter schema with `skit show`, run with `skit run --set … --no-input`. One `skit agent install` away — see [Works with your AI agent](#works-with-your-ai-agent).
 - **Speaks your language.** English, 繁體中文, and 简体中文, with more to come. See [Languages](#languages).
 
 | Problem | What skit does |
@@ -64,6 +39,7 @@ skit stores your Python scripts in one place and makes them painless to launch.
 | Scripts scattered all over the place | One central menu, with search |
 | Scripts with weird external dependencies | An isolated environment per script — dependencies declared in the file (PEP 723), resolved by uv |
 | CLI flags you forget ten minutes later, `input()` prompts, hard-coded constants meant to be edited by hand | Static analysis extracts them all into an interactive form — no code changes. Last-used values come prefilled; favorites save as presets. |
+| The weird script an AI wrote for you dies with the chat session | Agents check the library first, reuse what's there, and save the keepers — one-off scripts become permanent, parameterized tools |
 
 Nothing to set up per script — no refactoring, no config to maintain. The script an AI wrote last week and the one you barely remember from last year launch the same way.
 
@@ -102,6 +78,15 @@ uv tool install git+https://github.com/t41372/skit          # latest development
 uvx --from git+https://github.com/t41372/skit skit --help   # try it without installing
 ```
 
+## Update
+
+```bash
+uv tool upgrade skit-cli   # update to the latest release — also how you "check": it says up to date if you are
+skit --version             # the version you're on
+```
+
+`uv tool upgrade` follows whatever source you installed from: PyPI installs track PyPI releases, `git+…` installs re-fetch the main branch.
+
 ## Uninstall
 
 ```bash
@@ -149,12 +134,29 @@ The rest of the CLI exists for automation and AI agents — every TUI action, sc
 ```bash
 skit run my_script -p fast    # run with a saved preset
 skit run my_script --dry-run  # print the exact command, don't run it
+skit run my_script --set width=800 --no-input   # set values explicitly, never prompt
+skit show my_script --json    # one script's full parameter schema, machine-readable
 skit params my_script         # show managed parameters and last-used values
 skit list --json              # machine-readable listing
 skit config                   # settings: language, editor, mirror, form style
 skit --help                   # everything else
 ```
 
+## Works with your AI agent
+
+skit is a script repository for humans *and* AI agents: one library — you get the
+forms, agents get a deterministic CLI. The official [Agent Skill](https://agentskills.io)
+teaches compatible agents (Claude Code, Codex, Cursor, Gemini CLI, and many more) to
+check your library before writing yet another one-off script, to inspect and run what's
+already there, and to offer to save the useful scripts they write — so they outlive the
+session that created them.
+
+```bash
+skit agent install            # pick one of the agent directories found on your machine
+skit agent install claude     # or name it: claude / codex / agents (--project for this repo only)
+npx skills add t41372/skit    # or install through skills.sh into 70+ agents
+```
+
 ## Languages
 
 | Language | Status |

{skit_cli-0.0.1 → skit_cli-0.2.0}/pyproject.toml

@@ -2,14 +2,25 @@
 # Distribution name only ("skit" is admin-prohibited on PyPI); the import package,
 # CLI command, and config dirs all stay "skit".
 name = "skit-cli"
-version = "0.0.1"
-description = "Script launcher and parameter manager: pick a script, fill in a form, run — no more opening an IDE just to tweak constants."
+version = "0.2.0"
+description = "Script launcher and parameter manager: all your scripts in one menu, their flags, input() calls, and constants auto-extracted into a run form — no more opening an IDE just to tweak a value."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Yi-Ting Chiu", email = "mytim710@gmail.com" }]
-keywords = ["script", "launcher", "uv", "tui", "pep723", "script-manager"]
+keywords = [
+    "script",
+    "launcher",
+    "uv",
+    "tui",
+    "pep723",
+    "script-manager",
+    "script-runner",
+    "automation",
+    "ai-agent",
+    "agent-skills",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
@@ -174,5 +185,9 @@ ignore = [
 "tests/corpus/**" = ["ALL"]  # corpus files are verbatim analyzer inputs, not code style subjects
 
 [tool.mutmut]
-paths_to_mutate = ["src/skit/"]
-tests_dir = ["tests/"]
+# Modern key names (paths_to_mutate / tests_dir print deprecation warnings on 3.6).
+source_paths = ["src/skit/"]
+pytest_add_cli_args_test_selection = ["tests/"]
+# The skill-sync test (tests/test_agent_skill.py) compares the repo-root skill against
+# the packaged copy; mutmut's mutants/ tree only carries src/ + tests/ by default.
+also_copy = ["skills/"]

skit_cli-0.2.0/src/skit/__init__.py

@@ -0,0 +1,20 @@
+"""skit — a launcher and parameter manager for your scripts."""
+
+import os
+from importlib.metadata import PackageNotFoundError, version
+
+# Textual ≥ 8.2.7 enables the kitty keyboard protocol's "report all keys" mode, which
+# iTerm2 (3.6.x) implements in a way that fights the macOS IME: candidate-selection
+# digits and Enter reach the app as raw key events and the composed CJK text is never
+# delivered at all (iTerm2 issue 12906) — Chinese/Japanese/Korean typing breaks. No
+# skit binding needs the protocol, so opt out before the first textual import
+# (textual.constants reads this at import time). setdefault keeps an explicit user
+# override (=0 re-enables) winning.
+os.environ.setdefault("TEXTUAL_DISABLE_KITTY_KEY", "1")
+
+# pyproject.toml is the single source of the version; installed distributions carry it
+# as metadata (a wheel doesn't ship pyproject.toml), so read it from there.
+try:
+    __version__ = version("skit-cli")
+except PackageNotFoundError:  # a bare checkout on sys.path, no installed dist
+    __version__ = "0.0.0+unknown"

skit_cli-0.2.0/src/skit/agentskill.py

@@ -0,0 +1,99 @@
+"""The bundled Agent Skill and where it can be installed (headless; the CLI renders).
+
+skit ships an official Agent Skill (skills/skit/SKILL.md, agentskills.io format) that
+teaches AI coding agents to drive the library through the CLI. This module owns the
+headless half of `skit agent install`: locating the bundled copy inside the installed
+package and computing which agent skill directories exist on this machine.
+
+Non-invasive by design (AGENTS.md principle #6): detection only reports directories
+whose parent tool is already present (`~/.claude` exists, `./.codex` exists, …) — skit
+never conjures another tool's config tree uninvited. Writing anywhere requires either
+an explicit target/--to (consent by flag) or an interactive confirmation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+
+SKILL_DIR_NAME = "skit"
+SKILL_FILE_NAME = "SKILL.md"
+
+# Known agent conventions: tool marker directory -> skills subdirectory lives inside it.
+# claude: Claude Code (user ~/.claude/skills, project .claude/skills)
+# codex:  OpenAI Codex CLI (user ~/.codex/skills, project .codex/skills)
+# agents: the cross-agent project convention (.agents/skills), project-only.
+USER_TARGETS = {"claude": ".claude", "codex": ".codex"}
+PROJECT_TARGETS = {"claude": ".claude", "codex": ".codex", "agents": ".agents"}
+
+
+@dataclass
+class Target:
+    """One place the skill can be installed: `<base>/skills/skit/SKILL.md`."""
+
+    name: str  # "claude" | "codex" | "agents"
+    scope: str  # "user" | "project"
+    base: Path  # the tool's marker directory (e.g. ~/.claude)
+
+    @property
+    def skills_dir(self) -> Path:
+        return self.base / "skills"
+
+
+def default_roots() -> tuple[Path, Path]:
+    """(home, cwd) for target resolution — one seam for the CLI and for tests. Tests
+    redirect this instead of monkeypatching os.getcwd, which mutmut's stats
+    bookkeeping also relies on mid-test."""
+    return Path.home(), Path.cwd()
+
+
+def skill_text() -> str:
+    """The bundled SKILL.md, read from the installed package (single source: the repo's
+    skills/skit/SKILL.md is a test-enforced byte-identical copy of this file)."""
+    res = resources.files("skit").joinpath("skills", SKILL_DIR_NAME, SKILL_FILE_NAME)
+    # I/O kwarg mutants ("utf-8"→"UTF-8"/None) are equivalent aliases here; content is
+    # pinned by test_skill_text_is_the_bundled_skill (see docs/mutation-ledger.md).
+    return res.read_text(encoding="utf-8")  # pragma: no mutate
+
+
+def named_target(name: str, *, project: bool, home: Path, cwd: Path) -> Target | None:
+    """Resolve an explicit target name ("claude" / "codex" / "agents") to a Target.
+    None for an unknown name. `agents` is a project-level convention, so it resolves
+    to the project scope regardless of the --project flag."""
+    if name == "agents":
+        return Target(name=name, scope="project", base=cwd / PROJECT_TARGETS[name])
+    if project:
+        marker = PROJECT_TARGETS.get(name)
+        return Target(name=name, scope="project", base=cwd / marker) if marker else None
+    marker = USER_TARGETS.get(name)
+    return Target(name=name, scope="user", base=home / marker) if marker else None
+
+
+def detect_targets(*, home: Path, cwd: Path) -> list[Target]:
+    """Every known target whose marker directory already exists — the tool is in use,
+    so offering to drop a skill inside it is not an intrusion. User scope first."""
+    found: list[Target] = []
+    for name, marker in USER_TARGETS.items():
+        base = home / marker
+        if base.is_dir():
+            found.append(Target(name=name, scope="user", base=base))
+    for name, marker in PROJECT_TARGETS.items():
+        base = cwd / marker
+        if base.is_dir():
+            found.append(Target(name=name, scope="project", base=base))
+    return found
+
+
+def install_into(skills_dir: Path, text: str) -> Path:
+    """Write `text` as `<skills_dir>/skit/SKILL.md` (idempotent: rewriting is how an
+    upgrade lands). Returns the written file's path. Deliberately write-only — the
+    caller resolves the bundled copy via skill_text() first, so a broken installation
+    fails loudly there instead of masquerading as a destination write error here."""
+    dest = skills_dir / SKILL_DIR_NAME
+    dest.mkdir(parents=True, exist_ok=True)
+    out = dest / SKILL_FILE_NAME
+    # Same I/O kwarg equivalence; written content is pinned byte-for-byte by
+    # test_install_into_writes_and_upgrades (see docs/mutation-ledger.md).
+    out.write_text(text, encoding="utf-8")  # pragma: no mutate
+    return out

{skit_cli-0.0.1 → skit_cli-0.2.0}/src/skit/atomic.py

@@ -7,6 +7,7 @@ import os
 import shutil
 import sys
 import tempfile
+import time
 import tomllib
 from dataclasses import dataclass
 from pathlib import Path
@@ -14,6 +15,29 @@ from typing import Any
 
 import tomli_w
 
+# Windows can't replace a file that another handle has open (sharing violation →
+# PermissionError); concurrent readers of registry.toml hold it for microseconds, so a
+# bounded exponential backoff is the standard idiom (total worst-case wait ≈ 1.3 s).
+# POSIX replaces open files freely, so this path never fires there.
+_REPLACE_RETRIES = 7  # sleeps: 0.01 · 0.02 · 0.04 · 0.08 · 0.16 · 0.32 · 0.64 s
+_REPLACE_BACKOFF_START = 0.01
+
+
+def _replace_with_retry(src: str, dst: Path) -> None:
+    """os.replace that rides out transient Windows sharing violations. After the
+    retries are exhausted, the final attempt's PermissionError propagates — a target
+    held open indefinitely (antivirus, an actual leak) must stay loud."""
+    delay = _REPLACE_BACKOFF_START
+    for _ in range(_REPLACE_RETRIES):
+        try:
+            os.replace(src, dst)
+        except PermissionError:
+            time.sleep(delay)
+            delay *= 2
+        else:
+            return
+    os.replace(src, dst)
+
 
 def _fsync_dir(dir_path: Path) -> None:
     """Fsync a directory fd so a prior os.replace()'s rename entry is durable on stable storage.
@@ -39,7 +63,7 @@ def atomic_write_bytes(path: Path, data: bytes) -> None:
             f.write(data)
             f.flush()
             os.fsync(f.fileno())  # durable on disk BEFORE the rename, not just before this returns
-        os.replace(tmp, path)
+        _replace_with_retry(tmp, path)
         if sys.platform != "win32":  # os.open can't open a directory on Windows
             with contextlib.suppress(OSError):
                 _fsync_dir(path.parent)  # best-effort: persist the rename's directory entry too