dirigent-cli 0.23.4__tar.gz → 0.25.0__tar.gz

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: dirigent-cli
-Version: 0.23.4
+Version: 0.25.0
 Summary: The dirigent command line interface (dirigent / dg).
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-block-execute==0.23.4
-Requires-Dist: dirigent-blocks==0.23.4
-Requires-Dist: dirigent-client==0.23.4
-Requires-Dist: dirigent-common==0.23.4
-Requires-Dist: dirigent-core==0.23.4
-Requires-Dist: dirigent-examples==0.23.4
-Requires-Dist: dirigent-plugin==0.23.4
-Requires-Dist: dirigent-server==0.23.4
+Requires-Dist: dirigent-block-execute==0.25.0
+Requires-Dist: dirigent-blocks==0.25.0
+Requires-Dist: dirigent-client==0.25.0
+Requires-Dist: dirigent-common==0.25.0
+Requires-Dist: dirigent-core==0.25.0
+Requires-Dist: dirigent-examples==0.25.0
+Requires-Dist: dirigent-plugin==0.25.0
+Requires-Dist: dirigent-server==0.25.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: pyyaml>=6.0.3

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.23.4"
+version = "0.25.0"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,14 +11,14 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-block-execute==0.23.4",
-    "dirigent-blocks==0.23.4",
-    "dirigent-client==0.23.4",
-    "dirigent-common==0.23.4",
-    "dirigent-core==0.23.4",
-    "dirigent-examples==0.23.4",
-    "dirigent-plugin==0.23.4",
-    "dirigent-server==0.23.4",
+    "dirigent-block-execute==0.25.0",
+    "dirigent-blocks==0.25.0",
+    "dirigent-client==0.25.0",
+    "dirigent-common==0.25.0",
+    "dirigent-core==0.25.0",
+    "dirigent-examples==0.25.0",
+    "dirigent-plugin==0.25.0",
+    "dirigent-server==0.25.0",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.23.4"
+version = "0.25.0"
 description = "The dirigent command line interface (dirigent / dg)."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,14 +11,14 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-block-execute==0.23.4",
-    "dirigent-blocks==0.23.4",
-    "dirigent-client==0.23.4",
-    "dirigent-common==0.23.4",
-    "dirigent-core==0.23.4",
-    "dirigent-examples==0.23.4",
-    "dirigent-plugin==0.23.4",
-    "dirigent-server==0.23.4",
+    "dirigent-block-execute==0.25.0",
+    "dirigent-blocks==0.25.0",
+    "dirigent-client==0.25.0",
+    "dirigent-common==0.25.0",
+    "dirigent-core==0.25.0",
+    "dirigent-examples==0.25.0",
+    "dirigent-plugin==0.25.0",
+    "dirigent-server==0.25.0",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/src/dirigent_cli/commands.py

@@ -1,6 +1,7 @@
 """The commands that talk to a server: definitions, execution, catalog, connections, admin."""
 
 import asyncio
+import json
 import os
 import sys
 from collections.abc import Callable, Iterator, Mapping, Sequence
