opencontextengine-client 0.1.0__py3-none-any.whl

oce_client/state.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+from .models import FileRecord, FileStatus, WorkspaceSnapshot
+
+
+class SQLiteStateStore:
+    """Durable workspace state with an outbox-friendly transactional boundary."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(
+            str(self.path), timeout=30.0, check_same_thread=False
+        )
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA busy_timeout=30000")
+        self._init_schema()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    def _init_schema(self) -> None:
+        with self._lock, self._conn:
+            self._conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS meta (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL
+                );
+                CREATE TABLE IF NOT EXISTS files (
+                    path TEXT PRIMARY KEY,
+                    blob_name TEXT,
+                    committed_blob_name TEXT,
+                    status TEXT NOT NULL,
+                    content TEXT,
+                    size INTEGER NOT NULL DEFAULT 0,
+                    mtime_ns INTEGER,
+                    source TEXT NOT NULL DEFAULT 'filesystem',
+                    generation INTEGER NOT NULL DEFAULT 0,
+                    skip_reason TEXT
+                );
+                CREATE TABLE IF NOT EXISTS outbox_operations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    kind TEXT NOT NULL,
+                    payload TEXT NOT NULL,
+                    status TEXT NOT NULL DEFAULT 'pending',
+                    attempts INTEGER NOT NULL DEFAULT 0,
+                    last_error TEXT,
+                    created_at REAL NOT NULL
+                );
+                """
+            )
+
+    @contextmanager
+    def transaction(self) -> Iterator[sqlite3.Connection]:
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                yield self._conn
+            except Exception:
+                self._conn.rollback()
+                raise
+            else:
+                self._conn.commit()
+
+    def get_meta(self, key: str) -> str | None:
+        row = self._conn.execute("SELECT value FROM meta WHERE key = ?", (key,)).fetchone()
+        return None if row is None else str(row["value"])
+
+    def set_meta(self, key: str, value: str | None) -> None:
+        with self.transaction() as conn:
+            if value is None:
+                conn.execute("DELETE FROM meta WHERE key = ?", (key,))
+            else:
+                conn.execute(
+                    "INSERT INTO meta(key, value) VALUES (?, ?) "
+                    "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                    (key, value),
+                )
+
+    def load_snapshot(self) -> WorkspaceSnapshot:
+        rows = self._conn.execute(
+            "SELECT path, blob_name, committed_blob_name, status, "
+            "CASE WHEN source = 'explicit' THEN content ELSE NULL END AS content, "
+            "size, mtime_ns, source, generation, skip_reason "
+            "FROM files ORDER BY path"
+        ).fetchall()
+        files = {
+            row["path"]: FileRecord(
+            path=row["path"],
+            blob_name=row["blob_name"],
+            status=FileStatus(row["status"]),
+            committed_blob_name=row["committed_blob_name"],
+            content=row["content"],
+                size=row["size"],
+                mtime_ns=row["mtime_ns"],
+                source=row["source"],
+                generation=row["generation"],
+            )
+            for row in rows
+        }
+        return WorkspaceSnapshot(
+            files=files,
+            checkpoint_id=self.get_meta("checkpoint_id"),
+            generation=int(self.get_meta("generation") or "0"),
+        )
+
+    def load_file_rows(self) -> list[sqlite3.Row]:
+        return self._conn.execute(
+            "SELECT path, blob_name, committed_blob_name, status, size, mtime_ns, "
+            "source, generation, skip_reason FROM files ORDER BY path"
+        ).fetchall()
+
+    def load_file_content(self, path: str) -> str | None:
+        row = self._conn.execute(
+            "SELECT content FROM files WHERE path = ?",
+            (path,),
+        ).fetchone()
+        if row is None or row["content"] is None:
+            return None
+        return str(row["content"])
+
+    def upsert_file(self, record: FileRecord, *, committed_blob_name: str | None = None) -> None:
+        with self.transaction() as conn:
+            existing = conn.execute(
+                "SELECT committed_blob_name FROM files WHERE path = ?", (record.path,)
+            ).fetchone()
+            committed = (
+                committed_blob_name
+                if committed_blob_name is not None
+                else (existing["committed_blob_name"] if existing else None)
+            )
+            conn.execute(
+                """INSERT INTO files
+                   (path, blob_name, committed_blob_name, status, content, size,
+                    mtime_ns, source, generation, skip_reason)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                   ON CONFLICT(path) DO UPDATE SET
+                     blob_name=excluded.blob_name,
+                     committed_blob_name=COALESCE(excluded.committed_blob_name, files.committed_blob_name),
+                     status=excluded.status, content=excluded.content,
+                     size=excluded.size, mtime_ns=excluded.mtime_ns,
+                     source=excluded.source, generation=excluded.generation""",
+                (
+                    record.path,
+                    record.blob_name,
+                    committed,
+                    record.status.value,
+                    record.content,
+                    record.size,
+                    record.mtime_ns,
+                    record.source,
+                    record.generation,
+                    None,
+                ),
+            )
+
+    def apply_file_changes(
+        self,
+        records: list[FileRecord],
+        deleted_paths: list[str],
+        generation: int,
+    ) -> None:
+        with self.transaction() as conn:
+            conn.executemany(
+                """INSERT INTO files(path, blob_name, committed_blob_name, status,
+                   content, size, mtime_ns, source, generation, skip_reason)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                   ON CONFLICT(path) DO UPDATE SET blob_name=excluded.blob_name,
+                   status=excluded.status, content=excluded.content,
+                   size=excluded.size, mtime_ns=excluded.mtime_ns,
+                   source=excluded.source, generation=excluded.generation""",
+                [
+                    (
+                        record.path,
+                        record.blob_name,
+                        None,
+                        record.status.value,
+                        record.content,
+                        record.size,
+                        record.mtime_ns,
+                        record.source,
+                        generation,
+                        None,
+                    )
+                    for record in records
+                ],
+            )
+            if deleted_paths:
+                conn.executemany(
+                    "UPDATE files SET status = ?, blob_name = NULL, content = NULL, "
+                    "source = 'filesystem', generation = ? WHERE path = ?",
+                    [
+                        (FileStatus.DELETED.value, generation, path)
+                        for path in deleted_paths
+                    ],
+                )
+            conn.execute(
+                "INSERT INTO meta(key,value) VALUES('generation',?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (str(generation),),
+            )
+
+    def mark_missing_paths(self, paths: list[str], generation: int) -> None:
+        if not paths:
+            return
+        with self.transaction() as conn:
+            conn.executemany(
+                "UPDATE files SET status = ?, blob_name = NULL, content = NULL, generation = ? "
+                "WHERE path = ? AND source != 'explicit'",
+                [(FileStatus.DELETED.value, generation, path) for path in paths],
+            )
+
+    def mark_deleted_paths(self, paths: list[str], generation: int) -> None:
+        if not paths:
+            return
+        with self.transaction() as conn:
+            conn.executemany(
+                "UPDATE files SET status = ?, blob_name = NULL, content = NULL, "
+                "source = 'filesystem', generation = ? WHERE path = ?",
+                [(FileStatus.DELETED.value, generation, path) for path in paths],
+            )
+
+    def commit_sync(
+        self,
+        checkpoint_id: str,
+        deleted_paths: list[str],
+        generation: int,
+    ) -> None:
+        with self.transaction() as conn:
+            conn.execute("UPDATE files SET committed_blob_name = blob_name WHERE status = 'present'")
+            conn.execute("UPDATE files SET content = NULL WHERE source = 'filesystem'")
+            if deleted_paths:
+                conn.executemany("DELETE FROM files WHERE path = ?", [(p,) for p in deleted_paths])
+            conn.execute(
+                "INSERT INTO meta(key,value) VALUES('checkpoint_id',?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (checkpoint_id,),
+            )
+            conn.execute(
+                "INSERT INTO meta(key,value) VALUES('generation',?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (str(generation),),
+            )
+            conn.execute(
+                "INSERT INTO meta(key,value) VALUES('synced_generation',?) "
+                "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+                (str(generation),),
+            )
+
+    def add_outbox(self, kind: str, payload: dict[str, object]) -> int:
+        with self.transaction() as conn:
+            cursor = conn.execute(
+                "INSERT INTO outbox_operations(kind,payload,created_at) VALUES(?,?,?)",
+                (kind, json.dumps(payload, separators=(",", ":")), time.time()),
+            )
+            return int(cursor.lastrowid)
+
+    def update_outbox(self, operation_id: int, status: str, error: str | None = None) -> None:
+        with self.transaction() as conn:
+            conn.execute(
+                "UPDATE outbox_operations SET status=?, attempts=attempts+1, last_error=? WHERE id=?",
+                (status, error, operation_id),
+            )
+
+    def pending_outbox(self) -> list[sqlite3.Row]:
+        return self._conn.execute(
+            "SELECT * FROM outbox_operations WHERE status != 'complete' ORDER BY id"
+        ).fetchall()
+
+    def supersede_pending(self) -> None:
+        """Mark older attempts as superseded before a fresh sync is planned."""
+        with self.transaction() as conn:
+            conn.execute(
+                "UPDATE outbox_operations SET status = 'superseded' "
+                "WHERE status IN ('pending', 'failed')"
+            )

