hftracer 0.1.0__tar.gz

hftracer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,119 @@
+name: CI and release
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.11.2"
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync ty check
+      - run: uv run --no-sync pytest
+      - run: uv build
+
+  release:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: checks
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release-please
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      actions: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      sha: ${{ steps.release.outputs.sha }}
+    steps:
+      - uses: googleapis/release-please-action@v5
+        id: release
+        with:
+          target-branch: main
+      - name: Run checks for the release PR
+        if: steps.release.outputs.pr != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_PR: ${{ steps.release.outputs.pr }}
+        run: gh workflow run ci.yml --ref "$(jq -r .headBranchName <<< "$RELEASE_PR")"
+
+  build:
+    if: needs.release.outputs.release_created == 'true'
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ needs.release.outputs.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.11.2"
+          enable-cache: true
+      - run: uv sync --locked --no-dev
+      - run: uv build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          version: "0.11.2"
+          enable-cache: false
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - run: uv publish --trusted-publishing always
+
+  github:
+    needs: [release, build, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+      - name: Attach distributions to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ needs.release.outputs.tag_name }}
+        run: gh release upload "$RELEASE_TAG" dist/*

hftracer-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.idea/

hftracer-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

hftracer-0.1.0/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.1.0"}

hftracer-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (2026-10-27)
+
+
+### Features
+
+* add private bucket session sync ([a394504](https://github.com/twangodev/hftracer/commit/a39450451cffbbc3709230c3d472f853ef7a1f77))
+
+
+### Documentation
+
+* simplify description and organize readme ([5ef9e09](https://github.com/twangodev/hftracer/commit/5ef9e097480b95d0790780359b495ec008eb81c1))
+* simplify readme and add Shields.io badges ([9566b87](https://github.com/twangodev/hftracer/commit/9566b87fcc5ac8bf53c6dd1d5ffa542b0b5ac827))
+* trim readme badges and development section ([4390d6a](https://github.com/twangodev/hftracer/commit/4390d6af8a96a64d6849e718aea9530e685126f8))

hftracer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Usage & development
+
+## Usage
+
+| Command | Behavior |
+| --- | --- |
+| `hftracer init` | Prompt for a private bucket; default: `<username>/traces` |
+| `hftracer init --bucket namespace/name` | Configure without prompting |
+| `hftracer sync` | Upload new and changed files with HF progress bars |
+| `hftracer sync --dry-run` | Preview counts and transfer sizes |
+| `hftracer sync --preview` | Alias for `--dry-run` |
+
+- Authentication: existing HF login or `HF_TOKEN`.
+- Configuration: `$XDG_CONFIG_HOME/hftracer/config.json`; default: `~/.config/hftracer/config.json`.
+- Remote paths: `devices/<device>/codex/{sessions,archived_sessions}/` and `devices/<device>/claude/projects/`.
+- Device identity persists across setup runs. Keep each device's config separate.
+- All files, including hidden and supporting files, are included unchanged.
+- HF compares size and modification time. Same-size changes with unchanged timestamps may be skipped.
+- Uploads finalize in batches. Ctrl+C preserves finalized files; the current batch may need retrying.
+- Re-run after active sessions finish for a settled copy.
+- Missing sources are skipped. Transfer failures return a nonzero exit code.
+- Schedule externally with cron, systemd timers, or a Docker scheduler.
+
+## Development
+
+```sh
+uv sync --locked
+uv run pytest
+uv run ty check
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+Tests use synthetic files and mocked HF calls. Live checks are described in
+[manual integration](tests/manual-integration.md).
+
+Use focused Conventional Commits, such as `feat: ...`, `fix: ...`, `docs: ...`,
+and `ci: ...`.

hftracer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Ding
+
+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.

hftracer-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.5
+Name: hftracer
+Version: 0.1.0
+Summary: Synchronize agent traces to Hugging Face buckets.
+Project-URL: Repository, https://github.com/twangodev/hftracer
+Project-URL: Issues, https://github.com/twangodev/hftracer/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: huggingface-hub>=1.9.0
+Requires-Dist: typer>=0.24.0
+Description-Content-Type: text/markdown
+
+# hftracer
+
+[![Python](https://img.shields.io/badge/python-3.14%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Synchronize agent traces to Hugging Face buckets.
+
+## Installation
+
+```sh
+uv tool install hftracer
+```
+
+## Usage
+
+```sh
+uvx --from huggingface-hub hf auth login
+hftracer init
+hftracer sync --dry-run
+hftracer sync
+```
+
+## Supported agents
+
+| Agent | Sources |
+| --- | --- |
+| Codex | `~/.codex/sessions`, `~/.codex/archived_sessions` |
+| Claude Code | `~/.claude/projects` |
+
+## Features
+
+- Incremental uploads with progress bars
+- Original files and directory structure preserved
+- Separate device namespaces; no remote deletions

hftracer-0.1.0/README.md

@@ -0,0 +1,34 @@
+# hftracer
+
+[![Python](https://img.shields.io/badge/python-3.14%2B-blue?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Synchronize agent traces to Hugging Face buckets.
+
+## Installation
+
+```sh
+uv tool install hftracer
+```
+
+## Usage
+
+```sh
+uvx --from huggingface-hub hf auth login
+hftracer init
+hftracer sync --dry-run
+hftracer sync
+```
+
+## Supported agents
+
+| Agent | Sources |
+| --- | --- |
+| Codex | `~/.codex/sessions`, `~/.codex/archived_sessions` |
+| Claude Code | `~/.claude/projects` |
+
+## Features
+
+- Incremental uploads with progress bars
+- Original files and directory structure preserved
+- Separate device namespaces; no remote deletions

hftracer-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "hftracer"
+version = "0.1.0"
+description = "Synchronize agent traces to Hugging Face buckets."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+dependencies = [
+    "huggingface-hub>=1.9.0",
+    "typer>=0.24.0",
+]
+
+[project.scripts]
+hftracer = "hftracer.cli:app"
+
+[project.urls]
+Repository = "https://github.com/twangodev/hftracer"
+Issues = "https://github.com/twangodev/hftracer/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "ruff>=0.14",
+    "ty>=0.0.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

hftracer-0.1.0/release-please-config.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "uv.lock",
+          "jsonpath": "$.package[?(@.name.value == 'hftracer')].version"
+        }
+      ]
+    }
+  }
+}

hftracer-0.1.0/src/hftracer/__init__.py

@@ -0,0 +1 @@
+"""Sync native coding-agent sessions to private Hugging Face Storage Buckets."""

hftracer-0.1.0/src/hftracer/__main__.py

@@ -0,0 +1,3 @@
+from hftracer.cli import app
+
+app()

hftracer-0.1.0/src/hftracer/cli.py

@@ -0,0 +1,160 @@
+"""Discover local agent directories and delegate transfers to Hugging Face."""
+
+import os
+from contextlib import redirect_stdout
+from typing import Annotated, NoReturn
+
+import typer
+from huggingface_hub import HfApi
+
+from hftracer.config import (
+    Config,
+    config_path,
+    discover_sources,
+    load_config,
+    new_device_id,
+    save_config,
+    validate_bucket_id,
+)
+
+app = typer.Typer(
+    help="Sync Codex and Claude Code sessions to a private Hugging Face bucket.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_enable=False,
+)
+
+
+def fail(message: str) -> NoReturn:
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, err=True)
+    raise typer.Exit(1)
+
+
+def read_config() -> Config | None:
+    try:
+        return load_config()
+    except (OSError, ValueError) as exc:
+        fail(f"Cannot read configuration at {config_path()}: {exc}")
+
+
+def require_private(api: HfApi, bucket_id: str) -> None:
+    if api.bucket_info(bucket_id).private is not True:
+        raise ValueError(f"Bucket {bucket_id} is public; select a private bucket.")
+
+
+def format_size(size: int) -> str:
+    amount = float(size)
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if amount < 1024:
+            return f"{amount:.3g} {unit}"
+        amount /= 1024
+    return f"{amount:.3g} TiB"
+
+
+@app.command()
+def init(
+    bucket: Annotated[
+        str | None,
+        typer.Option(
+            "--bucket", help="Create or select namespace/name without prompting."
+        ),
+    ] = None,
+) -> None:
+    """Configure a private bucket and a persistent namespace for this device."""
+    previous = read_config()
+    api = HfApi()
+    try:
+        username = api.whoami()["name"]
+    except Exception as exc:
+        fail(
+            "Cannot authenticate with Hugging Face. "
+            f"Run `hf auth login` or set HF_TOKEN. {exc}"
+        )
+
+    if bucket is None:
+        default = previous.bucket_id if previous else f"{username}/traces"
+        bucket = typer.prompt("Bucket (namespace/name)", default=default)
+    try:
+        validate_bucket_id(bucket)
+        api.create_bucket(bucket, private=True, exist_ok=True)
+        require_private(api, bucket)
+    except Exception as exc:
+        fail(f"Cannot configure bucket: {exc}")
+
+    config = Config(bucket, previous.device_id if previous else new_device_id())
+    try:
+        sources = discover_sources()
+        save_config(config)
+    except OSError as exc:
+        fail(f"Cannot finish setup: {exc}")
+    typer.secho(f"Configured {config.bucket_id}", fg=typer.colors.GREEN)
+    if sources:
+        typer.secho(
+            f"Sources: {', '.join(remote for _, remote in sources)}",
+            fg=typer.colors.CYAN,
+        )
+    else:
+        typer.secho("No agent directories found yet.", fg=typer.colors.YELLOW)
+
+
+@app.command()
+def sync(
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run", "--preview", help="Preview planned changes without uploading."
+        ),
+    ] = False,
+) -> None:
+    """Upload new and modified files; never delete remote files."""
+    config = read_config()
+    if config is None:
+        fail("No configuration found. Run `hftracer init` first.")
+    api = HfApi()
+    try:
+        require_private(api, config.bucket_id)
+    except Exception as exc:
+        fail(f"Cannot verify private bucket: {exc}")
+    try:
+        sources = discover_sources()
+    except OSError as exc:
+        fail(f"Cannot discover agent directories: {exc}")
+    if not sources:
+        typer.secho(
+            "No agent directories found. Nothing to sync.", fg=typer.colors.YELLOW
+        )
+        return
+
+    mode = "Preview" if dry_run else "Sync"
+    upload_label = "to upload" if dry_run else "uploaded"
+    typer.secho(f"{mode}: {config.bucket_id}", fg=typer.colors.CYAN)
+    failed = False
+    for source, remote in sources:
+        destination = (
+            f"hf://buckets/{config.bucket_id}/devices/{config.device_id}/{remote}/"
+        )
+        try:
+            with open(os.devnull, "w") as sink, redirect_stdout(sink):
+                plan = api.sync_bucket(
+                    str(source),
+                    destination,
+                    delete=False,
+                    dry_run=dry_run,
+                    quiet=dry_run,
+                )
+            summary = plan.summary()
+            size = format_size(int(summary["total_size"]))
+            typer.echo(
+                f"{remote}: {summary['uploads']} {upload_label}, "
+                f"{summary['skips']} unchanged ({size})"
+            )
+        except Exception as exc:
+            typer.secho(f"Error for {remote}: {exc}", fg=typer.colors.RED, err=True)
+            failed = True
+    if failed:
+        command = "hftracer sync --dry-run" if dry_run else "hftracer sync"
+        fail(f"Some sources failed. Run `{command}` again to retry.")
+    if dry_run:
+        typer.secho("No files uploaded.", fg=typer.colors.YELLOW)
+    else:
+        typer.secho("Sync complete.", fg=typer.colors.GREEN)

hftracer-0.1.0/src/hftracer/config.py

@@ -0,0 +1,87 @@
+"""Small, local configuration and fixed agent-directory discovery."""
+
+import json
+import os
+import re
+import socket
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from uuid import uuid4
+
+SOURCES = (
+    (".codex/sessions", "codex/sessions"),
+    (".codex/archived_sessions", "codex/archived_sessions"),
+    (".claude/projects", "claude/projects"),
+)
+
+
+def validate_bucket_id(bucket_id: str) -> None:
+    """Require a bucket ID, rather than a URL or a bucket subdirectory."""
+    if not re.fullmatch(
+        r"[A-Za-z0-9_][A-Za-z0-9_.-]*/[A-Za-z0-9_][A-Za-z0-9_.-]*", bucket_id
+    ):
+        raise ValueError("Bucket must be in namespace/name format.")
+
+
+@dataclass(frozen=True)
+class Config:
+    bucket_id: str
+    device_id: str
+
+    def __post_init__(self) -> None:
+        validate_bucket_id(self.bucket_id)
+        if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", self.device_id):
+            raise ValueError("Invalid device namespace in configuration.")
+
+
+def config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME")
+    return (
+        (Path(base) if base else Path.home() / ".config") / "hftracer" / "config.json"
+    )
+
+
+def load_config() -> Config | None:
+    try:
+        content = config_path().read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    data = json.loads(content)
+    if not isinstance(data, dict):
+        raise ValueError("Configuration must be a JSON object.")
+    bucket_id, device_id = data.get("bucket_id"), data.get("device_id")
+    if not isinstance(bucket_id, str) or not isinstance(device_id, str):
+        raise ValueError("Configuration requires bucket_id and device_id strings.")
+    return Config(bucket_id=bucket_id, device_id=device_id)
+
+
+def save_config(config: Config) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, delete=False
+        ) as stream:
+            temporary_path = Path(stream.name)
+            json.dump(asdict(config), stream, indent=2)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary_path, path)
+    finally:
+        if temporary_path is not None:
+            temporary_path.unlink(missing_ok=True)
+
+
+def new_device_id() -> str:
+    hostname = re.sub(r"[^a-z0-9-]+", "-", socket.gethostname().lower()).strip("-")
+    return f"{hostname or 'device'}-{uuid4().hex}"
+
+
+def discover_sources() -> list[tuple[Path, str]]:
+    home = Path.home()
+    return [
+        (home / local, remote) for local, remote in SOURCES if (home / local).is_dir()
+    ]

