cache22

This is a playground for experimenting with curating and archiving source code on local filesystems. It's also meant as an exercise for trying out AI-assisted development workflows. Cache22 currently works on local POSIX filesystems (Linux and macOS).

Installation

uv sync
source .venv/bin/activate

Getting Started

# Configure where archives are stored
cache22 config root add /absolute/path/to/archive

# Fetch a repository (remote paths are lowercased by default)
cache22 fetch https://github.com/ar-jan/cache22.git

See docs/use.md for further documentation.

Browser manager

Run these in separate terminals:

cache22 web
# Open http://127.0.0.1:8001/

cache22 worker

The Datasette manager browses the index, registers repositories, submits bulk checks/fetches, changes schedules, and monitors progress. Web and worker run independently; stopping either does not stop the other. Jobs wait when no worker is available. Use cache22 worker --once for timer-driven operation. All index data is available for inspection; changes go through Cache22 services. Assets are bundled locally. See usage for commands and service examples.

The index uses schema version 3. Other versions are rejected without migration or automatic reset. To replace an older index, stop all Cache22 processes, back up the index, and remove it and its -wal/-shm sidecars. A fresh index is created on the next command. This loses registrations, schedules, queued work, and history, but leaves archive files intact. cache22 audit --fix can rediscover managed mirrors and bundles.

Inventory success timestamps and error summaries come from job attempts. Only a successful check job advances the last-check timestamp; fetches and conversions have their own success timestamps. Terminal job history expires after 30 days, except the latest successful job per repository and kind, which is retained to preserve those timestamps. See usage for status and recovery details.

Development

# Create .venv and install Python dependencies
uv sync --group dev
# Upgrade Python dependencies
uv lock --upgrade
# Install NPM dependencies for utils/editor
npm install
# Upgrade NPM dependencies
npm update
# Install git hooks for this repo
uv run --group dev pre-commit install
# Or run all pre-commit hooks:
uv run --group dev pre-commit run --all-files

Utils

Other related experiments:

Basic YAML editor for storing relevant projects.