oce_client/watcher.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+from watchfiles import Change, watch
+
+
+_INTERNAL_DIRECTORIES = {".git", ".oce-client"}
+
+
+def _is_relevant(path: str) -> bool:
+    return _INTERNAL_DIRECTORIES.isdisjoint(Path(path).parts)
+
+
+class WatchHandle:
+    def __init__(
+        self,
+        root: Path,
+        callback: Callable[[set[Path]], None],
+        debounce_ms: int = 300,
+    ) -> None:
+        self._root = root
+        self._callback = callback
+        self._debounce_ms = debounce_ms
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name="oce-client-watcher", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        try:
+            changes = watch(
+                self._root,
+                stop_event=self._stop,
+                debounce=self._debounce_ms,
+                yield_on_timeout=False,
+            )
+            for batch in changes:
+                if self._stop.is_set():
+                    return
+                relevant = {
+                    Path(path)
+                    for _change, path in batch
+                    if _is_relevant(path)
+                }
+                if relevant:
+                    self._callback(relevant)
+        except (OSError, RuntimeError):
+            # The owning context remains usable; a later explicit reconcile can recover.
+            return
+
+    def stop(self) -> None:
+        self._stop.set()
+
+    def join(self, timeout: float | None = None) -> None:
+        self._thread.join(timeout)

