nomnom-py 1.0.0__tar.gz

nomnom_py-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check
+
+      - name: Test
+        run: uv run pytest

nomnom_py-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nomnom-py
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1

nomnom_py-1.0.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Project-specific
+*.toml.local
+
+# plugins
+plugins/*
+!plugins/nomnom-plugin-rules/
+rules.toml
+
+# config
+config.toml
+
+# ai tools
+.jules/
+.codex/
+.conductor/

nomnom_py-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

nomnom_py-1.0.0/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Project Overview
+
+**nomnom** is a plugin-based file watcher CLI. It watches directories for file changes and dispatches events to plugins that perform filesystem operations.
+
+- **Entry point:** `nomnom/cli.py` (Typer app)
+- **Package:** `nomnom/`
+- **Tests:** `tests/`
+- **Built-in plugin:** `plugins/nomnom-plugin-rules/`
+
+## Tech Stack
+
+- Python 3.11+ (use modern syntax: `match/case`, `X | Y` unions, dataclasses)
+- CLI: `typer`
+- File watching: `watchfiles`
+- Build: `hatchling`
+- Deps: `uv`
+
+## Code Style
+
+- **Linter:** ruff — rules: E, F, W, I, UP, B, SIM. Line length: 100.
+- **Type checker:** mypy — strict mode enabled, target Python 3.11.
+- Prefer `Protocol` over ABC for plugin interfaces.
+- Use `dataclass` for data types (effects, events).
+- Use `TYPE_CHECKING` guards to avoid circular imports.
+
+## Testing
+
+- Framework: `pytest`
+- Run: `uv run pytest`
+- Test files: `tests/test_<module>.py`
+- Fixtures in `tests/conftest.py` (e.g. `make_event`, `StubPlugin`)
+
+## Commits
+
+- Keep commits minimal; describe the overview of changes.
+- Prefix with one of: `feat:`, `fix:`, `test:`, `refactor:`
+
+## Architecture
+
+- **Event-driven:** `watchfiles` detects changes → `FileEvent` objects are created.
+- **Plugin protocol:** plugins implement `matches(event)` and `handle(event)`.
+- **Effect system:** plugins return `Effect` objects (`MoveFile`, `DeleteFile`, `CreateFile`, `EditFile`, `EmitEvent`).
+- **Dispatcher:** routes events to matching plugins with depth-limited recursion for `EmitEvent`.
+- **Executor:** performs atomic file operations (tempfile + rename).
+- **Discovery:** plugins are loaded via Python entry points.
+- **Config:** TOML-based (`config.toml`) with watch groups and plugin settings.
+
+## Key Commands
+
+```sh
+uv run pytest              # run tests
+uv run ruff check .        # lint
+uv run mypy nomnom         # typecheck
+uv run nomnom --help       # CLI help
+```

nomnom_py-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Development Setup
+
+```bash
+uv sync --dev
+```
+
+This installs the project and the development toolchain into the local virtual environment managed by `uv`.
+
+## Common Commands
+
+```bash
+uv run pytest
+uv run ruff check
+uv run mypy
+```
+
+Run the full test suite before opening a pull request. If you change CLI behavior, also verify:
+
+```bash
+uv run nomnom --help
+```
+
+## Working on Plugins
+
+Use the built-in scaffold to create a local plugin package:
+
+```bash
+uv run nomnom plugin create my-plugin
+```
+
+Local plugins live under `plugins/`. The repository currently includes `nomnom-plugin-rules` as a reference implementation.
+
+## Pull Requests
+
+- Keep changes focused and minimal.
+- Add or update tests for behavior changes.
+- Update docs or examples when public-facing behavior changes.
+- Prefer small commits with clear messages.

nomnom_py-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Mohamad Kenaan]
+
+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.

nomnom_py-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: nomnom-py
+Version: 1.0.0
+Summary: Plugin-based CLI file watcher
+Project-URL: Homepage, https://github.com/MohammadKanaan/nomnom-py
+Project-URL: Repository, https://github.com/MohammadKanaan/nomnom-py
+Project-URL: Issues, https://github.com/MohammadKanaan/nomnom-py/issues
+Author-email: Mohammad Kanaan <mohammadkanaan.me@gmail.com>
+License: MIT
+License-File: LICENSE.md
+Keywords: cli,file-watcher,plugins
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.9
+Requires-Dist: watchfiles>=0.21
+Description-Content-Type: text/markdown
+
+# nomnom
+
+`nomnom` is an extensible file watcher for local automation. The core detects file changes and fires events. Plugins do the actual work: moving files, enriching them, or kicking off downstream workflows.
+
+## Install
+
+```bash
+pip install nomnom-py
+```
+
+## Quick Start
+
+### Initialize
+
+Generates a default `config.toml` in your project root.
+
+```bash
+nomnom setup
+```
+
+### Watch
+
+Starts watching your directories based on the configuration.
+
+```bash
+nomnom watch
+```
+
+Use `nomnom watch --once <group>` to process a single watch group one time, or `nomnom watch --dry` to inspect behavior without applying file effects.
+
+## Example Configuration
+
+`nomnom` reads `config.toml` from the current project by default, or a custom path passed with `--config`.
+
+```toml
+[[watch]]
+name = "inbox"
+paths = ["./fixtures/inbox"]
+extensions = [".pdf", ".txt"]
+
+[[watch]]
+name = "archive"
+paths = ["./fixtures/archive"]
+
+[[plugins]]
+name = "nomnom-plugin-rules"
+priority = 10
+enabled = true
+```
+
+For a fuller starter file, see [`config.example.toml`](config.example.toml).
+
+## Plugins
+
+### The Built-in Rules Plugin
+
+A rules plugin for declarative file automation driven by `rules.toml`.
+See [`plugins/nomnom-plugin-rules/README.md`](plugins/nomnom-plugin-rules/README.md) for the rule format and supported actions.
+
+### Installing Community Plugins
+
+Plugins can be installed from PyPI or directly from a Git repository:
+
+```bash
+nomnom plugin add <package-name-or-git-url>
+```
+
+Example:
+
+```bash
+nomnom plugin add git+https://github.com/<owner>/nomnom-plugin-example
+```
+
+### Creating a Plugin
+
+Scaffold a local plugin package inside `plugins/`:
+
+```bash
+nomnom plugin create <name>
+```
+
+The generated package includes a `pyproject.toml` entry point and a stub plugin module. Local plugins are automatically discoverable, no need to configure them.
+
+If you'd like to publish your plugin, move it to its own repo and publish it to GitHub or PyPI. There is no system for discovering plugins yet but shoot me an email if interested.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check
+```
+
+Contributor guidance lives in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+
+## CLI Reference
+
+```text
+Core Commands:
+  nomnom watch [GROUP] [OPTS]   Start watching (Opts: -c/--config, -v/--verbose, --dry-run, --once)
+  nomnom setup [OPTS]           Create or update the config file
+  nomnom --version / -v         Print installed version
+
+Plugin Management:
+  nomnom plugin add PACKAGE     Install and register a plugin
+  nomnom plugin remove PACKAGE  Remove a plugin
+  nomnom plugin enable NAME     Enable a plugin in config
+  nomnom plugin disable NAME    Disable a plugin in config
+  nomnom plugin list            List active plugins
+  nomnom plugin setup           Run setup for specific/all plugins
+  nomnom plugin create NAME     Scaffold a new local plugin
+```

nomnom_py-1.0.0/README.md

@@ -0,0 +1,113 @@
+# nomnom
+
+`nomnom` is an extensible file watcher for local automation. The core detects file changes and fires events. Plugins do the actual work: moving files, enriching them, or kicking off downstream workflows.
+
+## Install
+
+```bash
+pip install nomnom-py
+```
+
+## Quick Start
+
+### Initialize
+
+Generates a default `config.toml` in your project root.
+
+```bash
+nomnom setup
+```
+
+### Watch
+
+Starts watching your directories based on the configuration.
+
+```bash
+nomnom watch
+```
+
+Use `nomnom watch --once <group>` to process a single watch group one time, or `nomnom watch --dry` to inspect behavior without applying file effects.
+
+## Example Configuration
+
+`nomnom` reads `config.toml` from the current project by default, or a custom path passed with `--config`.
+
+```toml
+[[watch]]
+name = "inbox"
+paths = ["./fixtures/inbox"]
+extensions = [".pdf", ".txt"]
+
+[[watch]]
+name = "archive"
+paths = ["./fixtures/archive"]
+
+[[plugins]]
+name = "nomnom-plugin-rules"
+priority = 10
+enabled = true
+```
+
+For a fuller starter file, see [`config.example.toml`](config.example.toml).
+
+## Plugins
+
+### The Built-in Rules Plugin
+
+A rules plugin for declarative file automation driven by `rules.toml`.
+See [`plugins/nomnom-plugin-rules/README.md`](plugins/nomnom-plugin-rules/README.md) for the rule format and supported actions.
+
+### Installing Community Plugins
+
+Plugins can be installed from PyPI or directly from a Git repository:
+
+```bash
+nomnom plugin add <package-name-or-git-url>
+```
+
+Example:
+
+```bash
+nomnom plugin add git+https://github.com/<owner>/nomnom-plugin-example
+```
+
+### Creating a Plugin
+
+Scaffold a local plugin package inside `plugins/`:
+
+```bash
+nomnom plugin create <name>
+```
+
+The generated package includes a `pyproject.toml` entry point and a stub plugin module. Local plugins are automatically discoverable, no need to configure them.
+
+If you'd like to publish your plugin, move it to its own repo and publish it to GitHub or PyPI. There is no system for discovering plugins yet but shoot me an email if interested.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check
+```
+
+Contributor guidance lives in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+
+## CLI Reference
+
+```text
+Core Commands:
+  nomnom watch [GROUP] [OPTS]   Start watching (Opts: -c/--config, -v/--verbose, --dry-run, --once)
+  nomnom setup [OPTS]           Create or update the config file
+  nomnom --version / -v         Print installed version
+
+Plugin Management:
+  nomnom plugin add PACKAGE     Install and register a plugin
+  nomnom plugin remove PACKAGE  Remove a plugin
+  nomnom plugin enable NAME     Enable a plugin in config
+  nomnom plugin disable NAME    Disable a plugin in config
+  nomnom plugin list            List active plugins
+  nomnom plugin setup           Run setup for specific/all plugins
+  nomnom plugin create NAME     Scaffold a new local plugin
+```

nomnom_py-1.0.0/RELEASING.md

@@ -0,0 +1,48 @@
+# Releasing nomnom
+
+This project is set up to publish to PyPI from GitHub Actions using PyPI Trusted
+Publishing.
+
+## One-Time Setup
+
+1. Create a PyPI account for the maintainer if you do not already have one.
+2. In PyPI, go to `Account settings` -> `Publishing`.
+3. Add a pending trusted publisher with:
+   - PyPI project name: `nomnom-py`
+   - Owner: `MohammadKanaan`
+   - Repository: `nomnom-py`
+   - Workflow file: `publish.yml`
+   - Environment: `pypi`
+4. In GitHub, create an environment named `pypi`.
+5. Require manual approval for that environment before the publish job runs.
+
+## Release Checklist
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run mypy nomnom
+uv build
+uvx twine check dist/*
+```
+
+## Publish a Release
+
+1. Update `[project].version` in `pyproject.toml`.
+2. Commit the release changes.
+3. Create and push a tag that matches the version:
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+4. Approve the `pypi` environment in GitHub when the `Publish` workflow starts.
+5. Confirm the release at `https://pypi.org/project/nomnom-py/`.
+
+## Notes
+
+- `dist/` should be treated as build output; rebuild it for every release.
+- If you want to dry-run the pipeline before the first public release, publish to
+  TestPyPI manually instead of tagging production.

nomnom_py-1.0.0/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do not open public GitHub issues for security problems.
+
+Use GitHub's private vulnerability reporting flow if it is enabled for the repository. If that is not available, contact the maintainer privately through GitHub and include:
+
+- a description of the issue
+- affected versions or commit hashes
+- reproduction steps or a proof of concept
+- any suggested mitigation
+
+I will acknowledge valid reports as quickly as possible and coordinate a fix before public disclosure.
+
+## Supported Versions
+
+Security fixes are best-effort and prioritized for the latest release on the `main` branch.

nomnom_py-1.0.0/config.example.toml

@@ -0,0 +1,11 @@
+plugins = [
+    { name = "nomnom-plugin-rules", priority = 10 },
+]
+
+[[watch]]
+name = "transcribe"
+paths = [
+    "./fixtures/audio",
+]
+# include = ["*.wav", "*.mp3"]
+# exclude = ["*.tmp", "~*"]

nomnom_py-1.0.0/nomnom/__init__.py

@@ -0,0 +1,28 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from nomnom.effects import CreateFile, DeleteFile, EditAction, EditFile, Effect, EmitEvent, MoveFile
+from nomnom.events import EventType, FileEvent
+from nomnom.plugin import Plugin, SetupPlugin
+
+
+def get_version() -> str:
+    try:
+        return version("nomnom-py")
+    except PackageNotFoundError:
+        return "dev"
+
+
+__all__ = [
+    "Plugin",
+    "SetupPlugin",
+    "FileEvent",
+    "EventType",
+    "Effect",
+    "MoveFile",
+    "DeleteFile",
+    "CreateFile",
+    "EditFile",
+    "EmitEvent",
+    "EditAction",
+    "get_version",
+]