verdog-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{verdog_cli-0.1.2/verdog_cli.egg-info → verdog_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verdog-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: The Verdog command-line client.
 License-Expression: AGPL-3.0-only
 Project-URL: Repository, https://github.com/verdog-ai/verdog-cli
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://drexlerd.github.io/verdog-website/
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: verdog-runtime<0.2,>=0.1.4
+Requires-Dist: verdog-runtime<0.2,>=0.1.6
 Requires-Dist: packaging>=23.2
 Requires-Dist: tabulate>=0.10
 Requires-Dist: ty==0.0.72

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "verdog-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "The Verdog command-line client."
 readme = "README.md"
 license = "AGPL-3.0-only"
 license-files = ["LICENSE"]
 requires-python = ">=3.12"
-dependencies = ["verdog-runtime>=0.1.4,<0.2", "packaging>=23.2", "tabulate>=0.10", "ty==0.0.72"]
+dependencies = ["verdog-runtime>=0.1.6,<0.2", "packaging>=23.2", "tabulate>=0.10", "ty==0.0.72"]
 
 [project.scripts]
 verdog = "verdog_cli.main:main"

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/tests/test_backend_handoff.py

@@ -304,6 +304,9 @@ def test_new_projects_persist_the_selected_backend(
     assert received == (
         [f"{expected}/api/v1/check"] if command == "init" else []
     )
+    if command == "init":
+        project = json.loads((destination / "project.json").read_text("utf-8"))
+        assert (project["workflows"], project["subroutines"]) == ([], [])
 
 
 @pytest.mark.parametrize("selection", ["flag", "environment"])

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/tests/test_catalogue_cli.py

@@ -72,7 +72,7 @@ def test_describe_json_is_canonical_and_read_only(
     captured = capsys.readouterr()
     assert captured.err == ""
     assert json.loads(captured.out) == {
-        "schema_version": 32,
+        "schema_version": 33,
         "package": "test.project",
         "workflow_id": "main",
         "display_name": "Research workflow",
@@ -114,7 +114,7 @@ def test_describe_json_is_canonical_and_read_only(
         "closure": [],
         "environment": {
             "python": ">=3.12",
-            "schema_version": 32,
+            "schema_version": 33,
             "requirements": ["requests[security]>=2", "zeta>=2"],
         },
     }
@@ -171,7 +171,7 @@ def test_catalogue_client_encodes_filters_and_publication_environment(
         {"name": "Tools"},
         environment={
             "python": ">=3.12",
-            "schema_version": 32,
+            "schema_version": 33,
             "requirements": ["httpx>=0.27"],
         },
     )
@@ -197,7 +197,7 @@ def test_catalogue_client_encodes_filters_and_publication_environment(
                 "preview": {"name": "Tools"},
                 "environment": {
                     "python": ">=3.12",
-                    "schema_version": 32,
+                    "schema_version": 33,
                     "requirements": ["httpx>=0.27"],
                 },
             },
@@ -704,3 +704,25 @@ def test_retract_reports_the_entry_id_after_an_empty_204_response(
     assert captured.out.startswith(f"Retracted catalogue entry {entry_id}.\n")
     assert "@" not in captured.out
     assert retracted == [entry_id]
+
+
+@pytest.mark.parametrize(
+    ("roots", "requested", "expected"),
+    [
+        (["only"], None, "only"),
+        (["left", "main"], None, "main"),
+        (["left", "right"], "right", "right"),
+        (["left", "right"], None, "choose a root subroutine explicitly"),
+    ],
+)
+def test_import_into_defaults_to_the_only_root_subroutine_or_main(
+    roots: list[str], requested: str | None, expected: str
+) -> None:
+    from verdog_cli import manage
+
+    project = {"subroutines": [{"id": root} for root in roots]}
+    if expected.startswith("choose"):
+        with pytest.raises(WorkspaceError, match="left, right"):
+            manage._import_parent(project, requested)  # pyright: ignore[reportPrivateUsage]
+        return
+    assert manage._import_parent(project, requested) == expected  # pyright: ignore[reportPrivateUsage]

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/tests/test_sync.py

@@ -20,6 +20,7 @@ from verdog_cli.local import (
     Clone,
     LocalDefinition,
     WorkspaceError,
+    default_root,
 )
 from verdog_cli.requirements import parse_requirements
 from verdog_cli.sync import (
@@ -100,8 +101,8 @@ def _manifest(
             {
                 "schema_version": SCHEMA_VERSION,
                 "package": package,
-                "workflow": _workflow(cast(str, root_subroutine["id"])),
-                "subroutine": root_subroutine,
+                "workflows": [_workflow(cast(str, root_subroutine["id"]))],
+                "subroutines": [root_subroutine],
                 "externals": [] if externals is None else externals,
                 "sources": [],
             }
@@ -628,7 +629,7 @@ def test_environment_ids_cannot_escape_the_generated_root(
 ) -> None:
     clone = _clone(tmp_path, [])
     project = clone.project
-    project["workflow"]["subroutine"] = "../outside"
+    project["workflows"][0]["subroutine"] = "../outside"
     (clone.root / "project.json").write_text(
         json.dumps(project), encoding="utf-8"
     )
@@ -648,7 +649,7 @@ def test_local_definition_ids_use_the_language_identifier_grammar(
 ) -> None:
     clone = _clone(tmp_path, [])
     project = clone.project
-    project["subroutine"]["subroutines"] = [_subroutine(identifier)]
+    project["subroutines"][0]["subroutines"] = [_subroutine(identifier)]
     (clone.root / "project.json").write_text(
         json.dumps(project), encoding="utf-8"
     )
@@ -777,8 +778,8 @@ def test_sync_visits_every_workflow_in_each_nested_checkout(
 
     # Provision local workflow envelopes independently, also below pins.
     left_project = left_clone.project
-    left_project["subroutine"]["workflows"] = [_workflow("main__other")]
-    left_project["subroutine"]["subroutines"] = [_subroutine("other")]
+    left_project["subroutines"][0]["workflows"] = [_workflow("main__other")]
+    left_project["subroutines"][0]["subroutines"] = [_subroutine("other")]
     (left / "project.json").write_text(
         json.dumps(left_project), encoding="utf-8"
     )
@@ -1521,3 +1522,95 @@ def test_reachable_local_workflow_preflight_handles_recursive_calls(
     monkeypatch.setattr("verdog_cli.sync.require_current_environment", require)
     require_current_workflow_environments(root, _root_definition(root))
     assert checked == ["main", "main__child"]
+
+
+def _roots(root: Path, project: dict[str, Any]) -> Clone:
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "project.json").write_text(
+        json.dumps(
+            {"schema_version": SCHEMA_VERSION, "package": "ada.roots"} | project
+        ),
+        encoding="utf-8",
+    )
+    return Clone(root, "http://unused", None)
+
+
+@pytest.mark.parametrize(
+    ("ids", "expected"),
+    [(["one"], "one"), (["alpha", "main", "beta"], "main")],
+)
+def test_default_root_is_the_only_one_or_main(
+    ids: list[str], expected: str
+) -> None:
+    assert default_root("workflow", ids) == expected
+
+
+@pytest.mark.parametrize(
+    ("ids", "listed"),
+    [(["alpha", "beta"], "alpha, beta"), ([], "none declared")],
+)
+def test_default_root_otherwise_asks_for_a_choice(
+    ids: list[str], listed: str
+) -> None:
+    with pytest.raises(
+        WorkspaceError, match=f"choose a root subroutine explicitly: {listed}"
+    ):
+        default_root("subroutine", ids)
+
+
+def test_a_v32_manifest_reads_as_one_root_workflow_and_subroutine(
+    tmp_path: Path,
+) -> None:
+    clone = _roots(
+        tmp_path,
+        {
+            "schema_version": 32,
+            "workflow": _workflow("main"),
+            "subroutine": _subroutine("main"),
+        },
+    )
+    assert clone.project["schema_version"] == SCHEMA_VERSION
+    assert [(item.kind, item.module) for item in clone.local_definitions()] == [
+        ("workflow", "ada.roots.workflows.main"),
+        ("subroutine", "ada.roots.subroutines.main"),
+    ]
+    assert clone.workflow_definition().local_id == "main"
+
+
+def test_empty_and_multi_root_projects_list_their_definitions(
+    tmp_path: Path,
+) -> None:
+    empty = _roots(tmp_path / "empty", {"workflows": [], "subroutines": []})
+    assert empty.local_definitions() == ()
+    with pytest.raises(WorkspaceError, match="none declared"):
+        empty.workflow_definition()
+
+    clone = _roots(
+        tmp_path / "two",
+        {
+            "workflows": [_workflow("left"), _workflow("right")],
+            "subroutines": [
+                _subroutine("left", subroutines=[_subroutine("inner")]),
+                _subroutine("right"),
+            ],
+        },
+    )
+    assert [
+        (item.kind, item.local_id, item.module)
+        for item in clone.local_definitions()
+    ] == [
+        ("workflow", "left", "ada.roots.workflows.left"),
+        ("workflow", "right", "ada.roots.workflows.right"),
+        ("subroutine", "left", "ada.roots.subroutines.left"),
+        (
+            "subroutine",
+            "left__inner",
+            "ada.roots.subroutines.left.subroutines.inner",
+        ),
+        ("subroutine", "right", "ada.roots.subroutines.right"),
+    ]
+    assert clone.workflow_definition("right").local_id == "right"
+    with pytest.raises(
+        WorkspaceError, match="choose a root workflow explicitly: left, right"
+    ):
+        runner.run(clone)

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/verdog_cli/local.py

@@ -36,7 +36,7 @@ EXTERNAL_ROOT = "external"
 Shared by dependency paths, type-check exclusions, and drop cleanup.
 """
 
-SCHEMA_VERSION = 32
+SCHEMA_VERSION = 33
 
 _DEFINITION_SEPARATOR = "__"
 
@@ -51,6 +51,17 @@ def definition_leaf(identifier: str, /) -> str:
     return identifier.rsplit(_DEFINITION_SEPARATOR, 1)[-1]
 
 
+def default_root(kind: str, ids: list[str]) -> str:
+    """The root definition used when none is named: the only one, or `main`."""
+    if len(ids) == 1:
+        return ids[0]
+    if "main" in ids:
+        return "main"
+    raise WorkspaceError(
+        f"choose a root {kind} explicitly: {', '.join(ids) or 'none declared'}"
+    )
+
+
 def package_problem(package: str) -> str | None:
     """Why a canonical `<space>.<name>` package is invalid, if it is."""
     parts = package.split(".")
@@ -308,11 +319,19 @@ class Clone:
             raise WorkspaceError("project.json is not an object")
         project = cast(dict[str, Any], decoded)
         version = project.get("schema_version")
-        if version != SCHEMA_VERSION:
+        if version == 32:
+            # ponytail: the compiler migrates the file; reading v32 only needs
+            # its single root workflow and subroutine lifted into lists.
+            workflow = project.pop("workflow", None)
+            subroutine = project.pop("subroutine", None)
+            project["schema_version"] = SCHEMA_VERSION
+            project["workflows"] = [] if workflow is None else [workflow]
+            project["subroutines"] = [] if subroutine is None else [subroutine]
+        elif version != SCHEMA_VERSION:
             raise WorkspaceError(
                 f"project schema v"
                 f"{version} is unsupported; this CLI requires schema v"
-                f"{SCHEMA_VERSION}"
+                f"{SCHEMA_VERSION} (or v32)"
             )
         return project
 
@@ -563,18 +582,12 @@ class Clone:
         """Return the declared workflow envelopes and subroutine graphs."""
         project = self.project
         package = project.get("package")
-        root_workflow = project.get("workflow")
-        root_subroutine = project.get("subroutine")
         if (
             not isinstance(package, str)
             or not package
             or package_problem(package) is not None
-            or not isinstance(root_workflow, dict)
-            or not isinstance(root_subroutine, dict)
         ):
-            raise WorkspaceError(
-                "project.json has no root workflow and subroutine"
-            )
+            raise WorkspaceError("project.json has no valid package")
 
         definitions: list[LocalDefinition] = []
         identifiers: set[tuple[Literal["workflow", "subroutine"], str]] = set()
@@ -622,13 +635,18 @@ class Clone:
                 raise WorkspaceError("a local subroutine has no id")
             identifier = definition_child(owner, leaf)
             add(raw, module, "subroutine", identifier)
+            visit_children(raw, module, identifier)
+
+        def visit_children(
+            raw: dict[str, Any], module: str, owner: str | None
+        ) -> None:
             for child in objects(raw.get("workflows"), "workflows"):
                 if "external" in child:
                     continue
                 target = child.get("subroutine")
                 if not isinstance(target, str) or not target:
                     raise WorkspaceError("a local workflow has no subroutine")
-                child_id = definition_child(identifier, definition_leaf(target))
+                child_id = definition_child(owner, definition_leaf(target))
                 add(
                     child,
                     f"{module}.workflows.{definition_leaf(target)}",
@@ -642,26 +660,10 @@ class Clone:
                 visit_subroutine(
                     child,
                     f"{module}.subroutines.{child_id}",
-                    identifier,
+                    owner,
                 )
 
-        workflow_body = cast(dict[str, Any], root_workflow)
-        workflow_id = workflow_body.get("subroutine")
-        subroutine_body = cast(dict[str, Any], root_subroutine)
-        subroutine_id = subroutine_body.get("id")
-        if not isinstance(subroutine_id, str) or not subroutine_id:
-            raise WorkspaceError("the root subroutine has no id")
-        add(
-            workflow_body,
-            f"{package}.workflows.{workflow_id}",
-            "workflow",
-            workflow_id,
-        )
-        visit_subroutine(
-            subroutine_body,
-            f"{package}.subroutines.{subroutine_id}",
-            None,
-        )
+        visit_children(project, package, None)
         return tuple(definitions)
 
     def workflow_definitions(self) -> tuple[LocalDefinition, ...]:
@@ -675,12 +677,17 @@ class Clone:
     def workflow_definition(
         self, identifier: str | None = None, /
     ) -> LocalDefinition:
-        """Select a workflow by local id, defaulting to the first envelope."""
+        """Select a workflow by local id, defaulting per `default_root`."""
         workflows = self.workflow_definitions()
-        if not workflows:
-            raise WorkspaceError("project.json has no workflow")
         if identifier is None:
-            return workflows[0]
+            identifier = default_root(
+                "workflow",
+                [
+                    item.local_id
+                    for item in workflows
+                    if _DEFINITION_SEPARATOR not in item.local_id
+                ],
+            )
         found = next(
             (item for item in workflows if item.local_id == identifier), None
         )

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/verdog_cli/main.py

@@ -470,7 +470,8 @@ def build_parser() -> argparse.ArgumentParser:
         "workflow",
         nargs="?",
         metavar="WORKFLOW",
-        help="project-local workflow path (the root workflow by default)",
+        help="project-local workflow path (default: the only root workflow, "
+        "else main)",
     )
     execute.add_argument(
         "--output-dir",

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/verdog_cli/manage.py

@@ -37,9 +37,6 @@ def _objects(value: Any) -> list[dict[str, Any]]:
 def _scoped_subroutine_definitions(
     project: dict[str, Any],
 ) -> list[tuple[str, dict[str, Any]]]:
-    root = _object(project.get("subroutine"))
-    if not root:
-        return []
     found: list[tuple[str, dict[str, Any]]] = []
 
     def visit(definition: dict[str, Any], owner: str | None) -> None:
@@ -50,7 +47,8 @@ def _scoped_subroutine_definitions(
         for child in _objects(definition.get("subroutines")):
             visit(child, identifier)
 
-    visit(root, None)
+    for root in _objects(project.get("subroutines")):
+        visit(root, None)
     return found
 
 
@@ -208,11 +206,9 @@ def _clone(arguments: argparse.Namespace) -> int:
 
 
 ENTRY_WORKFLOW = "main"
-"""The fixed root workflow/subroutine id.
+"""The root workflow/subroutine id of `blank_graph`'s one-workflow project.
 
-The service uses the same root id. Integration tests run this client's
-output
-through the compiler; the client itself depends only on the public runtime.
+Backend integration tests and fixtures build on it; `init` starts empty.
 """
 
 
@@ -272,44 +268,52 @@ def blank_graph(package: str, name: str) -> dict[str, Any]:
         "schema_version": local.SCHEMA_VERSION,
         "package": package,
         "generated_from": "0" * 64,
-        "workflow": {
-            "subroutine": ENTRY_WORKFLOW,
-            "profiles": [],
-            "sessions": [],
-            "profile_arguments": {},
-            "session_arguments": {},
-        },
-        "subroutine": {
-            "id": ENTRY_WORKFLOW,
-            "name": name,
-            "ports": {"enter": "enter", "exit": "exit", "failure": "failure"},
-            "features": [],
-            "profiles": [],
-            "profile_parameters": [],
-            "sessions": [],
-            "session_parameters": [],
-            "nodes": [
-                port("enter", "Enter"),
-                port("exit", "Exit"),
-                port("failure", "Failure"),
-            ],
-            "edges": [
-                {
-                    "id": "enter__exit",
-                    "name": "Pass through",
-                    "source": "enter",
-                    "target": "exit",
-                    "conditions": [],
-                    "effects": [],
-                }
-            ],
-            "workflows": [],
-            "subroutines": [],
-        },
+        "workflows": [
+            {
+                "subroutine": ENTRY_WORKFLOW,
+                "profiles": [],
+                "sessions": [],
+                "profile_arguments": {},
+                "session_arguments": {},
+            }
+        ],
         "externals": [],
         "sources": [],
         "editor": {"layouts": {}},
         "extensions": {},
+        "subroutines": [
+            {
+                "id": ENTRY_WORKFLOW,
+                "name": name,
+                "ports": {
+                    "enter": "enter",
+                    "exit": "exit",
+                    "failure": "failure",
+                },
+                "features": [],
+                "profiles": [],
+                "profile_parameters": [],
+                "sessions": [],
+                "session_parameters": [],
+                "nodes": [
+                    port("enter", "Enter"),
+                    port("exit", "Exit"),
+                    port("failure", "Failure"),
+                ],
+                "edges": [
+                    {
+                        "id": "enter__exit",
+                        "name": "Pass through",
+                        "source": "enter",
+                        "target": "exit",
+                        "conditions": [],
+                        "effects": [],
+                    }
+                ],
+                "workflows": [],
+                "subroutines": [],
+            }
+        ],
     }
 
 
@@ -355,9 +359,14 @@ def _init(arguments: argparse.Namespace) -> int:
         )
 
     root.mkdir(parents=True, exist_ok=True)
+    # An empty project: root workflows and subroutines are added in the editor.
+    project: dict[str, Any] = {
+        **blank_graph(package, name),
+        "workflows": [],
+        "subroutines": [],
+    }
     (root / "project.json").write_text(
-        json.dumps(blank_graph(package, name), indent=2, ensure_ascii=False)
-        + "\n",
+        json.dumps(project, indent=2, ensure_ascii=False) + "\n",
         encoding="utf-8",
     )
     # Git, because every other verb finds the project by walking up to a `.git`.
@@ -372,13 +381,15 @@ def _init(arguments: argparse.Namespace) -> int:
     local.write_config(root, origin)
 
     print(f"Started {package} in {root}")
-    print(f"  workflow {ENTRY_WORKFLOW!r}: enter -> exit, with a failure port")
 
     from verdog_cli import main
 
     status = main.generate_clone(local.open_clone(root))
     if status == 0:
-        print("Next: `verdog sync` to create the runtime environments.")
+        print(
+            "Next: add a subroutine and make it runnable, then run "
+            "`verdog sync` to create its runtime environment."
+        )
     return status
 
 
@@ -582,9 +593,9 @@ def publish_workflow(arguments: argparse.Namespace) -> int:
         )
     repository = f"{owner}/{name}"
     commit = clone_head(clone, repository)
-    root_workflow = _object(clone.project.get("workflow"))
-    workflow = str(arguments.workflow or root_workflow.get("subroutine", ""))
-    descriptor = cli_catalogue.describe_workflow(clone, workflow)
+    descriptor = cli_catalogue.describe_workflow(
+        clone, arguments.workflow or None
+    )
     if arguments.private:
         print(
             "verdog: --private is deprecated; catalogue "
@@ -1065,11 +1076,19 @@ def _prepare_import(arguments: argparse.Namespace) -> _ImportPlan:
 
 
 def _import_parent(project: dict[str, Any], requested: object) -> str:
-    root = _object(project.get("subroutine"))
-    parent = str(requested or root.get("id", ""))
     known = {
         identifier for identifier, _ in _scoped_subroutine_definitions(project)
     }
+    parent = str(
+        requested
+        or local.default_root(
+            "subroutine",
+            [
+                str(root.get("id"))
+                for root in _objects(project.get("subroutines"))
+            ],
+        )
+    )
     if parent not in known:
         raise local.WorkspaceError(f"this project has no subroutine {parent}")
     return parent
@@ -2078,7 +2097,7 @@ def register(commands: Any) -> None:
     who.set_defaults(handler=_whoami)
 
     started = commands.add_parser("init", help="start a new project here")
-    started.add_argument("name", nargs="?", help="what the workflow is called")
+    started.add_argument("name", nargs="?", help="what the project is called")
     started.add_argument(
         "directory", nargs="?", help="where to put it (default: here)"
     )
@@ -2145,7 +2164,8 @@ def register(commands: Any) -> None:
     describe.add_argument(
         "workflow",
         nargs="?",
-        help="project-local workflow path; defaults to the entry workflow",
+        help="project-local workflow path (default: the only root workflow, "
+        "else main)",
     )
     describe.add_argument(
         "--project",
@@ -2171,7 +2191,8 @@ def register(commands: Any) -> None:
     publish.add_argument(
         "workflow",
         nargs="?",
-        help="project-local workflow path; defaults to the entry workflow",
+        help="project-local workflow path (default: the only root workflow, "
+        "else main)",
     )
     publish.add_argument(
         "--private",
@@ -2207,7 +2228,9 @@ def register(commands: Any) -> None:
         "workflow", help="the published workflow path to call"
     )
     imported.add_argument(
-        "--into", help="the project-local subroutine path that declares it"
+        "--into",
+        help="the project-local subroutine path that declares it "
+        "(default: the only root subroutine, else main)",
     )
     imported.add_argument(
         "--alias",

{verdog_cli-0.1.2 → verdog_cli-0.1.4/verdog_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: verdog-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: The Verdog command-line client.
 License-Expression: AGPL-3.0-only
 Project-URL: Repository, https://github.com/verdog-ai/verdog-cli
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://drexlerd.github.io/verdog-website/
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: verdog-runtime<0.2,>=0.1.4
+Requires-Dist: verdog-runtime<0.2,>=0.1.6
 Requires-Dist: packaging>=23.2
 Requires-Dist: tabulate>=0.10
 Requires-Dist: ty==0.0.72

{verdog_cli-0.1.2 → verdog_cli-0.1.4}/verdog_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-verdog-runtime<0.2,>=0.1.4
+verdog-runtime<0.2,>=0.1.6
 packaging>=23.2
 tabulate>=0.10
 ty==0.0.72