opencontextengine_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: opencontextengine-client
+Version: 0.1.0
+Summary: Standalone workspace and blob synchronization client for OpenContextEngine
+Project-URL: Homepage, https://github.com/oce-ai/oce-client
+Project-URL: Repository, https://github.com/oce-ai/oce-client
+Project-URL: Documentation, https://github.com/oce-ai/oce-client/blob/master/README.md
+Project-URL: Issues, https://github.com/oce-ai/oce-client/issues
+Author: OpenContextEngine Contributors
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai,code,context,mcp,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: watchfiles>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# opencontextengine-client
+
+Standalone synchronous Python client for OpenContextEngine workspace and blob
+management. The package owns local inventory, ignore rules, upload planning,
+checkpoint state, and retrieval adapters. It does not depend on Auggie SDK.
+
+Install the distribution package with `uv add opencontextengine-client` (or
+`pip install opencontextengine-client`). The installed command remains
+`oce-client`.
+
+## Version Information
+
+Run `oce-client --version` to print the installed client version.
+
+| Item | Value |
+| --- | --- |
+| PyPI distribution | `opencontextengine-client` |
+| Python package | `oce_client` |
+| CLI | `oce-client` |
+| MCP server | `oce-client-mcp` (separate interface) |
+| Version command | `oce-client --version` |
+
+The authoritative version is declared in `pyproject.toml` and mirrored by
+`oce_client.__version__`.
+
+## Release Preparation
+
+The first release uses the current version because the repository has no
+release tag yet:
+
+```powershell
+uv run python scripts/release.py 0.1.0 --dry-run
+uv run python scripts/release.py 0.1.0
+```
+
+For later releases, use `major`, `minor`, `patch`, or an exact higher version.
+The script updates version metadata, generates the changelog, builds the
+package, creates a release commit, and creates an annotated tag locally. It
+never pushes or publishes automatically; review the result before pushing the
+branch and tag.
+
+## CLI
+
+Install the package with `uv` and configure the service endpoint and key through
+the environment:
+
+```powershell
+# These are the built-in defaults; override them only when needed.
+$env:OCE_API_URL = "http://127.0.0.1:8986"
+$env:OCE_API_KEY = "sk-opencontextengine"
+$env:OCE_WORKSPACE = (Get-Location).Path
+uv run oce-client sync
+uv run oce-client retrieve "where is request authentication implemented?"
+```
+
+If unset, `OCE_API_URL` defaults to `http://127.0.0.1:8986` and `OCE_API_KEY`
+defaults to `sk-opencontextengine`. `status` is local-only and does not require
+an API key. `observe` and `remove`
+stage explicit editor changes in SQLite; run `sync` to publish them. Add
+`--json` to `sync`, `status`, `retrieve`, `observe`, or `remove` for
+machine-readable output. CLI options are placed before the subcommand, for
+example `oce-client --root C:\src\project sync`; `--root` falls back to
+`OCE_WORKSPACE`, and `--api-url`, `--state-path`, and repeated `--ignore`
+override `OCE_API_URL`, `OCE_STATE_PATH`, and `OCE_IGNORE`.
+
+The two interfaces have different lifecycles:
+
+| Interface | Workspace selection | State selection | Index lifecycle |
+| --- | --- | --- | --- |
+| CLI | one `--root` or `OCE_WORKSPACE` | `--state-path` or `OCE_STATE_PATH` | explicit `sync`, optional `watch` |
+| MCP | repeated `--workspace`, `OCE_WORKSPACE`, or `OCE_WORKSPACES` | one `--state-path`, or per-workspace `--state-dir` | process-owned background and incremental sync |
+
+## MCP
+
+Install the optional MCP extra and expose the stdio server to an MCP host:
+
+```powershell
+uv sync --extra mcp
+uv run oce-client-mcp --workspace C:\path\to\workspace
+```
+
+The server exposes one tool, `codebase-retrieval`. Workspace indexing belongs
+to the MCP process rather than the coding agent: the server starts the initial
+index in the background, watches the filesystem, and synchronizes only changed
+paths. Unchanged files are identified by stored filesystem metadata and are not
+read or rehashed on restart.
+
+Declare each allowed workspace with a repeated `--workspace` argument. With one
+workspace, the tool's `workspace_folder` input is optional. With multiple
+workspaces it is required and must exactly match an allowed path. Other paths
+are rejected. For an environment-only setup, use `OCE_WORKSPACE` for one path
+or `OCE_WORKSPACES` with paths separated by the platform path separator. MCP
+does not fall back to the process current directory.
+
+```powershell
+oce-client-mcp `
+  --workspace C:\src\project-a `
+  --workspace C:\src\project-b `
+  --state-dir $env:LOCALAPPDATA\oce-client `
+  --initial-sync background `
+  --debounce-ms 500 `
+  --ready-timeout 3
+```
+
+`--initial-sync` accepts `background` (default), `blocking`, or `off`; `off`
+defers initialization until the first retrieval call. A tool call waits up to
+`--ready-timeout` seconds for the latest observed filesystem generation. Its
+result status is `ready`, `indexing`, or `error`; only a `ready` result contains
+retrieval context. `OCE_API_URL`, `OCE_API_KEY`, `OCE_STATE_PATH`, `OCE_STATE_DIR`, `OCE_IGNORE`,
+`OCE_DEBOUNCE_MS`, `OCE_INITIAL_SYNC`, `OCE_READY_TIMEOUT`, and
+`OCE_LOG_LEVEL` provide environment equivalents. `--state-path` and
+`OCE_STATE_PATH` are for one workspace; use `--state-dir` or `OCE_STATE_DIR`
+for multiple workspaces. Keep the API key in the environment rather than
+command arguments.
+
+The service endpoint, API key, and ignore patterns are shared through the same
+environment variables. State selection follows the interface table above. A
+Codex-ready skill with the host configuration and command guidance is included
+at `skills/oce-client/SKILL.md`.
+
+After installing a wheel, locate or install that skill with:
+
+```powershell
+uv run oce-client skill path
+uv run oce-client skill install
+```
+
+The default installation target is `$CODEX_HOME/skills/oce-client` or
+`$HOME/.codex/skills/oce-client`. Existing skill directories are preserved;
+pass `--force` only when intentionally updating one.
+
+Keep `OCE_API_KEY` in the host's environment or secret manager; do not commit it
+to an MCP configuration file.

