Modernize project

.envrc

@@ -6,16 +6,22 @@ layout_uv() {
         VIRTUAL_ENV="$(pwd)/.venv"
     fi
 
-    if [[ -z $VIRTUAL_ENV || ! -d $VIRTUAL_ENV ]]; then
+    if [[ -d ".venv.$(uname)" ]]; then
+        VIRTUAL_ENV="$(pwd)/.venv.$(uname)"
+    fi
+
+    if [[ -z $VIRTUAL_ENV || ! -d $VIRTUAL_ENV ]] || ! $VIRTUAL_ENV/bin/python -c True; then
         log_status "No virtual environment exists. Executing \`uv venv\` to create one."
-        uv venv
-        VIRTUAL_ENV="$(pwd)/.venv"
+        VIRTUAL_ENV="$(pwd)/.venv.$(uname)"
+        uv venv --clear "$VIRTUAL_ENV"
     fi
 
+    UV_PROJECT_ENVIRONMENT="$VIRTUAL_ENV"
     PATH_add "$VIRTUAL_ENV/bin"
     export UV_ACTIVE=1
     export VENV_ACTIVE=1
     export VIRTUAL_ENV
+    export UV_PROJECT_ENVIRONMENT
 }
 
 layout_uv

.github/pull_request_template.md

@@ -0,0 +1,6 @@
+<!-- Thank you for your contribution! -->
+
+**Before submitting, please confirm the following:**
+
+- [ ] I have read and understood the project's [CONTRIBUTING.md](CONTRIBUTING.md) file.
+- [ ] I agree to dedicate my contribution to the public domain under the terms of the [LICENSE](LICENSE) file.

.github/workflows/test.yml

@@ -32,6 +32,9 @@ jobs:
     - name: Install dependencies
       run: uv sync --dev
 
