folder-nature 0.1.0__tar.gz

folder_nature-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Illia Hladkyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

folder_nature-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: folder-nature
+Version: 0.1.0
+Summary: Semantic identity for filesystem folders — folders become conversation partners
+Author: Illia Hladkyi
+License: MIT
+Project-URL: Homepage, https://github.com/myfjin/folder-nature
+Project-URL: Repository, https://github.com/myfjin/folder-nature
+Project-URL: Issues, https://github.com/myfjin/folder-nature/issues
+Keywords: filesystem,metadata,semantic,organization,self-hosted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# folder-nature
+
+> *Folders are not containers. They're ecosystems with collective memory, personality, and rules.*
+
+A directory becomes a conversation partner: it has identity, purpose, rules,
+and history, all captured in a hidden `.folder-nature` YAML file at the
+directory's root.
+
+## What problem this solves
+
+Filesystems don't carry meaning. `~/Projects/old_v3_final/` could be anything.
+Search-by-filename doesn't help when you can't remember the filename. New team
+members start from zero. AI assistants scan everything.
+
+folder-nature attaches a small piece of YAML to each directory that captures:
+- What this folder is for
+- What kind of folder it is (workspace, archive, configs, ...)
+- What tags apply
+- What rules govern it
+- When it was created and what notable things happened
+
+Once attached, you can search by meaning, walk up to find the boss folder,
+validate the tree, and let AI tools query a folder's intent before they
+interact with its contents.
+
+## Install
+
+```bash
+pip install git+https://github.com/myfjin/folder-nature.git
+```
+
+Requires Python 3.10+. Single runtime dependency: PyYAML.
+
+> **PyPI release planned for late July 2026.** Once published, install
+> will simplify to `pip install folder-nature`.
+
+## 5-minute tour
+
+```bash
+# Create something to tag
+mkdir demo && cd demo
+mkdir -p Old_Stuff RANDOM new_new_final download untitled_folder
+
+# Tag the root
+folder-nature init . --template workspace --name "demo-workspace"
+
+# Show what got created
+folder-nature show .
+
+# Reorganize + tag the new structure
+mkdir -p projects/{active,archive} clients/{acme,startup-x} documents
+folder-nature init projects/active --template workspace
+folder-nature init projects/archive --template archive
+folder-nature init clients --template client-project --name "my-clients"
+folder-nature init documents --template documentation
+
+# Search by meaning
+folder-nature search . --tag client
+folder-nature search . --being collector
+
+# Validate the tree
+folder-nature validate .
+
+# Tree view
+folder-nature list .
+```
+
+## Templates (`init --template`)
+
+Five archetypes ship with the package:
+
+| Template | When to use |
+|----------|-------------|
+| `workspace` | Active project working directory |
+| `client-project` | Client-specific work folder |
+| `archive` | Historical / inactive storage |
+| `deployment` | Production-touching configs and scripts |
+| `documentation` | Docs, references, guides |
+
+Customize at init time with `--name "your-name"` or edit the resulting
+`.folder-nature` file directly afterward.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `folder-nature init [PATH] [--template T]` | Create a new `.folder-nature` |
+| `folder-nature show [PATH]` | Print closest `.folder-nature` (walks up) |
+| `folder-nature query [PATH]` | Find the `director: true` ancestor |
+| `folder-nature search [ROOT] [--tag T] [--being B] [--name N]` | Filter folders by criteria |
+| `folder-nature validate [ROOT]` | Schema-check all `.folder-nature` files in tree |
+| `folder-nature list [ROOT]` | Tree view of every tagged folder |
+| `folder-nature version` | Print tool + schema versions |
+
+`PATH` and `ROOT` default to the current directory.
+
+## Schema v1.0
+
+A `.folder-nature` file is YAML with this shape:
+
+```yaml
+schema_version: "1.0"             # REQUIRED
+
+identity:                         # REQUIRED
+  name: "Projects"
+  being: "director"
+  purpose: "Canonical root for all work"
+
+director: true                    # OPTIONAL (default false)
+
+tags:                             # OPTIONAL
+  - work
+  - canonical
+  - active
+
+rules:                            # OPTIONAL
+  - "Only deployed code lives here"
+
+memory:                           # OPTIONAL
+  created: "2026-05-09"
+  last_significant_change: "2026-06-22"
+  notable_events:
+    - "2026-05-09: initial setup"
+```
+
+The `identity.being` field accepts a controlled vocabulary plus arbitrary
+custom values (extensibility hatch). Known types:
+
+`director` · `collector` · `workspace` · `assets` · `configs` ·
+`documentation` · `ideas` · `external` · `legal` · `team-shared` ·
+`private` · `system`
+
+## Design principles
+
+1. **Files, not databases.** Each folder owns its own YAML. Git-friendly,
+   editor-friendly, no central store.
+2. **Self-hosted.** Runs entirely local. No network calls. No telemetry.
+3. **Schema-versioned.** Future schema bumps migrate cleanly.
+4. **AI-readable.** Optional integration with LLM assistants — they query the
+   folder's nature before interacting with its contents.
+5. **Open from day one.** MIT licensed. Code reviewable. Schema documented.
+
+## Roadmap
+
+- **v0.1 (this release):** core MVP — schema, CLI, 5 templates, tests
+- **v0.2:** export/import, migration tool, more templates
+- **v1.0:** AI integration (`folder-nature ai-suggest`), filesystem watcher,
+  comprehensive docs
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/myfjin/folder-nature
+cd folder-nature
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+Test suite: 66 tests covering schema validation, filesystem operations,
+search, and CLI integration. Should run in <1 second.
+
+## Origin
+
+folder-nature emerged from internal infrastructure work in early 2026 —
+a working hypothesis that filesystems become more useful when directories
+carry semantic identity. The concept proved itself on a 3-node operational
+mesh before being extracted as this standalone tool.
+
+🐍🦅💎

