arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/__init__.py

@@ -0,0 +1 @@
+"""arctx CLI package."""

arctx_cli/alias.py

@@ -0,0 +1,238 @@
+"""Alias resolution for arctx CLI.
+
+Resolution priority (later wins for the same key when merging):
+1. Extension default_aliases (load order; first ext wins among ext-default conflicts)
+2. User config (~/.config/arctx/aliases.toml)
+3. Run-local config (<run_dir>/aliases.toml)
+
+Alias expansion is one-level only — alias-to-alias chains are prohibited to
+prevent infinite loops.
+
+Format of aliases.toml::
+
+    [aliases]
+    commit = "git commit"
+    c = "git commit"
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+try:
+    import tomllib  # py311+ stdlib
+except ModuleNotFoundError:  # py310 fallback
+    try:
+        import tomli as tomllib  # type: ignore[no-redef]
+    except ModuleNotFoundError as exc:
+        raise ImportError(
+            "Python 3.10 requires the 'tomli' package for TOML parsing. "
+            "Install it with: pip install tomli"
+        ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def _user_alias_path() -> Path:
+    """Return ``~/.config/arctx/aliases.toml``."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "arctx" / "aliases.toml"
+    return Path.home() / ".config" / "arctx" / "aliases.toml"
+
+
+def _run_alias_path(run_dir: Path | str) -> Path:
+    """Return ``<run_dir>/aliases.toml``."""
+    return Path(run_dir) / "aliases.toml"
+
+
+# ---------------------------------------------------------------------------
+# TOML writer (minimal — stdlib has no tomllib writer)
+# ---------------------------------------------------------------------------
+
+
+def _write_toml_aliases(path: Path, aliases: dict[str, str]) -> None:
+    """Write *aliases* to *path* as a ``[aliases]`` TOML section.
+
+    Entries are sorted for stable output.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = ["[aliases]\n"]
+    for key in sorted(aliases.keys()):
+        value = aliases[key].replace("\\", "\\\\").replace('"', '\\"')
+        lines.append(f'{key} = "{value}"\n')
+    path.write_text("".join(lines), encoding="utf-8")
+
+
+def _read_toml_aliases(path: Path) -> dict[str, str]:
+    """Read the ``[aliases]`` table from *path*.  Returns {} if missing."""
+    if not path.exists():
+        return {}
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+    raw = data.get("aliases", {})
+    return {str(k): str(v) for k, v in raw.items()}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def load_alias_table(
+    *,
+    run_dir: str | Path | None = None,
+    extensions_default_aliases: Optional[list[dict[str, str]]] = None,
+) -> dict[str, str]:
+    """Build the merged alias table.
+
+    Priority (later entries win for the same key):
+    - Extension defaults (in load order; first ext wins for ext-level conflicts)
+    - User config (~/.config/arctx/aliases.toml)
+    - Run-local config (<run_dir>/aliases.toml)
+
+    Parameters
+    ----------
+    run_dir:
+        Directory of the active run.  When provided, ``<run_dir>/aliases.toml``
+        is loaded and takes highest priority.
+    extensions_default_aliases:
+        List of ``default_aliases()`` dicts from enabled extensions, in load
+        order.  First ext wins for duplicate alias names at this tier.
+    """
+    merged: dict[str, str] = {}
+
+    # 1. Extension defaults (first ext wins → iterate in order, skip if already set)
+    if extensions_default_aliases:
+        for ext_aliases in extensions_default_aliases:
+            for name, target in ext_aliases.items():
+                if name not in merged:
+                    merged[name] = target
+
+    # 2. User config (overrides ext defaults)
+    user_aliases = _read_toml_aliases(_user_alias_path())
+    merged.update(user_aliases)
+
+    # 3. Run-local config (highest priority)
+    if run_dir is not None:
+        run_aliases = _read_toml_aliases(_run_alias_path(run_dir))
+        merged.update(run_aliases)
+
+    return merged
+
+
+def resolve_alias(alias_table: dict[str, str], tokens: list[str]) -> list[str]:
+    """Expand *tokens[0]* if it appears in *alias_table*; else return *tokens*.
+
+    Expansion is one-level only.  The alias value is split on whitespace (no
+    shell quoting support needed for now) and prepended to the remaining tokens.
+
+    Examples
+    --------
+    >>> resolve_alias({"commit": "git commit"}, ["commit", "-m", "x"])
+    ["git", "commit", "-m", "x"]
+    >>> resolve_alias({}, ["init", "req"])
+    ["init", "req"]
+    """
+    if not tokens:
+        return tokens
+    first = tokens[0]
+    if first not in alias_table:
+        return tokens
+    expansion = alias_table[first].split()
+    return expansion + tokens[1:]
+
+
+def save_user_alias(name: str, target: str) -> Path:
+    """Add or update *name → target* in the user aliases.toml.
+
+    Returns the path of the written file.
+    """
+    path = _user_alias_path()
+    existing = _read_toml_aliases(path)
+    existing[name] = target
+    _write_toml_aliases(path, existing)
+    return path
+
+
+def remove_user_alias(name: str) -> Path:
+    """Remove *name* from the user aliases.toml.
+
+    Returns the path of the written file.
+
+    Raises
+    ------
+    KeyError
+        If *name* is not present.
+    """
+    path = _user_alias_path()
+    existing = _read_toml_aliases(path)
+    if name not in existing:
+        raise KeyError(f"alias not found: {name!r}")
+    del existing[name]
+    _write_toml_aliases(path, existing)
+    return path
+
+
+def list_aliases(
+    *,
+    run_dir: str | Path | None = None,
+    extensions_default_aliases: Optional[list[dict[str, str]]] = None,
+    extension_names: Optional[list[str]] = None,
+) -> dict[str, tuple[str, str]]:
+    """Return ``{alias_name: (target, source)}`` with provenance.
+
+    *source* is one of:
+
+    - ``"run"`` — from ``<run_dir>/aliases.toml``
+    - ``"user"`` — from ``~/.config/arctx/aliases.toml``
+    - ``"ext:<name>"`` — from an extension's ``default_aliases()``
+
+    The same merge priority applies; this function exposes the winning source
+    for each alias name.
+
+    Parameters
+    ----------
+    extension_names:
+        Parallel list to *extensions_default_aliases* giving the extension name
+        for each entry.  If None, sources are labelled ``"ext:0"``, ``"ext:1"``
+        etc.
+    """
+    result: dict[str, tuple[str, str]] = {}
+
+    ext_aliases_list = extensions_default_aliases or []
+    ext_names_list = extension_names or []
+
+    # 1. Extension defaults (first ext wins)
+    for idx, ext_aliases in enumerate(ext_aliases_list):
+        ext_label = f"ext:{ext_names_list[idx]}" if idx < len(ext_names_list) else f"ext:{idx}"
+        for name, target in ext_aliases.items():
+            if name not in result:
+                result[name] = (target, ext_label)
+
+    # 2. User config
+    user_aliases = _read_toml_aliases(_user_alias_path())
+    for name, target in user_aliases.items():
+        result[name] = (target, "user")
+
+    # 3. Run-local (highest priority)
+    if run_dir is not None:
+        run_aliases = _read_toml_aliases(_run_alias_path(run_dir))
+        for name, target in run_aliases.items():
+            result[name] = (target, "run")
+
+    return result
+
+
+__all__ = [
+    "load_alias_table",
+    "resolve_alias",
+    "save_user_alias",
+    "remove_user_alias",
+    "list_aliases",
+]

arctx_cli/append_batch.py

@@ -0,0 +1,90 @@
+"""Helpers for turning in-memory mutations into SQLite append batches."""
+
+from __future__ import annotations
+
+from arctx.core.append import AppendBatch, GraphRecordEnvelope
+
+
+def graph_counts(handle) -> dict[str, set[str]]:
+    """Capture graph record IDs before a mutation."""
+    return {
+        "nodes": set(handle.run_graph.nodes),
+        "transitions": set(handle.run_graph.transitions),
+        "payloads": set(handle.run_graph.payloads),
+        "views": {view.view_id for view in handle.run_graph.views.values()},
+        "work_events": {event.event_id for event in handle.run_graph.work_events},
+    }
+
+
+def maybe_append_or_save(
+    *,
+    store,
+    handle,
+    user_id: str | None,
+    work_session_id: str | None,
+    before: dict[str, set[str]],
+) -> None:
+    """Use append_batch for capable stores, otherwise fall back to save_run."""
+    if user_id is None or work_session_id is None or not hasattr(store, "append_batch"):
+        store.save_run(handle)
+        return
+    store.append_batch(
+        build_append_batch(
+            handle,
+            user_id=user_id,
+            work_session_id=work_session_id,
+            before=before,
+        )
+    )
+
+
+def build_append_batch(
+    handle,
+    *,
+    user_id: str,
+    work_session_id: str,
+    before: dict[str, set[str]],
+) -> AppendBatch:
+    """Build an append batch from records added since *before*."""
+    records: list[GraphRecordEnvelope] = []
+
+    for node_id in _new_ids(handle.run_graph.nodes, before, "nodes"):
+        node = handle.run_graph.nodes[node_id]
+        records.append(GraphRecordEnvelope("node", node.node_id, node))
+
+    for transition_id in _new_ids(handle.run_graph.transitions, before, "transitions"):
+        transition = handle.run_graph.transitions[transition_id]
+        records.append(GraphRecordEnvelope("transition", transition.transition_id, transition))
+
+    for payload_id in _new_ids(handle.run_graph.payloads, before, "payloads"):
+        payload = handle.run_graph.payloads[payload_id]
+        records.append(GraphRecordEnvelope("payload", payload.payload_id, payload))
+
+    before_view_ids = before.get("views", set())
+    new_views = [
+        view for view in handle.run_graph.views.values() if view.view_id not in before_view_ids
+    ]
+    for view in new_views:
+        records.append(GraphRecordEnvelope("view", view.view_id, view))
+
+    new_events = [
+        event
+        for event in handle.run_graph.work_events
+        if event.event_id not in before.get("work_events", set())
+    ]
+    if not new_events:
+        raise RuntimeError("append batch requires at least one work event")
+
+    session = handle.run_graph.work_sessions[work_session_id]
+    return AppendBatch(
+        run_id=handle.run_id,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        work_session=session,
+        events=tuple(new_events),
+        records=tuple(records),
+    )
+
+
+def _new_ids(current: dict[str, object], before: dict[str, set[str]], key: str) -> list[str]:
+    return [record_id for record_id in current if record_id not in before.get(key, set())]

arctx_cli/commands/__init__.py

@@ -0,0 +1,85 @@
+"""Core CLI command registry."""
+
+from __future__ import annotations
+
+from arctx.ext import CliCommand
+
+
+def core_cli_commands() -> list[CliCommand]:
+    """Return the built-in, extension-independent CLI commands."""
+    from arctx_cli.commands.alias_cmd import add_parser as add_alias_parser
+    from arctx_cli.commands.alias_cmd import cli_alias
+    from arctx_cli.commands.anchor import add_parser as add_anchor_parser
+    from arctx_cli.commands.anchor import cli_anchor
+    from arctx_cli.commands.current import add_parser as add_current_parser
+    from arctx_cli.commands.current import cli_current
+    from arctx_cli.commands.cut import add_parser as add_cut_parser
+    from arctx_cli.commands.cut import cli_cut
+    from arctx_cli.commands.dump import add_parser as add_dump_parser
+    from arctx_cli.commands.dump import cli_dump
+    from arctx_cli.commands.ext import add_parser as add_ext_parser
+    from arctx_cli.commands.ext import cli_ext
+    from arctx_cli.commands.graph import add_parser as add_graph_parser
+    from arctx_cli.commands.graph import cli_graph
+    from arctx_cli.commands.guide import add_parser as add_guide_parser
+    from arctx_cli.commands.guide import cli_guide
+    from arctx_cli.commands.init import add_parser as add_init_parser
+    from arctx_cli.commands.init import cli_init
+    from arctx_cli.commands.list import add_parser as add_list_parser
+    from arctx_cli.commands.list import cli_list
+    from arctx_cli.commands.migrate import add_parser as add_migrate_parser
+    from arctx_cli.commands.migrate import cli_migrate
+    from arctx_cli.commands.node import add_parser as add_node_parser
+    from arctx_cli.commands.node import cli_node
+    from arctx_cli.commands.outcomes import add_parser as add_outcomes_parser
+    from arctx_cli.commands.outcomes import cli_outcomes
+    from arctx_cli.commands.payload import add_parser as add_payload_parser
+    from arctx_cli.commands.payload import cli_payload
+    from arctx_cli.commands.reachable import add_parser as add_reachable_parser
+    from arctx_cli.commands.reachable import cli_reachable
+    from arctx_cli.commands.show import add_parser as add_show_parser
+    from arctx_cli.commands.show import cli_show
+    from arctx_cli.commands.sync import add_parser as add_sync_parser
+    from arctx_cli.commands.sync import cli_sync
+    from arctx_cli.commands.trace import add_parser as add_trace_parser
+    from arctx_cli.commands.trace import cli_trace
+    from arctx_cli.commands.transition import add_parser as add_transition_parser
+    from arctx_cli.commands.transition import cli_transition
+    from arctx_cli.commands.use import add_parser as add_use_parser
+    from arctx_cli.commands.use import cli_use
+    from arctx_cli.commands.view import add_parser as add_view_parser
+    from arctx_cli.commands.view import cli_view
+    from arctx_cli.commands.work_session import add_parser as add_work_session_parser
+    from arctx_cli.commands.work_session import cli_work_session
+
+    return [
+        CliCommand("alias", add_alias_parser, cli_alias),
+        CliCommand("anchor", add_anchor_parser, cli_anchor),
+        CliCommand("current", add_current_parser, cli_current),
+        CliCommand("ext", add_ext_parser, cli_ext),
+        CliCommand("dump", add_dump_parser, cli_dump),
+        CliCommand("graph", add_graph_parser, cli_graph),
+        CliCommand("guide", add_guide_parser, cli_guide),
+        CliCommand("init", add_init_parser, cli_init),
+        CliCommand("list", add_list_parser, cli_list),
+        CliCommand("migrate", add_migrate_parser, cli_migrate),
+        CliCommand("node", add_node_parser, cli_node),
+        CliCommand("outcomes", add_outcomes_parser, cli_outcomes),
+        CliCommand("payload", add_payload_parser, cli_payload),
+        CliCommand("reachable", add_reachable_parser, cli_reachable),
+        CliCommand("cut", add_cut_parser, cli_cut),
+        CliCommand("show", add_show_parser, cli_show),
+        CliCommand("sync", add_sync_parser, cli_sync),
+        CliCommand("trace", add_trace_parser, cli_trace),
+        CliCommand("transition", add_transition_parser, cli_transition),
+        CliCommand("use", add_use_parser, cli_use),
+        CliCommand("view", add_view_parser, cli_view),
+        CliCommand("work-session", add_work_session_parser, cli_work_session),
+    ]
+
+
+def register_cli_commands(subparsers, commands: list[CliCommand]) -> None:
+    """Register CLI commands and attach their dispatch handlers."""
+    for command in commands:
+        parser = command.add_parser(subparsers)
+        parser.set_defaults(_arctx_handler=command.handler)

arctx_cli/commands/alias_cmd.py

@@ -0,0 +1,174 @@
+"""arctx alias subcommand — manage CLI aliases.
+
+Subcommands
+-----------
+list     Show the current alias table with provenance (run > user > ext).
+add      Add or update an alias in the user config.
+remove   Remove an alias from the user config.
+resolve  Show the expansion of a given alias token (debug helper).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``alias`` subcommand."""
+    parser = subparsers.add_parser("alias", help="Manage CLI aliases")
+    alias_sub = parser.add_subparsers(dest="alias_command", required=True)
+
+    # alias list
+    al_list = alias_sub.add_parser("list", help="Show all aliases with provenance")
+    al_list.add_argument("--run", default=None, help="Run ID")
+    al_list.add_argument("--store-dir", default=None, dest="store_dir")
+
+    # alias add <name> <target>
+    al_add = alias_sub.add_parser("add", help="Add or update a user alias")
+    al_add.add_argument("name", help="Alias name (e.g. 'c')")
+    al_add.add_argument("target", help="Alias target (e.g. 'git commit')")
+
+    # alias remove <name>
+    al_remove = alias_sub.add_parser("remove", help="Remove a user alias")
+    al_remove.add_argument("name", help="Alias name to remove")
+
+    # alias resolve <name>
+    al_resolve = alias_sub.add_parser("resolve", help="Show how a token resolves")
+    al_resolve.add_argument("name", help="Token to resolve")
+    al_resolve.add_argument("--run", default=None, help="Run ID")
+    al_resolve.add_argument("--store-dir", default=None, dest="store_dir")
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_run_dir_from_args(args) -> str | None:
+    """Best-effort: resolve run_dir from args."""
+    from pathlib import Path
+
+    store_dir = getattr(args, "store_dir", None)
+    run_id_arg = getattr(args, "run", None)
+    if run_id_arg is None:
+        import os
+
+        run_id_arg = os.environ.get("ARCTX_RUN_ID")
+    if run_id_arg and store_dir:
+        return str(Path(store_dir) / run_id_arg)
+    if run_id_arg:
+        from arctx_cli.paths import resolve_store_dir
+
+        return str(Path(resolve_store_dir()) / run_id_arg)
+    return None
+
+
+def _collect_ext_aliases(run_dir: str | None) -> tuple[list[dict[str, str]], list[str]]:
+    """Load default_aliases from standard and enabled extensions."""
+    from arctx.ext import load_extension
+    from arctx.ext.enabled import load_enabled
+
+    ext_aliases: list[dict[str, str]] = []
+    ext_names: list[str] = []
+    seen: set[str] = set()
+    for ext_name in ["git"]:
+        try:
+            ext = load_extension(ext_name)
+            ext_aliases.append(ext.default_aliases())
+            ext_names.append(ext.name)
+            seen.add(ext.name)
+        except (KeyError, ImportError):
+            continue
+
+    if run_dir is None:
+        return ext_aliases, ext_names
+
+    for ee in load_enabled(run_dir):
+        if ee.name in seen:
+            continue
+        try:
+            ext = load_extension(ee.name)
+            ext_aliases.append(ext.default_aliases())
+            ext_names.append(ext.name)
+            seen.add(ext.name)
+        except (KeyError, ImportError):
+            continue
+    return ext_aliases, ext_names
+
+
+# ---------------------------------------------------------------------------
+# CLI dispatcher
+# ---------------------------------------------------------------------------
+
+
+def cli_alias(args) -> int:
+    """Dispatch arctx alias subcommands."""
+    from arctx_cli.alias import list_aliases, remove_user_alias, resolve_alias, save_user_alias
+
+    cmd = args.alias_command
+
+    if cmd == "list":
+        run_dir = _resolve_run_dir_from_args(args)
+        ext_aliases, ext_names = _collect_ext_aliases(run_dir)
+        table = list_aliases(
+            run_dir=run_dir,
+            extensions_default_aliases=ext_aliases,
+            extension_names=ext_names,
+        )
+        output = {
+            name: {"target": target, "source": source}
+            for name, (target, source) in table.items()
+        }
+        print(json.dumps(output, indent=2, ensure_ascii=False, sort_keys=True))
+        return 0
+
+    if cmd == "add":
+        path = save_user_alias(args.name, args.target)
+        print(f"alias {args.name!r} -> {args.target!r} saved to {path}", file=sys.stderr)
+        return 0
+
+    if cmd == "remove":
+        try:
+            path = remove_user_alias(args.name)
+        except KeyError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(f"alias {args.name!r} removed from {path}", file=sys.stderr)
+        return 0
+
+    if cmd == "resolve":
+        run_dir = _resolve_run_dir_from_args(args)
+        ext_aliases, _ = _collect_ext_aliases(run_dir)
+        from arctx_cli.alias import load_alias_table
+
+        table = load_alias_table(run_dir=run_dir, extensions_default_aliases=ext_aliases)
+        expanded = resolve_alias(table, [args.name])
+        if expanded == [args.name]:
+            result = {"input": args.name, "resolved": False, "tokens": expanded}
+        else:
+            source = "unknown"
+            from arctx_cli.alias import list_aliases as _la
+
+            ext_aliases2, ext_names2 = _collect_ext_aliases(run_dir)
+            provenance = _la(
+                run_dir=run_dir,
+                extensions_default_aliases=ext_aliases2,
+                extension_names=ext_names2,
+            )
+            if args.name in provenance:
+                source = provenance[args.name][1]
+            result = {
+                "input": args.name,
+                "resolved": True,
+                "tokens": expanded,
+                "target": table[args.name],
+                "source": source,
+            }
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    return 1

arctx_cli/commands/anchor.py

@@ -0,0 +1,82 @@
+"""arctx CLI anchor command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+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.append_batch import graph_counts, maybe_append_or_save
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "anchor",
+        help="Create a scope anchor node from an existing node",
+        description=(
+            "Create a lightweight branching anchor using a scope_refinement plan "
+            "and a completed result."
+        ),
+    )
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--from", required=True, dest="from_node_id", metavar="NODE_ID")
+    parser.add_argument("--label", required=True)
+    parser.add_argument("--store-dir", default=None)
+    parser.add_argument("--user", default=None)
+    parser.add_argument("--work-session", default=None)
+    return parser
+
+
+def run_anchor_command(
+    *,
+    run_id: str,
+    from_node_id: str,
+    label: str,
+    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)
+    node = handle.anchor(
+        from_node_id,
+        label,
+        user_id=user_id,
+        work_session_id=work_session_id,
+    )
+    transition_id = handle.run_graph.transitions_to_node(node.node_id)[0]
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    return {
+        "anchor": {
+            "transition_id": transition_id,
+            "node_id": node.node_id,
+            "label": label,
+        }
+    }
+
+
+def cli_anchor(args) -> int:
+    result = run_anchor_command(
+        run_id=resolve_run_id_from_args(args),
+        from_node_id=args.from_node_id,
+        label=args.label,
+        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["anchor"], ensure_ascii=False, indent=2))
+    return 0