skit-cli 0.0.1__py3-none-any.whl

skit/models.py

@@ -0,0 +1,154 @@
+"""Data models: meta.toml (per-script, self-describing) and registry index entries.
+
+meta.toml is the source of truth; registry.toml is only an index (rebuildable via doctor --rebuild).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from .i18n import gettext
+
+SCHEMA_VERSION = 1
+
+Kind = Literal["python", "exe", "command"]
+Mode = Literal["copy", "reference"]
+Workdir = str  # "origin" | "store" | "invoke" | absolute path
+
+
+class ScriptMetaError(ValueError):
+    """meta.toml parsed as valid TOML but is missing a key ScriptMeta requires.
+
+    Distinguished from a bare KeyError so store.py's corruption handling (which already treats
+    malformed/unreadable meta.toml as "corrupt, skip and let doctor --rebuild report it") can catch
+    this alongside tomllib.TOMLDecodeError instead of a crash escaping list/resolve/doctor.
+    """
+
+
+@dataclass
+class ScriptMeta:
+    """Maps to scripts/<slug>/meta.toml."""
+
+    name: str
+    kind: Kind
+    mode: Mode = "copy"
+    source: str = ""  # provenance: original path at add time (also for exe/command)
+    source_hash: str = ""  # "sha256:…"; empty for command entries
+    added_at: str = ""
+    workdir: Workdir = "origin"
+    description: str = ""
+    template: str = ""  # command template when kind=command
+    dependencies: list[str] | None = None  # recorded deps when reference mode can't inject PEP 723
+    requires_python: str = ""  # same; in copy mode both are written into the copy's PEP 723 block
+    params: list[str] | None = (
+        None  # named placeholders in a command template (prompted before run)
+    )
+    schema: int = SCHEMA_VERSION
+
+    def to_toml_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "schema": self.schema,
+            "name": self.name,
+            "kind": self.kind,
+            "mode": self.mode,
+            "source": self.source,
+            "source_hash": self.source_hash,
+            "added_at": self.added_at,
+            "workdir": self.workdir,
+            "description": self.description,
+        }
+        if self.template:
+            d["template"] = self.template
+        if self.dependencies:
+            d["dependencies"] = self.dependencies
+        if self.requires_python:
+            d["requires_python"] = self.requires_python
+        if self.params:
+            d["params"] = self.params
+        return d
+
+    @classmethod
+    def from_toml_dict(cls, d: dict[str, Any]) -> ScriptMeta:
+        """Validate at the model boundary: a meta.toml can be well-formed TOML yet structurally
+        invalid (missing keys, or a scalar where a list is required). Every such case must raise
+        ScriptMetaError — never a raw KeyError/TypeError — so store.py's corruption handling
+        (_META_CORRUPTION) can catch it uniformly instead of it crashing list/resolve/doctor."""
+        missing = [key for key in ("name", "kind") if key not in d]
+        if missing:
+            raise ScriptMetaError(
+                gettext("meta.toml is missing required key(s): %(keys)s")
+                % {"keys": ", ".join(missing)}
+            )
+        invalid = [key for key in ("name", "kind") if not isinstance(d[key], str)]
+        invalid += [
+            key
+            for key in ("dependencies", "params")
+            if d.get(key) is not None and not isinstance(d[key], list)
+        ]
+        if invalid:
+            raise ScriptMetaError(
+                gettext("meta.toml has invalid type for key(s): %(keys)s")
+                % {"keys": ", ".join(invalid)}
+            )
+        return cls(
+            name=d["name"],
+            kind=d["kind"],
+            mode=d.get("mode", "copy"),
+            source=d.get("source", ""),
+            source_hash=d.get("source_hash", ""),
+            added_at=d.get("added_at", ""),
+            workdir=d.get("workdir", "origin"),
+            description=d.get("description", ""),
+            template=d.get("template", ""),
+            dependencies=list(d["dependencies"]) if d.get("dependencies") else None,
+            requires_python=d.get("requires_python", ""),
+            params=list(d["params"]) if d.get("params") else None,
+            schema=d.get("schema", SCHEMA_VERSION),
+        )
+
+
+@dataclass
+class RegistryEntry:
+    """A single index row in registry.toml."""
+
+    name: str
+    slug: str
+    kind: Kind
+    description: str = ""
+
+
+@dataclass
+class Entry:
+    """Combined view: index + full meta + directory path. The primary object of the Core API."""
+
+    slug: str
+    meta: ScriptMeta
+    dir: Path
+
+    @property
+    def script_path(self) -> Path:
+        """The in-store script in copy mode; the original path in reference mode."""
+        if self.meta.mode == "reference":
+            return Path(self.meta.source)
+        return self.dir / ("script.py" if self.meta.kind == "python" else "payload")
+
+
+def now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def slugify(name: str) -> str:
+    out: list[str] = []
+    prev_dash = False  # pragma: no mutate — falsy-equivalent init; `and out` guard hides it while out is empty
+    for ch in name.strip().lower():
+        if ch.isalnum():
+            out.append(ch)
+            prev_dash = False  # pragma: no mutate — falsy-equivalent; only read via truthiness
+        elif not prev_dash and out:
+            out.append("-")
+            prev_dash = True
+    slug = "".join(out).strip("-")  # pragma: no mutate — text already lowercased
+    return slug or "script"

skit/paths.py

@@ -0,0 +1,44 @@
+"""Directory resolution. Everything goes through platformdirs; overridable via env vars (for tests).
+
+SKIT_DATA_DIR / SKIT_STATE_DIR / SKIT_CONFIG_DIR override the matching root directory.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from platformdirs import user_config_dir, user_data_dir, user_state_dir
+
+_APP = "skit"
+
+
+def data_dir() -> Path:
+    override = os.environ.get("SKIT_DATA_DIR")
+    return Path(override) if override else Path(user_data_dir(_APP))
+
+
+def state_dir() -> Path:
+    override = os.environ.get("SKIT_STATE_DIR")
+    return Path(override) if override else Path(user_state_dir(_APP))
+
+
+def config_dir() -> Path:
+    override = os.environ.get("SKIT_CONFIG_DIR")
+    return Path(override) if override else Path(user_config_dir(_APP))
+
+
+def scripts_dir() -> Path:
+    return data_dir() / "scripts"
+
+
+def registry_path() -> Path:
+    return data_dir() / "registry.toml"
+
+
+def private_bin_dir() -> Path:
+    return data_dir() / "bin"
+
+
+def values_dir() -> Path:
+    return state_dir() / "values"

