aiscript 1.0.0__tar.gz

aiscript-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Illescas Romero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiscript-1.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: aiscript
+Version: 1.0.0
+Summary: JIT-compile plain-English intents into cached, reviewed shell scripts via an LLM.
+Author: Daniel Illescas Romero
+Author-email: Daniel Illescas Romero <illescas.daniel@protonmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: openai>=3.35.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: typesafe-sdk>=0.7.5
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# aiscript
+
+[![PyPI version](https://img.shields.io/pypi/v/aiscript)](https://pypi.org/project/aiscript/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiscript)](https://pypi.org/project/aiscript/)
+
+Describe what you want in plain English and `aiscript` asks an LLM to write a shell script
+(Bash on Linux/macOS, PowerShell on Windows), caches it, and runs it. The next run is instant:
+no network, no config. Before anything risky is saved or run, every generated script is checked
+by a built-in static scan and, optionally, by a decision model: [Jev](https://docs.typesafe.ai)
+by TypeSafe AI (hosted) or a local model served by [Ollaya](https://ollaya.dev). Risky scripts
+are shown to you and need an explicit `[y/N]` approval.
+
+## Install
+
+```sh
+uv tool install aiscript
+# or
+pipx install aiscript
+# or
+pip install aiscript
+```
+
+Requires Python 3.10+. To work on aiscript itself, see [docs/development.md](docs/development.md).
+
+## Quickstart
+
+```sh
+aiscript --init        # creates ~/.config/aiscript/config.yaml
+```
+
+Put your OpenAI and Jev API keys in `~/.config/aiscript/config.yaml` (or export `OPENAI_API_KEY`
+and `TYPESAFE_API_KEY`). The same file is where you pick the models: the one that writes the
+scripts (`default_provider`) and the decision model that reviews them (`reviewer_provider`).
+For a local, keyless review, use Ollaya instead of Jev (see below). Jev keys come from
+<https://console.typesafe.ai/keys>.
+
+Environment variables are the alternative to keys in the file:
+
+```sh
+export OPENAI_API_KEY=...
+export TYPESAFE_API_KEY=...
+```
+
+Then run your first command:
+
+```sh
+aiscript sizes                       # first run: asks "What should 'sizes' do?"
+aiscript sizes ~/Downloads --top 5   # later runs: cached, arguments passed straight through
+```
+
+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.
+
+## Safety review / decision models
+
+Every generated script is reviewed **before it is saved**:
+
+- A **static regex scan** (always on) flags privilege escalation, recursive or system-wide file
+  changes, networking/firewall changes and remote code execution (`curl | sh`, `iex`).
+- A **decision model** (`reviewer_provider`) gives a second opinion: **Jev** (hosted; key from
+  <https://console.typesafe.ai/keys>) or **Ollaya** (local and keyless; set
+  `reviewer_provider: ollaya`, default model `jevk5:4b` on `localhost:11435`; see
+  <https://ollaya.dev>). Comment `reviewer_provider` out to use only the static scan.
+
+If either check flags the script, you see the reasons and the code and must answer `[y/N]`;
+declining saves nothing. The review **fails closed**: if the reviewer errors or is unreachable,
+the script is treated as risky. With a non-interactive stdin, risky scripts are refused. This is
+a best-effort safety net, not a sandbox: read what you approve. Details: [docs/safety.md](docs/safety.md).
+
+## Configuration
+
+`aiscript --init` writes this starter `~/.config/aiscript/config.yaml` (mode 600; keep it out of git):
+
+```yaml
+# aiscript config. Contains API keys: keep it private (chmod 600) and out of git.
+# Keys can also come from the environment: OPENAI_API_KEY, TYPESAFE_API_KEY, <PROVIDER>_API_KEY.
+
+# Provider that writes the scripts (override with $AISCRIPT_PROVIDER).
+default_provider: openai
+
+# Decision model that reviews scripts on top of the built-in static scan.
+# Use `ollaya` for a local, keyless review; comment out to use only the static scan.
+reviewer_provider: jev
+
+providers:
+  # OpenAI (or any OpenAI-compatible API). API key: https://platform.openai.com/api-keys
+  openai:
+    api_key: "..."
+    model: "gpt-6-luna"
+    # reasoning_effort: low    # none | low | medium | high | xhigh | max (model-dependent)
+
+  # Jev (TypeSafe AI) safety reviewer. API key: https://console.typesafe.ai/keys
+  jev:
+    api_key: "..."
+
+  # Uses Ollaya for a local decision model (https://ollaya.dev), model example: jevk5:4b
+  # ollaya:
+  #   model: "jevk5:4b"
+
+  # Uses Ollama for a local LLM to create the scripts (set `default_provider: ollama`)
+  # ollama:
+  #   base_url: "http://localhost:11434/v1"
+  #   model: "qwen3"
+```
+
+Placeholder keys (`"..."`) are ignored, so if you leave them, the environment variables above work as-is.
+All options (provider kinds, `api`, `temperature`, key and model resolution, every environment
+variable, the legacy `secrets.yaml`): [docs/configuration.md](docs/configuration.md).
+
+## Usage
+
+| Command | Action |
+|---|---|
+| `aiscript NAME [args...]` | Run a command; created and built on first use |
+| `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) |
+| `aiscript --rebuild NAME` | Regenerate the script and print its path; does not run it |
+| `aiscript --remove NAME` | Delete the command's prompt and cached script |
+| `aiscript --help`, `--version` | Help / version |
+
+Command names must match `[A-Za-z0-9][A-Za-z0-9_-]*`.
+
+## How it works
+
+```
+~/.config/aiscript/          # or $XDG_CONFIG_HOME/aiscript, or $AISCRIPT_HOME
+├── config.yaml              # providers and keys
+├── prompts/<name>.txt       # your intent for each command
+└── functions/<name>.sh      # generated, reviewed scripts (.ps1 on Windows)
+```
+
+The first run of `NAME` saves your description to `prompts/NAME.txt`, asks the LLM for a script,
+reviews it, and stores it in `functions/`. Later runs just execute the cached script. If the
+prompt is newer than the script (after `--edit` or a manual change), the script is rebuilt on the
+next run. A `--rebuild` that fails or is rejected keeps the previous script.
+
+## Docs
+
+- [Configuration reference](docs/configuration.md)
+- [Safety review](docs/safety.md)
+- [Development](docs/development.md)

aiscript-1.0.0/README.md

@@ -0,0 +1,142 @@
+# aiscript
+
+[![PyPI version](https://img.shields.io/pypi/v/aiscript)](https://pypi.org/project/aiscript/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiscript)](https://pypi.org/project/aiscript/)
+
+Describe what you want in plain English and `aiscript` asks an LLM to write a shell script
+(Bash on Linux/macOS, PowerShell on Windows), caches it, and runs it. The next run is instant:
+no network, no config. Before anything risky is saved or run, every generated script is checked
+by a built-in static scan and, optionally, by a decision model: [Jev](https://docs.typesafe.ai)
+by TypeSafe AI (hosted) or a local model served by [Ollaya](https://ollaya.dev). Risky scripts
+are shown to you and need an explicit `[y/N]` approval.
+
+## Install
+
+```sh
+uv tool install aiscript
+# or
+pipx install aiscript
+# or
+pip install aiscript
+```
+
+Requires Python 3.10+. To work on aiscript itself, see [docs/development.md](docs/development.md).
+
+## Quickstart
+
+```sh
+aiscript --init        # creates ~/.config/aiscript/config.yaml
+```
+
+Put your OpenAI and Jev API keys in `~/.config/aiscript/config.yaml` (or export `OPENAI_API_KEY`
+and `TYPESAFE_API_KEY`). The same file is where you pick the models: the one that writes the
+scripts (`default_provider`) and the decision model that reviews them (`reviewer_provider`).
+For a local, keyless review, use Ollaya instead of Jev (see below). Jev keys come from
+<https://console.typesafe.ai/keys>.
+
+Environment variables are the alternative to keys in the file:
+
+```sh
+export OPENAI_API_KEY=...
+export TYPESAFE_API_KEY=...
+```
+
+Then run your first command:
+
+```sh
+aiscript sizes                       # first run: asks "What should 'sizes' do?"
+aiscript sizes ~/Downloads --top 5   # later runs: cached, arguments passed straight through
+```
+
+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.
+
+## Safety review / decision models
+
+Every generated script is reviewed **before it is saved**:
+
+- A **static regex scan** (always on) flags privilege escalation, recursive or system-wide file
+  changes, networking/firewall changes and remote code execution (`curl | sh`, `iex`).
+- A **decision model** (`reviewer_provider`) gives a second opinion: **Jev** (hosted; key from
+  <https://console.typesafe.ai/keys>) or **Ollaya** (local and keyless; set
+  `reviewer_provider: ollaya`, default model `jevk5:4b` on `localhost:11435`; see
+  <https://ollaya.dev>). Comment `reviewer_provider` out to use only the static scan.
+
+If either check flags the script, you see the reasons and the code and must answer `[y/N]`;
+declining saves nothing. The review **fails closed**: if the reviewer errors or is unreachable,
+the script is treated as risky. With a non-interactive stdin, risky scripts are refused. This is
+a best-effort safety net, not a sandbox: read what you approve. Details: [docs/safety.md](docs/safety.md).
+
+## Configuration
+
+`aiscript --init` writes this starter `~/.config/aiscript/config.yaml` (mode 600; keep it out of git):
+
+```yaml
+# aiscript config. Contains API keys: keep it private (chmod 600) and out of git.
+# Keys can also come from the environment: OPENAI_API_KEY, TYPESAFE_API_KEY, <PROVIDER>_API_KEY.
+
+# Provider that writes the scripts (override with $AISCRIPT_PROVIDER).
+default_provider: openai
+
+# Decision model that reviews scripts on top of the built-in static scan.
+# Use `ollaya` for a local, keyless review; comment out to use only the static scan.
+reviewer_provider: jev
+
+providers:
+  # OpenAI (or any OpenAI-compatible API). API key: https://platform.openai.com/api-keys
+  openai:
+    api_key: "..."
+    model: "gpt-6-luna"
+    # reasoning_effort: low    # none | low | medium | high | xhigh | max (model-dependent)
+
+  # Jev (TypeSafe AI) safety reviewer. API key: https://console.typesafe.ai/keys
+  jev:
+    api_key: "..."
+
+  # Uses Ollaya for a local decision model (https://ollaya.dev), model example: jevk5:4b
+  # ollaya:
+  #   model: "jevk5:4b"
+
+  # Uses Ollama for a local LLM to create the scripts (set `default_provider: ollama`)
+  # ollama:
+  #   base_url: "http://localhost:11434/v1"
+  #   model: "qwen3"
+```
+
+Placeholder keys (`"..."`) are ignored, so if you leave them, the environment variables above work as-is.
+All options (provider kinds, `api`, `temperature`, key and model resolution, every environment
+variable, the legacy `secrets.yaml`): [docs/configuration.md](docs/configuration.md).
+
+## Usage
+
+| Command | Action |
+|---|---|
+| `aiscript NAME [args...]` | Run a command; created and built on first use |
+| `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) |
+| `aiscript --rebuild NAME` | Regenerate the script and print its path; does not run it |
+| `aiscript --remove NAME` | Delete the command's prompt and cached script |
+| `aiscript --help`, `--version` | Help / version |
+
+Command names must match `[A-Za-z0-9][A-Za-z0-9_-]*`.
+
+## How it works
+
+```
+~/.config/aiscript/          # or $XDG_CONFIG_HOME/aiscript, or $AISCRIPT_HOME
+├── config.yaml              # providers and keys
+├── prompts/<name>.txt       # your intent for each command
+└── functions/<name>.sh      # generated, reviewed scripts (.ps1 on Windows)
+```
+
+The first run of `NAME` saves your description to `prompts/NAME.txt`, asks the LLM for a script,
+reviews it, and stores it in `functions/`. Later runs just execute the cached script. If the
+prompt is newer than the script (after `--edit` or a manual change), the script is rebuilt on the
+next run. A `--rebuild` that fails or is rejected keeps the previous script.
+
+## Docs
+
+- [Configuration reference](docs/configuration.md)
+- [Safety review](docs/safety.md)
+- [Development](docs/development.md)

aiscript-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "aiscript"
+version = "1.0.0"
+description = "JIT-compile plain-English intents into cached, reviewed shell scripts via an LLM."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=3.35.1",
+    "pyyaml>=6.0.3",
+    "typesafe-sdk>=0.7.5",
+]
+
+[[project.authors]]
+name = "Daniel Illescas Romero"
+email = "illescas.daniel@protonmail.com"
+
+[project.scripts]
+aiscript = "aiscript.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=9.1.1",
+    "ruff>=0.17.1",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "ANN",
+]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+warn_unused_ignores = true

aiscript-1.0.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "aiscript"
+version = "1.0.0"
+description = "JIT-compile plain-English intents into cached, reviewed shell scripts via an LLM."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Daniel Illescas Romero", email = "illescas.daniel@protonmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=3.35.1",
+    "pyyaml>=6.0.3",
+    "typesafe-sdk>=0.7.5",
+]
+
+[project.scripts]
+aiscript = "aiscript.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=9.1.1",
+    "ruff>=0.17.1",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ANN"]
+
+[tool.ruff.lint.flake8-annotations]
+# Test doubles forward arbitrary arguments as `*args: Any, **kwargs: Any`.
+allow-star-arg-any = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+warn_unused_ignores = true

aiscript-1.0.0/src/aiscript/__init__.py

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

aiscript-1.0.0/src/aiscript/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m aiscript``."""
+
+import sys
+
+from aiscript.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

aiscript-1.0.0/src/aiscript/builder.py

@@ -0,0 +1,66 @@
+"""Staleness check and build pipeline."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from aiscript import llm, paths, reviewer
+from aiscript.config import Settings
+from aiscript.errors import AiscriptError
+
+
+def needs_build(name: str) -> bool:
+    """True if the function is missing or older than its prompt."""
+    fpath = paths.function_path(name)
+    if not fpath.exists():
+        return True
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        return False
+    return ppath.stat().st_mtime_ns > fpath.stat().st_mtime_ns
+
+
+def _read_intent(name: str) -> str:
+    ppath = paths.prompt_path(name)
+    try:
+        intent = ppath.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        raise AiscriptError(
+            f"No prompt for {name!r}. Run `aiscript {name}` to create it."
+        ) from None
+    if not intent:
+        raise AiscriptError(f"Prompt for {name!r} is empty: {ppath}")
+    return intent
+
+
+def build(name: str, settings: Settings) -> Path:
+    """Generate, review and atomically write the script for ``name``."""
+    intent = _read_intent(name)
+    gen = settings.generator
+    print(f"Generating {name!r} with {gen.name}/{gen.model}...", file=sys.stderr)
+    script = llm.generate_script(gen, name, intent)
+
+    shell = paths.shell_kind()
+    result = reviewer.review(script, shell, settings.reviewer)
+    if not reviewer.confirm(script, result):
+        raise AiscriptError("Script rejected; nothing saved.")
+
+    paths.ensure_dirs()
+    target = paths.function_path(name)
+    fd, tmp_name = tempfile.mkstemp(dir=paths.functions_dir(), prefix=f".{name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(script)
+        if not paths.is_windows():
+            os.chmod(tmp_name, 0o755)
+        os.replace(tmp_name, target)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp_name)
+        raise
+    print(f"Saved {target}", file=sys.stderr)
+    return target

aiscript-1.0.0/src/aiscript/cli.py

@@ -0,0 +1,163 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+from aiscript import __version__, builder, paths
+from aiscript.config import load_settings
+from aiscript.errors import AiscriptError
+from aiscript.init_cmd import run_init
+from aiscript.listing import list_commands
+from aiscript.runner import run_script
+
+_HELP = """\
+usage: aiscript NAME [args...]       run a command (created/built on first use)
+       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)
+       aiscript --rebuild NAME       regenerate a command's script (does not run it)
+       aiscript --remove NAME        delete a command's prompt and script
+       aiscript --help | --version
+
+Everything after NAME is passed untouched to the generated script.
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aiscript", add_help=False)
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--init", action="store_true")
+    group.add_argument("--list", action="store_true")
+    group.add_argument("--edit", metavar="NAME")
+    group.add_argument("--rebuild", metavar="NAME")
+    group.add_argument("--remove", metavar="NAME")
+    group.add_argument("--help", "-h", action="store_true")
+    group.add_argument("--version", action="store_true")
+    return parser
+
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _editor_command() -> list[str]:
+    for var in ("VISUAL", "EDITOR"):
+        value = os.environ.get(var, "").strip()
+        if value:
+            return shlex.split(value, posix=not paths.is_windows())
+    if paths.is_windows():
+        return ["notepad"]
+    for candidate in ("nano", "vi"):
+        if shutil.which(candidate):
+            return [candidate]
+    raise AiscriptError("No editor found; set $VISUAL or $EDITOR.")
+
+
+def _edit(name: str) -> int:
+    paths.validate_command_name(name)
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        raise AiscriptError(f"No prompt for {name!r}. Run `aiscript {name}` to create it.")
+    before = ppath.stat().st_mtime_ns
+    cmd = [*_editor_command(), str(ppath)]
+    try:
+        proc = subprocess.run(cmd)
+    except OSError as exc:
+        raise AiscriptError(f"Could not launch editor {cmd[0]!r}: {exc}") from exc
+    if proc.returncode != 0:
+        _err(f"aiscript: editor exited with status {proc.returncode}")
+    if ppath.stat().st_mtime_ns != before:
+        _err(f"Prompt for {name!r} changed; it will be rebuilt on next run.")
+    else:
+        _err(f"Prompt for {name!r} unchanged.")
+    return 0
+
+
+def _rebuild(name: str) -> int:
+    paths.validate_command_name(name)
+    paths.ensure_dirs()
+    if not paths.prompt_path(name).exists():
+        raise AiscriptError(f"No prompt for {name!r}. Run `aiscript {name}` to create it.")
+    # build() replaces the cached script atomically, so a failed or rejected
+    # rebuild keeps the previous version.
+    print(builder.build(name, load_settings()))
+    return 0
+
+
+def _remove(name: str) -> int:
+    paths.validate_command_name(name)
+    targets = [p for p in (paths.prompt_path(name), paths.function_path(name)) if p.exists()]
+    if not targets:
+        raise AiscriptError(f"No command named {name!r}.")
+    for path in targets:
+        try:
+            path.unlink()
+        except OSError as exc:
+            raise AiscriptError(f"Could not remove {path}: {exc}") from exc
+        _err(f"Removed {path}")
+    return 0
+
+
+def _run_command(name: str, args: list[str]) -> int:
+    paths.validate_command_name(name)
+    paths.ensure_dirs()
+    ppath = paths.prompt_path(name)
+    if not ppath.exists():
+        sys.stderr.write(f"Command not found. What should '{name}' do? ")
+        sys.stderr.flush()
+        try:
+            answer = input("").strip()
+        except EOFError:
+            answer = ""
+        if not answer:
+            _err("")
+            raise AiscriptError("No description given; nothing saved.")
+        ppath.write_text(answer + "\n", encoding="utf-8")
+    if builder.needs_build(name):
+        builder.build(name, load_settings())
+    return run_script(paths.function_path(name), args)
+
+
+def _dispatch(argv: list[str]) -> int:
+    if not argv:
+        sys.stderr.write(_HELP)
+        return 2
+    if argv[0].startswith("-"):
+        try:
+            ns = _build_parser().parse_args(argv)
+        except SystemExit:
+            return 2
+        if ns.help:
+            sys.stderr.write(_HELP)
+            return 0
+        if ns.version:
+            print(f"aiscript {__version__}")
+            return 0
+        if ns.init:
+            return run_init()
+        if ns.list:
+            return list_commands()
+        if ns.edit is not None:
+            return _edit(ns.edit)
+        if ns.remove is not None:
+            return _remove(ns.remove)
+        return _rebuild(ns.rebuild)
+    return _run_command(argv[0], argv[1:])
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        return _dispatch(args)
+    except AiscriptError as exc:
+        _err(f"aiscript: error: {exc}")
+        return exc.exit_code
+    except KeyboardInterrupt:
+        _err("")
+        return 130