🗂 On PyPI · v0.2.4 · Apache-2.0

Your folders, self-aware.

A tiny convention that tags a directory with machine-readable context — what it is, how critical it is, what it needs. So your configuration travels with the service, not the admin.

pip install folder-nature
Star on GitHub → View on PyPI
Shipped — pip-installable now ✓ 124 tests, CI green ◇ Apache-2.0
The idea

A service that carries its own intent

Every folder in your infrastructure means something — but that meaning lives in the admin's head, in scattered config, or nowhere at all. folder-nature writes it down, right next to the thing it describes, in a small .folder-nature file.

Now tools can read what a directory is for before they touch its contents. Move it to another host and the context moves with it — no rebuilding configuration from scratch.

What it gives you

Small file, large leverage

🧳Portable contextThe description lives with the service. Move between hosts and nothing is lost.
🤖Machine-readableA simple YAML convention. Human-writable, tool-parsable, version-controllable.
🔎Searchable by meaningFind folders by tag, by type, by intent — not just by name.
🌳Validate the whole treeOne command schema-checks every .folder-nature under a root and returns a single verdict.
The mark layer — attribution, not prevention

Who published this. Has it been altered.

Shipped since v0.2.0. Nine of the sixteen CLI commands cover it, and about two-thirds of the code lives here. Signing and watermarking answer who published this and has it been altered — stated plainly inside the tool itself, they do not prevent copying. cp beats any in-file mechanism, and we have zero visibility into a customer's machine. What the mark layer makes is a copy that is checkable.

🏷️Watermark — three redundant channelsZero-width (invisible), comment-id (visible attribution), and a real language constant. Any one surviving channel yields a CRC-valid payload; channels that disagree are reported as tampered. Files still run after stamping — guaranteed for Python by an in-process compile() before write.
✍️Ed25519 signaturesEvery file hashed into a sha256 manifest; the manifest signed with a vendored Ed25519 implementation verified against the RFC 8032 test vectors. Private key written mode 600; the tool refuses to write one inside a git repo.
✅verify --root — one verdictStructure, folder marks, file signatures, manifest↔disk parity, and optional per-file selftests. Everything green, or a named failure RED. No partial pass.
🧾Sale → leak → claimPer-customer stamp at sale time; a leak scan traces a found file to the buyer and emits a claim citing the license they accepted. Mechanism ships now; license texts come later.
folder-nature keygen --out ~/.config/folder-nature/signing.key
folder-nature stamp  . --number 0
folder-nature sign   . --key ~/.config/folder-nature/signing.key
folder-nature verify . --root --pubkey ~/.config/folder-nature/signing.key.pub
Try it — 30 seconds

Python 3.10+, one dependency

pip install folder-nature

folder-nature init . --template workspace --name "my-workspace"
folder-nature show .
folder-nature search . --tag client
folder-nature verify . --root
Shipped, tested, Apache-2.0. 124 tests pass in seconds — 66 for the identity layer above, 58 for the mark layer. Full source, schema, and templates on GitHub.

Free and open — forever

Install it, star it, ship it. Building a commercial product on top and want it without the open-source obligations? There's a license for that.

Get folder-nature → Commercial license →
Backed by
△Illia Hladkyi
Join them ❤