@@ -43,6 +44,8 @@ from dirigent_cli.messages import (
     INIT_CANCELLED,
     INIT_REFUSED,
     INIT_WAY,
+    INPUT_FILE_UNREADABLE,
+    INPUT_REFUSED,
     INSTANCE_ALREADY_HERE,
     KEEP_IS_LOCAL_ONLY,
     LOCAL_RUN_HAD_NO_OUTCOME,
@@ -56,6 +59,7 @@ from dirigent_cli.messages import (
     NO_FAILURE_TO_RETRY,
     NO_FIRST_PASSWORD,
     NO_REPORT_DOCUMENT,
+    NO_SUCH_BLOCK,
     NO_SUCH_EXAMPLE,
     NOT_A_BLOCK_KIND,
     NOT_A_PRIORITY,
@@ -120,6 +124,7 @@ from dirigent_cli.project import (
     DEFAULT_PIPELINES_DIR,
     InitChoices,
     ProjectError,
+    agent_notes,
     check_choices,
     find_project,
     scaffold,
@@ -309,6 +314,18 @@ def _print_plan(result: ApplyResult, origin: str) -> bool:
     return True
 
 
+def _print_source_tokens(result: ApplyResult, *, base_url: str) -> None:
+    """Print each token an apply minted for a source, once, with where it is presented.
+
+    The instance stores only a token's hash; there is no second chance to read it.
+    """
+    for minted in result.sources.tokens:
+        console.print(f"\n  source [bold]{minted.code}[/]  {base_url.rstrip('/')}{minted.url_path}")
+        console.print(f"  Authorization: Bearer [bold]{minted.token}[/]")
+    if result.sources.tokens:
+        console.print("\n[yellow]Each token is shown once.[/] The instance stores only its hash.\n")
+
+
 def _print_graph(steps: Sequence[GraphStep], title: str = "steps") -> None:
     """Print a pipeline's shape: roots at the margin, each step under what it waits for."""
     lines = render_graph(steps)
@@ -322,7 +339,7 @@ def _print_graph(steps: Sequence[GraphStep], title: str = "steps") -> None:
 def graph_steps(definition: PipelineDefinition) -> list[GraphStep]:
     """Read a definition's steps in the shape the tree is drawn from."""
     return [
-        GraphStep(name=name, block=step.block, depends_on=tuple(step.depends_on), rule=step.rule.value)
+        GraphStep(name=name, block=step.block_id, depends_on=tuple(step.depends_on), rule=step.rule.value)
         for name, step in definition.steps.items()
     ]
 
@@ -402,6 +419,8 @@ def apply_command(
             raise typer.Exit(code=1)
         return
     accepted = all(_print_plan(result, origin) for result, origin in results)
+    for result, _ in results:
+        _print_source_tokens(result, base_url=dg.url)
     if pruned is not None:
         for code in pruned.pruned:
             console.print(f"{styled('deactivated'):<10} {code}  [dim](absent from the project)[/]")
@@ -484,10 +503,14 @@ def validate_command(
         bool, typer.Option("--explain", help="Also say what the work will cost: how wide, how many tries, how long.")
     ] = False,
 ) -> None:
-    """Check a document offline, or against a server's catalog too with --server.
+    """Check a document against the blocks installed beside dg, or against a server's with --server.
 
-    Offline, a triggers document is checked at the schema level: its clocks and its codes.
-    `--server` adds the pipeline it names and the parameters its schedules pin.
+    Offline, every step's block and config is checked against the blocks installed beside dg,
+    and a connection or pipeline a document names is not, since only an instance knows what it
+    holds; a triggers document is checked at the schema level, its clocks and its codes.
+    `--server` checks against the instance's own catalog instead, and adds the connections and
+    pipelines it holds, the pipeline a triggers document names, and the parameters its
+    schedules pin.
 
     `--explain` adds the shape of the work ahead for every pipeline document that is valid:
     the fan-out widths, the retry budgets and the waits. With `--server` too, a sensor that
@@ -509,11 +532,18 @@ def validate_command(
                 problems=[issue.model_dump(mode="json") for issue in error.problems],
             )
             failures += 1
-    catalog: Catalog | None = None
-    connections: list[str] = []
-    pipelines: list[str] = []
+    from dirigent_common import format_checker_with
+    from dirigent_core.plugins import load_plugin_host
+
+    host = load_plugin_host()
+    catalog = host.catalog()
+    blocks: Mapping[str, Any] | None = host.blocks
+    checker = format_checker_with(host.formats)
+    connections: list[str] | None = None
+    pipelines: list[str] | None = None
     targets: dict[str, TriggerTarget] = {}
     if server:
+        blocks = None
         with client_for(state) as dg:
             catalog = dg.call(dg.blocks.catalog())
             connections = [
@@ -527,10 +557,11 @@ def validate_command(
     for definition, label in parsed:
         issues = validate_against_catalog(
             definition,
-            catalog or Catalog(),
+            catalog,
             connections=connections,
             pipelines=pipelines,
-            check_blocks=catalog is not None,
+            blocks=blocks,
+            format_checker=checker,
             target=targets.get(definition.pipeline) if isinstance(definition, TriggersDefinition) else None,
         )
         if issues:
@@ -544,7 +575,7 @@ def validate_command(
             )
             failures += 1
             continue
-        checked = "document and catalog" if catalog is not None else "document, offline"
+        checked = "document and catalog" if server else "document and installed blocks"
         emit_fact(
             "validation",
             message="valid",
@@ -614,6 +645,10 @@ def init_command(
     ] = None,
     admin: Annotated[str, typer.Option(help="The first admin account's username.")] = "admin",
     password: Annotated[str | None, typer.Option(help="Its password; asked for when omitted.")] = None,
+    agents: Annotated[
+        bool,
+        typer.Option("--agents", help="Write only AGENTS.md and CLAUDE.md, into a project that already exists."),
+    ] = False,
 ) -> None:
     """Initialise a uv project and the instance it addresses, ready for `dg dev`.
 
@@ -624,7 +659,8 @@ def init_command(
     and mints it a token and a secret key, both kept in `.env`. `--template compose` writes the
     documents and a container stack instead, and initialises nothing locally: the instance is
     the containers. `--template documents` writes the documents alone, against an instance
-    somebody else runs.
+    somebody else runs. `--agents` writes a coding agent's notes alone, into a project made
+    before `dg init` wrote them, and keeps any the project already has.
     """
     import asyncio
 
@@ -633,6 +669,20 @@ def init_command(
     root = directory.resolve()
     version = cli_version()
     unasked = template is None and service is None and pack is None and pipeline is None and not workflow
+    if agents:
+        if not unasked or password is not None or admin != "admin":
+            _init_fail(INIT_REFUSED, detail="--agents writes the notes alone and takes no other option")
+        if not directory.is_dir():
+            _init_fail(INIT_REFUSED, detail=f"{directory} is not a directory; --agents writes into a project")
+        notes = agent_notes(directory)
+        emit_fact(
+            "project.scaffolded",
+            message="scaffolded",
+            directory=str(directory),
+            files=[_within(path, directory) for path in notes.files],
+            **({"skipped": [_within(path, directory) for path in notes.skipped]} if notes.skipped else {}),
+        )
+        return
     asked = unasked and sys.stdin.isatty() and sys.stdout.isatty()
     # Refusing happens before anything is written or asked for, so a run that cannot finish
     # has not half-created a project, and nobody fills a form for a command that was going
@@ -947,6 +997,29 @@ def pipeline_validate(
         raise typer.Exit(code=1)
 
 
+@pipeline_app.command("schema")
+def pipeline_schema(
+    file: Annotated[
+        Path | None, typer.Option("-f", "--file", help="Write the schema to this file instead of into the record.")
+    ] = None,
+) -> None:
+    """Compose the JSON Schema a document is written against, from the blocks installed beside dg.
+
+    It is the format and every installed block's config in one Draft 2020-12 schema, which an
+    editor or a language model checks a document against before anything validates it. Written
+    to a file, it is what a ``# yaml-language-server: $schema=`` comment names.
+    """
+    from dirigent_core.documentschema import document_schema
+
+    catalog = installed_catalog()
+    schema = document_schema(catalog)
+    if file is not None:
+        file.parent.mkdir(parents=True, exist_ok=True)
+        file.write_text(json.dumps(schema, indent=2) + "\n")
+        return emit_fact("pipeline.schema", message="written", path=str(file), blocks=len(catalog.blocks))
+    emit_fact("pipeline.schema", message="composed", blocks=len(catalog.blocks), schema=schema)
+
+
 @pipeline_app.command("activate")
 def pipeline_activate(ctx: typer.Context, code: Annotated[str, typer.Argument()]) -> None:
     """Make a pipeline runnable again."""
@@ -1080,6 +1153,23 @@ def parse_priority(value: str | None) -> RunPriority | None:
         )
 
 
+def parse_input(value: str | None) -> Any:
+    """Read what a hand run hands its source: JSON or YAML written out, or ``@FILE`` holding either."""
+    if value is None:
+        return None
+    text = value
+    if value.startswith("@"):
+        path = Path(value[1:])
+        try:
+            text = path.read_text()
+        except OSError as error:
+            fail(INPUT_FILE_UNREADABLE, path=str(path), detail=error.strerror or str(error))
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as error:
+        fail(INPUT_REFUSED, detail=str(error).splitlines()[0])
+
+
 def parse_importance(value: str | None) -> Importance | None:
     """Read the importance a rule was given, naming the vocabulary when it is not one."""
     if value is None:
@@ -1164,6 +1254,20 @@ def run_command(
             "Omitted takes the pipeline's own.",
         ),
     ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option(
+            "--source",
+            help="The source step a pipeline with sources is entered at. Omitted takes its only one.",
+        ),
+    ] = None,
+    given: Annotated[
+        str | None,
+        typer.Option(
+            "--input",
+            help="What arrives at that source, as JSON or YAML, or @FILE. Omitted takes the source's sample.",
+        ),
+    ] = None,
 ) -> None:
     """Run a pipeline by code, or apply and run a document in one command.
 
@@ -1182,6 +1286,7 @@ def run_command(
     wanted = parse_priority(priority)
     if wanted is not None and local:
         fail(PRIORITY_IS_NOT_LOCAL)
+    arrives = parse_input(given)
     if local:
         _run_locally(
             state,
@@ -1197,6 +1302,8 @@ def run_command(
             strict=strict,
             keep=keep,
             root=root,
+            source=source,
+            given=arrives,
         )
         return
     with client_for(state) as dg:
@@ -1224,7 +1331,11 @@ def run_command(
             stored = dg.call(dg.pipelines.get(code))
             schema = dict((stored.document or {}).get("params") or {})
         params = parse_params(param, schema=schema, files=params_file)
-        accepted = dg.call(dg.pipelines.run(code, params=params, window=covered, log_levels=levels, priority=wanted))
+        accepted = dg.call(
+            dg.pipelines.run(
+                code, params=params, window=covered, log_levels=levels, priority=wanted, source=source, input=arrives
+            )
+        )
         if accepted.run_id is None:
             if state.json_output:
                 emit_problem(
@@ -1315,6 +1426,8 @@ def _run_locally(
     strict: bool,
     keep: bool = False,
     root: Path | None = None,
+    source: str | None = None,
+    given: Any = None,
 ) -> None:
     """Apply and run a document in a throwaway instance, streaming what it logs."""
     if state.url is not None or state.profile is not None or state.token is not None:
@@ -1344,6 +1457,8 @@ def _run_locally(
             state=state,
             keep=keep,
             root=root,
+            source=source,
+            given=given,
         )
     )
     if outcome is None:  # pragma: no cover - the generator always ends with an outcome
@@ -1384,6 +1499,8 @@ async def _stream_local(
     state: CliState,
     keep: bool = False,
     root: Path | None = None,
+    source: str | None = None,
+    given: Any = None,
 ) -> LocalOutcome | None:
     """Drive a local run, printing each transition and log line as it lands."""
     outcome: LocalOutcome | None = None
@@ -1400,6 +1517,8 @@ async def _stream_local(
             inherited=settings,
             keep=keep,
             root=root,
+            source=source,
+            given=given,
         ):
             match item:
                 case LocalStarted():
@@ -2246,16 +2365,35 @@ def blocks_new(
     console.print("  [bold]uv sync && uv run pytest[/]")
 
 
+#: What ``--local`` means on the block commands.
+LOCAL_BLOCKS = "Read the blocks installed beside dg, instead of the instance's own."
+
+
+def installed_catalog() -> Catalog:
+    """Read the catalog every plugin installed beside this `dg` contributes, without addressing any server."""
+    from dirigent_core.plugins import load_plugin_host
+
+    return load_plugin_host().catalog()
+
+
 @blocks_app.command("list")
 def blocks_list(
     ctx: typer.Context,
     kind: Annotated[str | None, typer.Option(help="Only operators, or only sensors.")] = None,
+    local: Annotated[bool, typer.Option("--local", help=LOCAL_BLOCKS)] = False,
 ) -> None:
-    """List the blocks this instance can run."""
+    """List the blocks this instance can run, or with --local the ones installed beside dg."""
     if kind is not None and kind not in set(BlockKind):
         fail(NOT_A_BLOCK_KIND, kind=repr(kind), allowed=", ".join(sorted(BlockKind)))
-    with client_for(state_of(ctx)) as dg:
-        catalog = dg.call(dg.blocks.catalog(kind=BlockKind(kind) if kind else None))
+    wanted = BlockKind(kind) if kind else None
+    if local:
+        catalog = installed_catalog()
+        catalog = catalog.model_copy(
+            update={"blocks": [block for block in catalog.blocks if wanted is None or block.kind is wanted]}
+        )
+    else:
+        with client_for(state_of(ctx)) as dg:
+            catalog = dg.call(dg.blocks.catalog(kind=wanted))
     if state_of(ctx).json_output:
         emit_records("block", catalog.blocks)
         emit_records("storage_scheme", catalog.storage_schemes)
@@ -2276,10 +2414,17 @@ def blocks_list(
 def blocks_show(
     ctx: typer.Context,
     block_id: Annotated[str, typer.Argument(help="The block to describe.")],
+    local: Annotated[bool, typer.Option("--local", help=LOCAL_BLOCKS)] = False,
 ) -> None:
     """Show one block's config and output schemas."""
-    with client_for(state_of(ctx)) as dg:
-        entry = dg.call(dg.blocks.get(block_id))
+    if local:
+        found = [block for block in installed_catalog().blocks if block.id == block_id]
+        if not found:
+            fail(NO_SUCH_BLOCK, block=repr(block_id))
+        entry = found[0]
+    else:
+        with client_for(state_of(ctx)) as dg:
+            entry = dg.call(dg.blocks.get(block_id))
     if state_of(ctx).json_output:
         return emit_one("block", entry)
     fields(

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/src/dirigent_cli/explain.py

@@ -25,6 +25,7 @@ from dirigent_common import Duration, JsonMap, base_format_checker, format_durat
 from dirigent_core.engine.definition import ParameterError, PipelineDefinition, RetryPolicy, StepDefinition
 from dirigent_core.engine.failure import backoff_delay
 from dirigent_core.engine.references import ReferenceScope, UnknownReference, resolve
+from dirigent_core.engine.state import item_wise_parent
 
 #: What a cardinality says when the document alone cannot fix it.
 UNKNOWN: Final = "unknown"
@@ -65,7 +66,15 @@ def explain(definition: PipelineDefinition, catalog: Catalog | None = None) -> D
     order = definition.topological_order()
     shapes: dict[str, StepShape] = {}
     for name in order:
-        shapes[name] = _step_shape(name, definition.steps[name], params, shapes, catalog, definition.grid_source(name))
+        shapes[name] = _step_shape(
+            name,
+            definition.steps[name],
+            params,
+            shapes,
+            catalog,
+            definition.grid_source(name),
+            item_wise_parent(definition, name),
+        )
     rows = [shapes[name] for name in order]
     return DocumentShape(
         attempts_max=sum(row.max_attempts * (1 if row.elements is None else row.elements) for row in rows),
@@ -95,20 +104,23 @@ def _step_shape(
     done: Mapping[str, StepShape],
     catalog: Catalog | None,
     source: str | None,
+    paired: str | None = None,
 ) -> StepShape:
     """Read one step as the work it will become, against the steps already read.
 
-    ``source`` is the step a late grid waits for, which the row names.
+    ``source`` is the step a late grid waits for, and ``paired`` the fan-out whose items this
+    step's items wait for one by one; the row names both.
     """
     cardinality, elements = _cardinality(step, params, done, source)
     poll, deadline, from_block = _waits(step, _entry(step, catalog))
     return StepShape(
         name=name,
-        block=step.block,
+        block=step.block_id,
         depends_on=list(step.depends_on),
         cardinality=cardinality,
         elements=elements,
         grid_source=source,
+        item_wise_parent=paired,
         reference=step.for_each if isinstance(step.for_each, str) else None,
         items=step.items.value,
         max_attempts=step.retry.max_attempts,
@@ -147,7 +159,7 @@ def _cardinality(
 
 def _entry(step: StepDefinition, catalog: Catalog | None) -> BlockEntry | None:
     """Find what the catalog says about this step's block, where there is a catalog."""
-    return None if catalog is None else catalog.block(step.block)
+    return None if catalog is None or step.block is None else catalog.block(step.block)
 
 
 def _waits(step: StepDefinition, entry: BlockEntry | None) -> tuple[timedelta | None, timedelta | None, list[str]]:

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/src/dirigent_cli/graph.py

@@ -30,7 +30,7 @@ def steps_of_document(document: Mapping[str, Any]) -> list[GraphStep]:
         read.append(
             GraphStep(
                 name=str(name),
-                block=str(held.get("block", "-")),
+                block=_block_of(held),
                 depends_on=tuple(str(item) for item in cast("list[Any]", depends or ())),
                 rule=str(held.get("rule", DEFAULT_RULE)),
             )
@@ -38,6 +38,16 @@ def steps_of_document(document: Mapping[str, Any]) -> list[GraphStep]:
     return read
 
 
+def _block_of(step: Mapping[str, Any]) -> str:
+    """Name what a step runs: its block, a source's kind, or ``reply``."""
+    source = step.get("source")
+    if isinstance(source, dict):
+        return str(cast("dict[str, Any]", source).get("kind", "source"))
+    if "reply" in step:
+        return "reply"
+    return str(step.get("block", "-"))
+
+
 def render_graph(steps: Sequence[GraphStep]) -> list[str]:
     """Draw the graph as indented lines, each step under the last step it waits for.
 

{dirigent_cli-0.23.4 → dirigent_cli-0.25.0}/src/dirigent_cli/init_form.py

@@ -238,6 +238,8 @@ class InitForm(App[InitChoices | None]):
             ".dirigent/profiles.yaml",
             "pyproject.toml",
             "README.md",
+            "AGENTS.md",
+            "CLAUDE.md",
         ]
         if choices.stack:
             files += ["compose.yaml", "Dockerfile", ".env"]