arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/commands/migrate.py

@@ -0,0 +1,135 @@
+"""arctx CLI migrate command — convert a jsonl run directory to sqlite."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from arctx.storage.jsonl import JsonlRunStore
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``migrate`` subcommand parser."""
+    parser = subparsers.add_parser(
+        "migrate",
+        help="Migrate run storage format (currently: jsonl -> sqlite)",
+    )
+    parser.add_argument(
+        "--to",
+        required=True,
+        choices=["sqlite"],
+        help="Target storage format",
+    )
+    parser.add_argument(
+        "--store-dir",
+        default=None,
+        help="Directory where runs are stored (default: .arctx/runs)",
+    )
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("--run", metavar="RUN_ID", help="Single run ID to migrate")
+    target.add_argument("--all", action="store_true", help="Migrate all runs in store-dir")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing run.db if present",
+    )
+    return parser
+
+
+def run_migrate_command(
+    *,
+    to: str,
+    store_dir: str,
+    run_id: str | None,
+    all_runs: bool,
+    force: bool,
+) -> dict:
+    """Migrate one or all jsonl runs to sqlite.
+
+    Parameters
+    ----------
+    to:
+        Target format, currently only ``"sqlite"`` is supported.
+    store_dir:
+        Root directory of the run store.
+    run_id:
+        Single run to migrate. Mutually exclusive with *all_runs*.
+    all_runs:
+        When True, migrate all runs found via ``JsonlRunStore.list_runs()``.
+    force:
+        When True, overwrite an existing ``run.db`` instead of skipping.
+
+    Returns
+    -------
+    dict with ``migrated``, ``skipped``, and ``failed`` lists of run IDs.
+    """
+    if to != "sqlite":
+        raise ValueError(f"unsupported target format: {to!r}")
+
+    src_store = JsonlRunStore(store_dir)
+    from arctx.storage.sqlite import SqliteRunStore
+
+    dst_store = SqliteRunStore(store_dir)
+
+    if all_runs:
+        run_ids = [r["run_id"] for r in src_store.list_runs()]
+    else:
+        if run_id is None:
+            raise ValueError("either --run or --all must be specified")
+        run_ids = [run_id]
+
+    migrated: list[str] = []
+    skipped: list[str] = []
+    failed: list[str] = []
+
+    for rid in run_ids:
+        run_path = Path(store_dir) / rid
+        nodes_jsonl = run_path / "nodes.jsonl"
+        db_path = run_path / "run.db"
+
+        # Must look like a jsonl run dir
+        if not nodes_jsonl.exists():
+            print(
+                f"warning: {rid}: nodes.jsonl not found — not a jsonl run, skipping",
+                file=sys.stderr,
+            )
+            skipped.append(rid)
+            continue
+
+        # Already migrated?
+        if db_path.exists() and not force:
+            print(
+                f"warning: {rid}: run.db already exists — skipping (use --force to overwrite)",
+                file=sys.stderr,
+            )
+            skipped.append(rid)
+            continue
+
+        # Remove stale db so SqliteRunStore starts fresh
+        if db_path.exists() and force:
+            db_path.unlink()
+
+        try:
+            handle = src_store.load_run(rid)
+            dst_store.save_run(handle)
+            migrated.append(rid)
+        except Exception as exc:  # noqa: BLE001
+            print(f"error: {rid}: migration failed — {exc}", file=sys.stderr)
+            failed.append(rid)
+
+    return {"migrated": migrated, "skipped": skipped, "failed": failed}
+
+
+def cli_migrate(args) -> int:
+    """Entry point for ``arctx migrate`` subcommand."""
+    result = run_migrate_command(
+        to=args.to,
+        store_dir=args.store_dir,
+        run_id=getattr(args, "run", None),
+        all_runs=args.all,
+        force=args.force,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if not result["failed"] else 1

arctx_cli/commands/node.py

@@ -0,0 +1,55 @@
+"""arctx node commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.commands.show import run_show_command
+from arctx_cli.context import resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("node", help="Inspect nodes")
+    node_sub = parser.add_subparsers(dest="node_command", required=True)
+
+    sp_show = node_sub.add_parser("show", help="Show one node")
+    sp_show.add_argument("node_id")
+    sp_show.add_argument("--with-payloads", action="store_true")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    sp_payloads = node_sub.add_parser("payloads", help="Show node payloads")
+    sp_payloads.add_argument("node_id")
+    sp_payloads.add_argument("--run", default=None)
+    sp_payloads.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def cli_node(args) -> int:
+    if args.node_command == "show":
+        result = run_show_command(
+            run_id=resolve_run_id_from_args(args),
+            node_id=args.node_id,
+            transition_id=None,
+            payload_id=None,
+            with_payloads=args.with_payloads,
+            outputs=False,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    if args.node_command == "payloads":
+        result = run_show_command(
+            run_id=resolve_run_id_from_args(args),
+            node_id=args.node_id,
+            transition_id=None,
+            payload_id=None,
+            with_payloads=True,
+            outputs=False,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result["payloads"], ensure_ascii=False, indent=2))
+        return 0
+    return 1

arctx_cli/commands/outcomes.py

@@ -0,0 +1,58 @@
+"""arctx CLI outcomes command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.context import resolve_store, resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("outcomes", help="List output nodes for a Transition")
+    parser.add_argument("transition_id", help="Transition to inspect")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--include-payloads", action="store_true")
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_outcomes_command(
+    *,
+    run_id: str,
+    transition_id: str,
+    include_payloads: bool,
+    store_dir: str,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    g = handle.run_graph
+
+    result = handle.outcomes(transition_id)
+
+    if include_payloads:
+        result["transition_payloads"] = [
+            p.to_dict() for p in g.payloads_for_transition(transition_id)
+        ]
+        result["output_nodes"] = [
+            {
+                "node": g.nodes[node_id].to_dict(),
+                "payloads": [p.to_dict() for p in g.payloads_for_node(node_id)],
+            }
+            for node_id in result["output_node_ids"]
+        ]
+
+    return result
+
+
+def cli_outcomes(args) -> int:
+    result = run_outcomes_command(
+        run_id=resolve_run_id_from_args(args),
+        transition_id=args.transition_id,
+        include_payloads=args.include_payloads,
+        store_dir=args.store_dir,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0

arctx_cli/commands/payload.py

@@ -0,0 +1,192 @@
+"""arctx payload commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+from arctx_cli.payload_builder import (
+    build_payload,
+    parse_field_args,
+    parse_json_object,
+    payload_schema,
+    payload_type_names,
+)
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("payload", help="Inspect and attach payloads")
+    payload_sub = parser.add_subparsers(dest="payload_command", required=True)
+
+    sp_types = payload_sub.add_parser("types", help="List registered payload types")
+    sp_types.add_argument("--store-dir", default=None)
+
+    sp_schema = payload_sub.add_parser("schema", help="Show payload type fields")
+    sp_schema.add_argument("payload_type")
+    sp_schema.add_argument("--store-dir", default=None)
+
+    sp_add = payload_sub.add_parser("add", help="Attach a payload to a node or transition")
+    target = sp_add.add_mutually_exclusive_group(required=True)
+    target.add_argument("--node", dest="node_id", default=None)
+    target.add_argument("--transition", dest="transition_id", default=None)
+    sp_add.add_argument("--payload-type", required=True)
+    sp_add.add_argument("--field", action="append", default=None, help="Payload field as key=value")
+    sp_add.add_argument("--json", default=None, help="Payload fields as a JSON object")
+    sp_add.add_argument("--run", default=None)
+    sp_add.add_argument("--store-dir", default=None)
+    sp_add.add_argument("--user", default=None)
+    sp_add.add_argument("--work-session", default=None)
+
+    sp_list = payload_sub.add_parser("list", help="List payloads on a node or transition")
+    target = sp_list.add_mutually_exclusive_group(required=True)
+    target.add_argument("--node", dest="node_id", default=None)
+    target.add_argument("--transition", dest="transition_id", default=None)
+    sp_list.add_argument("--run", default=None)
+    sp_list.add_argument("--store-dir", default=None)
+
+    sp_show = payload_sub.add_parser("show", help="Show one payload")
+    sp_show.add_argument("payload_id")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def run_payload_add_command(
+    *,
+    run_id: str,
+    target_kind: str,
+    target_id: str,
+    payload_type: str,
+    field_data: dict | None,
+    json_data: dict | None,
+    store_dir: str,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    before = graph_counts(handle)
+    payload = build_payload(
+        payload_type=payload_type,
+        target_kind=target_kind,  # type: ignore[arg-type]
+        target_id=target_id,
+        payload_id=handle._next_id("pl"),
+        json_data=json_data,
+        field_data=field_data,
+    )
+    if payload.target_kind == "node":
+        attached = handle.attach(
+            payload.target_id,
+            payload,
+            user_id=user_id,
+            work_session_id=work_session_id,
+        )
+    else:
+        handle.run_graph.attach_payload(payload)
+        handle.record_work_event(
+            user_id=user_id,
+            work_session_id=work_session_id,
+            event_type="payload_attached",
+            target_kind="transition",
+            target_id=payload.target_id,
+            created_records=(payload.payload_id,),
+            summary=payload.payload_type,
+        )
+        attached = payload
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    return {"payload": attached.to_dict()}
+
+
+def run_payload_list_command(
+    *,
+    run_id: str,
+    target_kind: str,
+    target_id: str,
+    store_dir: str,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    g = handle.run_graph
+    if target_kind == "node":
+        if target_id not in g.nodes:
+            raise KeyError(f"unknown node_id: {target_id}")
+        payloads = g.payloads_for_node(target_id)
+    else:
+        if target_id not in g.transitions:
+            raise KeyError(f"unknown transition_id: {target_id}")
+        payloads = g.payloads_for_transition(target_id)
+    return {"payloads": [p.to_dict() for p in payloads]}
+
+
+def run_payload_show_command(*, run_id: str, payload_id: str, store_dir: str) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    payload = handle.run_graph.payloads.get(payload_id)
+    if payload is None:
+        raise KeyError(f"unknown payload_id: {payload_id}")
+    return {"payload": payload.to_dict()}
+
+
+def cli_payload(args) -> int:
+    if args.payload_command == "types":
+        print(json.dumps({"payload_types": payload_type_names()}, ensure_ascii=False, indent=2))
+        return 0
+    if args.payload_command == "schema":
+        print(json.dumps(payload_schema(args.payload_type), ensure_ascii=False, indent=2))
+        return 0
+    if args.payload_command == "add":
+        target_kind = "node" if args.node_id is not None else "transition"
+        target_id = args.node_id if args.node_id is not None else args.transition_id
+        result = run_payload_add_command(
+            run_id=resolve_run_id_from_args(args),
+            target_kind=target_kind,
+            target_id=target_id,
+            payload_type=args.payload_type,
+            field_data=parse_field_args(args.field),
+            json_data=parse_json_object(args.json),
+            store_dir=args.store_dir,
+            user_id=resolve_user_id_from_args(args),
+            work_session_id=resolve_work_session_id_from_args(args),
+        )
+        print(json.dumps(result["payload"], ensure_ascii=False, indent=2))
+        return 0
+    if args.payload_command == "list":
+        target_kind = "node" if args.node_id is not None else "transition"
+        target_id = args.node_id if args.node_id is not None else args.transition_id
+        result = run_payload_list_command(
+            run_id=resolve_run_id_from_args(args),
+            target_kind=target_kind,
+            target_id=target_id,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result["payloads"], ensure_ascii=False, indent=2))
+        return 0
+    if args.payload_command == "show":
+        result = run_payload_show_command(
+            run_id=resolve_run_id_from_args(args),
+            payload_id=args.payload_id,
+            store_dir=args.store_dir,
+        )
+        print(json.dumps(result["payload"], ensure_ascii=False, indent=2))
+        return 0
+    return 1

arctx_cli/commands/reachable.py

@@ -0,0 +1,75 @@
+"""arctx CLI reachable command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.context import resolve_store, resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "reachable", help="Show active subgraph forward-reachable from a node or view"
+    )
+    parser.add_argument("--run", default=None)
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--from-node", dest="from_node", default=None)
+    group.add_argument("--view", dest="view_name", default=None)
+    parser.add_argument("--include-records", action="store_true")
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_reachable_command(
+    *,
+    run_id: str,
+    from_node: str | None,
+    view_name: str | None,
+    include_records: bool,
+    store_dir: str,
+) -> dict:
+    if from_node is None and view_name is None:
+        raise ValueError("either from_node or view_name is required")
+    if from_node is not None and view_name is not None:
+        raise ValueError("from_node and view_name are mutually exclusive")
+
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    g = handle.run_graph
+
+    if view_name is not None:
+        view = handle.view_show(view_name)
+        root_node_id = view.root_node_id
+    else:
+        root_node_id = from_node
+
+    if root_node_id not in g.nodes:
+        raise KeyError(f"unknown node_id: {root_node_id}")
+
+    result: dict = {"root_node_id": root_node_id}
+    reachable = g.reachable_from(root_node_id)
+    result.update(reachable)
+
+    if include_records:
+        result["nodes"] = [g.nodes[nid].to_dict() for nid in reachable["node_ids"]]
+        result["transitions"] = [
+            g.transitions[tid].to_dict() for tid in reachable["transition_ids"]
+        ]
+        result["payloads"] = [g.payloads[pl_id].to_dict() for pl_id in reachable["payload_ids"]]
+
+    return result
+
+
+def cli_reachable(args) -> int:
+    result = run_reachable_command(
+        run_id=resolve_run_id_from_args(args),
+        from_node=args.from_node,
+        view_name=args.view_name,
+        include_records=args.include_records,
+        store_dir=args.store_dir,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0

arctx_cli/commands/show.py

@@ -0,0 +1,113 @@
+"""arctx CLI show command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.context import resolve_store, resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("show", help="Show run details")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--node", dest="node_id", default=None)
+    parser.add_argument("--transition", dest="transition_id", default=None)
+    parser.add_argument("--payload", dest="payload_id", default=None)
+    parser.add_argument("--with-payloads", action="store_true")
+    parser.add_argument(
+        "--outputs", action="store_true", help="(with --transition) include output nodes"
+    )
+    parser.add_argument(
+        "--history",
+        action="store_true",
+        help="(with --transition) show all GitChangePayload entries in append order",
+    )
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_show_command(
+    *,
+    run_id: str,
+    node_id: str | None,
+    transition_id: str | None,
+    payload_id: str | None,
+    with_payloads: bool,
+    outputs: bool,
+    history: bool = False,
+    store_dir: str,
+) -> dict:
+    if outputs and transition_id is None:
+        raise ValueError("--outputs can only be used with --transition")
+    if with_payloads and payload_id is not None:
+        raise ValueError("--with-payloads cannot be used with --payload")
+
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    g = handle.run_graph
+
+    if node_id is not None:
+        node = g.nodes.get(node_id)
+        if node is None:
+            raise KeyError(f"unknown node_id: {node_id}")
+        result: dict = {"node": node.to_dict()}
+        if with_payloads:
+            result["payloads"] = [p.to_dict() for p in g.payloads_for_node(node_id)]
+        return result
+
+    if transition_id is not None:
+        transition = g.transitions.get(transition_id)
+        if transition is None:
+            raise KeyError(f"unknown transition_id: {transition_id}")
+        result = {
+            "transition": transition.to_dict(),
+            "input_node_ids": g.transition_inputs(transition_id),
+        }
+        if with_payloads:
+            result["payloads"] = [p.to_dict() for p in g.payloads_for_transition(transition_id)]
+        if outputs:
+            result["output_nodes"] = [
+                g.nodes[node_id].to_dict() for node_id in g.transition_outputs(transition_id)
+            ]
+        # GitChangePayload display: --history shows all; default shows latest only.
+        git_payloads = g.payloads_for_transition(transition_id, payload_type="git_change")
+        if history:
+            result["git_change_history"] = [p.to_dict() for p in git_payloads]
+        else:
+            result["git_change"] = git_payloads[-1].to_dict() if git_payloads else None
+        return result
+
+    if payload_id is not None:
+        payload = g.payloads.get(payload_id)
+        if payload is None:
+            raise KeyError(f"unknown payload_id: {payload_id}")
+        return {"payload": payload.to_dict()}
+
+    return {
+        "run_id": handle.run_id,
+        "requirement_id": handle.requirement.requirement_id,
+        "root_node_id": handle.root_node_id,
+        "node_count": len(g.nodes),
+        "transition_count": len(g.transitions),
+
+        "payload_count": len(g.payloads),
+        "views": [v.name for v in handle.run_graph.views.values()],
+    }
+
+
+def cli_show(args) -> int:
+    result = run_show_command(
+        run_id=resolve_run_id_from_args(args),
+        node_id=args.node_id,
+        transition_id=args.transition_id,
+        payload_id=args.payload_id,
+        with_payloads=args.with_payloads,
+        outputs=args.outputs,
+        history=args.history,
+        store_dir=args.store_dir,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0