rillio

A pluggable, feature‑aware database façade: one clean CRUD API over multiple backends (Notion, Supabase, Postgres, SQLite), with a Rust core, CLI, and Python wrapper.

Status: name‑reservation / pre‑alpha. This repo initially ships a “hello world” so the names on crates.io, PyPI, and (optionally) npm are secured. The real code and workspace layout will follow.

Why rillio?

You often need the same data operations across very different storage systems (HTTP APIs like Notion/Supabase and SQL engines like Postgres/SQLite). rillio aims to provide:

• One façade: a single async CRUD interface.
• Multiple adapters: backends implement a common trait (Strategy/Adapter pattern).
• Capability negotiation: opt into extras (transactions, rich text, relations).
• Multiple frontends: use it as a Rust library, a CLI, or from Python.
• Feature flags: compile only what you need.

This README focuses on locking names (publish tiny placeholders) and the high‑level plan. The full workspace will come right after.

Quick goals

• Reserve package names:

  • crates.io: rillio
  • PyPI: rillio
  • npm (optional): @suhailphotos/rillio (recommended) or try to grab rillio if available

• Spin up a public GitHub repo at $MATRIX/crates/rillio

• Keep the initial code minimal (“hello world”) so publishing is trivial

Step‑by‑step: bootstrap + publish placeholders

Assumptions: macOS/Linux, gh, git, cargo, python3, pipx (optional), twine, build, and npm installed. You already have your truss helpers checked out.

0) Sanity‑check name availability (optional but nice)

You already have a helper:

cd ~/Library/CloudStorage/Dropbox/matrix/truss
scripts/names/namecheck.sh -r all rillio

If rillio is taken on npm, prefer the scoped form @suhailphotos/rillio.

1) Create the GitHub repo and local checkout

We’ll seed it with this README and a tiny Rust bin so cargo publish is possible.

# Save this README locally (if you haven’t already)
# Then run bootstrap (using your generic script)
./scripts/bootstrap/bootstrap_repo_generic.sh   -u suhailphotos   -r rillio   -t rust   -d "Pluggable, feature-aware database façade with Rust core, CLI, and Python bindings"   -R "/Users/suhail/Documents/Scratch/notes/README.md"   -O "op://devTools/GitHub Repo Key/secret key"   -V public

After this, your repo lives at:

$MATRIX/crates/rillio

The rust scaffold will have a minimal Cargo.toml and src/main.rs.

2) Prepare the crate for crates.io (hello world)

Edit Cargo.toml to include the metadata crates.io expects:

[package]
name = "rillio"
version = "0.0.1"
edition = "2021"
description = "Pluggable, feature-aware database façade with Rust core, CLI, and Python bindings"
license = "MIT"
readme = "README.md"
homepage = "https://github.com/suhailphotos/rillio"
repository = "https://github.com/suhailphotos/rillio"
keywords = ["database", "adapter", "facade", "notion", "postgres", "sqlite"]
categories = ["database", "command-line-utilities"]

Keep src/main.rs extremely simple for now:

fn main() {
    println!("rillio: hello world (name reservation)");
}

Now publish:

# login once (opens browser to create a token)
cargo login
# dry-run the package to verify
cargo package
# publish for real
cargo publish

If you see “package name is taken,” stop and pick an alternate spelling or add a suffix.

3) Publish a tiny Python package on PyPI (name reservation)

Do this inside the same repo in a python/ subfolder (keeps things tidy for now).

cd $MATRIX/crates/rillio
mkdir -p python/src/rillio
cat > python/src/rillio/__init__.py <<'PY'
__all__ = ["hello"]
__version__ = "0.0.1"

def hello() -> str:
    return "rillio: hello world (name reservation)"
PY

cat > python/pyproject.toml <<'TOML'
[project]
name = "rillio"
version = "0.0.1"
description = "Pluggable, feature-aware database façade (name reservation)"
readme = "../README.md"
requires-python = ">=3.10"
authors = [{name = "Suhail"}]
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
]

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
package-dir = {"" = "src"}
TOML

# build + upload
python3 -m pip install --upgrade build twine
cd python
python3 -m build
python3 -m twine upload dist/*

You’ll be prompted for PyPI credentials or a token. Consider setting up an API token on PyPI and using a ~/.pypirc for convenience later.

4) (Optional) Publish an npm placeholder

If unscoped rillio is free, you can try it; otherwise use your scope @suhailphotos/rillio which is safer.

cd $MATRIX/crates/rillio
mkdir -p npm
cat > npm/package.json <<'JSON'
{
  "name": "@suhailphotos/rillio",
  "version": "0.0.1",
  "description": "Pluggable, feature-aware database façade (name reservation)",
  "license": "MIT",
  "repository": "github:suhailphotos/rillio",
  "homepage": "https://github.com/suhailphotos/rillio",
  "type": "module",
  "main": "index.js"
}
JSON

echo 'export const hello = () => "rillio: hello world (name reservation)";' > npm/index.js

cd npm
npm login            # if not already
npm publish --access public

If you later want to switch from scoped to unscoped (or vice‑versa), you can publish a new package; npm doesn’t allow renaming a published package.

After the names are locked

We’ll replace the placeholder with the real multi‑crate workspace:

rillio/
├─ Cargo.toml        # workspace
├─ crates/
│  ├─ core/          # façade traits, types, errors, factory
│  ├─ backend-notion/
│  ├─ backend-supabase/
│  ├─ backend-postgres/
│  ├─ backend-sqlite/
│  └─ cli/
├─ py/               # pyo3 wrapper (published as rillio on PyPI after migration)
└─ README.md

Milestones:

1. Implement core with a mock backend (compiles, no deps).

2. Fill in SQLite adapter with sqlx for first real E2E.

3. Add Notion adapter (HTTP + rate‑limit handling).

4. Add Supabase, then Postgres.

5. Expose Python bindings via pyo3 and ship CLI commands.

6. Split docs into docs/ and add examples + tests.

License

MIT © Suhail