acli-spec 0.1.4__tar.gz

acli_spec-0.1.4/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# ACLI generated
+.cli/
+
+# MkDocs
+site/

acli_spec-0.1.4/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: acli-spec
+Version: 0.1.4
+Summary: Python SDK for the ACLI (Agent-friendly CLI) specification
+Project-URL: Homepage, https://github.com/alpibrusl/acli
+Project-URL: Documentation, https://alpibrusl.github.io/acli
+Project-URL: Repository, https://github.com/alpibrusl/acli
+Project-URL: Issues, https://github.com/alpibrusl/acli/issues
+Project-URL: Changelog, https://github.com/alpibrusl/acli/blob/main/CHANGELOG.md
+Author: ACLI Contributors
+License-Expression: EUPL-1.2
+Keywords: agent,ai,cli,specification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# acli-spec
+
+Python SDK for the [ACLI (Agent-friendly CLI) specification](../../ACLI_SPEC.md).
+
+Build CLI tools that AI agents can discover, learn, and use autonomously.
+
+## Installation
+
+```bash
+pip install acli-spec
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from acli import ACLIApp, acli_command, OutputFormat
+import typer
+
+app = ACLIApp(name="myapp", version="1.0.0")
+
+@app.command()
+@acli_command(
+    examples=[
+        ("Run a task", "myapp run --file task.yaml"),
+        ("Dry-run a task", "myapp run --file task.yaml --dry-run"),
+    ],
+    idempotent=False,
+)
+def run(
+    file: Path = typer.Option(..., help="Path to task file. type:path"),
+    dry_run: bool = typer.Option(False, help="Preview without executing."),
+    output: OutputFormat = typer.Option(OutputFormat.text, help="Output format."),
+) -> None:
+    """Execute a task from a YAML file."""
+    ...
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## What you get automatically
+
+- `introspect` command with full command tree as JSON
+- `.cli/` folder generation (README, examples, schemas)
+- JSON error envelope on `--output json`
+- Semantic exit codes (0-9)
+- `--version` with semver output
+
+## License
+
+[EUPL-1.2](../../LICENSE)

acli_spec-0.1.4/README.md

@@ -0,0 +1,52 @@
+# acli-spec
+
+Python SDK for the [ACLI (Agent-friendly CLI) specification](../../ACLI_SPEC.md).
+
+Build CLI tools that AI agents can discover, learn, and use autonomously.
+
+## Installation
+
+```bash
+pip install acli-spec
+```
+
+## Quick Start
+
+```python
+from pathlib import Path
+from acli import ACLIApp, acli_command, OutputFormat
+import typer
+
+app = ACLIApp(name="myapp", version="1.0.0")
+
+@app.command()
+@acli_command(
+    examples=[
+        ("Run a task", "myapp run --file task.yaml"),
+        ("Dry-run a task", "myapp run --file task.yaml --dry-run"),
+    ],
+    idempotent=False,
+)
+def run(
+    file: Path = typer.Option(..., help="Path to task file. type:path"),
+    dry_run: bool = typer.Option(False, help="Preview without executing."),
+    output: OutputFormat = typer.Option(OutputFormat.text, help="Output format."),
+) -> None:
+    """Execute a task from a YAML file."""
+    ...
+
+if __name__ == "__main__":
+    app.run()
+```
+
+## What you get automatically
+
+- `introspect` command with full command tree as JSON
+- `.cli/` folder generation (README, examples, schemas)
+- JSON error envelope on `--output json`
+- Semantic exit codes (0-9)
+- `--version` with semver output
+
+## License
+
+[EUPL-1.2](../../LICENSE)

acli_spec-0.1.4/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "acli-spec"
+version = "0.1.4"
+description = "Python SDK for the ACLI (Agent-friendly CLI) specification"
+readme = "README.md"
+license = "EUPL-1.2"
+requires-python = ">=3.10"
+authors = [{ name = "ACLI Contributors" }]
+keywords = ["cli", "agent", "ai", "specification"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typer>=0.9.0",
+]
+
+[project.scripts]
+acli = "acli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/alpibrusl/acli"
+Documentation = "https://alpibrusl.github.io/acli"
+Repository = "https://github.com/alpibrusl/acli"
+Issues = "https://github.com/alpibrusl/acli/issues"
+Changelog = "https://github.com/alpibrusl/acli/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acli"]
+
+# ── Ruff ──────────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = [
+    "F",      # pyflakes
+    "E", "W", # pycodestyle
+    "I",      # isort
+    "N",      # pep8-naming
+    "UP",     # pyupgrade
+    "B",      # flake8-bugbear
+    "A",      # flake8-builtins
+    "SIM",    # flake8-simplify
+    "T20",    # flake8-print
+    "PT",     # flake8-pytest-style
+    "RUF",    # ruff-specific
+    "S",      # flake8-bandit (security)
+    "C4",     # flake8-comprehensions
+    "DTZ",    # flake8-datetimez
+    "PIE",    # flake8-pie
+    "RET",    # flake8-return
+    "TCH",    # flake8-type-checking
+    "ARG",    # flake8-unused-arguments
+    "PLC", "PLE", "PLW", # pylint
+]
+ignore = [
+    "S101",    # allow assert in tests
+    "BLE001",  # allow broad exception catches (needed for introspect resilience)
+    "B008",    # typer.Option() in defaults is standard Typer pattern
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ARG001", "ARG002", "ARG005", "S", "T20", "PLC0415", "TC003", "PT017", "SIM105"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["acli"]
+
+# ── Mypy ──────────────────────────────────────────────────────────────────────
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = ["typer", "typer.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["acli.cli"]
+disallow_untyped_decorators = false
+
+# ── Pytest ────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--cov=acli",
+    "--cov-report=term-missing",
+    "--cov-report=html:htmlcov",
+    "--cov-fail-under=90",
+]

acli_spec-0.1.4/src/acli/__init__.py

@@ -0,0 +1,36 @@
+"""ACLI — Agent-friendly CLI Python SDK."""
+
+from acli.app import ACLIApp
+from acli.command import CommandExample, CommandMeta, acli_command
+from acli.errors import (
+    ACLIError,
+    ConflictError,
+    InvalidArgsError,
+    NotFoundError,
+    PreconditionError,
+    suggest_flag,
+)
+from acli.exit_codes import ExitCode
+from acli.output import OutputFormat, emit, error_envelope, success_envelope
+from acli.skill import generate_skill
+
+__all__ = [
+    "ACLIApp",
+    "ACLIError",
+    "CommandExample",
+    "CommandMeta",
+    "ConflictError",
+    "ExitCode",
+    "InvalidArgsError",
+    "NotFoundError",
+    "OutputFormat",
+    "PreconditionError",
+    "acli_command",
+    "emit",
+    "error_envelope",
+    "generate_skill",
+    "success_envelope",
+    "suggest_flag",
+]
+
+__version__ = "0.1.4"

acli_spec-0.1.4/src/acli/app.py

@@ -0,0 +1,179 @@
+"""ACLIApp — the main application class wrapping Typer per ACLI spec §8."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+
+from acli.cli_folder import generate_cli_folder, needs_update
+from acli.errors import ACLIError
+from acli.exit_codes import ExitCode
+from acli.introspect import build_command_tree
+from acli.output import OutputFormat, emit, error_envelope, success_envelope
+from acli.skill import generate_skill
+
+
+class ACLIApp:
+    """ACLI-compliant application wrapper around Typer.
+
+    Automatically registers the ``introspect`` command, enforces JSON error
+    envelopes, and generates the ``.cli/`` folder.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        version: str,
+        *,
+        cli_dir: Path | None = None,
+        **typer_kwargs: Any,
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.cli_dir = cli_dir
+        self._typer = typer.Typer(name=name, help=typer_kwargs.pop("help", None), **typer_kwargs)
+        self._register_introspect()
+        self._register_version()
+        self._register_skill()
+
+    @property
+    def typer_app(self) -> typer.Typer:
+        """Access the underlying Typer instance."""
+        return self._typer
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def command(self, *args: Any, **kwargs: Any) -> Any:
+        """Register a command — proxy to typer.command()."""
+        return self._typer.command(*args, **kwargs)
+
+    def add_typer(self, *args: Any, **kwargs: Any) -> None:
+        """Add a sub-group — proxy to typer.add_typer()."""
+        self._typer.add_typer(*args, **kwargs)
+
+    def run(self) -> None:
+        """Run the application with ACLI error handling."""
+        try:
+            self._typer()
+        except ACLIError as exc:
+            self._handle_acli_error(exc)
+        except SystemExit:
+            raise
+        except Exception as exc:
+            self._handle_unexpected_error(exc)
+
+    def get_command_tree(self) -> dict[str, Any]:
+        """Build the introspection command tree."""
+        return build_command_tree(self._typer, self.name, self.version)
+
+    # ── Built-in commands ─────────────────────────────────────────────────────
+
+    def _register_introspect(self) -> None:
+        @self._typer.command(name="introspect", hidden=True)
+        def introspect(
+            acli_version: bool = typer.Option(
+                False, "--acli-version", help="Show only the ACLI spec version. type:bool"
+            ),
+            output: OutputFormat = typer.Option(
+                OutputFormat.json, "--output", help="Output format. type:enum[text|json|table]"
+            ),
+        ) -> None:
+            """Output the full command tree as JSON for agent consumption."""
+            if acli_version:
+                if output == OutputFormat.json:
+                    json.dump({"acli_version": "0.1.0"}, sys.stdout)
+                    sys.stdout.write("\n")
+                else:
+                    sys.stdout.write("acli 0.1.0\n")
+                return
+
+            tree = self.get_command_tree()
+
+            # Update .cli/ if needed
+            if needs_update(tree, self.cli_dir):
+                generate_cli_folder(tree, self.cli_dir)
+
+            emit(success_envelope("introspect", tree, version=self.version), output)
+
+    def _register_version(self) -> None:
+        @self._typer.command(name="version", hidden=True)
+        def version_cmd(
+            output: OutputFormat = typer.Option(
+                OutputFormat.text,
+                "--output",
+                help="Output format. type:enum[text|json|table]",
+            ),
+        ) -> None:
+            """Show version information."""
+            if output == OutputFormat.json:
+                data = {
+                    "tool": self.name,
+                    "version": self.version,
+                    "acli_version": "0.1.0",
+                }
+                emit(success_envelope("version", data, version=self.version), output)
+            else:
+                sys.stdout.write(f"{self.name} {self.version}\n")
+                sys.stdout.write("acli 0.1.0\n")
+
+            # Update .cli/ if needed
+            tree = self.get_command_tree()
+            if needs_update(tree, self.cli_dir):
+                generate_cli_folder(tree, self.cli_dir)
+
+    def _register_skill(self) -> None:
+        @self._typer.command(name="skill", hidden=True)
+        def skill_cmd(
+            out: str = typer.Option(
+                "",
+                "--out",
+                help="Write skill file to this path instead of stdout. type:path",
+            ),
+            output: OutputFormat = typer.Option(
+                OutputFormat.text,
+                "--output",
+                help="Output format. type:enum[text|json|table]",
+            ),
+        ) -> None:
+            """Generate a SKILLS.md file for agent bootstrapping."""
+            tree = self.get_command_tree()
+            target = Path(out) if out else None
+            content = generate_skill(tree, target_path=target)
+
+            if output == OutputFormat.json:
+                data = {"path": str(target) if target else None, "content": content}
+                emit(success_envelope("skill", data, version=self.version), output)
+            elif target:
+                sys.stdout.write(f"Skill file written to {target}\n")
+            else:
+                sys.stdout.write(content)
+
+    # ── Error handling ────────────────────────────────────────────────────────
+
+    def _handle_acli_error(self, exc: ACLIError) -> None:
+        cmd_name = exc.command or self.name
+        envelope = error_envelope(
+            cmd_name,
+            code=exc.code.name,
+            message=str(exc),
+            hint=exc.hint,
+            docs=exc.docs,
+            version=self.version,
+        )
+        emit(envelope, OutputFormat.json)
+        raise SystemExit(exc.code.value)
+
+    def _handle_unexpected_error(self, exc: Exception) -> None:
+        envelope = error_envelope(
+            self.name,
+            code="GENERAL_ERROR",
+            message=str(exc),
+            hint="This is an unexpected error. Please report it.",
+            version=self.version,
+        )
+        emit(envelope, OutputFormat.json)
+        raise SystemExit(ExitCode.GENERAL_ERROR)