skit-cli 0.0.1__py3-none-any.whl

skit/launcher.py

@@ -0,0 +1,326 @@
+"""Launcher: assemble the run command and execute it straight through the terminal (C2/C5/C6).
+
+- python entries: always `uv run --no-project --script <path>` (C2). `--script` alone does NOT
+  isolate a block-less script — uv attaches it to any enclosing project's environment (verified
+  empirically), so --no-project is unconditional; PEP 723 blocks and --with deps still resolve.
+- exe entries: run directly.
+- command entries: template + placeholder fill-in, executed through the shell.
+- The terminal is handed entirely to the child process (stdin/stdout/stderr pass through); the TUI
+  caller is responsible for suspend/resume.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import config
+from .i18n import gettext
+from .models import Entry
+from .paths import private_bin_dir
+
+
+class LaunchError(Exception):
+    pass
+
+
+class TargetMissingError(LaunchError):
+    """The launch target (script file / executable) is gone from disk.
+
+    A distinct type so `skit run` can map it to exit 127 (command not found, docker
+    convention) while other skit-side failures map to 125 — scripts that themselves
+    exit 1 stay distinguishable from skit failing to launch them at all."""
+
+
+class NotExecutableError(LaunchError):
+    """The exe target exists but has no execute permission (exit 126, docker convention)."""
+
+
+def find_uv() -> str | None:
+    """Detection order: PATH -> skit's private bin (A9/§5.6)."""
+    found = shutil.which("uv")
+    if found:
+        return found
+    private = private_bin_dir() / "uv"
+    if private.exists():
+        return str(private)
+    private_exe = private_bin_dir() / "uv.exe"
+    if private_exe.exists():
+        return str(private_exe)
+    return None
+
+
+def ensure_uv() -> str:
+    """Find uv or auto-download a managed copy (first-run experience: zero user action). Raises
+    LaunchError on failure."""
+    found = find_uv()
+    if found:
+        return found
+    from . import uvman
+
+    try:
+        return uvman.ensure_uv_downloaded()
+    except uvman.UvDownloadError as exc:
+        raise LaunchError(
+            f"{gettext('uv not found. Install it (https://docs.astral.sh/uv/) or run skit doctor for guidance.')} ({exc})"
+        ) from exc
+
+
+def _resolve_workdir(entry: Entry, invoke_cwd: Path) -> Path:
+    policy = entry.meta.workdir
+    if policy == "origin":
+        src = entry.meta.source
+        origin_dir = Path(src).parent if src else invoke_cwd
+        if entry.meta.mode == "copy" and not origin_dir.is_dir():
+            # Copy mode exists to decouple the entry from its original location, so a vanished
+            # origin must not block a run when the store copy is intact — this also recovers
+            # entries persisted with workdir="origin" before store.add_python's copy-mode default
+            # changed to "invoke". Reference-mode entries are not decoupled from their origin (the
+            # script check already fails first with a clearer message if it's gone), so they keep
+            # resolving to the origin dir unconditionally.
+            return invoke_cwd
+        return origin_dir
+    if policy == "store":
+        return entry.dir
+    if policy == "invoke":
+        return invoke_cwd
+    return Path(policy)  # absolute path
+
+
+def _check_script_exists(script: Path) -> None:
+    if not script.exists():
+        raise TargetMissingError(
+            gettext("The script file doesn't exist: %(path)s") % {"path": str(script)}
+        )
+
+
+def _check_exe_exists(source: str) -> None:
+    path = Path(source)
+    if not path.exists():
+        raise TargetMissingError(
+            gettext("The executable doesn't exist: %(path)s") % {"path": source}
+        )
+    if sys.platform != "win32" and path.is_file() and not os.access(path, os.X_OK):
+        raise NotExecutableError(
+            gettext("%(path)s exists but isn't executable (chmod +x it?).") % {"path": source}
+        )
+
+
+def _build_python(entry: Entry, extra: list[str], script_override: Path | None) -> list[str]:
+    # Check the cheap, local condition (does the script exist?) before the potentially-network-
+    # bound one (is uv installed, or does it need downloading?) — mirrors preflight's ordering, and
+    # spares a user with a missing script a pointless uv download/error first.
+    script = script_override or entry.script_path
+    _check_script_exists(script)
+    uv = ensure_uv()
+    # C2: unconditional isolation. Without --no-project, `uv run --script` attaches a
+    # block-less script to whatever uv project encloses the cwd (empirically verified) —
+    # and copy-mode entries default to workdir="invoke", so "run it from inside any
+    # project directory" was a live hijack path. Scripts with a PEP 723 block and
+    # reference-mode --with deps are unaffected by the flag.
+    cmd = [uv, "run", "--no-project"]
+    # In reference mode, dependencies are recorded in meta (the original file can't take a PEP 723
+    # block), so pass them via --with/--python.
+    if entry.meta.requires_python:
+        cmd += ["--python", entry.meta.requires_python]
+    for dep in entry.meta.dependencies or []:
+        cmd += ["--with", dep]
+    return [*cmd, "--script", str(script), *extra]
+
+
+def _build_exe(entry: Entry, extra: list[str]) -> list[str]:
+    exe = entry.meta.source
+    _check_exe_exists(exe)
+    return [exe, *extra]
+
+
+def _quote_for_shell(value: str) -> str:
+    """Quote a single substituted value for the platform shell _build_shell executes under,
+    mirroring how `extra` args are already quoted below (shlex on POSIX, list2cmdline on Windows) —
+    otherwise a value with spaces or shell metacharacters reshapes the command's argument
+    structure or, worse, injects extra shell syntax."""
+    if sys.platform == "win32":
+        return subprocess.list2cmdline([value])
+    return shlex.quote(value)
+
+
+# Matches, left to right: a `{{` escape, a `}}` escape, or a `{name}` placeholder (the same
+# identifier rule as store.extract_placeholders). Substitution and escape-restoration run together
+# in ONE pass over the ORIGINAL template via this pattern so replacement text is never re-scanned —
+# doing it as two sequential passes (substitute placeholders, then str.replace "{{"/"}}") would
+# corrupt any substituted value that itself contains "{{" or "}}".
+_TEMPLATE_TOKEN_RE = re.compile(r"\{\{|\}\}|(?<!\{)\{([a-zA-Z_][a-zA-Z0-9_]*)\}(?!\})")
+
+
+def _build_shell(entry: Entry, extra: list[str], values: dict[str, str] | None) -> str:
+    template = entry.meta.template
+    vals = values or {}
+    if entry.meta.params:
+        missing = [p for p in entry.meta.params if p not in vals]
+        if missing:
+            raise LaunchError(
+                gettext("Missing parameter values: %(names)s") % {"names": ", ".join(missing)}
+            )
+
+    def repl(m: re.Match[str]) -> str:
+        matched = m.group(0)
+        if matched == "{{":
+            return "{"
+        if matched == "}}":
+            return "}"
+        name = m.group(1)
+        if name is None or name not in vals:
+            return matched
+        return _quote_for_shell(vals[name])
+
+    cmd = _TEMPLATE_TOKEN_RE.sub(repl, template)
+    if extra:
+        # shell=True execution: quoting must follow that platform's shell (POSIX uses shlex, Windows
+        # cmd uses list2cmdline), or arguments containing $ or backticks would be expanded.
+        if sys.platform == "win32":
+            cmd = cmd + " " + subprocess.list2cmdline(extra)
+        else:
+            cmd = cmd + " " + shlex.join(extra)
+    return cmd
+
+
+def build_command(
+    entry: Entry,
+    extra_args: list[str] | None = None,
+    values: dict[str, str] | None = None,
+    *,
+    script_override: Path | None = None,
+) -> list[str] | str:
+    """Return an argv list (python/exe) or a shell string (command).
+
+    values: fill-ins for the named placeholders of a command template (missing values raise
+    LaunchError).
+    script_override: the temporary script path after shim injection (python entries only; A5 leaves
+    the original copy untouched).
+    """
+    extra = extra_args or []
+    kind = entry.meta.kind
+    if kind == "python":
+        return _build_python(entry, extra, script_override)
+    if kind == "exe":
+        return _build_exe(entry, extra)
+    if kind == "command":
+        return _build_shell(entry, extra, values)
+    raise LaunchError(gettext("Unknown entry kind: %(kind)s") % {"kind": kind})
+
+
+def describe_command(
+    entry: Entry,
+    extra_args: list[str] | None = None,
+    values: dict[str, str] | None = None,
+    *,
+    script_override: Path | None = None,
+) -> str:
+    """A purely descriptive command line for transparency output and --dry-run: no uv
+    lookup or download, no existence checks, no side effects. Mirrors build_command's
+    shape; when uv isn't installed yet the literal "uv" stands in."""
+    extra = extra_args or []
+    kind = entry.meta.kind
+    if kind == "python":
+        uv = find_uv() or "uv"
+        cmd = [uv, "run", "--no-project"]  # mirrors _build_python's unconditional C2 isolation
+        if entry.meta.requires_python:
+            cmd += ["--python", entry.meta.requires_python]
+        for dep in entry.meta.dependencies or []:
+            cmd += ["--with", dep]
+        script = script_override or entry.script_path
+        return _join_for_display([*cmd, "--script", str(script), *extra])
+    if kind == "exe":
+        return _join_for_display([entry.meta.source, *extra])
+    try:
+        built = _build_shell(entry, extra, values)
+    except LaunchError:
+        built = entry.meta.template
+    return built
+
+
+def _join_for_display(argv: list[str]) -> str:
+    if sys.platform == "win32":
+        return subprocess.list2cmdline(argv)
+    return shlex.join(argv)
+
+
+def target_missing(entry: Entry) -> bool:
+    """Whether entry's launch target is already known to be gone from disk: the source path for
+    exe/reference entries, the stored copy for copy-mode python. Command entries have no file
+    target and never report missing."""
+    if entry.meta.kind == "exe":
+        return not Path(entry.meta.source).exists()
+    if entry.meta.kind == "python":
+        return not entry.script_path.exists()
+    return False  # command entries have no file target
+
+
+def missing_marker(entry: Entry) -> str | None:
+    """A human-readable "target is missing" message for entry, or None when it's healthy or has no
+    file target (command entries). Callers decide how to style/render it (TUI table, CLI list).
+    exe entries are always reference-mode, so script_path is exactly their source path."""
+    if not target_missing(entry):
+        return None
+    return gettext("⚠ missing: %(path)s") % {"path": str(entry.script_path)}
+
+
+def _check_workdir(cwd: Path) -> None:
+    if not cwd.is_dir():
+        raise LaunchError(
+            gettext("The working directory doesn't exist: %(path)s") % {"path": str(cwd)}
+        )
+
+
+def preflight(entry: Entry, invoke_cwd: Path | None = None) -> None:
+    """Validate what can be checked before any values/params are collected: the launch target
+    (script/exe) and the working directory. Raises LaunchError with the same messages the actual
+    build/run would eventually raise, but does none of the actual work (no uv lookup/download, no
+    process spawn) — so the TUI can call this before suspending the terminal."""
+    if entry.meta.kind == "python":
+        _check_script_exists(entry.script_path)
+    elif entry.meta.kind == "exe":
+        _check_exe_exists(entry.meta.source)
+    _check_workdir(_resolve_workdir(entry, invoke_cwd or Path.cwd()))
+
+
+def run_entry(
+    entry: Entry,
+    extra_args: list[str] | None = None,
+    *,
+    values: dict[str, str] | None = None,
+    invoke_cwd: Path | None = None,
+    script_override: Path | None = None,
+) -> int:
+    """Run straight through the terminal and return the exit code.
+
+    The TUI must be suspended before calling this.
+    """
+    cmd = build_command(entry, extra_args, values, script_override=script_override)
+    cwd = _resolve_workdir(entry, invoke_cwd or Path.cwd())
+    _check_workdir(cwd)
+    # Overlay skit's mirror settings onto uv's environment — a no-op unless the user enabled them,
+    # and never clobbering a variable the user set themselves (see config.mirror_env).
+    env = {**os.environ, **config.mirror_env(os.environ)}
+    if isinstance(cmd, str):
+        # A command entry is by definition "a shell command the user registered"; shell=True is a
+        # feature, not a hole. The template was written by the user via `skit add`, so the trust
+        # boundary is the same as the user's own shell history.
+        proc = subprocess.run(cmd, shell=True, cwd=cwd, check=False, env=env)  # noqa: S602  # pragma: no mutate — check=None is falsy-equivalent to False; omitting it matches subprocess.run's own default
+    else:
+        proc = subprocess.run(cmd, cwd=cwd, check=False, env=env)  # noqa: S603 — argv from a user entry  # pragma: no mutate — check=None is falsy-equivalent to False; omitting it matches subprocess.run's own default
+    return _normalize_exit_code(proc.returncode)
+
+
+def _normalize_exit_code(returncode: int) -> int:
+    """Map subprocess.run's signal-death reporting (a negative returncode -N for "killed by signal
+    N") onto the conventional shell exit status 128+N, matching what a user would see running the
+    same command directly in a POSIX shell. Left as a raw negative number, it would be silently
+    mangled by sys.exit (which reduces any status to a byte via `& 0xFF`, e.g. -11 -> 245) while
+    also being printed to the user as a confusing negative code."""
+    return returncode if returncode >= 0 else 128 - returncode

