crazy-crafters/cartulary
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
No description
926 commits 1 branch 3 tags 9.7 MiB
  • Rust 92.3%
  • Gherkin 7.1%
  • CSS 0.2%
  • HTML 0.2%
  • Just 0.1%
Find a file
Exact
Olivier Albiez 300a5a797a chore(issue): close the site refactor umbrella 
The site build is now a domain use case wired through ports;
the umbrella's stated target is met.

Refs: ISSUE-01C8JYKDYPBB0

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-20 16:18:56 +02:00
.claude/skills chore(skill): inscribe subject DR-ref rule and docs scope rule 2026-05-17 21:15:46 +02:00
.githooks ci: enforce conventional commits per ADR-0019 2026-04-29 16:09:29 +02:00
.vscode chore: share minimal vscode settings encoding project conventions 2026-05-03 12:14:32 +02:00
demo fix(config): migrate demo workspace to v6 tag-descriptor shape 2026-05-13 07:50:53 +02:00
docs chore(issue): close the site refactor umbrella 2026-05-20 16:18:56 +02:00
src refactor(site): extract the site build into a domain use case 2026-05-20 16:18:48 +02:00
tests feat(issue): accept any file as an issue companion 2026-05-19 12:55:53 +02:00
xtask docs: drop internal DDR refs from user-facing docs 2026-05-18 18:02:49 +02:00
.gitignore chore: untrack .claude/settings.local.json 2026-05-03 21:59:29 +02:00
.gitlab-ci.yml build: centralise rust toolchain in rust-toolchain.toml 2026-05-14 16:06:51 +02:00
Cargo.lock chore: Release 2026-05-17 19:46:03 +02:00
Cargo.toml chore: Release 2026-05-17 19:46:03 +02:00
cartulary.toml feat(config): register sr (Standard Record) as a decision-record kind 2026-05-17 19:09:28 +02:00
CHANGELOG.md chore(release): hand-curate v0.2.0-alpha.1 changelog before retag 2026-05-17 21:05:55 +02:00
CLAUDE.md docs: forbid internal ADR/DDR refs in user-facing CLI strings 2026-05-17 09:54:26 +02:00
cliff.toml chore(release): trim cliff.toml to user-visible commit types only 2026-05-17 20:27:54 +02:00
committed.toml ci: enforce conventional commits per ADR-0019 2026-04-29 16:09:29 +02:00
flake.lock build: bump toolchain to Rust 1.88 via rust-overlay 2026-05-13 14:25:10 +02:00
flake.nix build: ship cargo-release and git-cliff in the dev shell 2026-05-17 18:29:15 +02:00
justfile chore(release): embed reference docs under src/ so the crate publishes 2026-05-17 20:56:08 +02:00
LICENSE chore: add CeCILL license 2026-03-09 10:32:39 +01:00
readme.md build: ship cargo-release and git-cliff in the dev shell 2026-05-17 18:29:15 +02:00
rust-toolchain.toml build: centralise rust toolchain in rust-toolchain.toml 2026-05-14 16:06:51 +02:00

readme.md

📖 cartulary

status: alpha

The knowledge layer of your project — decisions, issues, docs, all in one place.

⚠️ Status: Alpha — cartulary is under active development. The CLI surface and cartulary.toml schema may change in incompatible ways before 1.0. Pin a specific version (--version "0.1.0-alpha.1") and watch CHANGELOG.md before upgrading.

cartulary is a CLI tool to manage everything that gives context to your project: Architecture Decision Records (ADR), Design Decision Records (DDR), issues, and project documentation. Everything lives as plain Markdown in your repository.

📚 Documentation

🚀 Installation

Pre-built binary (recommended)

Download the archive for your platform from the GitLab Releases page. One-liner for Linux x86_64:

VERSION="0.1.0-alpha.1"
TARGET="x86_64-unknown-linux-gnu"
curl -fsSL "https://gitlab.com/crazy-crafters/cartulary/-/releases/v${VERSION}/downloads/cartu-${VERSION}-${TARGET}.tar.gz" \
    | tar -xz -C /tmp
mv /tmp/cartu ~/.local/bin/cartu

Available targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-gnu. macOS users compile from source via cargo install (next section). Verify the archive against the SHA256SUMS file attached to the same release.

For Windows: download cartu-{version}-x86_64-pc-windows-gnu.zip, unzip, place cartu.exe on your PATH.

Via cargo binstall (no compilation)

If you have cargo-binstall:

cargo binstall cartulary --version "0.1.0-alpha.1"

cartulary ships a [package.metadata.binstall] block pointing at the GitLab Release artefacts — binstall picks the right archive for your platform.

Via cargo install (compile from source)

cargo install cartulary --version "0.1.0-alpha.1"

Compiles from the published crate on crates.io. Requires Rust 1.88+ via rustup.rs.

Build from source (contributors)

git clone https://gitlab.com/crazy-crafters/cartulary
cd cartulary
cargo install --path .

Requires Rust 1.88+. Beyond rustc/cargo, the dev workflow expects just (recipe runner) and cargo-llvm-cov (coverage). Nix users get them automatically via the flake (nix develop); other contributors should install them manually:

cargo install --locked just cargo-llvm-cov
rustup component add llvm-tools-preview

⚡ 30-second tour

cartu init                                          # scaffold cartulary.toml + docs/
cartu adr new "Use PostgreSQL as primary database"  # record an architecture decision
cartu issue new --tag flow:feature "Add MFA"        # open an issue
cartu issue list
cartu check                                         # validate frontmatter, links, transitions
cartu man                                           # browse concept docs
cartu site build --out site                         # static HTML site with syntax-highlighted code

Pick the next thread from the documentation section above.

🔎 Similar tools

Tool Category Decision records Issue tracking Flow metrics Plain files Single binary
adr-tools ADR CLI ✅ ❌ ❌ ✅ ❌
log4brains ADR + web UI ✅ ❌ ❌ ✅ ❌
git-bug Issue tracker ❌ ✅ ❌ ❌ ✅
git-issue Issue tracker ❌ ✅ ❌ ✅ ❌
cartulary ADR + issues ✅ ✅ ✅ ✅ ✅

The market is split: ADR tools have no issue tracking, issue trackers have no decision records. cartulary covers both, plus flow metrics, structural validation, and a TSID-based identifier scheme that survives parallel branches. See market-benchmark.md for the full analysis.

🤝 Contributing

Contributions welcome — open an issue or submit a merge request.

cartulary enforces Conventional Commits 1.0.0 (rationale in ADR-0019). Allowed types: feat, fix, docs, refactor, perf, test, build, ci, chore, style. Subject in imperative mood, lowercase, no trailing period, ≤72 chars. CI rejects non-conforming commits; to get the same check locally:

cargo install committed
just install-hooks

Releases are cut by maintainers with cargo release --execute X.Y.Z, which runs git-cliff to update CHANGELOG.md and triggers cargo publish + GitLab Release artefacts on tag push. Maintainers either enter the Nix dev shell (nix develop, which ships cargo-release and git-cliff) or install the two tools manually:

cargo install --locked cargo-release git-cliff

📄 License

CeCILL