opencontextengine_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+oce_client/__init__.py,sha256=askZ-UkmsiCUu7UJgPSUpxmPU5gqk-MaRyTU33XlG7I,897
+oce_client/cli.py,sha256=BLwezugvBw481yn3kF82oNcHZUIBmWjVrmpCVuKxf1I,9763
+oce_client/context.py,sha256=-p5oEUEuGKdUt36Mie7ts225ZOT8wF0VEmwoKJ7L6fo,19337
+oce_client/defaults.py,sha256=eUFMJjvIBtYpaaJCgU9Fhs7Wq-NTK-arMAB5BHeq_oI,83
+oce_client/filesystem.py,sha256=9ztsNiNRM8GzqyyLUsUiaFDcJTzYboR8_pwEQMLObo8,2245
+oce_client/http.py,sha256=YclxR1litwM7ILwe0XvLZbozJ-0kfBJnRjv-XRflp0o,4505
+oce_client/identity.py,sha256=3LXllaDhn-_SwVKOi7xR7yKB-lvIeMNWkKSwm-OxTto,586
+oce_client/ignore.py,sha256=U-w23UF68fqXcvxUFCuNtOg1aUVxm_y28gs_WkhYH80,2695
+oce_client/indexer.py,sha256=uKWAkrVYEKOCycCw-fSTyzxo0gZ1xLcoA0G03eWXqKA,9742
+oce_client/mcp_server.py,sha256=by8NkBA5Klyl2COetr1G8SiZAHsc-Vc_u9BPQZKGwJU,10743
+oce_client/models.py,sha256=hqR1i96rMWp93MMfRcHgrtTXnz-Q5Bs5K_aVI9Tx83E,2154
+oce_client/ports.py,sha256=y0v4l9c3nL7f0xCTef1wzFyaD6duR8bMaT5uxbYQBWA,1589
+oce_client/runtime.py,sha256=LsUMJG2Aw16bXHxr3xzwFkfPzYVegUadVl5Eb_6cHIY,8836
+oce_client/state.py,sha256=RR2Burbr8eJhHkA7dOEEga8a02Nd7Dx1mUaBsE9hUfs,11484
+oce_client/watcher.py,sha256=O56ScabFJ4vZTmd2QJrNzEloBNWV-xR45XR_5FzWQTs,1611
+oce_client/skill/SKILL.md,sha256=aI_bPGkBimvvOWUc81X6SC_E6L6hysuU15D-xeo6jAA,5516
+oce_client/skill/agents/openai.yaml,sha256=YymbN6Lq_e2BmxNM_DdOkNH4AC1w-V1cUO7R6xygv6Y,185
+opencontextengine_client-0.1.0.dist-info/METADATA,sha256=XOp3yP-1McARp7d7HyQw2NSom8LVmTSAz6dqeNK_6RU,6690
+opencontextengine_client-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+opencontextengine_client-0.1.0.dist-info/entry_points.txt,sha256=CoPgl3vSqrnBjEXs9iCS2JzUgdemWOPqtkxTPvQyuXU,95
+opencontextengine_client-0.1.0.dist-info/licenses/LICENSE,sha256=15ZzNvM0vOxXaFSjkXd36R7eJXymssYNJH3UvjTfe_o,11341
+opencontextengine_client-0.1.0.dist-info/RECORD,,

opencontextengine_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opencontextengine_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+oce-client = oce_client.cli:main
+oce-client-mcp = oce_client.mcp_server:main