dirigent-cli 0.24.0__tar.gz → 0.25.1__tar.gz

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: dirigent-cli
-Version: 0.24.0
+Version: 0.25.1
 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.24.0
-Requires-Dist: dirigent-blocks==0.24.0
-Requires-Dist: dirigent-client==0.24.0
-Requires-Dist: dirigent-common==0.24.0
-Requires-Dist: dirigent-core==0.24.0
-Requires-Dist: dirigent-examples==0.24.0
-Requires-Dist: dirigent-plugin==0.24.0
-Requires-Dist: dirigent-server==0.24.0
+Requires-Dist: dirigent-block-execute==0.25.1
+Requires-Dist: dirigent-blocks==0.25.1
+Requires-Dist: dirigent-client==0.25.1
+Requires-Dist: dirigent-common==0.25.1
+Requires-Dist: dirigent-core==0.25.1
+Requires-Dist: dirigent-examples==0.25.1
+Requires-Dist: dirigent-plugin==0.25.1
+Requires-Dist: dirigent-server==0.25.1
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: pyyaml>=6.0.3

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.24.0"
+version = "0.25.1"
 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.24.0",
-    "dirigent-blocks==0.24.0",
-    "dirigent-client==0.24.0",
-    "dirigent-common==0.24.0",
-    "dirigent-core==0.24.0",
-    "dirigent-examples==0.24.0",
-    "dirigent-plugin==0.24.0",
-    "dirigent-server==0.24.0",
+    "dirigent-block-execute==0.25.1",
+    "dirigent-blocks==0.25.1",
+    "dirigent-client==0.25.1",
+    "dirigent-common==0.25.1",
+    "dirigent-core==0.25.1",
+    "dirigent-examples==0.25.1",
+    "dirigent-plugin==0.25.1",
+    "dirigent-server==0.25.1",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-cli"
-version = "0.24.0"
+version = "0.25.1"
 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.24.0",
