aiscript 1.2.0__tar.gz → 1.3.0__tar.gz

{aiscript-1.2.0 → aiscript-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiscript
-Version: 1.2.0
+Version: 1.3.0
 Summary: JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM.
 Author: Daniel Illescas Romero
 Author-email: Daniel Illescas Romero <illescas.daniel@protonmail.com>
@@ -39,6 +39,20 @@ pip install aiscript
 
 Requires Python 3.10+.
 
+On Linux or macOS, check that the installed command is on your `PATH`:
+
+```sh
+command -v aiscript
+```
+
+If it is not found, use your installer's PATH setup: `uv tool update-shell` for uv, or
+`pipx ensurepath` for pipx. These commands update shell configuration when you run them; open a
+new terminal for the changes to take effect. With pip, add the directory containing its installed
+`aiscript` executable to your PATH using your shell's configuration. See the
+[uv tool documentation](https://docs.astral.sh/uv/concepts/tools/) and
+[pipx installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html) for details.
+Installing aiscript itself does not edit shell profiles.
+
 To upgrade to the latest version, use the same tool you installed with:
 
 ```sh
@@ -80,6 +94,46 @@ aiscript sizes ~/Downloads --top 5   # later runs: cached, arguments passed stra
 Everything after the command name is passed untouched to the script (including `--help`).
 `aiscript` messages go to stderr; stdout belongs to the script, and the exit code is the script's.
 
+## Executable prompt files
+
+On Linux and macOS, write a UTF-8 file named `biggest`:
+
+```text
+#!/usr/bin/env aiscript
+List the largest folders inside the directory given as the first argument.
+```
+
+Make it executable and run it with a directory:
+
+```sh
+chmod +x biggest
+./biggest ~/Downloads
+```
+
+`/usr/bin/env` finds `aiscript` on `PATH`. Alternatively, use its absolute path in the shebang,
+for example `#!/home/alex/.local/bin/aiscript`. The operating system does not expand `$HOME` or
+`~` in a shebang.
+
+You can also run a prompt file directly with `aiscript ./biggest ~/Downloads`; a shebang is
+optional in this form. On Windows, use direct invocation with an explicit path, for example
+`aiscript .\biggest Downloads`; Unix shebang execution is not supported there. The path must
+include a path separator: a bare name such as `biggest` selects the existing named-command
+workflow, even when a file with that name exists. Quote paths or arguments containing spaces.
+Arguments after the path, including flags, are passed through unchanged, as are the program's
+standard input, output and exit status.
+
+The first run generates and reviews a script using the same safety checks as named commands.
+Risky builds require approval and are refused when standard input is non-interactive. Later
+runs reuse a matching reviewed build without calling a model; changing the prompt rebuilds and
+reviews it. A changed shebang alone does not trigger a rebuild. If rebuilding fails or is
+rejected, aiscript keeps the old build but does not execute it for the changed prompt.
+File builds are stored separately from named commands under `~/.config/aiscript/file-cache/`
+(or `$XDG_CONFIG_HOME/aiscript/file-cache/`, or `$AISCRIPT_HOME/file-cache/`). Paths resolving
+to the same file share a cache; moving the file creates a new entry. Historical versions are
+retained. To reclaim their space, remove the file-cache directory only when no prompt-file
+invocation is using it; the next run will rebuild and review its script. Named-command
+management options such as `--remove` do not manage this cache.
+
 ## Safety review / decision models
 
 Every generated script is reviewed **before it is saved**:
@@ -165,6 +219,7 @@ and [safety](docs/safety.md#openai-decisions) for the full contract.
 | Command | Action |
 |---|---|
 | `aiscript NAME [args...]` | Run a command; created and built on first use |
+| `aiscript PATH [args...]` | Run a prompt file using an explicit path |
 | `aiscript --init` | Create config dirs and a `config.yaml` template (never overwrites) |
 | `aiscript --list` | Table of commands, descriptions and usage (`*` = prompt changed, will rebuild) |
 | `aiscript --edit NAME` | Open the prompt in `$VISUAL` / `$EDITOR` (fallback nano/vi, notepad on Windows) |
@@ -199,6 +254,7 @@ why in the script header). `aiscript --list` shows each command's language.
 ~/.config/aiscript/          # or $XDG_CONFIG_HOME/aiscript, or $AISCRIPT_HOME
 ├── config.yaml              # providers and keys
 ├── prompts/<name>.txt       # your intent for each command
+├── file-cache/              # reviewed builds for prompt files
 └── functions/
     ├── <name>.sh            # generated, reviewed scripts (.ps1 on Windows)
     ├── <name>.py            # standard-library Python

{aiscript-1.2.0 → aiscript-1.3.0}/README.md

@@ -25,6 +25,20 @@ pip install aiscript
 
 Requires Python 3.10+.
 
+On Linux or macOS, check that the installed command is on your `PATH`:
+
+```sh
+command -v aiscript
+```
+
+If it is not found, use your installer's PATH setup: `uv tool update-shell` for uv, or
+`pipx ensurepath` for pipx. These commands update shell configuration when you run them; open a
+new terminal for the changes to take effect. With pip, add the directory containing its installed
+`aiscript` executable to your PATH using your shell's configuration. See the
+[uv tool documentation](https://docs.astral.sh/uv/concepts/tools/) and
+[pipx installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html) for details.
+Installing aiscript itself does not edit shell profiles.
+
 To upgrade to the latest version, use the same tool you installed with:
 
 ```sh
@@ -66,6 +80,46 @@ aiscript sizes ~/Downloads --top 5   # later runs: cached, arguments passed stra
 Everything after the command name is passed untouched to the script (including `--help`).
 `aiscript` messages go to stderr; stdout belongs to the script, and the exit code is the script's.
 
+## Executable prompt files
+
+On Linux and macOS, write a UTF-8 file named `biggest`:
+
+```text
+#!/usr/bin/env aiscript
+List the largest folders inside the directory given as the first argument.
+```
+
+Make it executable and run it with a directory:
+
+```sh
+chmod +x biggest
+./biggest ~/Downloads
+```
+
+`/usr/bin/env` finds `aiscript` on `PATH`. Alternatively, use its absolute path in the shebang,
+for example `#!/home/alex/.local/bin/aiscript`. The operating system does not expand `$HOME` or
+`~` in a shebang.
+
+You can also run a prompt file directly with `aiscript ./biggest ~/Downloads`; a shebang is
+optional in this form. On Windows, use direct invocation with an explicit path, for example
+`aiscript .\biggest Downloads`; Unix shebang execution is not supported there. The path must
+include a path separator: a bare name such as `biggest` selects the existing named-command
+workflow, even when a file with that name exists. Quote paths or arguments containing spaces.
+Arguments after the path, including flags, are passed through unchanged, as are the program's
+standard input, output and exit status.
+
+The first run generates and reviews a script using the same safety checks as named commands.
+Risky builds require approval and are refused when standard input is non-interactive. Later
+runs reuse a matching reviewed build without calling a model; changing the prompt rebuilds and
+reviews it. A changed shebang alone does not trigger a rebuild. If rebuilding fails or is
+rejected, aiscript keeps the old build but does not execute it for the changed prompt.
+File builds are stored separately from named commands under `~/.config/aiscript/file-cache/`
+(or `$XDG_CONFIG_HOME/aiscript/file-cache/`, or `$AISCRIPT_HOME/file-cache/`). Paths resolving
+to the same file share a cache; moving the file creates a new entry. Historical versions are
+retained. To reclaim their space, remove the file-cache directory only when no prompt-file
+invocation is using it; the next run will rebuild and review its script. Named-command
+management options such as `--remove` do not manage this cache.
+
 ## Safety review / decision models
 
 Every generated script is reviewed **before it is saved**:
@@ -151,6 +205,7 @@ and [safety](docs/safety.md#openai-decisions) for the full contract.
 | Command | Action |
 |---|---|
 | `aiscript NAME [args...]` | Run a command; created and built on first use |
+| `aiscript PATH [args...]` | Run a prompt file using an explicit path |
 | `aiscript --init` | Create config dirs and a `config.yaml` template (never overwrites) |
 | `aiscript --list` | Table of commands, descriptions and usage (`*` = prompt changed, will rebuild) |
 | `aiscript --edit NAME` | Open the prompt in `$VISUAL` / `$EDITOR` (fallback nano/vi, notepad on Windows) |
@@ -185,6 +240,7 @@ why in the script header). `aiscript --list` shows each command's language.
 ~/.config/aiscript/          # or $XDG_CONFIG_HOME/aiscript, or $AISCRIPT_HOME
 ├── config.yaml              # providers and keys
 ├── prompts/<name>.txt       # your intent for each command
+├── file-cache/              # reviewed builds for prompt files
 └── functions/
     ├── <name>.sh            # generated, reviewed scripts (.ps1 on Windows)
     ├── <name>.py            # standard-library Python

{aiscript-1.2.0 → aiscript-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aiscript"
-version = "1.2.0"
+version = "1.3.0"
 description = "JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM."
 readme = "README.md"
 license = "MIT"

{aiscript-1.2.0 → aiscript-1.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "aiscript"
-version = "1.2.0"
+version = "1.3.0"
 description = "JIT-compile plain-English intents into cached, reviewed shell or Python scripts via an LLM."
 readme = "README.md"
 license = "MIT"

{aiscript-1.2.0 → aiscript-1.3.0}/src/aiscript/__init__.py

@@ -1,3 +1,3 @@
 """aiscript: JIT-compile plain-English intents into cached shell scripts."""
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"

{aiscript-1.2.0 → aiscript-1.3.0}/src/aiscript/builder.py

@@ -38,16 +38,21 @@ def _read_intent(name: str) -> str:
     return intent
 
 
-def build(name: str, settings: Settings) -> Path:
-    """Generate, review and atomically write the script for ``name``."""
-    intent = _read_intent(name)
+def generate_reviewed(name: str, intent: str, settings: Settings) -> llm.GeneratedScript:
+    """Generate a program and require the existing safety review before returning it."""
     gen = settings.generator
     print(f"Generating {name!r} with {gen.name}/{gen.model}...", file=sys.stderr)
     script = llm.generate_script(gen, name, intent)
-
     result = reviewer.review(script.code, script.language, settings.reviewer, script.dependencies)
     if not reviewer.confirm(script.code, result):
         raise AiscriptError("Script rejected; nothing saved.")
+    return script
+
+
+def build(name: str, settings: Settings) -> Path:
+    """Generate, review and atomically write the script for ``name``."""
+    intent = _read_intent(name)
+    script = generate_reviewed(name, intent, settings)
 
     paths.ensure_dirs()
     if script.dependencies:

{aiscript-1.2.0 → aiscript-1.3.0}/src/aiscript/cli.py

@@ -8,8 +8,9 @@ import shlex
 import shutil
 import subprocess
 import sys
+from pathlib import Path
 
-from aiscript import __version__, builder, paths
+from aiscript import __version__, builder, paths, prompt_file
 from aiscript.config import load_settings
 from aiscript.errors import AiscriptError
 from aiscript.init_cmd import run_init
@@ -18,6 +19,7 @@ from aiscript.runner import run_script
 
 _HELP = """\
 usage: aiscript NAME [args...]       run a command (created/built on first use)
+       aiscript PATH [args...]       run a prompt file specified by path
        aiscript --init               create config dir and config.yaml template
        aiscript --list               list commands
        aiscript --edit NAME          edit a command's prompt (rebuilds on next run)
@@ -131,6 +133,8 @@ def _dispatch(argv: list[str]) -> int:
     if not argv:
         sys.stderr.write(_HELP)
         return 2
+    if os.sep in argv[0] or (os.altsep is not None and os.altsep in argv[0]):
+        return prompt_file.execute(Path(argv[0]), argv[1:], load_settings)
     if argv[0].startswith("-"):
         try:
             ns = _build_parser().parse_args(argv)

aiscript-1.3.0/src/aiscript/file_contracts.py

@@ -0,0 +1,87 @@
+"""Domain values and ports for executable prompt files."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from contextlib import AbstractContextManager as ContextManager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class PromptSnapshot:
+    """A canonical source and the exact prompt content used for a build."""
+
+    source: Path
+    prompt: str
+    digest: str
+
+
+@dataclass(frozen=True)
+class ReviewedBuild:
+    """A reviewed, immutable entrypoint associated with a prompt digest."""
+
+    prompt_digest: str
+    entrypoint: Path
+
+
+@dataclass(frozen=True)
+class BuildDestination:
+    """A unique, permanent version directory, invisible until publication."""
+
+    version_dir: Path
+
+
+class PromptSource(Protocol):
+    """Read a prompt file into an immutable snapshot."""
+
+    def read(self, path: Path) -> PromptSnapshot: ...
+
+
+class BuildLease(Protocol):
+    """Exclusive per-source lease for matching and publishing builds."""
+
+    def find(self, snapshot: PromptSnapshot) -> ReviewedBuild | None:
+        """Find a complete reviewed build matching this snapshot."""
+        ...
+
+    def allocate(self) -> BuildDestination:
+        """Allocate a unique destination at its final path."""
+        ...
+
+    def publish(
+        self, snapshot: PromptSnapshot, destination: BuildDestination, entrypoint: Path
+    ) -> ReviewedBuild:
+        """Atomically publish the artifact and its identity together."""
+        ...
+
+    def discard(self, destination: BuildDestination) -> None:
+        """Discard an unpublished destination without affecting published versions."""
+        ...
+
+
+class FileBuildCache(Protocol):
+    """Coordinate file builds independently of named-command caches."""
+
+    def acquire(self, source: Path) -> ContextManager[BuildLease]:
+        """Acquire an exclusive lease for a canonical source."""
+        ...
+
+
+class PromptFileBuilder(Protocol):
+    """Build and review a prompt snapshot at its permanent destination."""
+
+    def build(self, snapshot: PromptSnapshot, destination: BuildDestination) -> Path: ...
+
+
+class ProgramRunner(Protocol):
+    """Run a reviewed build with the supplied arguments."""
+
+    def run(self, build: ReviewedBuild, args: Sequence[str]) -> int: ...
+
+
+class PromptFileExecution(Protocol):
+    """Execute a prompt file and return its program's exit status."""
+
+    def execute(self, path: Path, args: Sequence[str]) -> int: ...

aiscript-1.3.0/src/aiscript/prompt_file.py

@@ -0,0 +1,244 @@
+"""Execution and immutable reviewed cache for explicit prompt files."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import shutil
+import sys
+import tempfile
+from collections.abc import Callable, Generator, Sequence
+from pathlib import Path
+
+from aiscript import builder, env, paths, pysetup
+from aiscript.config import Settings
+from aiscript.errors import AiscriptError
+from aiscript.file_contracts import (
+    BuildDestination,
+    BuildLease,
+    FileBuildCache,
+    ProgramRunner,
+    PromptFileBuilder,
+    PromptSnapshot,
+    PromptSource,
+    ReviewedBuild,
+)
+from aiscript.runner import run_script
+
+
+def _snapshot(path: Path) -> PromptSnapshot:
+    try:
+        source = path.resolve(strict=True)
+        if not source.is_file():
+            raise AiscriptError(f"Not a regular prompt file: {path}")
+        with source.open(encoding="utf-8", newline="") as handle:
+            prompt = handle.read()
+    except (OSError, UnicodeError, RuntimeError) as exc:
+        raise AiscriptError(f"Cannot read prompt file {path}: {exc}") from exc
+    if prompt.startswith("#!"):
+        prompt = prompt.partition("\n")[2]
+    if not prompt.strip():
+        raise AiscriptError(f"Prompt file is empty: {path}")
+    digest = hashlib.sha256(prompt.encode("utf-8")).hexdigest()
+    return PromptSnapshot(source, prompt, digest)
+
+
+@contextlib.contextmanager
+def _lock(path: Path) -> Generator[None, None, None]:
+    with path.open("a+b") as handle:
+        if os.name == "nt":
+            import msvcrt
+
+            handle.seek(0, os.SEEK_END)
+            if handle.tell() == 0:
+                handle.write(b"0")
+                handle.flush()
+            handle.seek(0)
+            # LK_LOCK has a finite retry limit, so use blocking OS-level locking below.
+            import ctypes
+            from ctypes import wintypes
+
+            class Overlapped(ctypes.Structure):
+                _fields_ = [
+                    ("Internal", ctypes.c_size_t),
+                    ("InternalHigh", ctypes.c_size_t),
+                    ("Offset", wintypes.DWORD),
+                    ("OffsetHigh", wintypes.DWORD),
+                    ("hEvent", wintypes.HANDLE),
+                ]
+
+            kernel = ctypes.WinDLL("kernel32", use_last_error=True)  # type: ignore[attr-defined]
+            overlap = Overlapped()
+            raw = msvcrt.get_osfhandle(handle.fileno())  # type: ignore[attr-defined]
+            if not kernel.LockFileEx(wintypes.HANDLE(raw), 2, 0, 1, 0, ctypes.byref(overlap)):
+                raise OSError("Could not acquire prompt file cache lock")
+            try:
+                yield
+            finally:
+                if not kernel.UnlockFileEx(wintypes.HANDLE(raw), 0, 1, 0, ctypes.byref(overlap)):
+                    raise OSError("Could not release prompt file cache lock")
+        else:
+            import fcntl
+
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def _build(snapshot: PromptSnapshot, destination: Path, settings: Settings) -> Path:
+    name = "prompt-file"
+    script = builder.generate_reviewed(name, snapshot.prompt, settings)
+    if script.dependencies:
+        target = destination / "main.py"
+        target.write_text(script.code, encoding="utf-8", newline="\n")
+        deps = pysetup._normalise(script.dependencies)
+        python = env.find_python()
+        uv = env.uv_path()
+        print(f"Installing dependencies for {name!r}: {', '.join(deps)}...", file=sys.stderr)
+        if uv:
+            pysetup._install_uv(uv, name, destination, deps, python)
+        else:
+            pysetup._install_pip(destination, deps, python)
+    else:
+        ext = {"python": "py", "powershell": "ps1", "bash": "sh"}[script.language]
+        target = destination / f"script.{ext}"
+        target.write_text(script.code, encoding="utf-8", newline="\n")
+    if not paths.is_windows():
+        target.chmod(0o755)
+    return target
+
+
+def _lookup(manifest: Path, snapshot: PromptSnapshot, root: Path) -> Path | None:
+    if not manifest.exists():
+        return None
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError("manifest is not an object")
+        relative = data.get(snapshot.digest)
+        if relative is None:
+            return None
+        if not isinstance(relative, str):
+            raise ValueError("invalid entrypoint")
+        entry = (root / relative).resolve()
+        if not entry.is_relative_to(root.resolve()) or not entry.is_file():
+            raise ValueError("cached entrypoint is missing or outside cache")
+        return entry
+    except (OSError, ValueError) as exc:
+        raise AiscriptError(f"Cannot read prompt cache: {exc}") from exc
+
+
+def _publish(manifest: Path, snapshot: PromptSnapshot, root: Path, entry: Path) -> None:
+    data: dict[str, str] = {}
+    if manifest.exists():
+        value = json.loads(manifest.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise ValueError("invalid cache manifest")
+        data = value
+    data[snapshot.digest] = str(entry.relative_to(root))
+    fd, temporary = tempfile.mkstemp(dir=root, prefix=".manifest-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle)
+        os.replace(temporary, manifest)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(temporary)
+        raise
+
+
+def execute(path: Path, args: list[str], settings: Callable[[], Settings]) -> int:
+    """Run an explicit prompt file through the approved execution ports."""
+    use_case = FileExecution(
+        LocalPromptSource(),
+        LocalFileBuildCache(),
+        LocalPromptFileBuilder(settings),
+        LocalProgramRunner(),
+    )
+    return use_case.execute(path, args)
+
+
+class LocalPromptSource:
+    def read(self, path: Path) -> PromptSnapshot:
+        return _snapshot(path)
+
+
+class LocalBuildLease:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def find(self, snapshot: PromptSnapshot) -> ReviewedBuild | None:
+        entry = _lookup(self.root / "manifest.json", snapshot, self.root)
+        return ReviewedBuild(snapshot.digest, entry) if entry is not None else None
+
+    def allocate(self) -> BuildDestination:
+        return BuildDestination(Path(tempfile.mkdtemp(prefix="version-", dir=self.root)))
+
+    def publish(
+        self, snapshot: PromptSnapshot, destination: BuildDestination, entrypoint: Path
+    ) -> ReviewedBuild:
+        if not entrypoint.resolve().is_relative_to(destination.version_dir.resolve()):
+            raise AiscriptError("Built entrypoint is outside its version directory")
+        _publish(self.root / "manifest.json", snapshot, self.root, entrypoint)
+        return ReviewedBuild(snapshot.digest, entrypoint)
+
+    def discard(self, destination: BuildDestination) -> None:
+        shutil.rmtree(destination.version_dir, ignore_errors=True)
+
+
+class LocalFileBuildCache:
+    @contextlib.contextmanager
+    def acquire(self, source: Path) -> Generator[BuildLease, None, None]:
+        identity = hashlib.sha256(os.fsencode(str(source))).hexdigest()
+        root = paths.aiscript_home() / "file-cache" / identity
+        root.mkdir(parents=True, exist_ok=True)
+        with _lock(root / ".lock"):
+            yield LocalBuildLease(root)
+
+
+class LocalPromptFileBuilder:
+    def __init__(self, settings: Callable[[], Settings]) -> None:
+        self.settings = settings
+
+    def build(self, snapshot: PromptSnapshot, destination: BuildDestination) -> Path:
+        return _build(snapshot, destination.version_dir, self.settings())
+
+
+class LocalProgramRunner:
+    def run(self, build: ReviewedBuild, args: Sequence[str]) -> int:
+        return run_script(build.entrypoint, list(args))
+
+
+class FileExecution:
+    def __init__(
+        self,
+        source: PromptSource,
+        cache: FileBuildCache,
+        builder_port: PromptFileBuilder,
+        runner: ProgramRunner,
+    ) -> None:
+        self.source = source
+        self.cache = cache
+        self.builder = builder_port
+        self.runner = runner
+
+    def execute(self, path: Path, args: Sequence[str]) -> int:
+        snapshot = self.source.read(path)
+        try:
+            with self.cache.acquire(snapshot.source) as lease:
+                build = lease.find(snapshot)
+                if build is None:
+                    destination = lease.allocate()
+                    try:
+                        entry = self.builder.build(snapshot, destination)
+                        build = lease.publish(snapshot, destination, entry)
+                    except BaseException:
+                        lease.discard(destination)
+                        raise
+            return self.runner.run(build, args)
+        except (OSError, ValueError) as exc:
+            raise AiscriptError(f"Prompt file cache error: {exc}") from exc