scrolly 0.2.4__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrolly
-Version: 0.2.4
+Version: 0.3.0
 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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "scrolly"
-version = "0.2.4"
+version = "0.3.0"
 description = "CLI that compiles a JSON5 deck + slide files into a self-contained 2D-canvas HTML presentation."
 readme = "README.md"
 license = "MIT"
@@ -51,7 +51,7 @@ capture = [
 ]
 
 [project.scripts]
-scrolly = "scrolly._cli._cli:cli"
+scrolly = "scrolly._cli.cli:cli"
 
 [project.urls]
 Homepage = "https://scrolly.readthedocs.io/en/stable/"

{scrolly-0.2.4 → scrolly-0.3.0}/scrolly/_cli/_introspect/__init__.py

@@ -23,13 +23,13 @@ from __future__ import annotations
 
 import click
 
-from scrolly._cli._introspect._assets import assets_command
-from scrolly._cli._introspect._dom import dom_command
-from scrolly._cli._introspect._elements import elements_command
-from scrolly._cli._introspect._slides import slides_command
-from scrolly._cli._introspect._snaps import snaps_command
-from scrolly._cli._introspect._snapshot import snapshot_command
-from scrolly._cli._introspect._timeline import timeline_command
+from scrolly._cli._introspect.assets import assets_command
+from scrolly._cli._introspect.dom import dom_command
+from scrolly._cli._introspect.elements import elements_command
+from scrolly._cli._introspect.slides import slides_command
+from scrolly._cli._introspect.snaps import snaps_command
+from scrolly._cli._introspect.snapshot import snapshot_command
+from scrolly._cli._introspect.timeline import timeline_command
 
 
 @click.group(name="introspect")

scrolly-0.2.4/scrolly/_cli/_introspect/_assets.py → scrolly-0.3.0/scrolly/_cli/_introspect/assets.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.pipeline.introspect import assets_to_json
 
 

scrolly-0.2.4/scrolly/_cli/_introspect/_common.py → scrolly-0.3.0/scrolly/_cli/_introspect/common.py

@@ -13,23 +13,37 @@ Every subcommand goes through ``run_introspect_command``, which:
 from __future__ import annotations
 
 import json
-import sys
 from collections.abc import Callable
 from pathlib import Path
 
 import click
-from rich.console import Console
 
+from scrolly._cli.console import error_exit
 from scrolly.deck.model import Deck
 from scrolly.errors import ScrollyError
 from scrolly.pipeline import load_deck
 from scrolly.slide.ir import SlideIR
 
-_err_console = Console(stderr=True, highlight=False)
-
 ToJsonFn = Callable[[Deck, dict[str, SlideIR], tuple[str, ...] | None], dict]
 
 
