Codex/create setup script for codex environment

.agents/codex-setup

@@ -1,7 +1,15 @@
 #!/usr/bin/env bash
+set -euo pipefail
+
+# Install the tooling required to build and test the CodeTracer project.
+# The list of packages is derived from `Justfile` and `flake.nix`.
 
 AGENTS_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
-cd $AGENTS_DIR
+cd "$AGENTS_DIR"
 
 apt-get update
-apt-get install -y --no-install-recommends just
+DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    python3 python3-pip python3-venv python3-dev \
+    cargo rustc just pkg-config capnproto
+
+pip3 install --no-cache-dir --break-system-packages maturin uv

.agents/tasks/2025/08/14-1027-initial-python-api

@@ -0,0 +1,3 @@
+Implement the Python API described in the design document for the Rust-based module. Write tests. Don't actually implement tracing using `runtime_tracing` yet, just add placeholders.
+--- FOLLOW UP TASK ---
+Implement the Python API described in the design document for the Rust-based module. Write tests. Don't actually implement tracing using runtime_tracing yet, just add placeholders.

.agents/tasks/2025/08/15-1323-initial-test-suite

@@ -0,0 +1,25 @@
+Create an initial test suite for codetracer-python-recorder.
+
+Following TDD we want to start by writing tests.
+
+The test suite should follow the specification at design-docs/test-design-001.md
+The tests should be written in the `/tests` subdirectory and it should be possible to run them using our current approach of `just venv dev test`.
+
+If the module turns out to be missing functions or types required for the test, add them but with empty bodies. (for Python functions raise `NotImplemented` exception in the body of the function)
+If a test can be written both in Python and in Rust prefer writing it in Python.
+If a code modification needs to be done in the module and it is possible to do it both in Python and in Rust, prefer writing it in Python.
+
+If there is any item in the test suite which doesn't contain enough 
+--- FOLLOW UP TASK ---
+Create a script Hit:2 https://mise.jdx.dev/deb stable InRelease
+Hit:1 https://apt.llvm.org/noble llvm-toolchain-noble-20 InRelease
+Hit:3 http://archive.ubuntu.com/ubuntu noble InRelease
+Hit:4 http://security.ubuntu.com/ubuntu noble-security InRelease
+Hit:5 http://archive.ubuntu.com/ubuntu noble-updates InRelease
+Hit:6 http://archive.ubuntu.com/ubuntu noble-backports InRelease
+Reading package lists...
+Reading package lists...
+Building dependency tree...
+Reading state information...
+just is already the newest version (1.21.0-1).
+0 upgraded, 0 newly installed, 0 to remove and 25 not upgraded. which will be used in future to set-up the Codex environment for development and testing of this project. Base this on what you see in Justfile and flake.nix. Note that not all packages described in flake.nix will be needed in the Codex environment, but we do care about building the project and running the tests.

.github/workflows/ci.yml

@@ -9,38 +9,43 @@ on:
 
 jobs:
   nix-tests:
+    name: Testing on Python ${{matrix.python-version}}
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10","3.11","3.12","3.13"]
     steps:
       - uses: actions/checkout@v4
       - uses: cachix/install-nix-action@v27
         with:
           nix_path: nixpkgs=channel:nixos-25.05
           extra_nix_config: |
             experimental-features = nix-command flakes
-      - name: Run tests via Nix
-        run: nix develop --command just test
+      - name: Build Rust module and run tests via Nix
+        run: nix develop --command bash -lc 'just venv ${{matrix.python-version}} dev test'
 
