dirigent-cli 0.15.1__tar.gz → 0.15.2__tar.gz

{dirigent_cli-0.15.1 → dirigent_cli-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirigent-cli
-Version: 0.15.1
+Version: 0.15.2
 Summary: The dirigent command line interface (dirigent / dg).
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE

{dirigent_cli-0.15.1 → dirigent_cli-0.15.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.15.1"
+version = "0.15.2"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"

{dirigent_cli-0.15.1 → dirigent_cli-0.15.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.15.1"
+version = "0.15.2"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"

{dirigent_cli-0.15.1 → dirigent_cli-0.15.2}/src/dirigent_cli/commands.py

@@ -65,7 +65,14 @@ from dirigent_cli.project import (
     write_token_env,
 )
 from dirigent_cli.scaffold import ScaffoldedRecord, ScaffoldError, ScaffoldRecord, scaffold_pack
-from dirigent_cli.sources import Document, SourceError, looks_like_a_document, read_document, read_path
+from dirigent_cli.sources import (
+    Document,
+    SourceError,
+    looks_like_a_document,
+    parse_document,
+    read_document,
+    read_path,
+)
 from dirigent_cli.stream import Sink, track_steps, use_scratch_prefix
 from dirigent_cli.timing import RunProfile, attempt_timing, by_step, profile, step_timing
 from dirigent_client import (
@@ -184,9 +191,13 @@ def _apply_one(
     source: ProvenanceSource | None = None,
 ) -> ApplyResult:
     """Apply one document and return the server's result."""
+    try:
+        body = parse_document(document)
+    except SourceError as error:
+        fail(str(error))
     return dg.call(
         dg.pipelines.apply(
-            cast("dict[str, Any]", yaml.safe_load(document.text)),
+            body,
             code=code,
             source=source if source is not None else document.source,
             source_ref=document.ref,
@@ -374,12 +385,20 @@ def export_command(
     """Export a pipeline as canonical YAML."""
     with client_for(state_of(ctx)) as dg:
         text = dg.call(dg.pipelines.export(code, version=version))
+    if file is not None:
+        file.write_text(text)
     if state_of(ctx).json_output:
-        return emit_fact("pipeline.exported", message="exported", code=code, version=version, document=text)
+        return emit_fact(
+            "pipeline.exported",
+            message="exported",
+            code=code,
+            version=version,
+            document=text,
+            path=None if file is None else str(file),
+        )
     if file is None:
         console.print(text, end="", highlight=False, markup=False)
         return
-    file.write_text(text)
     console.print(f"Wrote [bold]{file}[/].")
 
 
@@ -2713,11 +2732,25 @@ def examples_list(
 def examples_show(
     ctx: typer.Context,
     code: Annotated[str, typer.Argument(help="The example to read.")],
+    file: Annotated[
+        Path | None, typer.Option("-f", "--file", help="Write the document to a file instead of stdout.")
+    ] = None,
     local: Annotated[bool, typer.Option("--local", help=LOCAL_CATALOGUE)] = False,
 ) -> None:
-    """Print one example's document, verbatim, as the shelf holds it."""
+    """Print one example's document, verbatim, as the shelf holds it, or write it to a file.
+
+    Stdout in a pipe carries records like every command, so a redirect keeps a record and
+    not the document; `-f` writes the document itself.
+    """
     state = state_of(ctx)
     entry = _example(state, code, local=local)
+    if file is not None:
+        file.parent.mkdir(parents=True, exist_ok=True)
+        file.write_text(entry.source)
+        if state.json_output:
+            return emit_fact("example.written", message="written", code=entry.code, path=str(file))
+        console.print(f"Wrote [bold]{file}[/].")
+        return
     if state.json_output:
         return emit_fact("example.source", message="example", **entry.model_dump(mode="json"))
     console.print(entry.source, end="", highlight=False, markup=False)

{dirigent_cli-0.15.1 → dirigent_cli-0.15.2}/src/dirigent_cli/sources.py

@@ -2,9 +2,10 @@
 
 import sys
 from pathlib import Path
-from typing import Final
+from typing import Any, Final, cast
 
 import httpx2
+import yaml
 from pydantic import BaseModel, ConfigDict
 
 from dirigent_client.enums import ProvenanceSource
@@ -67,6 +68,31 @@ def read_path(path: Path) -> Document:
     return Document(text=path.read_text(), source=ProvenanceSource.FILE, ref=str(path))
 
 
+def parse_document(document: Document) -> dict[str, Any]:
+    """Parse a document's text, refusing what is plainly not a pipeline document, by name.
+
+    The server checks the same things, but it never saw the file: an error that names the path
+    is the one a person can act on when a whole project was applied.
+    """
+    try:
+        parsed = yaml.safe_load(document.text)
+    except yaml.YAMLError as error:
+        raise SourceError(f"{document.label} is not readable YAML or JSON: {error}") from error
+    if not isinstance(parsed, dict):
+        kind = "empty" if parsed is None else type(parsed).__name__
+        raise SourceError(f"{document.label} is not a document: a document is a mapping, and this file is {kind}")
+    if "format" not in parsed:
+        if "kind" in parsed:
+            raise SourceError(
+                f"{document.label} holds a dg record (kind {parsed['kind']!r}), not a document: a command whose "
+                "stdout is a pipe writes records, so a redirect keeps the record and not the rendering. Write "
+                "the document with `dg examples show CODE -f FILE` or `dg export CODE -f FILE`, or copy a "
+                "starter with `dg pipeline new STARTER`."
+            )
+        raise SourceError(f"{document.label} declares no format; add `format: dirigent/v1`")
+    return cast("dict[str, Any]", parsed)
+
+
 def looks_like_a_document(reference: str) -> bool:
     """Report whether an argument names a document rather than a pipeline.