skit/pep723.py

@@ -0,0 +1,292 @@
+"""PEP 723 inline script metadata: parse, generate, inject (comment-only edits, A5).
+
+- parse_block(): read the `# /// script` block from a script.
+- suggest_dependencies(): walk imports via AST, diff against stdlib, suggest third-party deps.
+- inject_block(): insert the completed block into the script text (after shebang / encoding lines).
+  The injected content is pure comments and changes no semantics, so a copy-mode copy just runs.
+
+This module is headless; it imports neither CLI nor TUI.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+import sys
+import tomllib
+from typing import Any
+
+_BLOCK_RE = re.compile(
+    # The closer's trailing whitespace is restricted to horizontal whitespace ([^\S\n], i.e. space /
+    # tab / \r for CRLF) so it cannot cross a line boundary and swallow blank lines that follow the
+    # block — `\s*$` would otherwise match greedily across newlines and absorb them into the block,
+    # deleting them on rewrite (metawriter/pep723 both rebuild the text from m.end()).
+    r"(?m)^# /// script\s*$\n(?P<body>(?:^#(?:| .*)$\n)*?)^# ///[^\S\n]*$\n?",
+)
+
+# Import name -> PyPI distribution name, for the common cases where they differ. Without this an
+# `import PIL` becomes a `PIL` dependency, which uv can't resolve (the package is `Pillow`). Curated
+# and stdlib-only (a static dict, no network / importlib.metadata probing): we only rewrite names we
+# are sure about and leave everything else untouched.
+_IMPORT_TO_PACKAGE = {
+    "PIL": "Pillow",
+    "cv2": "opencv-python",
+    "yaml": "PyYAML",
+    "bs4": "beautifulsoup4",
+    "sklearn": "scikit-learn",
+    "skimage": "scikit-image",
+    "dotenv": "python-dotenv",
+    "dateutil": "python-dateutil",
+    "serial": "pyserial",
+    "jwt": "PyJWT",
+    "docx": "python-docx",
+    "pptx": "python-pptx",
+    "fitz": "PyMuPDF",
+    "OpenSSL": "pyOpenSSL",
+    "Crypto": "pycryptodome",
+    "Cryptodome": "pycryptodomex",
+    "git": "GitPython",
+    "attr": "attrs",
+    "slugify": "python-slugify",
+    "usb": "pyusb",
+    "win32com": "pywin32",
+    "win32api": "pywin32",
+}
+
+
+def _strip_comment_prefix(line: str) -> str:
+    """_BLOCK_RE guarantees "#" or "# ..." lines; both branches agree on a bare "#"."""
+    if line.startswith("# "):  # pragma: no mutate — TOML tolerates the extra leading space
+        return line[2:]
+    return line[1:]  # pragma: no mutate — only reached on a bare "#"; [1:] == [2:] == ""
+
+
+def parse_block(text: str) -> dict[str, Any] | None:
+    """Return the PEP 723 metadata dict (dependencies / requires-python); None if no block."""
+    m = _BLOCK_RE.search(text)
+    if not m:
+        return None
+    lines = [_strip_comment_prefix(line) for line in m.group("body").splitlines()]
+    try:
+        return tomllib.loads("\n".join(lines))
+    except tomllib.TOMLDecodeError:
+        return None
+
+
+def has_block(text: str) -> bool:
+    return _BLOCK_RE.search(text) is not None
+
+
+def suggest_dependencies(text: str) -> list[str]:
+    """Scan imports, return the top-level module names that look third-party (sorted, deduped).
+
+    Returns an empty list on syntax errors.
+    """
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return []
+    found: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                found.add(alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            found.add(node.module.split(".")[0])
+    stdlib = sys.stdlib_module_names
+    third_party = (m for m in found if m not in stdlib and not m.startswith("_"))
+    # Map known import names to their real PyPI distribution names, then dedupe again in case two
+    # imports collapse to the same package (e.g. `Crypto` and its submodules -> pycryptodome).
+    return sorted({_IMPORT_TO_PACKAGE.get(m, m) for m in third_party})
+
+
+def _next_nonspace(text: str, pos: int) -> str:
+    """The first non-whitespace character at or after pos, or "" when none is left."""
+    for ch in text[pos:]:
+        if not ch.isspace():
+            return ch
+    return ""
+
+
+def split_requirements(text: str) -> list[str]:
+    """Split a comma-separated requirement list without shredding PEP 508 internals.
+
+    A single requirement may itself contain commas — in a version-specifier list
+    (``requests>=2,<3``), an extras bracket (``pkg[security,socks]``), a parenthesized
+    specifier (``foo (>=1.0,<2.0)``), or a quoted marker value
+    (``x; sys_platform in "linux,darwin"``). A naive ``split(",")`` turns
+    ``requests>=2,<3`` into the two bogus items ``requests>=2`` and ``<3``.
+
+    A comma separates two requirements only when it sits outside brackets/quotes AND
+    what follows starts a new requirement: PEP 508 names begin with a letter or digit,
+    while a continued specifier clause always begins with an operator (``<`` ``>``
+    ``=`` ``!`` ``~``). A trailing comma (nothing follows) also terminates. Known
+    limitation: a direct-URL reference whose URL itself contains a comma is not
+    supported (rare enough that guessing would be worse).
+    """
+    parts: list[str] = []
+    buf: list[str] = []
+    depth = 0
+    quote = ""  # pragma: no mutate — falsy-equivalent sentinel (""/None): only read via truthiness
+    for i, ch in enumerate(text):
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = ""  # pragma: no mutate — falsy-equivalent sentinel, as above
+            continue
+        if ch in ('"', "'"):
+            quote = ch
+        elif ch in "([":
+            depth += 1
+        elif ch in ")]":
+            depth -= 1
+        elif ch == "," and depth == 0:
+            nxt = _next_nonspace(text, i + 1)
+            if not nxt or nxt.isalnum():
+                parts.append("".join(buf))
+                buf = []
+                continue
+        buf.append(ch)
+    parts.append("".join(buf))
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _toml_str(value: str) -> str:
+    r"""A TOML basic string for the PEP 723 comment block. A raw double quote or backslash
+    would terminate/mangle the string — a PEP 508 marker like `; python_version >= "3.8"`
+    carries embedded quotes — and any newline-class character would break out of the single
+    comment line the block is built from, so the rewritten block fails to re-parse and the
+    dependency list is silently lost. (Kept local: metawriter imports pep723, so pep723 must
+    not import back for the shared _toml_str.)"""
+    out = value.replace("\\", "\\\\").replace('"', '\\"')
+    out = out.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+
+    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
+
+    return '"' + "".join(_escape(ch) for ch in out) + '"'
+
+
+def build_block(dependencies: list[str], requires_python: str = "") -> str:
+    """Generate the PEP 723 block text (including the trailing newline)."""
+    lines = ["# /// script"]
+    if requires_python:
+        lines.append(f"# requires-python = {_toml_str(requires_python)}")
+    if dependencies:
+        lines.append("# dependencies = [")
+        lines.extend(f"#     {_toml_str(dep)}," for dep in dependencies)
+        lines.append("# ]")
+    else:
+        lines.append("# dependencies = []")
+    lines.append("# ///")
+    return "\n".join(lines) + "\n"
+
+
+def _structural_bracket_delta(s: str) -> int:
+    """Net count of structural `[` minus `]` in a line of TOML content (already stripped of its
+    leading PEP 723 `#`/`# ` comment marker).
+
+    A naive `s.count("[") - s.count("]")` over the raw text is wrong whenever a bracket lives
+    inside a TOML string value (e.g. a dependency string `"foo]bar"`) or inside an inline `#`
+    comment (e.g. `# pin later [`) — those brackets are data/prose, not array syntax, and must
+    not perturb the array-nesting depth used to find the real closing `]`.
+
+    This walks the line char-by-char, tracking whether we are inside a quoted string (TOML basic
+    `"..."` strings, where `\\` escapes the next char, or literal `'...'` strings, which have no
+    escapes) and stops counting entirely once an unquoted `#` starts an inline comment. Only
+    brackets seen outside a string and outside a comment are counted, which is exactly what makes
+    them structural TOML array syntax.
+    """
+    delta = 0
+    quote: str | None = None
+    i = 0
+    n = len(s)
+    while i < n:
+        ch = s[i]
+        if quote:
+            if quote == '"' and ch == "\\":
+                i += 2  # pragma: no mutate — skip the escaped char; only reachable via `"` strings
+                continue
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in ("'", '"'):
+            quote = ch
+        elif ch == "#":
+            break  # rest of the line is an inline TOML comment; nothing after this is structural
+        elif ch == "[":
+            delta += 1
+        elif ch == "]":
+            delta -= 1
+        i += 1
+    return delta
+
+
+def set_dependencies(text: str, dependencies: list[str], requires_python: str = "") -> str:
+    """Update the dependencies / requires-python lines in an existing block, keeping the rest
+    (such as [tool.skit]). With no block this behaves like inject_block. Still comment-only (A5)."""
+    m = _BLOCK_RE.search(text)
+    if not m:
+        return inject_block(text, dependencies, requires_python)
+    body_lines = m.group("body").splitlines()
+    kept: list[str] = []
+    in_deps_array = False  # pragma: no mutate — only read via truthiness (`if in_deps_array`)
+    depth = 0
+    for line in body_lines:
+        stripped = _strip_comment_prefix(line)
+        if in_deps_array:
+            # Track bracket nesting depth rather than requiring the closer to be alone on its line:
+            # a hand-edited array may close on the same line as the last element (`"requests"]`) or
+            # carry a trailing comment (`] # pin`). Only structural brackets count, so
+            # `"pkg[extra]"` requirement strings, a stray `]` inside a string (`"foo]bar"`), and a
+            # comment containing a bracket (`# pin later [`) can't desync the depth.
+            depth += _structural_bracket_delta(stripped)
+            if depth <= 0:
+                in_deps_array = False  # pragma: no mutate — only read via truthiness
+            continue
+        s = stripped.strip()
+        if s.startswith("requires-python"):
+            continue
+        if s.startswith("dependencies"):
+            # Multi-line array detection: `[` opened but not closed on the same line
+            # (including a `[  # comment` trailing-comment form). Structural-only counting here
+            # too, for the same reasons as the in-array depth tracking above.
+            net = _structural_bracket_delta(s)
+            if net > 0:
+                in_deps_array = True
+                depth = net
+            continue
+        kept.append(line)
+    new_head: list[str] = []
+    if requires_python:
+        new_head.append(f"# requires-python = {_toml_str(requires_python)}")
+    if dependencies:
+        new_head.append("# dependencies = [")
+        new_head.extend(f"#     {_toml_str(dep)}," for dep in dependencies)
+        new_head.append("# ]")
+    else:
+        new_head.append("# dependencies = []")
+    new_body = "\n".join(new_head + kept) + "\n"
+    new_block = "# /// script\n" + new_body + "# ///\n"
+    return text[: m.start()] + new_block + text[m.end() :]
+
+
+def inject_block(text: str, dependencies: list[str], requires_python: str = "") -> str:
+    """Insert the block at the top of the script (after shebang / coding declarations).
+    If a block already exists, return the text unchanged."""
+    if has_block(text):
+        return text
+    lines = text.splitlines(keepends=True)
+    insert_at = 0
+    if lines and lines[0].startswith("#!"):
+        insert_at = 1
+    if len(lines) > insert_at and re.match(r"^#.*coding[:=]", lines[insert_at]):
+        insert_at += 1
+    block = build_block(dependencies, requires_python)
+    prefix = "".join(lines[:insert_at])
+    suffix = "".join(lines[insert_at:])
+    sep = "\n" if suffix and not suffix.startswith("\n") else ""
+    return prefix + block + sep + suffix

skit/promptform.py

@@ -0,0 +1,67 @@
+"""Plain form renderer: the unified form as line prompts (rich Prompt/Confirm).
+
+One of the FormPlan renderers ("one flow, N renderings"): the TUI renders widgets,
+the inline mini-form renders a Textual window, and this renders the humble line-by-line
+questionnaire — the deliberate fallback for SSH, dumb terminals, and the `--plain`
+flag / `form = "plain"` preference. All logic (prefill, validation, assembly) lives in
+flows; this module only asks."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.markup import escape
+from rich.prompt import Confirm, Prompt
+
+from . import flows
+from .i18n import gettext
+
+
+def collect(
+    plan: flows.FormPlan,
+    prefill: dict[str, str],
+    *,
+    console: Console,
+) -> dict[str, str]:
+    """Ask for every field, re-prompting on a validation error. Returns raw (token/glob
+    original) values keyed by field key."""
+    values: dict[str, str] = {}
+    for f in plan.fields:
+        if f.help:
+            console.print(f"  [dim]{escape(f.help)}[/dim]")
+        if f.degraded:
+            console.print(f"  [dim]{gettext("Leave empty to use the script's own default.")}[/dim]")
+        values[f.key] = _ask_until_valid(f, prefill.get(f.key, ""), console)
+    return values
+
+
+def _ask_until_valid(f: flows.FormField, default: str, console: Console) -> str:
+    while True:
+        value = _ask_once(f, default, console)
+        error = flows.validate_value(f, value)
+        if error is None:
+            return value
+        console.print(f"  [red]{escape(error)}[/red]")
+
+
+def _ask_once(f: flows.FormField, default: str, console: Console) -> str:
+    label = escape(f.label)
+    if f.kind == "bool":
+        checked = Confirm.ask(
+            f"  {label}", default=default.strip().lower() in ("true", "1", "yes"), console=console
+        )
+        return "true" if checked else "false"
+    if f.secret:
+        if f.env_source:
+            console.print(
+                "  [dim]"
+                + gettext("Enter to read it from the environment variable %(env)s.")
+                % {"env": escape(f.env_source)}
+                + "[/dim]"
+            )
+        return Prompt.ask(f"  {label}", password=True, console=console)
+    if f.kind == "choice" and f.choices:
+        return Prompt.ask(
+            f"  {label}", choices=f.choices, default=default or f.choices[0], console=console
+        )
+    answer = Prompt.ask(f"  {label}", default=default or None, console=console)
+    return (answer or "").strip()