-  rust-tests:
-    name: Rust module test on ${{ matrix.os }} (Python ${{ matrix.python-version }})
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["10", "11", "12", "13"]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.${{ matrix.python-version }}
-      - uses: astral-sh/setup-uv@v4
-      - uses: messense/maturin-action@v1
-        with:
-          command: build
-          args: --interpreter python3.${{ matrix.python-version }} -m crates/codetracer-python-recorder/Cargo.toml --release
-      - name: Install and test built wheel with uv (pytest)
-        shell: bash
-        run: |
-          v=${{matrix.python-version}}
-          file=(crates/codetracer-python-recorder/target/wheels/*.whl)
-          file="${file[0]}"
-          uv run -p python3.$v --with "${file}" --with pytest -- python -m pytest crates/codetracer-python-recorder/test -q
+  # rust-tests:
+  #   name: Rust module test on ${{ matrix.os }} (Python ${{ matrix.python-version }})
+  #   runs-on: ${{ matrix.os }}
+  #   strategy:
+  #     matrix:
+  #       os: [ubuntu-latest, macos-latest, windows-latest]
+  #       python-version: ["10", "11", "12", "13"]
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-python@v5
+  #       with:
+  #         python-version: 3.${{ matrix.python-version }}
+  #     - uses: astral-sh/setup-uv@v4
+  #     - uses: messense/maturin-action@v1
+  #       with:
+  #         command: build
+  #         args: --interpreter python3.${{ matrix.python-version }} -m crates/codetracer-python-recorder/Cargo.toml --release
+  #     - name: Install and test built wheel with uv (pytest)
+  #       shell: bash
+  #       run: |
+  #         v=${{matrix.python-version}}
+  #         file=(crates/codetracer-python-recorder/target/wheels/*.whl)
+  #         file="${file[0]}"
+  #         uv run -p python3.$v --with "${file}" --with pytest -- \
+  #           python -m pytest crates/codetracer-python-recorder/test tests/test_codetracer_api.py -q

.gitignore

@@ -3,4 +3,5 @@
 .aider*
 .venv/
 **/target/
-build
+build
+*~

AGENTS.md

@@ -5,20 +5,16 @@ This repository contains two related projects:
 - codetracer-pure-python-recorder — the original pure-Python tracer.
 - codetracer-python-recorder — a Rust-backed Python module built with PyO3 and maturin.
 
-To run the Python test suite for the pure-Python tracer, execute:
+To build the modules in development mode run:
 
-```
-just test
-```
+```sh
+just venv 3.13 dev #You can use any other Python version >=3.12
+``
 
-The tester executes a number of sample programs in `tests/programs` and compares their outputs to the fixtures in `tests/fixtures`.
+Then to run the tests do
 
-To build and locally develop-install the Rust-backed module:
-
-```
-just build-rust
-# or:
-maturin develop -m crates/codetracer-python-recorder/Cargo.toml
+```sh
+just test
 ```
 
 # Code quality guidelines

Justfile

@@ -1,48 +1,58 @@
+default:
+    @just --list
+
 # Development helpers for the monorepo
 
+# Python version used for development
+PYTHON_DEFAULT_VERSION := "3.13"
+
 # Python versions used for multi-version testing/building with uv
 PY_VERSIONS := "3.10 3.11 3.12 3.13"
 PY_SHORT_VERSIONS := "10 11 12 13"
+
 # Print toolchain versions to verify the dev environment
 env:
+    uv --version
     python3 --version
     cargo --version
     rustc --version
     maturin --version
 
-# Create a local virtualenv for Python tooling
-venv:
-    test -d .venv || python3 -m venv .venv
+clean:
+    rm -rf .venv **/__pycache__ **/*.pyc **/*.pyo **/.pytest_cache
+    rm -rf codetracer-python-recorder/target codetracer-python-recorder/**/*.so
+
 
-# Build and develop-install the Rust-backed Python module
-build-rust:
-    test -d .venv || python3 -m venv .venv
-    VIRTUAL_ENV=.venv maturin develop -m crates/codetracer-python-recorder/Cargo.toml
+# Create a clean local virtualenv for Python tooling (without editable packages installed)
+venv version=PYTHON_DEFAULT_VERSION:
+    uv sync -p {{version}}
 
-# Smoke test the Rust module after build
-smoke-rust:
-    .venv/bin/python -m pip install -U pip pytest
-    .venv/bin/python -m pytest crates/codetracer-python-recorder/test -q
+# Build the module in dev mode
+dev:
+    uv run --directory codetracer-python-recorder maturin develop --uv
 
-# Run the Python test suite for the pure-Python recorder
+# Run unit tests of dev build
 test:
-    python3 -m unittest discover -v
+    uv run --group dev --group test pytest
 
-# Run the test suite across multiple Python versions using uv
-test-uv-all:
-    uv python install {{PY_VERSIONS}}
-    for v in {{PY_VERSIONS}}; do uv run -p "$v" -m unittest discover -v; done
+# Run tests only on the pure recorder
+test-pure:
+    uv run --group dev --group test pytest codetracer-pure-python-recorder
+
+# Build the module in release mode
+build:
+    just venv \
+    uv run --directory codetracer-python-recorder maturin build --release
 
 # Build wheels for all target Python versions with maturin
-build-rust-uv-all:
-    for v in {{PY_VERSIONS}}; do \
-        maturin build --interpreter "python$v" -m crates/codetracer-python-recorder/Cargo.toml --release; \
-    done
+build-all:
+    just venv
+    uv run --directory codetracer-python-recorder maturin build --release --interpreter {{PY_VERSIONS}}
 
 # Smoke the built Rust wheels across versions using uv
-smoke-rust-uv-all:
+test-all:
     for v in {{PY_SHORT_VERSIONS}}; do \
-        file=(crates/codetracer-python-recorder/target/wheels/codetracer_python_recorder-*-cp3$v-cp3$v-*.whl); \
+        file=(codetracer-python-recorder/target/wheels/codetracer_python_recorder-*-cp3$v-cp3$v-*.whl); \
         file="${file[0]}"; \
-        uv run -p "python3.$v" --with "${file}" --with pytest -- python -m pytest crates/codetracer-python-recorder/test -q; \
+        uv run -p "python3.$v" --with "${file}" --with pytest -- pytest -q; \
     done

codetracer-pure-python-recorder/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codetracer-pure-python-recorder"
+version = "0.1.0"
+description = "Pure-Python prototype recorder producing CodeTracer traces"
+authors = [{name = "Metacraft Labs Ltd"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[tool.setuptools]
+py-modules = ["trace"]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+codetracer-record = "codetracer_pure_python_recorder.cli:main"
+codetracer-record-pure = "codetracer_pure_python_recorder.cli:main"