codex2opencode 0.1.0__py3-none-any.whl

codex2opencode/errors.py

@@ -0,0 +1,36 @@
+EXIT_OK = 0
+EXIT_OPENCODE_ERROR = 1
+EXIT_TIMEOUT = 2
+EXIT_LOCK_CONFLICT = 3
+EXIT_INVALID_ARGS = 4
+EXIT_STATE_ERROR = 5
+EXIT_STREAM_ERROR = 6
+EXIT_SESSION_ERROR = 7
+
+
+class BridgeError(Exception):
+    exit_code = EXIT_OPENCODE_ERROR
+
+
+class TimeoutError(BridgeError):
+    exit_code = EXIT_TIMEOUT
+
+
+class LockConflictError(BridgeError):
+    exit_code = EXIT_LOCK_CONFLICT
+
+
+class InvalidArgsError(BridgeError):
+    exit_code = EXIT_INVALID_ARGS
+
+
+class StateError(BridgeError):
+    exit_code = EXIT_STATE_ERROR
+
+
+class StreamError(BridgeError):
+    exit_code = EXIT_STREAM_ERROR
+
+
+class SessionError(BridgeError):
+    exit_code = EXIT_SESSION_ERROR

codex2opencode/event_stream.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Iterable, Iterator, TextIO
+
+
+@dataclass(slots=True)
+class StreamSummary:
+    session_id: str | None
+    text_output: str
+    malformed_lines: int
+    event_counts: dict[str, int]
+
+
+def parse_event_lines(lines: Iterable[str]) -> StreamSummary:
+    session_id: str | None = None
+    text_parts: list[str] = []
+    malformed_lines = 0
+    event_counts: dict[str, int] = {}
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            malformed_lines += 1
+            continue
+
+        if not isinstance(event, dict):
+            malformed_lines += 1
+            continue
+
+        event_type = str(event.get("type", "unknown"))
+        event_counts[event_type] = event_counts.get(event_type, 0) + 1
+        if session_id is None:
+            candidate_session_id = event.get("sessionID")
+            if isinstance(candidate_session_id, str):
+                session_id = candidate_session_id
+        part = event.get("part") or {}
+        if event_type == "text" and isinstance(part, dict):
+            text = part.get("text")
+            if isinstance(text, str):
+                text_parts.append(text)
+
+    return StreamSummary(
+        session_id=session_id,
+        text_output="".join(text_parts),
+        malformed_lines=malformed_lines,
+        event_counts=event_counts,
+    )
+
+
+def iter_stream_events(handle: TextIO) -> Iterator[str]:
+    for line in handle:
+        yield line

codex2opencode/locking.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+
+from .errors import LockConflictError
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover
+    fcntl = None
+
+
+@contextmanager
+def acquire_thread_lock(lock_path: Path):
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = lock_path.open("a+", encoding="utf-8")
+    try:
+        if fcntl is None:
+            raise LockConflictError("Locking unsupported on this platform.")
+        try:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as exc:
+            raise LockConflictError("Lock already held.") from exc
+        yield lock_path
+    finally:
+        if fcntl is not None:
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        handle.close()

codex2opencode/logging_utils.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+from .paths import logs_dir
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def append_bridge_log(payload: dict[str, object]) -> None:
+    log_path = logs_dir() / "bridge.log"
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, sort_keys=True) + "\n")
+    except OSError:
+        return

codex2opencode/models.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+from .errors import StateError
+
+
+@dataclass(slots=True)
+class ThreadState:
+    thread_key: str
+    workspace_root: str
+    thread_name: str | None
+    opencode_session_id: str | None
+    opencode_title: str | None
+    created_at: str
+    last_used_at: str
+    last_status: str
+    last_run_mode: str | None
+    bridge_version: str
+    opencode_version: str | None
+    last_error: str | None
+    message_count: int
+    last_exported_at: str | None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, object]) -> "ThreadState":
+        required = {
+            "thread_key",
+            "workspace_root",
+            "thread_name",
+            "opencode_session_id",
+            "opencode_title",
+            "created_at",
+            "last_used_at",
+            "last_status",
+            "last_run_mode",
+            "bridge_version",
+            "opencode_version",
+            "last_error",
+            "message_count",
+            "last_exported_at",
+        }
+        missing = required - set(data.keys())
+        if missing:
+            raise StateError(f"Missing required state fields: {sorted(missing)}")
+
+        def expect_str(value: object, name: str) -> str:
+            if not isinstance(value, str):
+                raise StateError(f"Invalid type for {name}.")
+            return value
+
+        def expect_optional_str(value: object, name: str) -> str | None:
+            if value is None:
+                return None
+            if not isinstance(value, str):
+                raise StateError(f"Invalid type for {name}.")
+            return value
+
+        def expect_int(value: object, name: str) -> int:
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise StateError(f"Invalid type for {name}.")
+            return value
+
+        return cls(
+            thread_key=expect_str(data["thread_key"], "thread_key"),
+            workspace_root=expect_str(data["workspace_root"], "workspace_root"),
+            thread_name=expect_optional_str(data["thread_name"], "thread_name"),
+            opencode_session_id=expect_optional_str(
+                data["opencode_session_id"], "opencode_session_id"
+            ),
+            opencode_title=expect_optional_str(data["opencode_title"], "opencode_title"),
+            created_at=expect_str(data["created_at"], "created_at"),
+            last_used_at=expect_str(data["last_used_at"], "last_used_at"),
+            last_status=expect_str(data["last_status"], "last_status"),
+            last_run_mode=expect_optional_str(data["last_run_mode"], "last_run_mode"),
+            bridge_version=expect_str(data["bridge_version"], "bridge_version"),
+            opencode_version=expect_optional_str(data["opencode_version"], "opencode_version"),
+            last_error=expect_optional_str(data["last_error"], "last_error"),
+            message_count=expect_int(data["message_count"], "message_count"),
+            last_exported_at=expect_optional_str(data["last_exported_at"], "last_exported_at"),
+        )

