swarph-cli 0.1.1__tar.gz → 0.2.0__tar.gz

{swarph_cli-0.1.1/src/swarph_cli.egg-info → swarph_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.1.1
+Version: 0.2.0
 Summary: The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13).
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -49,7 +49,42 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.1.0 — Phase 2 one-shot mode.** The `swarph "prompt"` binary works end-to-end against `--provider gemini` per PLAN.md §13 falsifiability gate. Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, import).
+**v0.2.0 — Phase 2 one-shot + Phase 2.5 import.** Two verbs ship:
+
+1. `swarph "prompt"` — Phase 2 one-shot mode (against `--provider gemini`)
+2. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
+
+Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, additional source formats).
+
+### `swarph import`
+
+Per PLAN.md §17, session import is the **knowledge half of onboarding** — gives a memory-carrying peer (or human migrating CLIs) the substantive context they're bringing into the swarph, paired with §15's contract half (handshake DM acknowledging the four invariants).
+
+```bash
+# Inspect what would be imported (lossy → honest framing)
+$ swarph import ~/.claude/projects/.../X.jsonl --report-only
+
+# Commit — writes ~/.swarph/sessions/<session-id>.jsonl
+$ swarph import ~/.claude/projects/.../X.jsonl
+
+# Refuse-with-error if target exists (protects continuation turns)
+$ swarph import same-source.jsonl
+swarph import: target /home/.../X.jsonl already exists (...)
+To proceed:
+  --force                  overwrite (destroys continuation turns)
+  --target-session NAME    write to a different file
+```
+
+**What ports cleanly:** plain user/assistant/system text, role tags, conversation order.
+
+**What's lossy** (counted in report, kept as visible text where possible):
+- `thinking` blocks (Anthropic-specific reasoning trace)
+- `tool_use` blocks (call shape doesn't port across providers)
+- `tool_result` blocks (companion drop with `tool_use`)
+
+**What's dropped:** attachments (would need re-upload), provider-side KV cache, conversation IDs, `cache_control` annotations.
+
+Honest framing per PLAN.md §17.3: **teleport is "import + continue", not "freeze and resume"** — the first turn after import on a new provider pays cold-cache cost. Phase 5+ adds `--continue` for live REPL integration.
 
 ```bash
 $ swarph "say pong" --provider gemini

{swarph_cli-0.1.1 → swarph_cli-0.2.0}/README.md

@@ -17,7 +17,42 @@ This is one of three repos in the v0.3.x architecture:
 
 ## Status
 
-**v0.1.0 — Phase 2 one-shot mode.** The `swarph "prompt"` binary works end-to-end against `--provider gemini` per PLAN.md §13 falsifiability gate. Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, import).
+**v0.2.0 — Phase 2 one-shot + Phase 2.5 import.** Two verbs ship:
+
+1. `swarph "prompt"` — Phase 2 one-shot mode (against `--provider gemini`)
+2. `swarph import <path>` — Phase 2.5 session import (Claude JSONL → swarph-native, with `--report-only` for honest pre-commit inspection)
+
+Subsequent phases extend the CLI surface (REPL, `--ask <peer>`, onboard/ratify, daemon, additional source formats).
+
+### `swarph import`
+
+Per PLAN.md §17, session import is the **knowledge half of onboarding** — gives a memory-carrying peer (or human migrating CLIs) the substantive context they're bringing into the swarph, paired with §15's contract half (handshake DM acknowledging the four invariants).
+
+```bash
+# Inspect what would be imported (lossy → honest framing)
+$ swarph import ~/.claude/projects/.../X.jsonl --report-only
+
+# Commit — writes ~/.swarph/sessions/<session-id>.jsonl
+$ swarph import ~/.claude/projects/.../X.jsonl
+
+# Refuse-with-error if target exists (protects continuation turns)
+$ swarph import same-source.jsonl
+swarph import: target /home/.../X.jsonl already exists (...)
+To proceed:
+  --force                  overwrite (destroys continuation turns)
+  --target-session NAME    write to a different file
+```
+
+**What ports cleanly:** plain user/assistant/system text, role tags, conversation order.
+
+**What's lossy** (counted in report, kept as visible text where possible):
+- `thinking` blocks (Anthropic-specific reasoning trace)
+- `tool_use` blocks (call shape doesn't port across providers)
+- `tool_result` blocks (companion drop with `tool_use`)
+
+**What's dropped:** attachments (would need re-upload), provider-side KV cache, conversation IDs, `cache_control` annotations.
+
+Honest framing per PLAN.md §17.3: **teleport is "import + continue", not "freeze and resume"** — the first turn after import on a new provider pays cold-cache cost. Phase 5+ adds `--continue` for live REPL integration.
 
 ```bash
 $ swarph "say pong" --provider gemini

{swarph_cli-0.1.1 → swarph_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.1.1"
+version = "0.2.0"
 description = "The `swarph` binary — multi-LLM CLI with mesh-gateway integration. Phase 2 one-shot mode shipped (PLAN.md §13)."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.1.1 → swarph_cli-0.2.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = ["__version__"]

swarph_cli-0.2.0/src/swarph_cli/commands/__init__.py

@@ -0,0 +1,15 @@
+"""Subcommand handlers for ``swarph``.
+
+Phase 2.5 ships ``import``. Phase 3+ adds ``--ask`` / ``list-peers``;
+Phase 5+ adds ``chat`` REPL; Phase 5.5 adds ``onboard`` / ``ratify``;
+Phase 5.7 adds ``daemon``.
+
+Each handler is a function that takes a list of argv-style argument
+strings (the verb stripped off) and returns an int exit code.
+"""
+
+from __future__ import annotations
+
+from swarph_cli.commands.import_session import run_import
+
+__all__ = ["run_import"]

swarph_cli-0.2.0/src/swarph_cli/commands/import_session.py

@@ -0,0 +1,232 @@
+"""``swarph import`` — Phase 2.5 implementation.
+
+Per PLAN.md §17.6 forward-reorder, Phase 2.5 ships:
+- Parser + converter for Claude session JSONL
+- Import-report writer
+- ``--report-only`` mode (no writes, no continuation)
+
+Phase 3.5+ adds gemini + llm source formats. Phase 5+ adds
+``--continue`` for live REPL integration.
+
+Per PLAN.md §17.4 the subcommand spec:
+
+    swarph import <source-path>
+                  [--source-format claude|gemini|llm|chatgpt-export]
+                  [--report-only]                   # v0.2.0 — this release
+                  [--target-session NAME]           # v0.2.0 (write path)
+                  [--force]                         # v0.2.0 (write path)
+                  [--continue]                      # Phase 5+
+                  [--provider gemini|...]           # Phase 5+
+                  [--last N]                        # Phase 5+
+
+v0.2.0 implements `--report-only` as the primary path. Write +
+target-session + force land in the same release because they
+share the cursor.json output codepath. `--continue` defers to
+Phase 5+ (gates on REPL).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from swarph_cli.parsers import ClaudeParser, ImportResult
+
+
+SUPPORTED_FORMATS = {"claude"}  # gemini + llm + chatgpt-export land in 3.5+/6+
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph import",
+        description=(
+            "Import a session from another CLI into swarph-native format. "
+            "v0.2.0 ships --report-only + write paths for Claude JSONL "
+            "sessions; teleport (--continue) lands in Phase 5+."
+        ),
+    )
+    p.add_argument(
+        "source_path",
+        help="Path to source session file (e.g. ~/.claude/projects/.../X.jsonl).",
+    )
+    p.add_argument(
+        "--source-format",
+        default=None,
+        choices=sorted(SUPPORTED_FORMATS),
+        help="Override source-format detection (currently only 'claude' supported).",
+    )
+    p.add_argument(
+        "--report-only",
+        action="store_true",
+        help="Print the import report and exit; do NOT write a swarph-native "
+        "session. Use this to inspect what would be imported (and what would "
+        "be lost) before committing.",
+    )
+    p.add_argument(
+        "--target-session",
+        default=None,
+        help="Custom name for the swarph-native session file (default: source "
+        "session-id or filename stem). Stored at ~/.swarph/sessions/<NAME>.jsonl.",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite the target session file if it already exists. Without "
+        "--force, swarph import refuses-with-error to prevent silently "
+        "destroying continuation turns added since a prior import (drop PR "
+        "#138 review concern (g)).",
+    )
+    p.add_argument(
+        "--json-report",
+        action="store_true",
+        help="Emit the import report as a JSON object on stdout instead of "
+        "human-readable text. Useful for downstream tooling.",
+    )
+    return p
+
+
+def _detect_format(path: Path) -> Optional[str]:
+    """Heuristic source-format detection. Phase 2.5 only knows 'claude'."""
+    pstr = str(path).lower()
+    if ".claude/projects/" in pstr or path.suffix == ".jsonl":
+        # Sniff first line for Claude record-type discriminator
+        try:
+            with path.open(encoding="utf-8") as f:
+                first = f.readline().strip()
+            if first:
+                rec = json.loads(first)
+                if isinstance(rec, dict) and rec.get("type") in {
+                    "user", "assistant", "system", "permission-mode",
+                    "file-history-snapshot", "attachment", "queue-operation",
+                }:
+                    return "claude"
+        except (json.JSONDecodeError, OSError):
+            pass
+    return None
+
+
+def _swarph_native_path(target_session: Optional[str], result: ImportResult) -> Path:
+    """Resolve the target swarph-native session file path."""
+    base = Path.home() / ".swarph" / "sessions"
+    base.mkdir(parents=True, exist_ok=True)
+    if target_session:
+        name = target_session
+    else:
+        name = (
+            result.metadata.get("session_id")
+            or Path(result.report.source_path).stem
+        )
+    if not name.endswith(".jsonl"):
+        name = f"{name}.jsonl"
+    return base / name
+
+
+def _write_swarph_native_session(
+    out_path: Path,
+    result: ImportResult,
+) -> None:
+    """Write the swarph-native JSONL per PLAN.md §17.5.
+
+    First line is the metadata header; subsequent lines are
+    role+content turns with `_meta.source = "imported"` per drop's
+    PR #138 review carry-forward (f).
+    """
+    header = {
+        "_meta": {
+            "version": "v1",
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "imported_from": {
+                "format": result.report.source_format,
+                "path": result.report.source_path,
+                "session_id": result.report.session_id,
+            },
+            "import_report": result.report.to_dict(),
+        }
+    }
+    with out_path.open("w", encoding="utf-8") as f:
+        f.write(json.dumps(header, separators=(",", ":")) + "\n")
+        for m in result.messages:
+            row = {
+                "role": m.role,
+                "content": m.content,
+                "_meta": {"source": "imported"},
+            }
+            f.write(json.dumps(row, separators=(",", ":")) + "\n")
+
+
+def run_import(argv: list[str]) -> int:
+    """Entry point for the ``swarph import`` verb."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    src_path = Path(args.source_path).expanduser()
+    if not src_path.exists():
+        print(f"swarph import: source file not found: {src_path}", file=sys.stderr)
+        return 2
+
+    fmt = args.source_format or _detect_format(src_path)
+    if fmt is None:
+        print(
+            f"swarph import: could not detect source format for {src_path}; "
+            f"specify with --source-format. Supported: {sorted(SUPPORTED_FORMATS)}",
+            file=sys.stderr,
+        )
+        return 2
+    if fmt not in SUPPORTED_FORMATS:
+        print(
+            f"swarph import: source-format '{fmt}' not supported in v0.2.0; "
+            f"Phase 3.5+ adds gemini + llm; Phase 6+ adds chatgpt-export.",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Parse
+    try:
+        if fmt == "claude":
+            result = ClaudeParser().parse(src_path)
+        else:  # pragma: no cover — guarded above
+            raise NotImplementedError(fmt)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"swarph import: parse failed: {exc}", file=sys.stderr)
+        return 2
+
+    # Print report
+    if args.json_report:
+        print(json.dumps(result.report.to_dict(), indent=2, sort_keys=True))
+    else:
+        print(result.report.render_human())
+
+    if args.report_only:
+        return 0
+
+    # Write path — refuse-with-error default per drop's PR #138 review (g)
+    out_path = _swarph_native_path(args.target_session, result)
+    if out_path.exists() and not args.force:
+        # Show diff-summary so the operator knows what they'd be
+        # destroying — same-shape as `git commit --amend` requiring
+        # explicit intent on already-pushed commits.
+        try:
+            existing_lines = sum(1 for _ in out_path.open(encoding="utf-8"))
+        except OSError:
+            existing_lines = -1
+        new_total_lines = 1 + len(result.messages)  # header + turns
+        print(
+            f"swarph import: target {out_path} already exists "
+            f"({existing_lines} existing lines vs {new_total_lines} would-be lines).\n"
+            f"Refuse-with-error default protects swarph-continuation turns "
+            f"added since the prior import.\n"
+            f"To proceed:\n"
+            f"  --force                  overwrite (destroys continuation turns)\n"
+            f"  --target-session NAME    write to a different file",
+            file=sys.stderr,
+        )
+        return 3
+
+    _write_swarph_native_session(out_path, result)
+    print(f"\nwrote swarph-native session: {out_path}", file=sys.stderr)
+    return 0

{swarph_cli-0.1.1 → swarph_cli-0.2.0}/src/swarph_cli/main.py

@@ -1,20 +1,20 @@
-"""``swarph`` entry-point — Phase 2 one-shot mode.
-
-v0.0.1 was the scaffold (banner-only). v0.1.0 ships the falsifiability
-gate from PLAN.md §13 Phase 2:
-
-    swarph "explain Hawkes process briefly" --provider gemini --model flash
-
-Subsequent phases extend the CLI:
-- Phase 3:    --ask <peer> mesh-aware one-shot via MeshClient
-- Phase 5:    interactive REPL (``swarph chat``)
-- Phase 5.5:  ``swarph onboard`` + ``swarph ratify``
-- Phase 5.7:  ``swarph daemon`` foreground drain
-- Phase 2.5:  ``swarph import --report-only`` per PLAN.md §17.6 reorder
-
-For now the entry-point handles ONE shape: positional prompt argument
-+ provider/model flags + JSON-mode toggle. argparse subparsers will
-land in Phase 3 when more verbs need their own surface.
+"""``swarph`` entry-point — Phase 2 one-shot + Phase 2.5 import.
+
+v0.0.1 was the scaffold (banner-only). v0.1.0 shipped the Phase 2
+one-shot falsifiability gate. v0.2.0 adds the Phase 2.5 ``import``
+verb per PLAN.md §17.6 forward-reorder.
+
+Verb dispatch shape: if the first arg matches a known verb keyword
+(currently ``import``), the rest of argv is passed to that verb's
+handler. Otherwise argv is treated as the one-shot path (positional
+prompt + flags). Phase 3+ adds ``--ask``, ``list-peers``,
+``list-adapters``; Phase 5 adds ``chat`` REPL; Phase 5.5 adds
+``onboard``/``ratify``; Phase 5.7 adds ``daemon``.
+
+Disambiguation note: a literal one-shot prompt that starts with the
+word "import" (e.g. ``swarph "import this report"``) collides with
+the verb. Workaround: rephrase (``swarph "please import this
+report"``) — the collision is rare and the verb takes precedence.
 """
 
 from __future__ import annotations
@@ -36,19 +36,28 @@ swarph v{version}
 
 Usage:
   swarph "your prompt here" [--provider gemini] [--model gemini-2.5-flash]
+  swarph import <path-to-source-session> [--report-only] [--target-session NAME]
 
 Examples:
   swarph "explain Hawkes process briefly"
   swarph "list 5 tickers" --json
-  swarph "summarise" --provider gemini --model gemini-2.5-pro
+  swarph import ~/.claude/projects/.../X.jsonl --report-only
 
-Status: Phase 2 one-shot mode. REPL (Phase 5), --ask <peer>
-(Phase 3), onboard/ratify (Phase 5.5), daemon (Phase 5.7) and
-import (Phase 2.5) ship in subsequent releases.
+Status: Phase 2 one-shot + Phase 2.5 import ready. REPL (Phase 5),
+--ask <peer> (Phase 3), onboard/ratify (Phase 5.5), daemon (Phase 5.7)
+ship in subsequent releases.
 
 Spec: https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
 """
 
+# Known verb keywords that route to their own handler. Order matters
+# only for disambiguation against one-shot prompts (rare).
+_VERB_HANDLERS: dict[str, str] = {
+    # verb keyword: dotted-path to handler function (lazy-imported)
+    "import": "swarph_cli.commands.import_session.run_import",
+    # Future: "chat", "daemon", "onboard", "ratify", "list-peers", etc.
+}
+
 
 def _build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
@@ -209,7 +218,32 @@ async def _run_one_shot(args: argparse.Namespace) -> int:
     return 0 if resp.error_class is None else 1
 
 
+def _dispatch_verb(verb: str, verb_argv: list[str]) -> int:
+    """Lazy-import the verb's handler and run it.
+
+    Lazy import keeps the one-shot path's import surface minimal —
+    callers who never use ``swarph import`` don't pay the parser
+    package's import cost.
+    """
+    handler_path = _VERB_HANDLERS[verb]
+    module_path, func_name = handler_path.rsplit(".", 1)
+    import importlib
+
+    mod = importlib.import_module(module_path)
+    handler = getattr(mod, func_name)
+    return handler(verb_argv)
+
+
 def main(argv: Optional[list[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Verb dispatch — first positional arg may be a known verb keyword.
+    # If so, route the rest to that verb's handler. Otherwise fall
+    # through to the one-shot path.
+    if argv and argv[0] in _VERB_HANDLERS:
+        return _dispatch_verb(argv[0], argv[1:])
+
     parser = _build_parser()
     args = parser.parse_args(argv)
 

swarph_cli-0.2.0/src/swarph_cli/parsers/__init__.py

@@ -0,0 +1,27 @@
+"""Source-format parsers for ``swarph import``.
+
+v0.1.x ships only the Claude parser (Phase 2.5 build target per
+PLAN.md §17.6). Phase 3.5+ adds gemini-cli + Simon Willison ``llm``;
+Phase 6+ adds chatgpt-export.
+
+Each parser accepts a path and returns a normalized
+:class:`ImportResult` containing:
+
+  - ``messages``: list[swarph_mesh.ChatMessage] — portable turns
+  - ``report``: ImportReport — what was kept, what was dropped, why
+  - ``metadata``: dict — source format, original session id, model, etc.
+
+Parsers are pure (no side effects beyond filesystem read). The
+write step (swarph-native JSONL emission) lives separately so
+``--report-only`` skips it cleanly.
+"""
+
+from __future__ import annotations
+
+from swarph_cli.parsers.claude import (
+    ClaudeParser,
+    ImportReport,
+    ImportResult,
+)
+
+__all__ = ["ClaudeParser", "ImportReport", "ImportResult"]