Add cli ai llms-txt, publish /llms.txt, release 0.7.1

.github/workflows/python-app.yaml

@@ -9,6 +9,9 @@ on:
       - 'tests/**'
       - 'examples/**'
       - '!examples/generated/**'
+      - 'docs/**'
+      - 'scripts/**'
+      - 'README.md'
       - 'pyproject.toml'
       - 'uv.lock'
       - 'Makefile'
@@ -19,6 +22,9 @@ on:
       - 'tests/**'
       - 'examples/**'
       - '!examples/generated/**'
+      - 'docs/**'
+      - 'scripts/**'
+      - 'README.md'
       - 'pyproject.toml'
       - 'uv.lock'
       - 'Makefile'
@@ -68,6 +74,23 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
+  # the reference pages and llms.txt are generated; this fails when one is stale and runs every manifest
+  # shown in the docs
+  docs:
+    name: Docs are in sync with the code
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - name: Install library
+        run: uv sync --locked --all-extras
+      - name: Check generated docs and snippets
+        run: make docs-check
+
   # cliffy has to work, lint and pass its tests without the optional `rich` and `ai` extras
   no-extras:
     name: Without extras (Python 3.11)

README.md

@@ -85,6 +85,7 @@ HELLO, ADA!
 | `cli docs <manifest>` | Generate documentation for the CLI |
 | `cli list`, `info`, `update`, `remove` | Manage loaded CLIs |
 | `cli ai generate`, `cli ai ask` | Draft manifests with an LLM (needs the `ai` extra) |
+| `cli ai llms-txt` | Print cliffy's documentation as one text file for a coding agent (no extra needed) |
 
 Every command and option is described in the
 [CLI reference](https://jaykv.github.io/cliffy/reference/cli/).

cliffy/ai.py

@@ -9,6 +9,7 @@
 import json
 import os
 import re
+from importlib.resources import files
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any
 
@@ -28,6 +29,7 @@
 
 MODEL_ENV_VAR = "CLIFFY_AI_MODEL"
 INSTALL_HINT = "pip install 'cliffy[ai]'"
+LLMS_TXT_FILE = "llms.txt"  # the documentation bundled in the package, see scripts/docs.py
 
 # Used when neither --model nor CLIFFY_AI_MODEL is given: the first provider with an API key in the
 # environment wins. Where a provider publishes a rolling alias it is preferred over a dated model id.
@@ -332,7 +334,9 @@ def report_usage(usage: RunUsage) -> None:
 )
 
 
-@click.group(help="AI-powered commands. Requires the `ai` extra: " + INSTALL_HINT)
+@click.group(
+    help="AI-powered commands. `generate` and `ask` require the `ai` extra: " + INSTALL_HINT,
+)
 def ai() -> None:
     pass
 
@@ -424,5 +428,12 @@ def ask(prompt: str, cli: IO[Any] | str | None, model: str | None, max_tokens: i
     report_usage(usage)
 
 
+@click.command(name="llms-txt", help="Print the bundled cliffy documentation as llms.txt. Needs no model.")
+def llms_txt() -> None:
+    # raw text on purpose: `out` would apply click styling to a file meant to be piped into other tools
+    click.echo(files("cliffy").joinpath(LLMS_TXT_FILE).read_text(encoding="utf-8"), nl=False)
+
+
 ai.command("generate", help="Generate a CLI manifest based on a description.")(generate)
 ai.command("ask", help="Ask a question about cliffy or a specific CLI manifest.")(ask)
+ai.add_command(llms_txt)

cliffy/checker.py

@@ -8,6 +8,7 @@
 import typer
 
 from cliffy.commander import CLI
+from cliffy.manifest import CLIManifest, Command, CommandParam
 
 GENERATED_FILE = "<generated CLI>"
 FUNCTION_DEFINITION = re.compile(r"(?:async\s+)?def (\w+)\(")
@@ -73,3 +74,29 @@ def check_generated_code(cli: CLI) -> None:
         ]
         line_number = generated_frames[-1].lineno if generated_frames else None
         raise GeneratedCodeError(describe(cli, e, line_number)) from e
+
+
+def ignored_param_settings(manifest: CLIManifest) -> list[str]:
+    """Params whose `default` or `help` is dropped because their type is a complete Typer definition."""
+    complete = {name for name, definition in manifest.types.items() if "typer." in definition}
+    problems = []
+    params = [("global_params", param) for param in manifest.global_params]
+    commands = manifest.commands
+    if isinstance(commands, list):
+        commands = {command.name: command for command in commands}
+    # a command can also be a bare run block, which has no params
+    params += [
+        (f"command `{name}`", param)
+        for name, command in commands.items()
+        if isinstance(command, Command)
+        for param in command.params
+    ]
+    for where, param in params:
+        if isinstance(param, CommandParam) and param.type in complete:
+            ignored = [setting for setting in ("default", "help", "short") if getattr(param, setting)]
+            if ignored:
+                problems.append(
+                    f"{where}, param `{param.name}`: `types.{param.type}` is a complete Typer definition, "
+                    f"so the param's {' and '.join(f'`{setting}`' for setting in ignored)} is ignored"
+                )
+    return problems

cliffy/cli.py

@@ -17,7 +17,7 @@
     format_size,
     run_cli,
 )
-from cliffy.checker import GeneratedCodeError, check_generated_code
+from cliffy.checker import GeneratedCodeError, check_generated_code, ignored_param_settings
 from cliffy.doc import DocGenerator
 from cliffy.helper import (
     CLI_NAME_PATTERN,
@@ -466,10 +466,13 @@ def validate(manifest: TextIO, blueprint: str | None = None) -> None:
     try:
         T = Transformer(manifest, blueprint=blueprint)
         check_generated_code(T.cli)
+        warnings = ignored_param_settings(T.manifest) if isinstance(T.manifest, CLIManifest) else []
     except GeneratedCodeError as e:
         exit_err(f"Manifest {manifest.name} is invalid: the generated code does not work\n  {e}")
     except Exception as e:
         exit_err(f"Manifest {manifest.name} is invalid: {e}")
+    for warning in warnings:
+        out(f"~ warning: {warning}", fg="yellow", err=True)
     out(f"Manifest {manifest.name} is valid", fg="green")