codex2opencode/opencode_cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+from codex2opencode.errors import InvalidArgsError
+
+
+def build_run_command(
+    prompt: str,
+    cwd: str,
+    session_id: str | None,
+    fork: bool,
+    title: str | None,
+    opencode_bin: str = "opencode",
+) -> list[str]:
+    if fork and not session_id:
+        raise InvalidArgsError("fork requires an existing session id")
+    command = [opencode_bin, "run", prompt, "--format", "json", "--dir", cwd]
+    if session_id:
+        command.extend(["--session", session_id])
+    if fork:
+        command.append("--fork")
+    if title:
+        command.extend(["--title", title])
+    return command
+
+
+def build_export_command(session_id: str, opencode_bin: str = "opencode") -> list[str]:
+    return [opencode_bin, "export", session_id]
+
+
+def build_delete_session_command(session_id: str, opencode_bin: str = "opencode") -> list[str]:
+    return [opencode_bin, "session", "delete", session_id]
+
+
+def _run_command(command: list[str], cwd: str | None = None) -> subprocess.CompletedProcess[str] | None:
+    try:
+        return subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+        )
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+
+
+def read_opencode_version(opencode_bin: str = "opencode", cwd: str | None = None) -> str | None:
+    completed = _run_command([opencode_bin, "--version"], cwd=cwd)
+    if not completed or completed.returncode != 0:
+        return None
+    output = completed.stdout.strip()
+    if not output:
+        return None
+    return output
+
+
+def read_debug_paths(opencode_bin: str = "opencode", cwd: str | None = None) -> str | None:
+    completed = _run_command([opencode_bin, "debug", "paths"], cwd=cwd)
+    if not completed or completed.returncode != 0:
+        return None
+    output = completed.stdout.strip()
+    if not output:
+        return None
+    return output
+
+
+def read_debug_config(opencode_bin: str = "opencode", cwd: str | None = None) -> dict[str, Any] | None:
+    completed = _run_command([opencode_bin, "debug", "config"], cwd=cwd)
+    if not completed or completed.returncode != 0:
+        return None
+    output = completed.stdout.strip()
+    if not output:
+        return None
+    try:
+        parsed = json.loads(output)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    return parsed

codex2opencode/paths.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .errors import InvalidArgsError
+
+
+def bridge_root() -> Path:
+    override = os.environ.get("CODEX2OPENCODE_HOME")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".codex" / "codex2opencode"
+
+
+def threads_dir() -> Path:
+    return bridge_root() / "threads"
+
+
+def runs_dir() -> Path:
+    return bridge_root() / "runs"
+
+
+def logs_dir() -> Path:
+    return bridge_root() / "logs"
+
+
+def _validate_thread_key(thread_key: str) -> None:
+    if not thread_key or thread_key.strip() == "":
+        raise InvalidArgsError("Thread key must be non-empty.")
+    if os.sep in thread_key:
+        raise InvalidArgsError("Thread key contains path separators.")
+    if os.altsep and os.altsep in thread_key:
+        raise InvalidArgsError("Thread key contains path separators.")
+    if thread_key in {".", ".."} or ".." in thread_key:
+        raise InvalidArgsError("Thread key contains invalid segments.")
+
+
+def thread_file_path(thread_key: str) -> Path:
+    _validate_thread_key(thread_key)
+    return threads_dir() / f"{thread_key}.json"
+
+
+def lock_file_path(thread_key: str) -> Path:
+    _validate_thread_key(thread_key)
+    return threads_dir() / f"{thread_key}.lock"