+def _load_deck_or_exit(deck_path: Path) -> tuple[Deck, dict[str, SlideIR]]:
+    """Load and validate a deck, or print the error to stderr and exit non-zero."""
+    try:
+        return load_deck(deck_path)
+    except ScrollyError as e:
+        error_exit(str(e))
+
+
+def _emit_json(payload: dict, output_path: Path | None) -> None:
+    """Write an indented JSON payload to ``output_path``, or stdout when ``None``."""
+    rendered = json.dumps(payload, indent=2)
+    if output_path is not None:
+        output_path.write_text(rendered, encoding="utf-8")
+    else:
+        click.echo(rendered)
+
+
 def run_introspect_command(
     deck_path: Path,
     slide_ids: tuple[str, ...],
@@ -49,28 +63,16 @@ def run_introspect_command(
         SystemExit: Non-zero exit on validation gate failure or unknown
             ``--slide`` ids; the error message goes to stderr.
     """
-    try:
-        deck, slide_irs = load_deck(deck_path)
-    except ScrollyError as e:
-        _err_console.print(f"[red]error:[/red] {e}")
-        sys.exit(1)
+    deck, slide_irs = _load_deck_or_exit(deck_path)
 
     if slide_ids:
         known = {s.id for s in deck.slides}
         unknown = [sid for sid in slide_ids if sid not in known]
         if unknown:
-            _err_console.print(
-                f"[red]error:[/red] unknown slide id(s): {', '.join(unknown)}. Known: {', '.join(sorted(known))}"
-            )
-            sys.exit(1)
+            error_exit(f"unknown slide id(s): {', '.join(unknown)}. Known: {', '.join(sorted(known))}")
 
     payload = to_json_fn(deck, slide_irs, slide_ids or None)
-    rendered = json.dumps(payload, indent=2)
-
-    if output_path is not None:
-        output_path.write_text(rendered, encoding="utf-8")
-    else:
-        click.echo(rendered)
+    _emit_json(payload, output_path)
 
 
 def run_snapshot_command(
@@ -103,16 +105,11 @@ def run_snapshot_command(
     """
     from scrolly.slide.introspect import snapshot_to_json
 
-    try:
-        deck, slide_irs = load_deck(deck_path)
-    except ScrollyError as e:
-        _err_console.print(f"[red]error:[/red] {e}")
-        sys.exit(1)
+    deck, slide_irs = _load_deck_or_exit(deck_path)
 
     known = {s.id for s in deck.slides}
     if slide_id not in known:
-        _err_console.print(f"[red]error:[/red] unknown slide id: '{slide_id}'. Known: {', '.join(sorted(known))}")
-        sys.exit(1)
+        error_exit(f"unknown slide id: '{slide_id}'. Known: {', '.join(sorted(known))}")
 
     ir = slide_irs[slide_id]
     scroll_range = ir.scroll_range
@@ -124,13 +121,7 @@ def run_snapshot_command(
             invalid.append((scroll, f"exceeds slide's scroll_range ({scroll_range})"))
     if invalid:
         lines = "\n".join(f"  scroll={s}: {reason}" for s, reason in invalid)
-        _err_console.print(f"[red]error:[/red] --scroll out-of-range for slide '{slide_id}':\n{lines}")
-        sys.exit(1)
+        error_exit(f"--scroll out-of-range for slide '{slide_id}':\n{lines}")
 
     payload = snapshot_to_json(deck, slide_irs, slide_id, scrolls)
-    rendered = json.dumps(payload, indent=2)
-
-    if output_path is not None:
-        output_path.write_text(rendered, encoding="utf-8")
-    else:
-        click.echo(rendered)
+    _emit_json(payload, output_path)

scrolly-0.2.4/scrolly/_cli/_introspect/_dom.py → scrolly-0.3.0/scrolly/_cli/_introspect/dom.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.slide.introspect import dom_to_json
 
 

scrolly-0.2.4/scrolly/_cli/_introspect/_elements.py → scrolly-0.3.0/scrolly/_cli/_introspect/elements.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.slide.introspect import element_tree_to_json
 
 

scrolly-0.2.4/scrolly/_cli/_introspect/_slides.py → scrolly-0.3.0/scrolly/_cli/_introspect/slides.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.deck.introspect import slides_to_json
 
 

scrolly-0.2.4/scrolly/_cli/_introspect/_snaps.py → scrolly-0.3.0/scrolly/_cli/_introspect/snaps.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.slide.introspect import snaps_to_json
 
 
@@ -26,10 +26,10 @@ from scrolly.slide.introspect import snaps_to_json
     help="Write JSON to this file instead of stdout.",
 )
 def snaps_command(deck_path: Path, slide_ids: tuple[str, ...], output_path: Path | None) -> None:
-    """Per-slide snap positions: author-supplied + element-derived (image_sequence hold-centres).
+    """Per-slide snap positions: author-supplied + element-derived (image_sequence hold-centers).
 
     Author entries come from each slide's ``snap_positions`` field;
-    derived entries come from ``ImageSequenceElement`` hold-centres
+    derived entries come from ``ImageSequenceElement`` hold-centers
     (one per frame). The ``merged`` list is the deduplicated + sorted
     union — what the canvas runtime actually uses.
 

scrolly-0.2.4/scrolly/_cli/_introspect/_snapshot.py → scrolly-0.3.0/scrolly/_cli/_introspect/snapshot.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_snapshot_command
+from scrolly._cli._introspect.common import run_snapshot_command
 
 
 @click.command(name="snapshot")

scrolly-0.2.4/scrolly/_cli/_introspect/_timeline.py → scrolly-0.3.0/scrolly/_cli/_introspect/timeline.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 import click
 
-from scrolly._cli._introspect._common import run_introspect_command
+from scrolly._cli._introspect.common import run_introspect_command
 from scrolly.slide.introspect import timeline_to_json
 
 

scrolly-0.3.0/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/_cli/_cli.py → scrolly-0.3.0/scrolly/_cli/cli.py

@@ -3,21 +3,38 @@ import sys
 from pathlib import Path
 
 import click
-from rich.console import Console
 
 from scrolly import __version__
-from scrolly._cli._errors import errors_command
 from scrolly._cli._introspect import introspect
-from scrolly._cli._schema import schema
+from scrolly._cli.console import err_console, error_exit, print_error
+from scrolly._cli.errors import errors_command
+from scrolly._cli.schema import schema
+from scrolly.deck import Deck
 from scrolly.errors import ScrollyError, ValidationError
 from scrolly.pipeline import build_deck, load_deck
 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."""
 
@@ -74,8 +91,7 @@ def build(
             offline=offline,
         )
     except ScrollyError as e:
-        _err_console.print(f"[red]error:[/red] {e}")
-        sys.exit(1)
+        error_exit(str(e))
 
     if strict:
         _report_diagnostics(deck)
@@ -100,7 +116,7 @@ def validate(deck_path: Path, strict: bool, as_json: bool) -> None:
         if as_json:
             click.echo(json.dumps({"ok": False, "errors": [_error_to_dict(e)]}, indent=2))
         else:
-            _err_console.print(f"[red]error:[/red] {e}")
+            print_error(str(e))
         sys.exit(1)
 
     if strict:
@@ -113,7 +129,7 @@ def validate(deck_path: Path, strict: bool, as_json: bool) -> None:
 
 
 def _error_to_dict(err: ScrollyError) -> dict:
-    """Serialise a ``ScrollyError`` for JSON output."""
+    """Serialize a ``ScrollyError`` for JSON output."""
     if isinstance(err, ValidationError):
         return {
             "code": err.code,
@@ -126,11 +142,11 @@ def _error_to_dict(err: ScrollyError) -> dict:
     return {"code": None, "message": str(err)}
 
 
-def _report_diagnostics(deck) -> None:
+def _report_diagnostics(deck: Deck) -> None:
     """Run lint checks and print any diagnostics to stderr."""
     diagnostics = lint_deck(deck)
     for d in diagnostics:
-        _err_console.print(f"[yellow]{d.level}:[/yellow] {d.location}: {d.message}")
+        err_console.print(f"[yellow]{d.level}:[/yellow] {d.location}: {d.message}")
 
 
 _INIT_DECK = """\
@@ -145,7 +161,7 @@ _INIT_DECK = """\
 
 _INIT_SLIDE = """\
 {
-  title: "My Deck",
+  title: "Intro",
   elements: [
     { markdown: "# My Deck\\n\\nWelcome to your new presentation." },
   ],
@@ -158,8 +174,7 @@ _INIT_SLIDE = """\
 def init(dir_path: Path) -> None:
     """Scaffold a minimal deck in DIR_PATH."""
     if dir_path.exists() and any(dir_path.iterdir()):
-        _err_console.print(f"[red]error:[/red] directory is not empty: {dir_path}")
-        sys.exit(1)
+        error_exit(f"directory is not empty: {dir_path}")
 
     slides_dir = dir_path / "slides"
     slides_dir.mkdir(parents=True, exist_ok=True)

scrolly-0.3.0/scrolly/_cli/console.py

@@ -0,0 +1,28 @@
+"""Shared stderr console and error-reporting helpers for the CLI commands.
+
+Every command surfaces failures the same way — a red ``error:`` line on a
+stderr-only Rich console, followed (for terminal failures) by a non-zero
+exit. Centralizing the console instance and that idiom here keeps the
+formatting identical across ``build``, ``validate``, ``schema``,
+``errors``, and the ``introspect`` subcommands.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import NoReturn
+
+from rich.console import Console
+
+err_console = Console(stderr=True, highlight=False)
+
+
+def print_error(message: str) -> None:
+    """Print a red ``error:`` line to stderr without exiting."""
+    err_console.print(f"[red]error:[/red] {message}")
+
+
+def error_exit(message: str) -> NoReturn:
+    """Print a red ``error:`` line to stderr and exit non-zero."""
+    print_error(message)
+    sys.exit(1)

scrolly-0.2.4/scrolly/_cli/_errors.py → scrolly-0.3.0/scrolly/_cli/errors.py

@@ -10,16 +10,12 @@ Three forms, mirroring the progressive-disclosure pattern used by
 
 from __future__ import annotations
 
-import sys
-
 import click
-from rich.console import Console
 
+from scrolly._cli.console import error_exit
 from scrolly.errors import is_registered_code, registered_codes
 from scrolly.errors._catalog import load_body, load_summary
 
-_err_console = Console(stderr=True, highlight=False)
-
 
 @click.command(name="errors")
 @click.argument("code", required=False)
@@ -48,7 +44,6 @@ def errors_command(code: str | None, list_codes: bool) -> None:
         return
 
     if not is_registered_code(code):
-        _err_console.print(f"[red]error:[/red] unknown error code '{code}'")
-        sys.exit(1)
+        error_exit(f"unknown error code '{code}'")
 
     click.echo(load_body(code))

scrolly-0.2.4/scrolly/_cli/_schema.py → scrolly-0.3.0/scrolly/_cli/schema.py

@@ -18,12 +18,10 @@ specific *resolved deck instance* — different surfaces, kept distinct.
 from __future__ import annotations
 
 import json
-import sys
 
 import click
-from rich.console import Console
 
-_err_console = Console(stderr=True, highlight=False)
+from scrolly._cli.console import error_exit
 
 # Width of the name / suffix columns in the human-readable index, matching
 # the alignment used by ``scrolly errors``.
@@ -53,9 +51,9 @@ def schema(ctx: click.Context) -> None:
         _print_element_index()
 
 
-# --------------------------------------------------------------------------
+# ==================================================================================================
 #  Subcommands
-# --------------------------------------------------------------------------
+# ==================================================================================================
 @schema.command(name="file")
 @click.argument("type_name", required=False)
 @click.option(
@@ -72,7 +70,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 +81,10 @@ 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:
-        _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))
+    schema_text = file_schema_json(type_name)
+    if schema_text is None:
+        error_exit(f"unknown file type '{type_name}' (known: {', '.join(names)})")
+    click.echo(schema_text)
 
 
 @schema.command(name="element")
@@ -119,16 +116,16 @@ def schema_element(type_name: str | None, list_types: bool) -> None:
         _print_element_index()
         return
 
-    if type_name not in elements:
-        _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))
+    schema_text = element_schema_json(type_name)
+    if schema_text is None:
+        error_exit(f"unknown element type '{type_name}' (known: {', '.join(elements)})")
+    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 +145,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

scrolly-0.3.0/scrolly/_shared/__init__.py

@@ -0,0 +1 @@
+"""Layer-neutral primitives shared across the deck / slide / render / pipeline layers."""