-    "dirigent-blocks==0.24.0",
-    "dirigent-client==0.24.0",
-    "dirigent-common==0.24.0",
-    "dirigent-core==0.24.0",
-    "dirigent-examples==0.24.0",
-    "dirigent-plugin==0.24.0",
-    "dirigent-server==0.24.0",
+    "dirigent-block-execute==0.25.1",
+    "dirigent-blocks==0.25.1",
+    "dirigent-client==0.25.1",
+    "dirigent-common==0.25.1",
+    "dirigent-core==0.25.1",
+    "dirigent-examples==0.25.1",
+    "dirigent-plugin==0.25.1",
+    "dirigent-server==0.25.1",
     "httpx2>=2.12.0",
     "python-dotenv>=1.1.0",
     "pyyaml>=6.0.3",

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/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
@@ -58,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,
@@ -122,6 +124,7 @@ from dirigent_cli.project import (
     DEFAULT_PIPELINES_DIR,
     InitChoices,
     ProjectError,
+    agent_notes,
     check_choices,
     find_project,
     scaffold,
@@ -500,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
@@ -525,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 = [
@@ -543,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:
@@ -560,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",
@@ -630,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`.
 
@@ -640,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
 
@@ -649,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
@@ -963,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."""
@@ -2308,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)
@@ -2338,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.24.0 → dirigent_cli-0.25.1}/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"]

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/src/dirigent_cli/messages.py

@@ -335,3 +335,7 @@ SOURCE_NOT_CALLABLE = CLI.define(
 )
 
 SOURCE_UNREACHABLE = CLI.define("source_unreachable", "{url} could not be called: {detail}")
+
+NO_SUCH_BLOCK = CLI.define(
+    "no_such_block", "no block {block} is installed beside dg; dg blocks list --local names them"
+)

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/src/dirigent_cli/project.py

@@ -842,7 +842,8 @@ README_TEMPLATE = """\
 # __NAME__
 
 A dirigent project. `pipelines/` holds the pipeline documents and `dirigent.yaml` the
-project's settings.
+project's settings. `AGENTS.md` says how to find, check and run a document, for a person or a
+coding agent working here.
 
 `pyproject.toml` pins the dirigent runtime, so the `dg` this project runs on is that pinned
 one and `uv run` is how it is reached.
@@ -854,6 +855,75 @@ __RUN__
 ```
 """
 
+AGENTS_TEMPLATE = """\
+# Working in __NAME__
+
+This is a dirigent project: pipelines are YAML documents under `pipelines/`, checked and run by
+the `dg` command line this project pins. These notes are for whoever edits it, a person or a
+coding agent.
+
+## The loop
+
+Every command goes through `uv run dg`, so it runs the dirigent version `pyproject.toml` pins.
+
+1. **Find what exists before writing anything.**
+   - `uv run dg examples list --local` lists the documents every installed plugin ships, and
+     `uv run dg examples show CODE --local` prints one verbatim. Copy from the closest one.
+   - `uv run dg pipeline new STARTER` copies a starter into `pipelines/` as a pipeline of its own;
+     `uv run dg examples list --local --starter` names the starters.
+   - `uv run dg blocks list --local` lists every block, and `uv run dg blocks show BLOCK --local`
+     gives its config and output schemas.
+   - `uv run dg pipeline schema -f .dirigent/document.schema.json` writes the JSON Schema a
+     document is checked against, every installed block's config included. A document whose first
+     line is `# yaml-language-server: $schema=../.dirigent/document.schema.json` is checked by any
+     editor that reads that comment.
+2. **Check it offline:** `uv run dg validate pipelines/NAME.yaml`. `--explain` adds how wide the
+   work is, how many tries it may take and how long it may run.
+3. **Run it in a throwaway instance:** `uv run dg run --local pipelines/NAME.yaml`, with `-v` to
+   see every step's output. A pipeline that starts at a source takes `--input '{...}'`, or runs
+   with its source's `sample`.
+4. **Apply it to an instance** once it runs: `uv run dg apply`, then `uv run dg run CODE --watch`.
+   `uv run dg dev` starts a local instance with its web UI; it keeps running, so a person starts it
+   in a terminal of its own.
+
+## Reading what dg says
+
+Outside a terminal, which is every agent's shell, every `dg` command writes NDJSON: one JSON
+record per line, each with a `kind`. Select with `jq`, for example
+`uv run dg run --local pipelines/NAME.yaml | jq -c 'select(.kind == "run")'`.
+
+- A document that does not validate is a `validation` record with `message` `invalid` and
+  `problems[]`, each with a stable `code`, a `message` and the `location` in the document it is
+  about. Fix what `location` names, then validate again.
+- Anything else refused is a record of kind `error`, with a stable `code`, the `params` it was
+  built from, and `problems[]` where there is more than one thing to say.
+- A run's stream is `run`, `step`, `log` and `output` records, and the closing `run` record
+  carries every step's outcome, its output and the failures. `exit_code` is the command's own.
+- `uv run dg runs show RUN_ID`, `uv run dg runs logs RUN_ID` and `uv run dg runs profile RUN_ID`
+  read a run an instance holds.
+
+## Rules that are easy to get wrong
+
+- A document starts `format: dirigent/v1`, `kind: pipeline`, and a `code` in lowercase with
+  dashes. A step is exactly one of `block`, `source` or `reply`.
+- Values move between steps by reference, never by copying: `${params.NAME}`,
+  `${steps.STEP.output.FIELD}`, and `${item}` inside a `for_each`. A step that reads another's
+  output lists it under `depends_on`.
+- Secrets never go in a document. A connection holds them, created once with
+  `uv run dg connection create KIND CODE`, and a step names it by its code.
+- `.dirigent/state/` and `.env` belong to the local instance; they are not edited by hand.
+
+## Reading further
+
+The documentation is at https://winterop-com.github.io/dirigent/, and
+https://winterop-com.github.io/dirigent/llms.txt lists every page with what it covers. The
+installed examples are the most reliable reference, because each one is run by dirigent's own
+tests.
+"""
+
+#: Claude Code reads CLAUDE.md, and this makes it read the same notes every other agent does.
+CLAUDE_TEMPLATE = "@AGENTS.md\n"
+
 #: The commands a scaffolded project's README opens with, per template.
 README_RUN: Final = {
     "local": (
@@ -909,6 +979,7 @@ def scaffold(directory: Path, choices: InitChoices, *, version: str = "0.0.0") -
     _record(directory / "pyproject.toml", pyproject_document(name, choices, version), written, skipped)
     readme = README_TEMPLATE.replace("__NAME__", name).replace("__RUN__", "\n".join(README_RUN[choices.template]))
     _record(directory / "README.md", readme, written, skipped)
+    _record_agent_notes(directory, written, skipped)
     _merge_ignore(directory / ".gitignore", ROOT_IGNORE_TEMPLATE, written, skipped)
     if choices.workflow:
         written.append(_write(directory / ".github" / "workflows" / "dirigent.yaml", WORKFLOW_TEMPLATE))
@@ -919,6 +990,20 @@ def scaffold(directory: Path, choices: InitChoices, *, version: str = "0.0.0") -
     return Scaffolded(files=written, skipped=skipped)
 
 
+def agent_notes(directory: Path) -> Scaffolded:
+    """Write a coding agent's notes into a project, leaving any it already has alone."""
+    written: list[Path] = []
+    skipped: list[Path] = []
+    _record_agent_notes(directory, written, skipped)
+    return Scaffolded(files=written, skipped=skipped)
+
+
+def _record_agent_notes(directory: Path, written: list[Path], skipped: list[Path]) -> None:
+    """Write AGENTS.md, and the CLAUDE.md that points at it, unless the project has its own."""
+    _record(directory / "AGENTS.md", AGENTS_TEMPLATE.replace("__NAME__", project_name(directory)), written, skipped)
+    _record(directory / "CLAUDE.md", CLAUDE_TEMPLATE, written, skipped)
+
+
 def write_instance_env(directory: Path, token: str) -> Path:
     """Write the ``.env`` holding a new instance's token and key, readable by its owner alone."""
     document = INSTANCE_ENV_TEMPLATE.replace("__TOKEN__", token).replace("__SECRET_KEY__", _an_instance_key())

{dirigent_cli-0.24.0 → dirigent_cli-0.25.1}/src/dirigent_cli/summaries.py

@@ -50,6 +50,7 @@ BULKY: Final = frozenset(
         "issues",
         "files",
         "token",
+        "schema",
         "preflight",
         "requires",
         "used_by",