codex2opencode/state.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .errors import StateError
+from .models import ThreadState
+
+
+def save_thread_state(path: Path, state: ThreadState) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temp_path = path.with_suffix(".tmp")
+        temp_path.write_text(
+            json.dumps(state.to_dict(), indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        temp_path.replace(path)
+    except OSError as exc:
+        raise StateError(f"Failed to write state to {path}: {exc}") from exc
+
+
+def load_thread_state(path: Path) -> ThreadState:
+    try:
+        raw = path.read_text(encoding="utf-8")
+        payload = json.loads(raw)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise StateError(f"Failed to read state from {path}.") from exc
+    if not isinstance(payload, dict):
+        raise StateError(f"Invalid state payload in {path}.")
+    return ThreadState.from_dict(payload)

codex2opencode/threading.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+def resolve_workspace_root(workspace_root: str) -> str:
+    return str(Path(workspace_root).expanduser().resolve())
+
+
+def make_thread_key(workspace_root: str, thread_name: str | None) -> str:
+    payload = {
+        "workspace_root": resolve_workspace_root(workspace_root),
+        "thread_name": thread_name,
+    }
+    encoded = json.dumps(payload, sort_keys=True).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()

codex2opencode/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

codex2opencode-0.1.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: codex2opencode
+Version: 0.1.0
+Summary: Local Codex-to-Opencode bridge CLI
+Author: OpenAI Codex
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# codex2opencode
+
+`codex2opencode` is a local one-way bridge from Codex to Opencode.
+
+It provides:
+
+- a reusable Python CLI bridge
+- Opencode session persistence via native `sessionID`
+- deterministic per-thread locking
+- export-backed session verification
+- a thin Codex skill wrapper surface
+- no non-stdlib Python runtime dependency inside the bridge
+
+Current implementation target:
+
+- macOS / POSIX environments with Python 3 and local Opencode CLI access
+- not designed for Windows in its current `fcntl`-based form
+
+## Current Status
+
+Implemented and locally verified in this repository:
+
+- `ask`
+- `status`
+- `forget`
+- `gc`
+- `doctor`
+- automatic resume via stored Opencode `sessionID`
+- Opencode-native `--fork`
+- Opencode-native `--title`
+- same-thread lock conflict handling
+
+Primary verification commands:
+
+- `PYTHONPATH=bridge python3 -m unittest discover -s tests -p 'test_*.py' -v`
+- direct `codex2opencode ask ...` smoke
+- direct `codex2opencode doctor ...` smoke
+- opt-in real Opencode smoke when local auth is available
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e .
+```
+
+When a PyPI release is available:
+
+```bash
+python3 -m pip install codex2opencode
+```
+
+You can also run it directly without installing:
+
+```bash
+PYTHONPATH=bridge python3 -m codex2opencode ask --prompt "Reply with ok only" --workspace "$PWD"
+```
+
+After editable install, both of these work:
+
+```bash
+python -m codex2opencode --help
+codex2opencode --help
+```
+
+## Usage
+
+Ask Opencode in the current workspace thread:
+
+```bash
+codex2opencode ask --prompt "Review this design" --workspace "$PWD"
+```
+
+Successful `ask` output begins with a one-line metadata header before the reply body, for example:
+
+```text
+[oc provider=opencode model=mimo-v2-omni-free session=ses_...]
+```
+
+If session verification fails after a successful run, the bridge still prints the reply plus a minimal header with the session id, then exits non-zero.
+
+Use a named thread:
+
+```bash
+codex2opencode ask --prompt "Continue the review" --workspace "$PWD" --thread review
+```
+
+Force a fresh session:
+
+```bash
+codex2opencode ask --prompt "Start over" --workspace "$PWD" --new
+```
+
+Fork the current mapped Opencode session:
+
+```bash
+codex2opencode ask --prompt "Take this in a different direction" --workspace "$PWD" --fork
+```
+
+Set an Opencode title on creation or fork:
+
+```bash
+codex2opencode ask --prompt "Review the release checklist" --workspace "$PWD" --new --title "release-review"
+```
+
+Inspect stored thread state:
+
+```bash
+codex2opencode status --workspace "$PWD"
+```
+
+Run diagnostics:
+
+```bash
+codex2opencode doctor --workspace "$PWD"
+```
+
+Forget the current thread and delete the mapped Opencode session:
+
+```bash
+codex2opencode forget --workspace "$PWD"
+```
+
+Remove stale bridge-owned files:
+
+```bash
+codex2opencode gc --max-age-days 7
+```
+
+## Threading Model
+
+By default, one workspace maps to one Opencode thread.
+
+Use `--thread <name>` to split conversations inside the same repo:
+
+```bash
+codex2opencode ask --prompt "Review API design" --workspace "$PWD" --thread api
+codex2opencode ask --prompt "Review docs tone" --workspace "$PWD" --thread docs
+```
+
+Use `--new` when you want a fresh Opencode session for the selected thread key.
+
+Use `--fork` when you want Opencode to branch from the current mapped session instead of starting unrelated context. `--new` and `--fork` are intentionally mutually exclusive.
+
+## Codex Skill
+
+The Codex-facing wrapper lives at:
+
+```text
+skills/codex-to-opencode/SKILL.md
+```
+
+The skill should stay thin. It should only:
+
+- collect the user prompt
+- choose default thread, named thread, `--new`, or `--fork`
+- invoke `codex2opencode`
+- return stdout or surface stderr
+
+It must not own JSONL parsing, session storage, retries, export verification, or custom lock handling.
+
+Recommended high-signal trigger phrases:
+
+- `Use the codex-to-opencode skill`
+- `ask Opencode about this`
+- `ask oc about this`
+- `send this to Opencode`
+- `send this to oc`
+- `let Opencode review this`
+- `let oc review this`
+- `give this to Opencode`
+- `给 Opencode 看看`
+- `给oc看看`
+- `让 Opencode review 一下`
+- `让oc review一下`
+- `问问 Opencode`
+- `问问oc`
+
+Treat `oc` as a supported short alias for `Opencode` when it appears with a clear action.
+Avoid relying on bare `opencode` by itself.
+Avoid relying on bare `oc` by itself.
+Trigger phrases should include a clear action like ask, review, check, continue, send, or look.
+
+Practical everyday examples:
+
+- `问问oc这个方案哪里最危险`
+- `给oc看看这个 diff`
+- `让oc review一下发布流程`
+- `发给oc继续聊这个线程`
+- `ask oc to review this design`
+
+## Activation Scope
+
+These paths are expected to work:
+
+- new Codex sessions started after the skill was installed
+- `codex exec` runs started after the skill was installed
+- direct `codex2opencode` CLI usage
+
+Do not assume already-open Codex sessions will hot-reload newly installed or updated skills.
+
+If you changed trigger phrases or installed the skill during an existing session, restart Codex or open a fresh session before testing.
+
+## Troubleshooting
+
+If a trigger phrase does not route to Opencode:
+
+1. Start a new Codex session.
+2. Test with a high-signal phrase such as `Use the codex-to-opencode skill. Ask Opencode: reply with ok only.`
+3. Verify the bridge directly with `codex2opencode ask --prompt "Reply with ok only" --workspace "$PWD"`.
+4. Run `codex2opencode doctor --workspace "$PWD"` to confirm Opencode availability, debug-path output, and thread-state diagnostics.
+
+If direct CLI usage works but a natural-language trigger does not, the issue is skill discovery in that session, not the bridge itself.
+
+If `doctor` reports an `orphaned` thread state, the local mapping points at an Opencode session that no longer exports successfully. `forget` will remove that mapping and attempt remote deletion again.
+
+## Environment
+
+- `CODEX2OPENCODE_OPENCODE_BIN`: override the Opencode executable path
+- `CODEX2OPENCODE_HOME`: override the bridge state root without changing your real shell `HOME`
+- `CODEX2OPENCODE_RUN_REAL=1`: enable opt-in real Opencode integration tests
+
+## Doctor Output
+
+`codex2opencode doctor --workspace "$PWD"` prints JSON and checks:
+
+- the resolved bridge root and key paths
+- whether `opencode --version` is readable
+- whether `opencode debug paths` is readable
+- whether `opencode debug config` is parseable
+- whether the selected thread state is `missing`, `ok`, `error`, or `orphaned`
+- whether the mapped session can still be verified through `opencode export`
+- whether the selected lock path is healthy or currently locked
+
+It returns `0` when required checks are healthy and non-zero when Opencode availability checks fail, the state file is corrupted, or the mapped session is orphaned.
+
+## State Layout
+
+Default bridge state root:
+
+```text
+~/.codex/codex2opencode/
+  threads/
+  runs/
+  logs/
+```
+
+Key files:
+
+- `threads/<thread_key>.json`: current thread state
+- `threads/<thread_key>.lock`: per-thread lock file
+- `runs/<thread_key>/*.json`: per-run artifacts
+- `logs/bridge.log`: append-only JSONL bridge events
+
+## Boundaries
+
+This repository is intentionally narrow:
+
+- one-way Codex-to-Opencode only
+- no Claude orchestration here
+- no roundtable or multi-model discussion system
+- no bridge-owned retry orchestration
+- no over-generalized multi-backend framework
+
+For design rationale and internals, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+For developer workflow, see [DEVELOPMENT.md](./DEVELOPMENT.md).
+For contribution and release details, see [CONTRIBUTING.md](./CONTRIBUTING.md).