scrolly 0.2.4__tar.gz → 0.2.5__tar.gz

{scrolly-0.2.4 → scrolly-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrolly
-Version: 0.2.4
+Version: 0.2.5
 Summary: CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation.
 Project-URL: Homepage, https://scrolly.readthedocs.io/en/stable/
 Project-URL: Documentation, https://scrolly.readthedocs.io/en/stable/

{scrolly-0.2.4 → scrolly-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.4"
+version = "0.2.5"
 description = "CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation."
 readme = "README.md"
 license = "MIT"

scrolly-0.2.5/scrolly/_cli/_ai_help.py

@@ -0,0 +1,124 @@
+"""Builds the ``scrolly --help-for-ai-tools`` document.
+
+One markdown document covering the entire CLI surface in a single read —
+the command tree, every source-file and element schema, and every error
+code — so an LLM agent gets the whole picture without round-tripping
+through ``scrolly schema`` / ``scrolly errors`` per type and code. It is
+a pure aggregator: every section is the output the individual commands
+already produce, merged under markdown headers, never re-rendered.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import click
+
+from scrolly._cli._schema import element_schema_json, file_schema_json, file_type_names
+from scrolly.errors import registered_codes
+from scrolly.errors._catalog import load_body
+from scrolly.slide import element_source_types
+
+
+# ==================================================================================================
+#  Document assembly
+# ==================================================================================================
+def build_ai_help(root_command: click.Command, version: str) -> str:
+    """Render the whole CLI reference as one self-contained markdown document.
+
+    Args:
+        root_command: The top-level ``scrolly`` Click group, walked for the command tree.
+        version: The scrolly version string, shown in the document header.
+
+    Returns:
+        A single markdown document: header, command tree, file schemas,
+        element schemas, and error codes — heading levels nested so the
+        whole document forms one consistent hierarchy.
+    """
+    sections = [
+        _header(version),
+        _commands_section(root_command),
+        _file_schemas_section(),
+        _element_schemas_section(),
+        _error_codes_section(),
+    ]
+    return "\n\n".join(sections) + "\n"
+
+
+def _header(version: str) -> str:
+    """Render the document title and one-paragraph orientation."""
+    return (
+        f"# scrolly {version} — CLI reference for AI tools\n\n"
+        "The complete scrolly command-line surface in one document: every command, "
+        "every source-file and element schema, and every error code. Generated from "
+        "the installed scrolly, so it matches this version exactly."
+    )
+
+
+# ==================================================================================================
+#  Sections
+# ==================================================================================================
+def _commands_section(root_command: click.Command) -> str:
+    """Render every command's help text, walking the full command tree."""
+    blocks = ["## Commands"]
+    for path, help_text in _walk_commands(root_command, "scrolly", None):
+        blocks.append(f"### `{path}`\n\n```\n{help_text.rstrip()}\n```")
+    return "\n\n".join(blocks)
+
+
+def _file_schemas_section() -> str:
+    """Render the JSON Schema for every source-file type (deck, slide)."""
+    blocks = ["## File schemas"]
+    for name in file_type_names():
+        blocks.append(f"### `{name}`\n\n```json\n{file_schema_json(name)}\n```")
+    return "\n\n".join(blocks)
+
+
+def _element_schemas_section() -> str:
+    """Render the JSON Schema for every slide-element type."""
+    blocks = ["## Element schemas"]
+    for key in element_source_types():
+        blocks.append(f"### `{key}`\n\n```json\n{element_schema_json(key)}\n```")
+    return "\n\n".join(blocks)
+
+
+def _error_codes_section() -> str:
+    """Render the catalog entry for every registered error code.
+
+    Each catalog body is verbatim markdown starting at its own ``# E…``
+    heading; demoting by two levels nests every entry under this section.
+    """
+    blocks = ["## Error codes"]
+    for code in sorted(registered_codes()):
+        blocks.append(_demote_headings(load_body(code).rstrip(), 2))
+    return "\n\n".join(blocks)
+
+
+# ==================================================================================================
+#  Helpers
+# ==================================================================================================
+def _walk_commands(
+    command: click.Command, info_name: str, parent_ctx: click.Context | None
+) -> Iterator[tuple[str, str]]:
+    """Yield ``(command_path, help_text)`` for a command and all its subcommands, depth-first."""
+    ctx = click.Context(command, info_name=info_name, parent=parent_ctx)
+    yield ctx.command_path, command.get_help(ctx)
+    if isinstance(command, click.Group):
+        for name in command.list_commands(ctx):
+            sub = command.get_command(ctx, name)
+            if sub is None or sub.hidden:
+                continue
+            yield from _walk_commands(sub, name, ctx)
+
+
+def _demote_headings(markdown: str, levels: int) -> str:
+    """Deepen every ATX heading by ``levels`` ``#``, leaving fenced code blocks untouched."""
+    out = []
+    in_fence = False
+    for line in markdown.splitlines():
+        if line.lstrip().startswith("```"):
+            in_fence = not in_fence
+        if not in_fence and line.startswith("#"):
+            line = "#" * levels + line
+        out.append(line)
+    return "\n".join(out)

{scrolly-0.2.4 → scrolly-0.2.5}/scrolly/_cli/_cli.py

@@ -16,8 +16,26 @@ from scrolly.pipeline.lint import lint_deck
 _err_console = Console(stderr=True, highlight=False)
 
 
+def _emit_ai_help(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    """Eager ``--help-for-ai-tools`` callback: print the full CLI reference and exit."""
+    if not value or ctx.resilient_parsing:
+        return
+    from scrolly._cli._ai_help import build_ai_help
+
+    click.echo(build_ai_help(ctx.find_root().command, __version__))
+    ctx.exit()
+
+
 @click.group()
 @click.version_option(__version__, prog_name="scrolly")
+@click.option(
+    "--help-for-ai-tools",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_emit_ai_help,
+    help="Print the entire CLI reference (commands, schemas, error codes) as one markdown document for AI agents.",
+)
 def cli() -> None:
     """scrolly — compile a JSON5 deck into a self-contained 2D-canvas HTML presentation."""
 

{scrolly-0.2.4 → scrolly-0.2.5}/scrolly/_cli/_schema.py

@@ -72,7 +72,7 @@ def schema_file(type_name: str | None, list_types: bool) -> None:
     scrolly schema file <type>       → JSON Schema for <type>
     scrolly schema file --list-types → bare type names, one per line (agent / scripting)
     """
-    names = _file_type_names()
+    names = file_type_names()
 
     if list_types:
         for name in names:
@@ -83,11 +83,11 @@ def schema_file(type_name: str | None, list_types: bool) -> None:
         _print_file_index()
         return
 
-    schema_dict = _file_schema(type_name)
-    if schema_dict is None:
+    schema_text = file_schema_json(type_name)
+    if schema_text is None:
         _err_console.print(f"[red]error:[/red] unknown file type '{type_name}' (known: {', '.join(names)})")
         sys.exit(1)
-    click.echo(json.dumps(schema_dict, indent=2))
+    click.echo(schema_text)
 
 
 @schema.command(name="element")
@@ -119,16 +119,17 @@ def schema_element(type_name: str | None, list_types: bool) -> None:
         _print_element_index()
         return
 
-    if type_name not in elements:
+    schema_text = element_schema_json(type_name)
+    if schema_text is None:
         _err_console.print(f"[red]error:[/red] unknown element type '{type_name}' (known: {', '.join(elements)})")
         sys.exit(1)
-    click.echo(json.dumps(elements[type_name].source_schema(), indent=2))
+    click.echo(schema_text)
 
 
 # --------------------------------------------------------------------------
 #  Schema lookup + index rendering
 # --------------------------------------------------------------------------
-def _file_type_names() -> list[str]:
+def file_type_names() -> list[str]:
     """Return the sorted source-file type names (deck + registered slide types)."""
     from scrolly.slide import registered_ir_types
 
@@ -148,6 +149,22 @@ def _file_schema(type_name: str) -> dict | None:
     return None
 
 
+def file_schema_json(type_name: str) -> str | None:
+    """Render a source-file type's JSON Schema as indented JSON text, or ``None`` if unknown."""
+    schema_dict = _file_schema(type_name)
+    return None if schema_dict is None else json.dumps(schema_dict, indent=2)
+
+
+def element_schema_json(type_name: str) -> str | None:
+    """Render an element type's JSON Schema as indented JSON text, or ``None`` if unknown."""
+    from scrolly.slide import element_source_types
+
+    elements = element_source_types()
+    if type_name not in elements:
+        return None
+    return json.dumps(elements[type_name].source_schema(), indent=2)
+
+
 def _print_file_index() -> None:
     """Print the human-readable index of source-file schemas."""
     from scrolly.slide import registered_ir_types