hftracer-0.1.0/tests/conftest.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import MagicMock, create_autospec
+
+import pytest
+from huggingface_hub import HfApi, SyncPlan
+
+from hftracer import cli
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
+    return home
+
+
+@pytest.fixture
+def api(monkeypatch: pytest.MonkeyPatch) -> MagicMock:
+    mock = create_autospec(HfApi, instance=True)
+    mock.whoami.return_value = {"name": "alice"}
+    mock.bucket_info.return_value = SimpleNamespace(private=True)
+    mock.sync_bucket.return_value = SyncPlan(source="", dest="", timestamp="")
+    monkeypatch.setattr(cli, "HfApi", lambda: mock)
+    return mock

hftracer-0.1.0/tests/manual-integration.md

@@ -0,0 +1,40 @@
+# Manual private-bucket integration check
+
+Use synthetic files and a dedicated private bucket. This procedure is not part
+of the automated tests and requires existing HF authentication with bucket write
+access. Run it only when you intend to create that bucket and upload test data.
+
+1. Create two temporary home directories representing devices A and B, with
+   separate `XDG_CONFIG_HOME` directories. Set `HF_TOKEN` through your normal
+   credential mechanism before changing `HOME`, so the HF client does not lose
+   access to its usual credential cache. Do not copy your real session directories.
+2. In device A's home, create files beneath `.codex/sessions/2026/10/`,
+   `.codex/archived_sessions/`, and `.claude/projects/example/nested/`. Include a
+   `.jsonl` file, a hidden file, and a binary file with known contents. Keep a copy
+   of the synthetic fixture tree outside these source directories for comparison.
+3. With device A's `HOME` and `XDG_CONFIG_HOME`, run
+   `uv run hftracer init --bucket YOUR_USER/hftracer-integration`, then
+   `uv run hftracer sync --dry-run`. Verify the plan lists the fixture uploads
+   while the bucket stays empty. The `--preview` alias should produce the same
+   plan. Run `uv run hftracer sync` to transfer the files.
+   Verify the bucket is private and files appear under
+   `devices/<device-A>/` with the expected agent and directory prefixes. There
+   should be no hftracer metadata or manifest objects.
+4. Run sync again without changing the fixture files. HF's sync summary should
+   show no uploads and should report skipped files.
+5. Modify an existing file (changing its size and modification time), add another,
+   and delete a third locally. Run sync. Only the modified and new files should be
+   uploaded; the locally deleted file must remain remotely.
+6. Download `hf://buckets/YOUR_USER/hftracer-integration/devices/<device-A>/` into
+   a separate temporary directory using `hf buckets sync`. Compare downloaded
+   file bytes against the original fixture copy plus the modifications. Verify
+   hidden files, binary contents, nested paths, and the retained deleted file.
+7. Create a file at the same relative session path in device B's temporary home,
+   using different contents. Initialize device B against the same bucket and sync.
+   Verify its device ID differs from A's and both versions remain at their
+   respective prefixes. Re-run A's init and confirm its namespace stays unchanged.
+8. Optionally change the test bucket to public, then run sync and verify it fails
+   before any upload. Restore it to private through HF before further testing.
+
+Remove the temporary local directories when finished. Remote cleanup is manual;
+hftracer never deletes the bucket or its files.