Merge pull request #103 from MohammadKanaan/refactor/builtin-plugin-handling

Refactor/builtin plugin handling

Author: MohammadKanaan

.github/workflows/ci.yml

@@ -28,5 +28,14 @@ jobs:
       - name: Lint
         run: uv run ruff check
 
+      - name: Typecheck
+        run: uv run mypy nomnom
+
       - name: Test
         run: uv run pytest
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check distributions
+        run: uvx twine check dist/*

.gitignore

@@ -39,6 +39,7 @@ env/
 
 # Testing
 .pytest_cache/
+.mypy_cache/
 .coverage
 htmlcov/
 
@@ -47,13 +48,13 @@ htmlcov/
 
 # plugins
 plugins/*
-!plugins/nomnom-plugin-rules/
 rules.toml
 
 # config
 config.toml
 
 # ai tools
 .jules/
+.jj/
 .codex/
-.conductor/
+.conductor/

AGENTS.md

@@ -7,7 +7,7 @@
 - **Entry point:** `nomnom/cli.py` (Typer app)
 - **Package:** `nomnom/`
 - **Tests:** `tests/`
-- **Built-in plugin:** `plugins/nomnom-plugin-rules/`
+- **Built-in plugin:** `nomnom/builtin/rules.py`
 
 ## Tech Stack
 

CONTRIBUTING.md

@@ -30,7 +30,7 @@ Use the built-in scaffold to create a local plugin package:
 uv run nomnom plugin create my-plugin
 ```
 
-Local plugins live under `plugins/`. The repository currently includes `nomnom-plugin-rules` as a reference implementation.
+Local plugins live under `plugins/`. The built-in `rules` plugin is implemented in `nomnom.builtin.rules`.
 
 ## Pull Requests
 

README.md

@@ -21,6 +21,7 @@ pip install nomnom-py
 ### Initialize
 
 Generates a default `config.toml` in your project root.
+If you use the built-in `rules` plugin, keep `rules.toml` in that same directory so `nomnom` can read both files together.
 
 ```bash
 nomnom setup
@@ -39,19 +40,20 @@ Use `nomnom watch --once <group>` to process a single watch group one time, or `
 ## Example Configuration
 
 `nomnom` reads `config.toml` from the current project by default, or a custom path passed with `--config`.
+When the built-in `rules` plugin is enabled, `nomnom` also reads `rules.toml` from that same directory.
 
 ```toml
 [[watch]]
 name = "inbox"
 paths = ["./fixtures/inbox"]
-extensions = [".pdf", ".txt"]
+include = ["*.pdf", "*.txt"]
 
 [[watch]]
 name = "archive"
 paths = ["./fixtures/archive"]
 
 [[plugins]]
-name = "nomnom-plugin-rules"
+name = "rules"
 priority = 10
 enabled = true
 ```
@@ -63,7 +65,10 @@ For a fuller starter file, see [`config.example.toml`](config.example.toml).
 ### 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.
+It ships with the main `nomnom-py` install and is configured as `rules`.
+Keep `config.toml` and `rules.toml` side by side. If you run `nomnom --config /path/to/config.toml`, the built-in plugin will read `/path/to/rules.toml` automatically.
+See [`RULES.md`](RULES.md) for the rule format and supported actions, and
+[`rules.example.toml`](rules.example.toml) for a starter example.
 
 ### Installing Community Plugins
 
@@ -97,6 +102,7 @@ If you'd like to publish your plugin, move it to its own repo and publish it to
 uv sync --dev
 uv run pytest
 uv run ruff check
+uv run mypy nomnom
 ```
 
 Contributor guidance lives in [`CONTRIBUTING.md`](CONTRIBUTING.md).
@@ -106,7 +112,7 @@ Contributor guidance lives in [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
 ```text
 Core Commands:
-  nomnom watch [GROUP] [OPTS]   Start watching (Opts: -c/--config, -v/--verbose, --dry-run, --once)
+  nomnom watch [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
 

plugins/nomnom-plugin-rules/README.md RULES.mdplugins/nomnom-plugin-rules/README.md renamed to RULES.md

@@ -1,10 +1,9 @@
-# nomnom-plugin-rules
+# Rules Plugin
 
-This is a built-in plugin for simple workflows.
+`nomnom` ships with a built-in `rules` plugin for simple file automation.
 
-If you are an AI, follow the rules below attentively to implement what the user asked you to implement.
-
-Define file-event rules in `rules.toml`.
+Define file-event rules in `rules.toml` next to your active `config.toml`.
+`nomnom` scans those two files together: by default it reads both from the current project directory, and if you pass `--config /path/to/config.toml` it will read `/path/to/rules.toml`.
 
 ## Rule Format
 
@@ -52,3 +51,9 @@ content = "..."             # required for prepend/append
 - Missing `rules.toml`: plugin starts with no rules and logs an info message.
 - Invalid TOML syntax: plugin starts with no rules and logs a warning.
 - Invalid rules handling: Invalid rules are skipped and a warning is logged; other rules still load.
+
+## File Placement
+
+- Keep `config.toml` and `rules.toml` in the same directory.
+- Relative paths inside `config.toml` are resolved from the config file's directory.
+- The built-in `rules` plugin reads the colocated `rules.toml` from that same directory.

config.example.toml

@@ -1,5 +1,7 @@
+# Keep this file next to rules.toml when using the built-in rules plugin.
+# nomnom reads both files from the same directory.
 plugins = [
-    { name = "nomnom-plugin-rules", priority = 10 },
+    { name = "rules", priority = 10 },
 ]
 
 [[watch]]

nomnom/builtin/__init__.py

@@ -0,0 +1,3 @@
+from nomnom.builtin.rules import RulesPlugin
+
+__all__ = ["RulesPlugin"]

…in-rules/nomnom_plugin_rules/__init__.py nomnom/builtin/rules/__init__.pyplugins/nomnom-plugin-rules/nomnom_plugin_rules/__init__.py renamed to nomnom/builtin/rules/__init__.py plugins/nomnom-plugin-rules/nomnom_plugin_rules/__init__.py renamed to nomnom/builtin/rules/__init__.py

@@ -11,9 +11,6 @@
 
 logger = logging.getLogger(__name__)
 
-PLUGIN_ROOT = Path(__file__).resolve().parent.parent
-RULES_PATH = PLUGIN_ROOT / "rules.toml"
-
 VALID_EVENTS = {"created", "modified", "deleted"}
 VALID_ACTIONS = {"prepend", "append", "delete", "move"}
 
@@ -37,11 +34,11 @@ def matches(self, event_type_value: str, watch_group: str, path_name: str) -> bo
 
 
 class RulesPlugin:
-    def __init__(self) -> None:
+    def __init__(self, rules_path: Path | None = None) -> None:
+        self._rules_path = rules_path or Path("rules.toml")
         self._rules = self._load_rules()
 
     def matches(self, event: FileEvent) -> bool:
-        # Cache properties to avoid redundant attribute access overhead in the loop
         event_type_value = event.event_type.value
         watch_group = event.watch_group
         path_name = event.path.name
@@ -50,7 +47,6 @@ def matches(self, event: FileEvent) -> bool:
     def handle(self, event: FileEvent) -> list[Effect]:
         effects: list[Effect] = []
 
-        # Cache properties to avoid redundant attribute access overhead in the loop
         event_type_value = event.event_type.value
         watch_group = event.watch_group
         path_name = event.path.name
@@ -91,14 +87,14 @@ def handle(self, event: FileEvent) -> list[Effect]:
         return effects
 
     def _load_rules(self) -> list[Rule]:
-        if not RULES_PATH.is_file():
-            logger.info("Rules file not found at %s", RULES_PATH)
+        if not self._rules_path.is_file():
+            logger.info("Rules file not found at %s", self._rules_path)
             return []
 
         try:
-            raw = tomllib.loads(RULES_PATH.read_text())
+            raw = tomllib.loads(self._rules_path.read_text())
         except Exception as exc:
-            logger.warning("Failed to parse rules file at %s: %s", RULES_PATH, exc)
+            logger.warning("Failed to parse rules file at %s: %s", self._rules_path, exc)
             return []
 
         items = raw.get("rule")
@@ -117,7 +113,7 @@ def _load_rules(self) -> list[Rule]:
         logger.info(
             "Loaded %d rule(s) from %s. Restart nomnom to pick up changes.",
             len(rules),
-            RULES_PATH,
+            self._rules_path,
         )
         return rules
 
@@ -147,9 +143,7 @@ def _parse_rule(candidate: object) -> Rule | None:
 
     if action in {"prepend", "append"} and not isinstance(content, str):
         return None
-    if action == "move" and (
-        not isinstance(destination, str) or not destination.strip()
-    ):
+    if action == "move" and (not isinstance(destination, str) or not destination.strip()):
         return None
 
     try:

nomnom/commands/plugin.py

@@ -1,4 +1,5 @@
 from pathlib import Path
+from subprocess import CompletedProcess
 
 import typer
 from rich.console import Console
@@ -105,27 +106,53 @@ def _remove_plugin_from_config(config_path: Path, plugin_name: str) -> bool:
     return False
 
 
+def _run_package_command(*, action: str, package: str) -> CompletedProcess[str]:
+    import subprocess
+    import sys
+
+    if action == "install":
+        commands = [
+            ["uv", "pip", "install", "--python", sys.executable, "--", package],
+            [sys.executable, "-m", "pip", "install", package],
+        ]
+    elif action == "uninstall":
+        commands = [
+            ["uv", "pip", "uninstall", "--python", sys.executable, package],
+            [sys.executable, "-m", "pip", "uninstall", "-y", package],
+        ]
+    else:
+        raise ValueError(f"Unsupported package action: {action}")
+
+    last_error: OSError | None = None
+    for command in commands:
+        try:
+            return subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+            )
+        except OSError as e:
+            last_error = e
+
+    if last_error is not None:
+        raise last_error
+
+    raise RuntimeError("No package command was attempted")
+
+
 def plugin_add_command(
     *,
     package: str,
     no_setup: bool,
     config_path: Path,
 ) -> None:
-    import subprocess
-    import sys
-
     typer.echo(f"Installing {package}...")
     installed_before = get_installed_plugin_names()
-    install_cmd = ["uv", "pip", "install", "--python", sys.executable, "--", package]
 
     try:
-        result = subprocess.run(
-            install_cmd,
-            capture_output=True,
-            text=True,
-        )
+        result = _run_package_command(action="install", package=package)
     except OSError as e:
-        typer.echo(f"Installation failed: could not execute '{install_cmd[0]}': {e}")
+        typer.echo(f"Installation failed: could not execute a package installer: {e}")
         raise typer.Exit(1) from e
 
     if result.returncode != 0:
@@ -165,21 +192,13 @@ def plugin_remove_command(
     package: str,
     config_path: Path,
 ) -> None:
-    import subprocess
-    import sys
-
     typer.echo(f"Removing {package}...")
     installed_before = get_installed_plugin_names()
-    uninstall_cmd = ["uv", "pip", "uninstall", "--python", sys.executable, package]
 
     try:
-        result = subprocess.run(
-            uninstall_cmd,
-            capture_output=True,
-            text=True,
-        )
+        result = _run_package_command(action="uninstall", package=package)
     except OSError as e:
-        typer.echo(f"Removal failed: could not execute '{uninstall_cmd[0]}': {e}")
+        typer.echo(f"Removal failed: could not execute a package installer: {e}")
         raise typer.Exit(1) from e
 
     if result.returncode != 0:
@@ -248,7 +267,7 @@ def plugin_list_command(
     config_path: Path,
     console: Console,
 ) -> None:
-    discovered = discover_plugins()
+    discovered = discover_plugins(rules_path=config_path.parent.resolve() / "rules.toml")
     discovered_names = {name for name, _ in discovered}
 
     config_plugins = {}