5dive 0.1.0__tar.gz

5dive-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Internal punch lists (kept local, never committed)
+*_TASKS.md
+
+# OS cruft
+.DS_Store
+Thumbs.db
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Node / Bun (any local UI or tooling working trees)
+node_modules/
+dist/
+build/
+.cache/
+bun.lockb
+
+# Logs
+*.log
+npm-debug.log*
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Recovered or stashed working trees (e.g. the removed ui/ Vite SPA
+# from commit 8932961 — strategic removal; if anyone restores it locally,
+# don't let it accidentally get re-added to the OSS repo)
+/ui/
+
+# transient mutants written by tests/meta/harness-verdict-probe.sh during a
+# `selfcheck --full` / probe sweep. They are deleted on a clean exit; a killed run
+# leaves them behind, and `git add -A` in the same tree would commit them (it did).
+tests/.probe-*
+
+# DIVE-2097: transient mutated build.sh written by
+# tests/build_bundle_self_order_unit.sh. Can't live under tests/.probe-* above —
+# build.sh does `cd "$(dirname "$0")"`, so the mutant must run from a path that
+# still sees src/, i.e. the repo root — but it is the same "deleted on a clean
+# exit, survives a kill, git add -A would commit it" shape as the probe mutants.
+/.dive2097-mutant-build.sh
+
+# DIVE-2091: the built bundle is generated at TAG time by release-cut.yml,
+# never committed on main — a 47k-line generated file on main invalidates every
+# open PR on every merge. install.sh fetches it from the tag's tree.
+/5dive
+/5dive.sha256
+
+# DIVE-3911: python package build output
+python/dist/
+python/src/*.egg-info/

5dive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 5dive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

5dive-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: 5dive
+Version: 0.1.0
+Summary: Python client for the 5dive CLI — read the task queue, agents and org chart of a 5dive box.
+Project-URL: Homepage, https://5dive.ai
+Project-URL: Source, https://github.com/5dive-ai/5dive
+Project-URL: Issues, https://github.com/5dive-ai/5dive/issues
+Author: 5dive
+License: MIT
+License-File: LICENSE
+Keywords: 5dive,agents,automation,cli,multi-agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 5dive
+
+Python client for the [5dive](https://5dive.ai) CLI — read the task queue, agent
+seats and org chart of a 5dive box from Python.
+
+5dive runs a team of AI coding agents on your own machine. State lives on that
+box and the CLI is the interface with a stable contract over it, so this package
+is a thin, dependency-free wrapper over `5dive <verb> --json` rather than an HTTP
+client.
+
+## Install
+
+```bash
+pip install 5dive
+```
+
+The distribution is named `5dive`; the import name is `fivedive`, because a
+Python identifier cannot begin with a digit.
+
+## Use
+
+```python
+from fivedive import FiveDive
+
+fd = FiveDive()
+
+for t in fd.tasks("--status=todo"):
+    print(t["ident"], t["assignee"], t["title"])
+
+print(fd.task("DIVE-3903")["status"])
+
+for a in fd.agents():
+    print(a["name"], a["active"])
+```
+
+Anything the CLI can answer in JSON is reachable, whether or not this package
+has a named helper for it:
+
+```python
+fd.raw("org", "tree")
+fd.raw("task", "ls", "--assignee=main")
+```
+
+## Errors are raised, not returned
+
+Every `--json` verb answers in one envelope:
+
+```json
+{"ok": true,  "data": {...}}
+{"ok": false, "error": {"code": 4, "class": "not_found", "message": "no such task: NOPE-1"}}
+```
+
+An unchecked `ok` is the bug this package exists to prevent, so the false branch
+raises instead of handing back a dict you have to remember to test:
+
+```python
+from fivedive import FiveDive, FiveDiveError, CliNotFound
+
+try:
+    fd.task("NOPE-1")
+except FiveDiveError as e:
+    print(e.err_class, e.code, e)   # not_found 4 no such task: NOPE-1
+```
+
+Branch on `err_class`, not on message text — the class is the stable contract.
+`CliNotFound` is raised when the `5dive` binary is not on `PATH`.
+
+## Requirements
+
+Python 3.9+, no third-party dependencies, and a 5dive box with the CLI
+installed. Get the CLI at [5dive.ai](https://5dive.ai) or
+[github.com/5dive-ai/5dive](https://github.com/5dive-ai/5dive).
+
+## Licence
+
+MIT.

5dive-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 5dive
+
+Python client for the [5dive](https://5dive.ai) CLI — read the task queue, agent
+seats and org chart of a 5dive box from Python.
+
+5dive runs a team of AI coding agents on your own machine. State lives on that
+box and the CLI is the interface with a stable contract over it, so this package
+is a thin, dependency-free wrapper over `5dive <verb> --json` rather than an HTTP
+client.
+
+## Install
+
+```bash
+pip install 5dive
+```
+
+The distribution is named `5dive`; the import name is `fivedive`, because a
+Python identifier cannot begin with a digit.
+
+## Use
+
+```python
+from fivedive import FiveDive
+
+fd = FiveDive()
+
+for t in fd.tasks("--status=todo"):
+    print(t["ident"], t["assignee"], t["title"])
+
+print(fd.task("DIVE-3903")["status"])
+
+for a in fd.agents():
+    print(a["name"], a["active"])
+```
+
+Anything the CLI can answer in JSON is reachable, whether or not this package
+has a named helper for it:
+
+```python
+fd.raw("org", "tree")
+fd.raw("task", "ls", "--assignee=main")
+```
+
+## Errors are raised, not returned
+
+Every `--json` verb answers in one envelope:
+
+```json
+{"ok": true,  "data": {...}}
+{"ok": false, "error": {"code": 4, "class": "not_found", "message": "no such task: NOPE-1"}}
+```
+
+An unchecked `ok` is the bug this package exists to prevent, so the false branch
+raises instead of handing back a dict you have to remember to test:
+
+```python
+from fivedive import FiveDive, FiveDiveError, CliNotFound
+
+try:
+    fd.task("NOPE-1")
+except FiveDiveError as e:
+    print(e.err_class, e.code, e)   # not_found 4 no such task: NOPE-1
+```
+
+Branch on `err_class`, not on message text — the class is the stable contract.
+`CliNotFound` is raised when the `5dive` binary is not on `PATH`.
+
+## Requirements
+
+Python 3.9+, no third-party dependencies, and a 5dive box with the CLI
+installed. Get the CLI at [5dive.ai](https://5dive.ai) or
+[github.com/5dive-ai/5dive](https://github.com/5dive-ai/5dive).
+
+## Licence
+
+MIT.

5dive-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "5dive"
+version = "0.1.0"
+description = "Python client for the 5dive CLI — read the task queue, agents and org chart of a 5dive box."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "5dive" }]
+keywords = ["5dive", "agents", "multi-agent", "cli", "automation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://5dive.ai"
+Source = "https://github.com/5dive-ai/5dive"
+Issues = "https://github.com/5dive-ai/5dive/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fivedive"]

5dive-0.1.0/src/fivedive/__init__.py

@@ -0,0 +1,14 @@
+"""Python client for the 5dive CLI.
+
+The distribution is named ``5dive``; the import name is ``fivedive`` because a
+Python identifier cannot begin with a digit.
+
+    from fivedive import FiveDive
+    for t in FiveDive().tasks():
+        print(t["ident"], t["status"])
+"""
+
+from .client import FiveDive, FiveDiveError, CliNotFound
+
+__all__ = ["FiveDive", "FiveDiveError", "CliNotFound"]
+__version__ = "0.1.0"

5dive-0.1.0/src/fivedive/client.py

@@ -0,0 +1,120 @@
+"""A thin, dependency-free wrapper over the local ``5dive`` CLI's JSON mode.
+
+WHY THIS IS A WRAPPER AND NOT AN HTTP CLIENT: 5dive's state lives on the box the
+agents run on, and the CLI is the only interface with a stable contract over it.
+Every ``--json`` verb answers in one envelope::
+
+    {"ok": true,  "data": {...}}
+    {"ok": false, "error": {"code": 4, "class": "not_found", "message": "..."}}
+
+so the whole job of this module is to run the binary, parse that envelope, and
+raise on the false branch instead of handing back a dict the caller has to
+remember to check. An unchecked ``ok`` is the bug this exists to prevent.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any, Dict, List, Optional, Sequence
+
+
+class FiveDiveError(RuntimeError):
+    """The CLI answered with ``ok: false``.
+
+    Carries the machine-readable fields so callers can branch on ``err_class``
+    rather than matching on message text, which is not a stable contract.
+    """
+
+    def __init__(self, message: str, code: Optional[int] = None, err_class: Optional[str] = None):
+        super().__init__(message)
+        self.code = code
+        self.err_class = err_class
+
+
+class CliNotFound(FiveDiveError):
+    """The ``5dive`` binary is not on PATH."""
+
+
+class FiveDive:
+    """Run 5dive CLI verbs and return parsed JSON.
+
+    :param binary: path to the CLI, if it is not simply ``5dive`` on PATH.
+    :param timeout: seconds before a call is abandoned. ``None`` waits forever,
+        which is rarely what you want from a library.
+    """
+
+    def __init__(self, binary: str = "5dive", timeout: Optional[float] = 30.0):
+        self.binary = binary
+        self.timeout = timeout
+
+    # -- the one place a subprocess is run -------------------------------
+    def raw(self, *args: str) -> Any:
+        """Run ``5dive <args> --json`` and return the ``data`` payload.
+
+        ``--json`` is appended only when the caller has not already passed it,
+        so ``raw("task", "ls", "--json")`` and ``raw("task", "ls")`` agree.
+        """
+        argv: List[str] = [self.binary, *args]
+        if "--json" not in argv:
+            argv.append("--json")
+
+        if shutil.which(self.binary) is None and "/" not in self.binary:
+            raise CliNotFound(f"{self.binary!r} is not on PATH — is this a 5dive box?")
+
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True, timeout=self.timeout)
+        except FileNotFoundError as exc:  # binary named by path, but absent
+            raise CliNotFound(f"cannot execute {self.binary!r}: {exc}") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise FiveDiveError(f"{' '.join(argv)} timed out after {self.timeout}s") from exc
+
+        # A non-zero exit still carries a JSON envelope on the error path, so
+        # parse BEFORE judging the status: the envelope's message is better than
+        # "exited 4", and falling back to stderr only when there is no envelope
+        # keeps a genuine crash legible instead of masking it as a parse error.
+        payload = None
+        if proc.stdout.strip():
+            try:
+                payload = json.loads(proc.stdout)
+            except json.JSONDecodeError:
+                payload = None
+
+        if payload is None:
+            detail = (proc.stderr or proc.stdout or "").strip() or f"exited {proc.returncode}"
+            raise FiveDiveError(f"{' '.join(argv)}: no JSON envelope — {detail}")
+
+        if not payload.get("ok", False):
+            err = payload.get("error") or {}
+            raise FiveDiveError(
+                err.get("message", "unknown error"),
+                code=err.get("code"),
+                err_class=err.get("class"),
+            )
+        return payload.get("data")
+
+    # -- convenience readers ---------------------------------------------
+    def tasks(self, *flags: str) -> List[Dict[str, Any]]:
+        """The task queue. Extra flags pass straight through, e.g.
+        ``tasks("--status=todo", "--assignee=main")``."""
+        data = self.raw("task", "ls", *flags) or {}
+        return data.get("tasks", [])
+
+    def task(self, ident: str) -> Dict[str, Any]:
+        """One task by ident, e.g. ``task("DIVE-3903")``."""
+        return self.raw("task", "show", ident) or {}
+
+    def agents(self, *flags: str) -> List[Dict[str, Any]]:
+        """The agent seats on this box."""
+        data = self.raw("agent", "list", *flags)
+        if isinstance(data, list):
+            return data
+        return (data or {}).get("agents", [])
+
+    def version(self) -> str:
+        """The CLI's version string (does not use the JSON envelope)."""
+        proc = subprocess.run(
+            [self.binary, "--version"], capture_output=True, text=True, timeout=self.timeout
+        )
+        return proc.stdout.strip()

5dive-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+"""Unit arms for the envelope contract. No 5dive binary is required: every arm
+drives the real FiveDive.raw() and fakes only subprocess.run, so the parsing and
+the raising under test are the shipped ones.
+"""
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from fivedive import FiveDive, FiveDiveError, CliNotFound  # noqa: E402
+
+
+def completed(stdout="", stderr="", rc=0):
+    return subprocess.CompletedProcess(args=[], returncode=rc, stdout=stdout, stderr=stderr)
+
+
+class EnvelopeTests(unittest.TestCase):
+    def setUp(self):
+        self.fd = FiveDive()
+        patcher = mock.patch("shutil.which", return_value="/usr/local/bin/5dive")
+        patcher.start()
+        self.addCleanup(patcher.stop)
+
+    def test_ok_true_returns_data(self):
+        env = json.dumps({"ok": True, "data": {"tasks": [{"ident": "DIVE-1"}]}})
+        with mock.patch("subprocess.run", return_value=completed(env)):
+            self.assertEqual(self.fd.tasks(), [{"ident": "DIVE-1"}])
+
+    def test_ok_false_raises_with_machine_fields(self):
+        env = json.dumps(
+            {"ok": False, "error": {"code": 4, "class": "not_found", "message": "no such task: NOPE-1"}}
+        )
+        with mock.patch("subprocess.run", return_value=completed(env, rc=4)):
+            with self.assertRaises(FiveDiveError) as ctx:
+                self.fd.task("NOPE-1")
+        self.assertEqual(ctx.exception.code, 4)
+        self.assertEqual(ctx.exception.err_class, "not_found")
+        self.assertIn("NOPE-1", str(ctx.exception))
+
+    def test_error_envelope_is_read_even_though_exit_is_nonzero(self):
+        """The regression this guards: judging returncode first would report
+        'exited 4' and throw away the message the CLI actually sent."""
+        env = json.dumps({"ok": False, "error": {"code": 4, "class": "not_found", "message": "gone"}})
+        with mock.patch("subprocess.run", return_value=completed(env, stderr="error: gone", rc=4)):
+            with self.assertRaises(FiveDiveError) as ctx:
+                self.fd.raw("task", "show", "X")
+        self.assertEqual(str(ctx.exception), "gone")
+
+    def test_no_envelope_falls_back_to_stderr(self):
+        with mock.patch("subprocess.run", return_value=completed("", "segfault", rc=139)):
+            with self.assertRaises(FiveDiveError) as ctx:
+                self.fd.raw("task", "ls")
+        self.assertIn("segfault", str(ctx.exception))
+
+    def test_json_flag_not_duplicated(self):
+        env = json.dumps({"ok": True, "data": {}})
+        with mock.patch("subprocess.run", return_value=completed(env)) as run:
+            self.fd.raw("task", "ls", "--json")
+        self.assertEqual(run.call_args[0][0].count("--json"), 1)
+
+    def test_missing_binary_raises_cli_not_found(self):
+        with mock.patch("shutil.which", return_value=None):
+            with self.assertRaises(CliNotFound):
+                FiveDive().raw("task", "ls")
+
+    def test_timeout_is_reported_not_swallowed(self):
+        with mock.patch("subprocess.run", side_effect=subprocess.TimeoutExpired(cmd="5dive", timeout=1)):
+            with self.assertRaises(FiveDiveError) as ctx:
+                self.fd.raw("task", "ls")
+        self.assertIn("timed out", str(ctx.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()