graph-lcb 0.1.0__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,244 @@
+"""A small, dependency-free command-line interface helper."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import TypeVar, overload
+
+__all__ = ["CLIError", "Context", "CLI"]
+
+_MISSING = object()
+_COMMAND_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
+_FLAG_PATTERN = re.compile(r"[A-Za-z][A-Za-z0-9_-]*\Z")
+_T = TypeVar("_T")
+
+
+class CLIError(ValueError):
+    """An expected command-line usage error."""
+
+
+class Context:
+    """Arguments and options for one command invocation."""
+
+    def __init__(
+        self,
+        command: str,
+        positionals: Sequence[str],
+        options: Sequence[tuple[str, str | bool]],
+    ) -> None:
+        self.command = command
+        self.args = tuple(positionals)
+        self._options = tuple(options)
+
+    @overload
+    def positional(self, index: int) -> str: ...
+
+    @overload
+    def positional(self, index: int, default: _T) -> str | _T: ...
+
+    def positional(self, index: int, default: object = _MISSING) -> str | object:
+        """Return a positional argument, or its default if one was provided."""
+        if index < 0:
+            raise ValueError("positional indexes must not be negative")
+        if index < len(self.args):
+            return self.args[index]
+        if default is not _MISSING:
+            return default
+        raise CLIError(f"missing positional argument {index + 1}")
+
+    @overload
+    def flag(self, name: str, default: None = None) -> str | bool | None: ...
+
+    @overload
+    def flag(self, name: str, default: _T = ...) -> str | bool | _T: ...
+
+    def flag(
+        self,
+        name: str,
+        default: object = None,
+    ) -> str | bool | object:
+        """Return an option's value by its long name."""
+        normalized_name = name.removeprefix("--").removeprefix("-")
+        if not _FLAG_PATTERN.fullmatch(normalized_name):
+            raise ValueError(f"invalid flag name: {name!r}")
+
+        for option_name, value in reversed(self._options):
+            if option_name == normalized_name:
+                return value
+        return default
+
+
+@dataclass(frozen=True)
+class _Handler:
+    description: str
+    callback: Callable[[Context], int | None]
+
+
+class CLI:
+    """Register commands and dispatch arguments without third-party packages."""
+
+    def __init__(self, prog: str | None = None) -> None:
+        self.prog = prog
+        self._handlers: dict[str, _Handler] = {}
+        self._before_run_callbacks: list[Callable[[], None]] = []
+
+    @overload
+    def before_run(self, callback: Callable[[], None]) -> Callable[[], None]: ...
+
+    @overload
+    def before_run(self) -> Callable[[Callable[[], None]], Callable[[], None]]: ...
+
+    def before_run(
+        self, callback: Callable[[], None] | None = None
+    ) -> Callable[[], None] | Callable[[Callable[[], None]], Callable[[], None]]:
+        """Register a no-argument callback to run before a command handler.
+
+        Supports both ``@cli.before_run`` and ``@cli.before_run()``.
+        Callbacks run in registration order after command selection and argument
+        parsing, so help and usage paths do not trigger command setup.
+        """
+        def register(function: Callable[[], None]) -> Callable[[], None]:
+            self._before_run_callbacks.append(function)
+            return function
+
+        return register(callback) if callback is not None else register
+
+    def new_handler(
+        self,
+        name: str,
+        description: str,
+        handler: Callable[[Context], int | None],
+    ) -> None:
+        """Register a command and the function that handles it."""
+        if not _COMMAND_PATTERN.fullmatch(name):
+            raise ValueError(f"invalid command name: {name!r}")
+        if name in {"help"} or name in self._handlers:
+            raise ValueError(f"command already registered or reserved: {name!r}")
+        self._handlers[name] = _Handler(description, handler)
+
+    def handler(
+        self, name: str, description: str
+    ) -> Callable[[Callable[[Context], int | None]], Callable[[Context], int | None]]:
+        """Register a command using a decorator and return its handler unchanged."""
+
+        def register(
+            callback: Callable[[Context], int | None],
+        ) -> Callable[[Context], int | None]:
+            self.new_handler(name, description, callback)
+            return callback
+
+        return register
+
+    def run(self, argv: Sequence[str] | None = None) -> int:
+        """Run the CLI with arguments, defaulting to ``sys.argv[1:]``."""
+        arguments = list(sys.argv[1:] if argv is None else argv)
+        program = self.prog or os.path.basename(sys.argv[0]) or "cli"
+
+        if not arguments or arguments[0] in {"-h", "--help", "help"}:
+            if arguments and arguments[0] == "help":
+                if len(arguments) > 2:
+                    return self._usage_error("help accepts at most one command", program)
+                if len(arguments) == 2:
+                    return self._show_command_help(arguments[1], program)
+            self._show_help(program)
+            return 0
+
+        command = arguments[0]
+        registered = self._handlers.get(command)
+        if registered is None:
+            return self._usage_error(f"unknown command: {command}", program)
+        command_arguments = arguments[1:]
+        help_arguments = (
+            command_arguments[: command_arguments.index("--")]
+            if "--" in command_arguments
+            else command_arguments
+        )
+        if any(argument in {"-h", "--help"} for argument in help_arguments):
+            self._show_command_help(command, program)
+            return 0
+
+        try:
+            positionals, options = self._parse_arguments(command_arguments)
+            for callback in self._before_run_callbacks:
+                callback()
+            result = registered.callback(Context(command, positionals, options))
+        except CLIError as error:
+            return self._usage_error(str(error), program, command)
+
+        return 0 if result is None else result
+
+    def _parse_arguments(
+        self, arguments: Sequence[str]
+    ) -> tuple[list[str], list[tuple[str, str | bool]]]:
+        positionals: list[str] = []
+        options: list[tuple[str, str | bool]] = []
+        parse_options = True
+        index = 0
+
+        while index < len(arguments):
+            argument = arguments[index]
+            if parse_options and argument == "--":
+                parse_options = False
+                index += 1
+                continue
+            if not parse_options or argument == "-" or not argument.startswith("-"):
+                positionals.append(argument)
+                index += 1
+                continue
+            if len(argument) > 1 and argument[1].isdigit():
+                positionals.append(argument)
+                index += 1
+                continue
+
+            if not argument.startswith("--"):
+                raise CLIError(f"short options are not supported: {argument}")
+            option_name, equals, attached_value = argument[2:].partition("=")
+            if not option_name:
+                raise CLIError("empty option name")
+            if equals:
+                options.append((option_name, attached_value))
+                index += 1
+                continue
+
+            if index + 1 < len(arguments) and not arguments[index + 1].startswith("-"):
+                options.append((option_name, arguments[index + 1]))
+                index += 2
+            else:
+                options.append((option_name, True))
+                index += 1
+
+        return positionals, options
+
+    def _show_help(self, program: str) -> None:
+        print(f"Usage: {program} <command> [arguments]", file=sys.stdout)
+        print("\nCommands:", file=sys.stdout)
+        if not self._handlers:
+            print("  (no commands registered)", file=sys.stdout)
+        for name, handler in self._handlers.items():
+            print(f"  {name:<16} {handler.description}", file=sys.stdout)
+        print(f"\nRun '{program} help <command>' for command details.", file=sys.stdout)
+
+    def _show_command_help(self, command: str, program: str) -> int:
+        if command == "help":
+            self._show_help(program)
+            return 0
+        registered = self._handlers.get(command)
+        if registered is None:
+            return self._usage_error(f"unknown command: {command}", program)
+        print(f"Usage: {program} {command} [arguments]", file=sys.stdout)
+        if registered.description:
+            print(f"\n{registered.description}", file=sys.stdout)
+        print("\nOptions: -h, --help  Show this help.", file=sys.stdout)
+        return 0
+
+    def _usage_error(self, message: str, program: str, command: str | None = None) -> int:
+        print(f"{program}: error: {message}", file=sys.stderr)
+        if command is None:
+            print(f"Try '{program} --help' for usage.", file=sys.stderr)
+        else:
+            print(f"Try '{program} {command} --help' for usage.", file=sys.stderr)
+        return 2

commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands, grouped by domain."""

commands/admin.py

@@ -0,0 +1,103 @@
+from pathlib import Path
+
+from cli import CLIError, Context
+from graphs.engine import Graph, GraphError, GraphNotInitializedError, InvalidContractError
+from commands.common import cli, emit, starter_contracts
+
+@cli.handler("validate", "Validate stored graph records against the current contracts (read-only).")
+def validate_graph(ctx: Context) -> int:
+    if ctx.args or ctx._options:
+        raise CLIError("validate accepts no arguments or options")
+    try:
+        result = Graph(allow_invalid_contracts=True).validate()
+    except GraphNotInitializedError as exc:
+        result = {
+            "valid": False,
+            "errors": [{"kind": "workspace", "code": "not_initialized", "message": str(exc)}],
+            "summary": {"nodes": 0, "edges": 0, "errors": 1},
+            "unavailable": True,
+        }
+    except InvalidContractError as exc:
+        result = {
+            "valid": False,
+            "errors": [{"kind": "contract", "code": "invalid_contract", "message": str(exc)}],
+            "summary": {"nodes": 0, "edges": 0, "errors": 1},
+        }
+        emit(result)
+        return 3
+    except GraphError as exc:
+        result = {
+            "valid": False,
+            "errors": [{"kind": "contract", "code": "invalid_contract", "message": str(exc)}],
+            "summary": {"nodes": 0, "edges": 0, "errors": 1},
+        }
+        emit(result)
+        return 4
+    unavailable = result.pop("unavailable", False)
+    emit(result)
+    return 4 if unavailable else 0 if result["valid"] else 3
+
+@cli.handler("contract", "Show entity and edge contracts: contract [entities|edges] [--compact]")
+def show_schema(ctx: Context) -> None:
+    if len(ctx.args) > 1:
+        raise CLIError("use contract [entities|edges] [--compact]")
+    category = ctx.positional(0, "all").lower()
+    if category not in {"all", "entity", "entities", "edge", "edges"}:
+        raise CLIError("expected 'entities' or 'edges'")
+
+    contracts_directory = Path(".graph")
+    entity_contract_path = contracts_directory / "entities.json"
+    edge_contract_path = contracts_directory / "edges.json"
+    if (not contracts_directory.exists()
+            or (contracts_directory.is_dir()
+                and not entity_contract_path.exists()
+                and not edge_contract_path.exists())):
+        entities, edge_types = starter_contracts()
+    else:
+        graph = Graph(contracts_directory)
+        entities, edge_types = graph.entities, graph.edge_types
+
+    sections = []
+    if category in {"all", "entity", "entities"}:
+        sections.append(("entities", entities, False))
+    if category in {"all", "edge", "edges"}:
+        sections.append(("edges", edge_types, True))
+    compact = ctx.flag("compact")
+    json_output = ctx.flag("json")
+    for option, value in (("--compact", compact), ("--json", json_output)):
+        if value is not None and value is not True:
+            raise CLIError(f"{option} does not accept a value")
+    if not compact:
+        if len(sections) == 1:
+            emit(sections[0][1])
+        else:
+            emit({name: types for name, types, _ in sections})
+        return
+    summaries = []
+    for section_name, types, is_edge in sections:
+        section_summaries = []
+        for name, contract in types.items():
+            if name == "$schema":
+                continue
+            description = contract.get("description", "")
+            lines = [f"{name}: {description}" if description else name]
+            if is_edge:
+                lines.extend((
+                    f"Source: {', '.join(contract.get('source', []))}",
+                    f"Target: {', '.join(contract.get('target', []))}",
+                ))
+            lines.append("Properties:")
+            for property_name, definition in contract.get("properties", {}).items():
+                if isinstance(definition, str):
+                    property_type, required = definition, False
+                else:
+                    property_type = definition.get("type", "unknown")
+                    required = definition.get("required") is True
+                suffix = "; required" if required else ""
+                lines.append(f"- {property_name}: {property_type}{suffix}")
+            section_summaries.append("\n".join(lines))
+        summary = "\n\n".join(section_summaries)
+        if len(sections) > 1:
+            summary = f"# {section_name.title()}\n" + summary
+        summaries.append(summary)
+    print("\n\n".join(summaries))

commands/common.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python
+"""Graph management CLI."""
+import json
+import shutil
+from copy import deepcopy
+from pathlib import Path
+
+from cli import CLI, CLIError, Context
+from graphs.engine import Graph
+from graphs.types import Edge, EdgeResponse, Node
+
+cli = CLI("graph")
+
+STARTER_ENTITY_CONTRACT = {
+    "$schema": "./schemas/entities.schema.json",
+    "API": {
+        "description": "An API or application service",
+        "properties": {
+            "language": {"type": "string", "required": True},
+        },
+    },
+}
+STARTER_EDGE_CONTRACT = {
+    "$schema": "./schemas/edges.schema.json",
+    "CALLS": {
+        "description": "A service synchronously invokes another service or API.",
+        "source": ["API"],
+        "target": ["API"],
+        "properties": {
+            "protocol": {"type": "string", "required": False},
+        },
+    },
+}
+
+
+def edge_response(edge: Edge, nodes: list[Node]) -> EdgeResponse:
+    target = next((node for node in nodes if node.id == edge.target), None)
+    return EdgeResponse.from_edge(edge, target.type if target else "")
+
+
+def json_default(value: object) -> dict:
+    if isinstance(value, (Node, Edge, EdgeResponse)):
+        return value.to_dict()
+    raise TypeError(f"cannot serialize {type(value).__name__}")
+
+
+def emit(value: object) -> None:
+    print(json.dumps(value, ensure_ascii=False, default=json_default, separators=(",", ":")))
+
+
+def initialize_graph_contracts() -> None:
+    """Create missing starter contracts and schemas for the explicit init command."""
+    directory = Path(".graph")
+    schema_directory = directory / "schemas"
+    bundled_schema_directory = Path(__file__).resolve().parents[1] / "schemas"
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        schema_directory.mkdir(parents=True, exist_ok=True)
+        for filename in ("entities.schema.json", "edges.schema.json"):
+            source = bundled_schema_directory / filename
+            destination = schema_directory / filename
+            if not destination.exists():
+                shutil.copyfile(source, destination)
+            elif not destination.is_file():
+                raise CLIError(f"cannot initialize graph schema: {destination} is not a file")
+        for filename, contract in (
+            ("entities.json", STARTER_ENTITY_CONTRACT),
+            ("edges.json", STARTER_EDGE_CONTRACT),
+        ):
+            path = directory / filename
+            if path.exists() and not path.is_file():
+                raise CLIError(f"cannot initialize graph contract: {path} is not a file")
+            if not path.exists():
+                path.write_text(json.dumps(contract) + "\n", encoding="utf-8")
+    except OSError as exc:
+        raise CLIError(f"cannot initialize graph contracts: {exc}") from exc
+
+
+def starter_contracts() -> tuple[dict, dict]:
+    """Return fresh starter contracts without the schema metadata."""
+    entities = deepcopy(STARTER_ENTITY_CONTRACT)
+    edges = deepcopy(STARTER_EDGE_CONTRACT)
+    entities.pop("$schema")
+    edges.pop("$schema")
+    return entities, edges
+
+
+@cli.handler("init", "Initialize a graph workspace in the current directory.")
+def init_graph(ctx: Context) -> None:
+    if ctx.args or ctx._options:
+        raise CLIError("init accepts no arguments or options")
+    initialize_graph_contracts()
+    emit({"initialized": True, "directory": ".graph"})
+
+
+def properties(ctx: Context) -> dict:
+    return parse_properties(ctx.flag("properties", default="{}")) or {}
+
+
+def parse_properties(raw: object | None) -> dict | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, str):
+        raise CLIError("--properties requires a JSON object")
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CLIError(f"invalid properties JSON: {exc.msg}") from exc
+    if not isinstance(value, dict):
+        raise CLIError("--properties must be a JSON object")
+    return value
+
+
+def parse_fields(raw: object | None, allowed: set[str]) -> list[str] | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, str) or not raw:
+        raise CLIError("--fields requires comma-separated field names")
+    fields = [field.strip() for field in raw.split(",")]
+    if any(not field for field in fields):
+        raise CLIError("--fields requires comma-separated field names")
+    unknown = set(fields) - allowed
+    if unknown:
+        raise CLIError(f"unknown field: {', '.join(sorted(unknown))}")
+    return fields
+
+
+def parse_edge_types(raw: object | None, graph: Graph) -> set[str] | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, str):
+        raise CLIError("--edge requires comma-separated edge types")
+    values = {value.strip() for value in raw.split(",")}
+    if not values or "" in values:
+        raise CLIError("--edge requires comma-separated edge types")
+    canonical = {name.casefold(): name for name in graph.edge_types}
+    unknown = {value for value in values if value.casefold() not in canonical}
+    if unknown:
+        raise CLIError(f"unknown edge type: {', '.join(sorted(unknown))}; valid types: {', '.join(sorted(graph.edge_types)) or '(none)'}")
+    return {canonical[value.casefold()] for value in values}
+
+
+def evidences(raw: object) -> list[dict]:
+    if not isinstance(raw, str):
+        raise CLIError("--evidences requires a JSON array of objects")
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CLIError(f"invalid evidences JSON: {exc.msg}") from exc
+    if not isinstance(value, list) or any(not isinstance(item, dict) for item in value):
+        raise CLIError("--evidences must be a JSON array of objects")
+    return value
+
+
+def positive_limit(value: object, default: int | None = None) -> int | None:
+    """Parse an optional --limit value, which must be a positive integer."""
+    if value is None:
+        return default
+    if not isinstance(value, str):
+        raise CLIError("--limit requires a positive integer")
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise CLIError("--limit requires a positive integer") from exc
+    if parsed < 1:
+        raise CLIError("--limit must be a positive integer")
+    return parsed

commands/mutations.py

@@ -0,0 +1,85 @@
+import sys
+from cli import CLIError, Context
+from graphs.engine import Graph, GraphError
+from commands.common import cli, evidences, edge_response, emit, parse_properties
+
+@cli.handler("edit", "Edit node fields or edge description/properties/evidences: edit node|edge ...")
+def edit_record(ctx: Context) -> None:
+    target = ctx.positional(0).lower()
+    graph = Graph()
+    if target == "node":
+        if ctx.flag("id") is not None:
+            raise CLIError("edit node ID is positional: edit node ID --name=...")
+        if len(ctx.args) != 2:
+            raise CLIError("use edit node ID with --name, --properties, and/or --evidences")
+        reference = ctx.positional(1)
+        name = ctx.flag("name")
+        raw_properties = ctx.flag("properties")
+        raw_evidences = ctx.flag("evidences")
+        if name is None and raw_properties is None and raw_evidences is None:
+            raise CLIError("provide --name, --properties, and/or --evidences")
+        if name is not None and not isinstance(name, str):
+            raise CLIError("--name requires a value")
+        parsed_properties = parse_properties(raw_properties)
+        parsed_evidences = None
+        if raw_evidences is not None:
+            parsed_evidences = evidences(raw_evidences)
+        result = graph.edit_node(reference, name=name, properties=parsed_properties, evidences=parsed_evidences)
+    elif target == "edge":
+        if ctx.flag("id") is not None:
+            raise CLIError("edit edge ID is positional: edit edge ID --description=...")
+        if len(ctx.args) != 2:
+            raise CLIError("use edit edge ID with --description, --properties, and/or --evidences")
+        edge_id = ctx.positional(1)
+        description = ctx.flag("description")
+        raw_properties = ctx.flag("properties")
+        raw_evidences = ctx.flag("evidences")
+        if not isinstance(edge_id, str):
+            raise CLIError("edit edge requires an edge ID")
+        if description is not None and not isinstance(description, str):
+            raise CLIError("--description requires text")
+        if description is None and raw_properties is None and raw_evidences is None:
+            raise CLIError("provide --description, --properties, and/or --evidences")
+        parsed_properties = parse_properties(raw_properties)
+        parsed_evidences = None
+        if raw_evidences is not None:
+            parsed_evidences = evidences(raw_evidences)
+        result = graph.edit_edge(edge_id, description=description, properties=parsed_properties, evidences=parsed_evidences)
+        result = edge_response(result, graph.load()["nodes"])
+    else:
+        raise CLIError("expected 'node' or 'edge'")
+    emit(result)
+
+@cli.handler("delete", "Delete a node and its edges, or delete an edge: delete node|edge ...")
+def delete_record(ctx: Context) -> int | None:
+    target = ctx.positional(0).lower()
+    graph = Graph()
+    if target == "node":
+        if ctx.flag("id") is not None:
+            raise CLIError("delete node ID is positional: delete node ID")
+        if len(ctx.args) != 2:
+            raise CLIError("use delete node ID")
+        node_id = ctx.positional(1)
+        node, edge_count = graph.delete_node(node_id=node_id)
+        emit({"deleted_node": node, "deleted_edges": edge_count})
+    elif target == "edge":
+        if ctx.flag("id") is not None:
+            raise CLIError("delete edge ID is positional: delete edge ID")
+        if len(ctx.args) == 2:
+            edge_id = ctx.positional(1)
+            kind = source = destination = None
+        elif len(ctx.args) == 4:
+            edge_id = None
+            source, kind, destination = ctx.args[1:]
+        else:
+            raise CLIError("use delete edge ID or delete edge SOURCE_NODE_ID EDGE_TYPE TARGET_NODE_ID")
+        matches = graph.delete_edge(edge_id=edge_id, kind=kind, source=source, target=destination)
+        nodes = graph.load()["nodes"]
+        if len(matches) > 1:
+            print("Multiple matching edges found; none were deleted. Delete one by ID:", file=sys.stderr)
+            emit([edge_response(edge, nodes) for edge in matches])
+            print("Use: graph delete edge EDGE_ID", file=sys.stderr)
+            return 2
+        emit({"deleted_edge": edge_response(matches[0], nodes)})
+    else:
+        raise CLIError("expected 'node' or 'edge'")

commands/queries.py

@@ -0,0 +1,69 @@
+from cli import CLIError, Context
+from graphs.engine import Graph, GraphError
+from commands.common import cli, emit, positive_limit, parse_edge_types
+
+@cli.handler("traverse", "Traverse from a node: traverse NODE_ID [--depth N] [--direction in|out|both] [--edge TYPE[,TYPE...]] [--limit N]")
+def traverse(ctx: Context) -> None:
+    if len(ctx.args) != 1:
+        raise CLIError("traverse requires exactly one NODE_ID positional argument")
+    if ctx.flag("from") is not None or ctx.flag("to") is not None:
+        raise CLIError("traverse uses a positional NODE_ID; --from and --to are not supported")
+    anchor_id = ctx.positional(0)
+
+    def integer_flag(name: str, default: int | None) -> int | None:
+        value = ctx.flag(name)
+        if value is None:
+            return default
+        if not isinstance(value, str):
+            raise CLIError(f"--{name} requires an integer")
+        try:
+            parsed = int(value)
+        except ValueError as exc:
+            raise CLIError(f"--{name} requires an integer") from exc
+        if parsed < (1 if name == "depth" else 0):
+            raise CLIError(f"--{name} must be {'positive' if name == 'depth' else 'non-negative'}")
+        return parsed
+
+    depth = integer_flag("depth", 1)
+    limit = positive_limit(ctx.flag("limit"))
+    direction = ctx.flag("direction", default="both")
+    if direction is not None and not isinstance(direction, str):
+        raise CLIError("--direction requires in, out, or both")
+    graph = Graph()
+    edge_types = parse_edge_types(ctx.flag("edge"), graph)
+    result = graph.traverse(anchor_id, depth=depth, direction=direction,
+                              edge_types=edge_types, limit=limit)
+    emit(result)
+
+@cli.handler("path", "Find shortest paths between nodes: path SOURCE TARGET [--direction out|in|both] [--edge TYPE[,TYPE...]] [--max-depth N] [--limit N]")
+def path(ctx: Context) -> None:
+    if len(ctx.args) != 2:
+        raise CLIError("path requires exactly SOURCE and TARGET")
+    source, target = ctx.positional(0), ctx.positional(1)
+    direction = ctx.flag("direction", default="out")
+    if not isinstance(direction, str):
+        raise CLIError("--direction requires out, in, or both")
+    graph = Graph()
+    edge_types = parse_edge_types(ctx.flag("edge"), graph)
+
+    def non_negative_option(name: str, default: int) -> int:
+        value = ctx.flag(name)
+        if value is None:
+            return default
+        if not isinstance(value, str):
+            raise CLIError(f"--{name} requires a non-negative integer")
+        try:
+            parsed = int(value)
+        except ValueError as exc:
+            raise CLIError(f"--{name} requires a non-negative integer") from exc
+        if parsed < 0:
+            raise CLIError(f"--{name} must be non-negative")
+        return parsed
+
+    max_depth = ctx.flag("max-depth")
+    if max_depth is not None:
+        max_depth = non_negative_option("max-depth", 0)
+    limit = positive_limit(ctx.flag("limit"), default=1)
+    result = graph.find_paths(source, target, direction=direction, edge_types=edge_types,
+                              max_depth=max_depth, limit=limit)
+    emit(result)