folder_nature-0.1.0/README.md

@@ -0,0 +1,174 @@
+# folder-nature
+
+> *Folders are not containers. They're ecosystems with collective memory, personality, and rules.*
+
+A directory becomes a conversation partner: it has identity, purpose, rules,
+and history, all captured in a hidden `.folder-nature` YAML file at the
+directory's root.
+
+## What problem this solves
+
+Filesystems don't carry meaning. `~/Projects/old_v3_final/` could be anything.
+Search-by-filename doesn't help when you can't remember the filename. New team
+members start from zero. AI assistants scan everything.
+
+folder-nature attaches a small piece of YAML to each directory that captures:
+- What this folder is for
+- What kind of folder it is (workspace, archive, configs, ...)
+- What tags apply
+- What rules govern it
+- When it was created and what notable things happened
+
+Once attached, you can search by meaning, walk up to find the boss folder,
+validate the tree, and let AI tools query a folder's intent before they
+interact with its contents.
+
+## Install
+
+```bash
+pip install git+https://github.com/myfjin/folder-nature.git
+```
+
+Requires Python 3.10+. Single runtime dependency: PyYAML.
+
+> **PyPI release planned for late July 2026.** Once published, install
+> will simplify to `pip install folder-nature`.
+
+## 5-minute tour
+
+```bash
+# Create something to tag
+mkdir demo && cd demo
+mkdir -p Old_Stuff RANDOM new_new_final download untitled_folder
+
+# Tag the root
+folder-nature init . --template workspace --name "demo-workspace"
+
+# Show what got created
+folder-nature show .
+
+# Reorganize + tag the new structure
+mkdir -p projects/{active,archive} clients/{acme,startup-x} documents
+folder-nature init projects/active --template workspace
+folder-nature init projects/archive --template archive
+folder-nature init clients --template client-project --name "my-clients"
+folder-nature init documents --template documentation
+
+# Search by meaning
+folder-nature search . --tag client
+folder-nature search . --being collector
+
+# Validate the tree
+folder-nature validate .
+
+# Tree view
+folder-nature list .
+```
+
+## Templates (`init --template`)
+
+Five archetypes ship with the package:
+
+| Template | When to use |
+|----------|-------------|
+| `workspace` | Active project working directory |
+| `client-project` | Client-specific work folder |
+| `archive` | Historical / inactive storage |
+| `deployment` | Production-touching configs and scripts |
+| `documentation` | Docs, references, guides |
+
+Customize at init time with `--name "your-name"` or edit the resulting
+`.folder-nature` file directly afterward.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `folder-nature init [PATH] [--template T]` | Create a new `.folder-nature` |
+| `folder-nature show [PATH]` | Print closest `.folder-nature` (walks up) |
+| `folder-nature query [PATH]` | Find the `director: true` ancestor |
+| `folder-nature search [ROOT] [--tag T] [--being B] [--name N]` | Filter folders by criteria |
+| `folder-nature validate [ROOT]` | Schema-check all `.folder-nature` files in tree |
+| `folder-nature list [ROOT]` | Tree view of every tagged folder |
+| `folder-nature version` | Print tool + schema versions |
+
+`PATH` and `ROOT` default to the current directory.
+
+## Schema v1.0
+
+A `.folder-nature` file is YAML with this shape:
+
+```yaml
+schema_version: "1.0"             # REQUIRED
+
+identity:                         # REQUIRED
+  name: "Projects"
+  being: "director"
+  purpose: "Canonical root for all work"
+
+director: true                    # OPTIONAL (default false)
+
+tags:                             # OPTIONAL
+  - work
+  - canonical
+  - active
+
+rules:                            # OPTIONAL
+  - "Only deployed code lives here"
+
+memory:                           # OPTIONAL
+  created: "2026-05-09"
+  last_significant_change: "2026-06-22"
+  notable_events:
+    - "2026-05-09: initial setup"
+```
+
+The `identity.being` field accepts a controlled vocabulary plus arbitrary
+custom values (extensibility hatch). Known types:
+
+`director` · `collector` · `workspace` · `assets` · `configs` ·
+`documentation` · `ideas` · `external` · `legal` · `team-shared` ·
+`private` · `system`
+
+## Design principles
+
+1. **Files, not databases.** Each folder owns its own YAML. Git-friendly,
+   editor-friendly, no central store.
+2. **Self-hosted.** Runs entirely local. No network calls. No telemetry.
+3. **Schema-versioned.** Future schema bumps migrate cleanly.
+4. **AI-readable.** Optional integration with LLM assistants — they query the
+   folder's nature before interacting with its contents.
+5. **Open from day one.** MIT licensed. Code reviewable. Schema documented.
+
+## Roadmap
+
+- **v0.1 (this release):** core MVP — schema, CLI, 5 templates, tests
+- **v0.2:** export/import, migration tool, more templates
+- **v1.0:** AI integration (`folder-nature ai-suggest`), filesystem watcher,
+  comprehensive docs
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Development
+
+```bash
+git clone https://github.com/myfjin/folder-nature
+cd folder-nature
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+Test suite: 66 tests covering schema validation, filesystem operations,
+search, and CLI integration. Should run in <1 second.
+
+## Origin
+
+folder-nature emerged from internal infrastructure work in early 2026 —
+a working hypothesis that filesystems become more useful when directories
+carry semantic identity. The concept proved itself on a 3-node operational
+mesh before being extracted as this standalone tool.
+
+🐍🦅💎

folder_nature-0.1.0/folder_nature/__init__.py

@@ -0,0 +1,57 @@
+"""folder-nature — semantic identity for filesystem folders.
+
+A directory becomes a conversation partner: it has identity, purpose, rules,
+and history, all captured in a hidden ``.folder-nature`` YAML file.
+
+Public API:
+
+    from folder_nature import (
+        FolderNature,
+        SchemaError,
+        find_director,
+        get_folder_nature,
+        write_folder_nature,
+        search,
+        validate,
+    )
+
+CLI entry point: ``folder-nature`` (see ``folder_nature.cli``).
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__schema_version__ = "1.0"
+
+from .schema import (
+    FolderNature,
+    SchemaError,
+    SCHEMA_VERSION,
+    BEING_TYPES,
+    validate as validate_data,
+)
+from .core import (
+    find_director,
+    get_folder_nature,
+    read_folder_nature,
+    write_folder_nature,
+    NATURE_FILENAME,
+)
+from .search import search, list_all
+
+__all__ = [
+    "__version__",
+    "__schema_version__",
+    "FolderNature",
+    "SchemaError",
+    "SCHEMA_VERSION",
+    "BEING_TYPES",
+    "NATURE_FILENAME",
+    "validate_data",
+    "find_director",
+    "get_folder_nature",
+    "read_folder_nature",
+    "write_folder_nature",
+    "search",
+    "list_all",
+]