+    - name: Lint with ruff
+      run: uv run ruff check .
+
     - name: Run CLI tests
       run: uv run python -m pytest bead_cli/ -v
 

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Bead
+
+Thank you for your interest in contributing to the Bead project! We welcome contributions from everyone. To ensure a smooth and collaborative process, please review these guidelines.
+
+This document provides instructions for both human developers and AI agents to ensure that all contributions are consistent and high-quality.
+
+## Development Workflow
+
+### Version Control & Commits
+
+We use Git for version control. Please follow these conventions for your commits:
+
+- **Use the [Conventional Commits](https://www.conventionalcommits.org/) format.** This helps us automate releases and makes the project history easy to read.
+- Your commit message should clearly explain the **reason** for the change.
+- Focus on the **"why"** of the change in the commit body, not just the "what."
+
+### Build, Lint, and Test Commands
+
+Before submitting your contribution, please ensure it passes all checks.
+
+#### Testing
+- **Run all tests**: `make test`
+- **Run a single test**: `pytest path/to/test_file.py::TestClass::test_method` or `pytest path/to/test_file.py -k "test_name"`
+- **Check test coverage**: `pytest --cov=. --cov-report=term-missing`
+
+#### Linting & Formatting
+- **Run the linter**: `ruff check .`
+- **Format imports automatically**: `isort .`
+- **Run the static type checker**: `pytype -k -j auto bead bead_cli __main__.py tests tracelog.py dev/build.py` or `uvx ty check`
+- **Run all pre-commit hooks**: `pre-commit run --all-files`
+
+#### Building
+- **Build a wheel**: `uv build --wheel`
+- **Build executables**: `make executables`
+
+## Code Style Guidelines
+
+### General Principles
+- Keep code simple, readable, and self-explanatory.
+- Use meaningful names that reveal intent for variables, functions, classes, etc.
+
+### Variables
+- If a variable's name conflicts with its content or meaning, it **MUST** be renamed.
+
+### Functions
+- Each function should do one thing and do it well.
+- Keep functions small (a few lines).
+- Prefer a maximum of 2-3 parameters.
+- Function names should describe the action being performed.
+- If a function's name conflicts with its behavior, it **MUST** be renamed.
+
+### Classes
+- Each class should have a single responsibility.
+- Follow the [SOLID principles](https://en.wikipedia.org/wiki/SOLID).
+
+### Imports
+- Place all imports at the top of the file.
+- Use one import per line.
+- Our configuration for `isort` enforces single-line, lexicographically sorted imports.
+
+### Formatting
+- Maximum line length is 99 characters.
+- Use 4 spaces for indentation.
+- We follow PEP8 with the following exceptions: W503, W504, E251, E241, E221, E722.
+
+### Types
+- Use type hints where they improve clarity and correctness.
+- Pyright is configured to ignore unknown parameter/variable types.
+- We use `pytype` for static type checking.
+
+### Error Handling
+- Handle errors and exceptions properly to ensure robustness.
+- Consider the security implications of your code.
+- Avoid bare `except:` clauses.
+
+### Comments
+- Prefer self-explanatory code over comments.
+- Only add comments when they provide information that isn't apparent from the code itself.
+- If you add comments, ensure they are kept up-to-date with code changes.
+
+### Database/SQL
+- Isolate functions that use direct SQL from other logic.
+- These functions should perform a single database operation.
+- They should return materialized values (e.g., lists of objects), not cursors or generators.
+- Hide the database implementation details from the rest of the application.
+
+### Bead-Specific Knowledge
+- `content_id` and `kind` are internal, technical identifiers (long strings). They are not supplied directly by the user.
+- Users specify beads and files by their names.
+- `bead_ref_base` refers to a user-provided name or filename.

Makefile

@@ -1,13 +1,11 @@
-.PHONY: test clean executables shiv
+.PHONY: test clean executables
 
 test:
-	tox
+	uv run python -m pytest --cov=. --cov-report=term-missing
+	uv run ruff check .
 
 executables:
 	dev/build.py
 
-shiv:
-	shiv -o executables/bead.shiv -c bead -p '/usr/bin/python -sE' .
-
-container-image:
+vm:
 	podman build --no-cache -t bead-dev - < dev/Containerfile

README.md

@@ -1,4 +1,4 @@
-[![Tests](https://github.com/e3krisztian/bead/actions/workflows/test.yml/badge.svg)](https://github.com/e3krisztian/bead/actions/workflows/test.yml)
+[![Tests](../../actions/workflows/test.yml/badge.svg)](../../actions/workflows/test.yml)
 
 
     B-E-+
@@ -37,7 +37,7 @@ New computations get a new, universally unique `kind` (technically an uuid).
 
 ## Status
 
-### Used in production for almost 10 years now, there are hundreds of frozen computations
+### Used in production since 2015, there are hundreds of frozen computations
 
 Although most of the important stuff is implemented, there are still some raw edges.
 
@@ -46,8 +46,11 @@ Documentation for the tool is mostly the command line help.
 The `doc` directory has concept descriptions, maybe some use cases,
 but there are also design fragments - you might be mislead by them as they
 are nor describing the current situations nor are they showing the future.
+
 FIXME: clean up documentation.
 
+NOTE: https://bead.zip has new user documentation (as of September, 2025).
+
 
 ## Install instructions
 
@@ -71,14 +74,16 @@ $ cp executables/bead ~/.local/bin
 
 Alternatively it can be installed with pipx:
 
+For production use choose the latest released, non-pre-release version:
 ```
-pipx install git+https://github.com/e3krisztian/bead
+pipx install git+https://github.com/bead-project/bead@VERSION
 ```
-For development version, or
+
+or for latest development version:
+
 ```
-pipx install git+https://github.com/e3krisztian/bead@VERSION
+pipx install git+https://github.com/bead-project/bead
 ```
-for any tagged versions.
 
 ----
 
@@ -90,4 +95,12 @@ If you test it, please give [feedback](../../issues) on
 
 Any other nuisance reported - however minor you think it be - is important and welcome!
 
+## Contributing
+
+We welcome contributions! If you feel like working on code, please open an issue first to discuss your ideas.
+
+This project is dedicated to the public domain via the [LICENSE](LICENSE) file. By submitting a pull request, you agree to irrevocably release your work under the same license.
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on our development process.
+
 Thank you for your interest!

bead/tech/__init__.py

@@ -1,4 +1,4 @@
-# flake8: noqa
+# ruff: noqa
 
 '''
 Technologies

dev/Containerfile

@@ -2,17 +2,27 @@
 FROM python:3.12-slim-trixie
 
 RUN apt update
-RUN apt install -y direnv fd-find fzf git less ripgrep tree graphviz unzip sqlite3 visidata pipx
+RUN apt install -y direnv fd-find fzf git less ripgrep tree graphviz unzip sqlite3 visidata pipx npm
 
 # uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
 # aider
 RUN uv venv --python python3.12 /opt/aider
 RUN bash -c 'source /opt/aider/bin/activate && uv pip install aider-chat'
-
 ENV PATH="$PATH:/opt/aider/bin"
 
+# opencode
+ADD https://github.com/sst/opencode/releases/latest/download/opencode-linux-arm64.zip /tmp/opencode-linux-arm64.zip
+RUN unzip /tmp/opencode-linux-arm64.zip -d /opt/opencode && chmod -R a-w /opt/opencode
+ENV PATH="$PATH:/opt/opencode"
+# RUN mkdir -p /opt/opencode-ai && npm install -g --prefix /opt/opencode-ai opencode-ai
+# ENV PATH="$PATH:/opt/opencode-ai/bin"
+
+# gemini-cli
+RUN mkdir -p /opt/gemini && npm install -g --prefix /opt/gemini @google/gemini-cli
+ENV PATH="$PATH:/opt/gemini/bin"
+
 RUN cat > /opt/bashrc <<EOS
 eval "\$(direnv hook bash)"
 EOS

dev/test

@@ -6,7 +6,7 @@ cd $(dirname "$0")
 packages_to_test=(bead bead_cli tests)
 
 pwd
-flake8 "${packages_to_test[@]}"
+ruff check .
 mypy --ignore-missing-imports "${packages_to_test[@]}"
 
 # coverage

dev/vm

@@ -1,27 +1,20 @@
 #!/bin/bash
 
 directories_to_map=(
-    $PWD
-    ~/.aider
-    ~/.aider.tags.cache.v4
-    ~/.cache/uv
-    ~/.cache/pre-commit
-    ~/.local/share/direnv
-    ~/.local/share/uv
 )
 
 files_to_map=(
     ~/.gitconfig
-    ~/.aider.chat.history.md
-    ~/.aider.input.history
 )
 
 args=(
     --user $(id -u):$(id -g)
     --env "HOME=$HOME"
     --workdir "$PWD"
     --env-file ~/.env
-    --tmpfs ~
+#    --tmpfs ~
+    -v $HOME/podman:$HOME
+    -v $PWD:$PWD
 )
 
 for f in "${files_to_map[@]}"
@@ -39,4 +32,6 @@ do
     args+=(-v "$d:$d")
 done
 
+set -x
+
 exec podman run --rm -it "${args[@]}" bead-dev

pyproject.toml

@@ -55,12 +55,25 @@ dev = [
     "mypy",
     "pre-commit",
     "ruff",
-    "flake8",
     "pytype>=2024.10.11",
 ]
 
-[tool.flake8]
-line_length= 120
+[tool.ruff]
+line-length = 120
+lint.ignore = [
+    "E251", # unexpected spaces around keyword / parameter equals
+    "E241", # multiple spaces after ','
+    "E221", # multiple spaces before operator
+    "E722", # do not use bare except
+]
+exclude = [
+    "appdirs.py",
+    "test-env",
+    ".eggs",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
 
 [tool.isort]
 force_single_line=true

test_requirements.txt

@@ -1,4 +1,4 @@
-flake8
+ruff
 mypy==0.761
 freezegun==0.3.12
 pytest-cov==2.8.1