skit/metawriter.py

@@ -0,0 +1,267 @@
+"""MetaWriter: write parameter definitions into the `[tool.skit]` table of a PEP 723 block (A5/A6).
+
+Strict discipline:
+- **Plain-text operations, never through the AST** — never reorder or reformat a single line of the
+  user's code.
+- Only touch the `# /// script … # ///` comment block; create one (with empty dependencies) if none
+  exists.
+- Inside the block, only the `[tool.skit]` section is replaced; everything else (dependencies, other
+  tool tables) is preserved verbatim.
+- Definitions travel with the file (portable, hand-editable); values and presets live in central
+  state (argstate).
+
+Shape of `[tool.skit]` (the TOML once comment prefixes are stripped):
+
+    [tool.skit]
+    schema = 1
+
+    [[tool.skit.params]]
+    name = "API_KEY"
+    kind = "const"          # const | input
+    type = "str"            # str | int | float | bool
+    default = "xxx"         # const: the source value (absent for input)
+    prompt = "API key: "    # input: the original prompt; const may set a custom form prompt
+    order = 0               # input: the call-order key (B1); omitted for const
+    secret = true           # C3: the value never lands in a state file
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from . import pep723
+
+if TYPE_CHECKING:
+    from .analyzer import Candidate
+
+SCT_SCHEMA = 1
+
+_BLOCK_RE = re.compile(
+    # See the identical comment on pep723._BLOCK_RE: the closer's trailing whitespace is restricted
+    # to horizontal whitespace so a greedy `\s*$` can't cross a line boundary and swallow blank lines
+    # that follow the block, deleting them on rewrite.
+    r"(?m)^# /// script\s*$\n(?P<body>(?:^#(?:| .*)$\n)*?)^# ///[^\S\n]*$\n?",
+)
+
+
+@dataclass
+class ParamSpec:
+    """One `[[tool.skit.params]]`. Field-aligned with analyzer.Candidate and inter-convertible."""
+
+    name: str
+    kind: str = "const"  # "const" | "input"
+    type: str = "str"
+    default: str | int | float | bool | None = None
+    prompt: str = ""
+    order: int = -1
+    secret: bool = False
+    # Secret-value source: the name of an environment variable to read at run time instead of
+    # asking on every run. Stores WHERE to find the value, never the value itself — the reason
+    # this may live in a plain-text file at all (C3: values never land on disk; a variable
+    # *name* is not a secret).
+    env_source: str = ""
+
+    @classmethod
+    def from_candidate(cls, c: Candidate) -> ParamSpec:
+        """Build a managed-parameter spec from an analyzer.Candidate (the two are
+        field-aligned by design — A2). The one place this conversion lives, so the CLI,
+        TUI add panel, TUI settings, and reconcile can't drift on which fields carry over."""
+        return cls(
+            name=c.name,
+            kind=c.kind,
+            type=c.type,
+            default=c.default,
+            prompt=c.prompt,
+            order=c.order,
+            secret=c.secret,
+        )
+
+    def to_dict(self) -> dict[str, str | int | float | bool]:
+        d: dict[str, str | int | float | bool] = {
+            "name": self.name,
+            "kind": self.kind,
+            "type": self.type,
+        }
+        if self.default is not None:
+            d["default"] = self.default
+        if self.prompt:
+            d["prompt"] = self.prompt
+        if self.order >= 0:
+            d["order"] = self.order
+        if self.secret:
+            d["secret"] = True
+        if self.env_source:
+            d["env_source"] = self.env_source
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ParamSpec:
+        # read_params is contracted to be total: a hand-edited `order` can be any valid TOML scalar
+        # (e.g. a non-numeric string), so an uncoercible value must fall back to "no explicit order"
+        # rather than raising and crashing every caller (TUI load, `skit params`/`run`/`edit`).
+        try:
+            order = int(d.get("order", -1))
+        except (TypeError, ValueError):
+            order = -1
+        return cls(
+            name=str(d.get("name", "")),
+            kind=str(d.get("kind", "const")),
+            type=str(d.get("type", "str")),
+            default=d.get("default"),
+            prompt=str(d.get("prompt", "")),
+            order=order,
+            secret=bool(d.get("secret", False)),
+            env_source=str(d.get("env_source", "")),
+        )
+
+
+@dataclass
+class SctMeta:
+    params: list[ParamSpec] = field(default_factory=list)
+
+
+def _toml_str(value: str) -> str:
+    r"""A TOML basic string. Control characters must be escaped: if a prompt contains something like
+    \n and is emitted verbatim, it splits the string across comment lines, the rewritten block fails
+    to parse, and all definitions are lost."""
+    out = value.replace("\\", "\\\\").replace('"', '\\"')
+    out = out.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+
+    # A TOML basic string forbids unescaped U+0000..U+001F and U+007F; escape those.
+    # ALSO escape U+0085/U+2028/U+2029: TOML permits them literally, but _commentify splits
+    # the rewritten block with str.splitlines(), which breaks on those three too — an
+    # unescaped one would shred the comment body and drop every managed param definition.
+    def _escape(ch: str) -> str:
+        if ch < " " or ch in ("\x7f", "\x85", "\u2028", "\u2029"):  # pragma: no mutate
+            return f"\\u{ord(ch):04X}"
+        return ch
+
+    out = "".join(_escape(ch) for ch in out)
+    return '"' + out + '"'
+
+
+def _toml_value(value: str | int | float | bool) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    return _toml_str(value)
+
+
+def render_skit_toml(params: list[ParamSpec]) -> str:
+    """Generate the comment-stripped [tool.skit] TOML text (without the comment prefix)."""
+    lines = ["[tool.skit]", f"schema = {SCT_SCHEMA}"]
+    for p in params:
+        lines.append("")
+        lines.append("[[tool.skit.params]]")
+        for key, val in p.to_dict().items():
+            lines.append(f"{key} = {_toml_value(val)}")
+    return "\n".join(lines) + "\n"
+
+
+def _commentify(toml_text: str) -> list[str]:
+    return [("# " + ln).rstrip() for ln in toml_text.splitlines()]
+
+
+def _strip_comment_prefix(line: str) -> str:
+    if line.startswith("# "):  # pragma: no mutate — prefix length is unobservable, re-stripped next
+        return line[2:]
+    if line.startswith("#"):
+        return line[1:]
+    return line
+
+
+def _strip_skit_section(body_lines: list[str]) -> list[str]:
+    """Remove any existing [tool.skit] section (and its [[tool.skit.params]]) from the block body,
+    keeping the rest."""
+    out: list[str] = []
+    skipping = False  # pragma: no mutate — only read via truthiness (`if not skipping`)
+    for line in body_lines:
+        stripped = _strip_comment_prefix(line).strip()
+        if stripped.startswith("["):
+            in_skit = stripped.startswith("[tool.skit]") or stripped.startswith("[[tool.skit.")
+            skipping = in_skit
+        if not skipping:
+            out.append(line)
+    # Drop trailing empty comment lines.
+    while out and out[-1].strip() in ("#", ""):
+        out.pop()
+    return out
+
+
+def _drop_synthetic_separator(base: str, original: str) -> str:
+    """Undo inject_block()'s optional blank-line separator when write_params() is about to fill the
+    freshly-created block with params in the same operation.
+
+    inject_block() inserts a blank line between the closer and the following code purely for
+    readability when it is used on its own (e.g. `skit deps` adding a bare dependencies-only
+    block). But when write_params() creates the block itself (this is the "no block yet, non-empty
+    params" path), that blank line would be the ONLY thing ever added outside the
+    "# /// … # ///" block — breaking the comment-only-edits contract (A5) and the golden-corpus
+    byte-fidelity invariant. Detected structurally (not by re-deriving inject_block's shebang/coding
+    insertion logic): strip exactly one blank line, and only when it truly is synthetic (i.e.
+    `original`'s own content did not already start with a blank line at that point — inject_block
+    itself skips the separator in that case, to avoid a double blank line).
+    """
+    block_only = pep723.build_block([])
+    idx = base.index(block_only)
+    prefix = base[:idx]
+    rest = base[idx + len(block_only) :]
+    suffix = original[len(prefix) :]
+    if rest == "\n" + suffix:
+        return prefix + block_only + suffix
+    return base
+
+
+def write_params(text: str, params: list[ParamSpec]) -> str:
+    """Write (or replace) the script's [tool.skit] with the parameter definitions. Empty params
+    means removing the section.
+
+    - Existing PEP 723 block: replace/append [tool.skit] inside the block, other lines verbatim.
+    - No block and non-empty params: create a block with empty dependencies (same insertion point as
+      pep723.inject_block).
+    """
+    m = _BLOCK_RE.search(text)
+    if m is None:
+        if not params:
+            return text
+        base = pep723.inject_block(
+            text, []
+        )  # pragma: no mutate — build_block only checks truthiness of dependencies
+        # inject_block has inserted the block; recurse once through the "block exists" path.
+        if _BLOCK_RE.search(base) is None:  # pragma: no cover — inject_block guarantees a block
+            raise RuntimeError("inject_block failed to create a PEP 723 block")
+        base = _drop_synthetic_separator(base, text)
+        return write_params(base, params)
+    body_lines = m.group("body").splitlines()
+    kept = _strip_skit_section(body_lines)
+    new_body_lines = list(kept)
+    if params:
+        if new_body_lines:
+            new_body_lines.append("#")
+        new_body_lines.extend(_commentify(render_skit_toml(params)))
+    new_block = "# /// script\n"
+    if new_body_lines:
+        new_block += "\n".join(new_body_lines) + "\n"
+    new_block += "# ///\n"
+    return text[: m.start()] + new_block + text[m.end() :]
+
+
+def read_params(text: str) -> list[ParamSpec]:
+    """Read the script's [tool.skit] parameter definitions; empty list if no block/section/parse."""
+    meta = pep723.parse_block(text)
+    if not meta:
+        return []
+    # All valid TOML, all defended: `tool`, `tool.skit`, and `tool.skit.params` could each be a
+    # scalar (e.g. `tool = 5`) rather than the table/array shape this module writes. read_params is
+    # contracted to be total ("empty list if no block/section/parse"), so a malformed shape must
+    # fall back to [] rather than raising AttributeError/TypeError out of the `.get` chain or the
+    # iteration below.
+    tool = meta.get("tool")
+    skit = tool.get("skit") if isinstance(tool, dict) else None
+    raw = skit.get("params") if isinstance(skit, dict) else None
+    if not isinstance(raw, list):
+        return []
+    return [ParamSpec.from_dict(d) for d in raw if isinstance(d, dict) and d.get("name")]