agent-nook 0.1.2__tar.gz

agent_nook-0.1.2/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,143 @@
+name: Publish Python 🐍 distribution 📦 to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+      - 'b*'
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.x'
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build a binary wheel and a source tarball
+        run: python -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          retention-days: 3
+
+  validate-tag:
+    name: Validate tag format
+    runs-on: ubuntu-latest
+    outputs:
+      is-valid-version: ${{ steps.validate.outputs.is-valid-version }}
+      is-prerelease: ${{ steps.validate.outputs.is-prerelease }}
+      version-matches: ${{ steps.validate.outputs.version-matches }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Validate tag
+        id: validate
+        run: |
+          TAG="${{ github.ref_name }}"
+          VERSION_FILE="src/agent_nook/__init__.py"
+
+          # Single source of truth for the version; hatch reads this dynamically.
+          SRC_VERSION="$(grep -E "^[[:space:]]*__version__[[:space:]]*=" "$VERSION_FILE" \
+            | head -n1 \
+            | sed -E 's/.*= *"([^"]+)".*/\1/')"
+
+          # Strip a single leading v/b prefix from the tag to get the numeric version.
+          TAG_VERSION="$(printf '%s' "$TAG" | sed -E 's/^[vb]//')"
+
+          echo "tag='${TAG}' tag-version='${TAG_VERSION}' package-version='${SRC_VERSION}'"
+
+          # The tag version must match the version declared in the package.
+          if [[ "$TAG_VERSION" != "$SRC_VERSION" ]]; then
+            echo "::error::Tag version '${TAG_VERSION}' does not match the package version '${SRC_VERSION}' in src/agent_nook/__init__.py"
+            exit 1
+          fi
+          echo "version-matches=true" >> $GITHUB_OUTPUT
+
+          # Tag format: vMAJOR.MINOR.PATCH is a stable release, bMAJOR.MINOR.PATCH is a beta.
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "is-valid-version=true" >> $GITHUB_OUTPUT
+            echo "is-prerelease=false" >> $GITHUB_OUTPUT
+          elif [[ "$TAG" =~ ^b[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "is-valid-version=true" >> $GITHUB_OUTPUT
+            echo "is-prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "is-valid-version=false" >> $GITHUB_OUTPUT
+            echo "is-prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, validate-tag]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-nook
+    permissions:
+      id-token: write
+    if: ${{ needs.validate-tag.outputs.is-valid-version == 'true' && needs.validate-tag.outputs.is-prerelease == 'false' && needs.validate-tag.outputs.version-matches == 'true' }}
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-test:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    runs-on: ubuntu-latest
+    needs: [build, validate-tag]
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/agent-nook
+    permissions:
+      id-token: write
+    if: ${{ needs.validate-tag.outputs.is-valid-version == 'true' && needs.validate-tag.outputs.version-matches == 'true' }}
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution 📦 to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  release:
+    name: Create GitHub Release 🏷️
+    runs-on: ubuntu-latest
+    needs: [build, validate-tag]
+    permissions:
+      contents: write
+    if: ${{ needs.validate-tag.outputs.is-valid-version == 'true' && needs.validate-tag.outputs.version-matches == 'true' }}
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        id: create_release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          body: ${{ needs.validate-tag.outputs.is-prerelease == 'false' && '🎉 A new stable release is available!' || '🧪 A new beta/pre-release is available!' }}
+          prerelease: ${{ needs.validate-tag.outputs.is-prerelease == 'true' }}

agent_nook-0.1.2/.github/workflows/tests.yml

@@ -0,0 +1,65 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install bubblewrap
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bubblewrap
+          # Ubuntu 24.04 blocks unprivileged user namespaces by default
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+
+      - name: Verify bwrap works
+        run: bwrap --bind / / -- echo bwrap-ok
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Run test suite
+        run: ./run_tests.sh
+
+  lint:
+    name: ruff
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+          cache: pip
+
+      - name: Install package with dev extras
+        run: pip install -e ".[dev]"
+
+      - name: Run lint checks
+        run: ./run_lint.sh --check

agent_nook-0.1.2/.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

agent_nook-0.1.2/.lsp.json

@@ -0,0 +1,9 @@
+{
+  "python": {
+    "command": "pylsp",
+    "args": ["--check-parent-process"],
+    "extensionToLanguage": {
+      ".py": "python"
+    }
+  }
+}

agent_nook-0.1.2/.ruff.toml

@@ -0,0 +1,154 @@
+# Ruff configuration for pylsp LSP integration
+# This file is loaded by pylsp when it uses ruff for linting
+# See: https://github.com/charliermarsh/ruff-lsp
+
+# ───────────────────────────────────────────────────────────────────────────────
+# LSP CONFIGURATION RULES
+# ───────────────────────────────────────────────────────────────────────────────
+#
+# This configuration is specifically designed for the agent-nook project.
+# It enforces the following rules:
+#
+#   ✅ FIX AUTOMATICALLY (Error/Warning level):
+#     - E, W: pycodestyle errors/warnings (except minor style issues)
+#     - F: flake8 errors (undefined names, imports, etc.)
+#     - B: bugbear rules (bug-prone patterns)
+#     - I: import sorting
+#     - N: pep8-naming
+#     - C4: comprehensions
+#     - TCH: type checking hints
+#     - UP: pyupgrade (modernize code)
+#     - PLC, PLR, PLW: pylint rules (errors only, not warnings)
+#     - RUF: ruff-specific rules
+#     - SIM: flake8-simplify (simplify code)
+#     - BLE: flake8-blind-except
+#     - A: flake8-builtins (shadowing builtins)
+#
+#   🟡 IGNORE (Warning only, or suppress entirely):
+#     - D: pydocstyle (we use comprehensive docstrings)
+#     - ERA: eradicate (commented code)
+#     - FA: flake8-future-annotations (we use future imports)
+#     - PGH: pygrep-hooks (not needed)
+#     - PT: flake8-pytest-style (we have our own conventions)
+#     - RSE: flake8-raise (we use logging for errors)
+#     - S: flake8-bandit (security - we handle security manually)
+#     - SLF: flake8-self (private method access)
+#     - TID: flake8-tidy-imports (we allow relative imports)
+#     - TRY: tryceratops (we handle exceptions intentionally)
+#     - W191, W291, W293: Minor style issues (let humans decide)
+#     - PYI034, PYI036: Type hints (handled with type: ignore if needed)
+#     - C901: Too complex function (we keep complexity manageable)
+#     - PLR0911-PLR0917: Return/branch/arg/statement counts (we manage manually)
+#     - RUF012: Mutable defaults (we use dataclasses with field())
+#     - SIM102: Nested if statements (useful in some cases)
+#     - BLE001: Blind except (we handle specific exception types)
+#     - PLC0415: Function-level imports (needed for CLI)
+#     - PLR2004: Magic values (intentional)
+#     - PLW2901: Loop variable overwritten (intentional)
+#     - E712: Equality with True (use for clarity)
+#     - B007: Unused loop variable (intentional pattern)
+#     - PLW0603: Global statement (used in logger init)
+#     - TC003: Type checking imports (conditional use)
+#     - E501: Line too long (we have 135 char limit)
+#
+#   ❌ NEVER FIX (Critical issues we must handle manually):
+#     - No critical security issues (S*) - we handle security manually
+#     - No deprecated code (deprecated is warning only)
+#     - No known issues in production code
+# ───────────────────────────────────────────────────────────────────────────────
+
+# Line length (matches pep8, but we allow longer lines for docstrings)
+line-length = 135
+
+# Target Python version
+target-version = "py310"
+
+# Exclude patterns
+exclude = [
+    "__pycache__",
+    ".git",
+    "dist",
+    "build",
+    ".venv",
+    "venv",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".pytype",
+    "*.egg-info",
+]
+
+# Enable automatic fixing (safe fixes only)
+fix = true
+
+[lint]
+select = [
+    # pycodestyle errors and warnings
+    "E", "W",
+    # flake8
+    "F",
+    # bugbear
+    "B",
+    # isort
+    "I",
+    # pep8 naming
+    "N",
+    # comprehensions
+    "C4",
+    # type checking
+    "TCH",
+    # pyupgrade
+    "UP",
+    # pylint (errors only, not warnings)
+    "PLC", "PLR", "PLW",
+    # ruff-specific
+    "RUF",
+    # flake8-simplify
+    "SIM",
+    # flake8-blind-except
+    "BLE",
+    # flake8-builtins
+    "A",
+]
+
+# Rules to ignore
+ignore = [
+    "W191",  # Tab before character
+    "W291",  # Trailing whitespace (minor)
+    "W293",  # Blank line with whitespace (minor)
+    "PYI034", # Non-self return type
+    "PYI036", # Bad exit annotation
+    "C901",   # Too complex function
+    "PLR0911", # Too many return statements
+    "PLR0912", # Too many branches
+    "PLR0913", # Too many arguments
+    "PLR0915", # Too many statements
+    "PLR0917", # Too many positional arguments
+    "RUF012", # Mutable default value
+    "SIM102", # Collapsible if
+    "BLE001", # Blind except
+    "PLC0415", # Import at function level (CLI needs late imports)
+    "PLR2004", # Magic values
+    "PLW2901", # Loop variable overwritten
+    "E712",   # Equality with True
+    "B007",   # Unused loop variable
+    "PLW0603", # Global statement
+    "PLW0602", # Global statement with no assignment (logger.py)
+    "TC003",  # Type checking imports
+    "E501",   # Line too long (we have 135 char limit)
+]
+
+[lint.per-file-ignores]
+"src/agent_nook/config/loader.py" = ["TID252"]
+"src/agent_nook/config/config.py" = ["TID252"]
+"src/agent_nook/sandbox/builder.py" = ["TID252"]
+
+[lint.isort]
+force-single-line = true
+lines-after-imports = 2
+known-first-party = ["agent_nook"]
+
+[lint.pyflakes]
+allowed-unused-imports = []
+
+[lint.pycodestyle]
+max-line-length = 135

agent_nook-0.1.2/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS.md — Rules & Guidelines
+
+## Core Principles
+- **Simplicity first**: Straightforward solutions, no overengineering.
+- **Solid engineering**: Follow best practices, document everything.
+- **Unprivileged**: NO root/sudo. Runs as normal user.
+- **Sandboxing**: Bubblewrap (`bwrap`) ONLY. NO podman, docker, or apptainer. No dedicated images; starts from host FS. Uses `--unshare=cgroup`.
+
+## XDG Configuration & Paths
+- **Config**: `~/.config/agent-nook/sandbox.yaml` (default copied from `src/agent_nook/config/sandbox.yaml`), `logging.yaml`
+- **State/Logs**: `~/.local/state/agent-nook/`
+- **Cache**: `~/.local/state/agent-nook/cache/`
+- **Format**: Human-readable YAML. `/home` mounted as tmpfs by default.
+
+## Code Quality & DRY
+- **NEVER DUPLICATE CODE**: Do not copy-paste logic. If you write the same logic twice, you failed.
+- **Rule of Two (MANDATORY)**: If identical control flow, validation, or data processing appears ≥2 times, you MUST extract it into a shared, generic helper.
+- **Search First**: Always check existing utilities before writing new helpers, array manipulations, or API wrappers. Re-use and extend existing code.
+- **Single Source of Truth**: Business logic (validation, calculations, permissions) must exist in EXACTLY ONE authoritative location. NEVER duplicate domain rules across files.
+- **Avoid Over-Engineering**: Keep extracted helpers minimal and single-purpose. No complex "do-everything" functions with boolean flags.
+- **Permitted Duplication**: ONLY allowed for Unit/Integration tests (prioritize DAMP readability) and decoupled DTOs/schemas across distinct service boundaries.
+- **Refactoring Protocol**: If removing duplication requires changing public signatures or adding shared modules, PROPOSE the plan first and wait for approval.
+
+## Testing & Verification (MANDATORY)
+Run after EVERY change:
+- `./run_tests.sh`
+- `ruff check src/ --fix`
+- `ruff format src/`
+- Update tests for all behavior changes. Tests are the contract.
+
+## Linting (Ruff)
+- **Tool**: Ruff only. Line length: 135.
+- **Action**: Auto-fix safe violations. Use `# type: ignore` for intentional type issues.
+- **Disabled entirely**: D, ERA, FA, PGH, PT, RSE, S, SLF, TID, TRY.
+- **Ignore (manual review)**: W191, W291, W293, PYI034, PYI036, C901, PLR0911-PLR0917, RUF012, SIM102, BLE001, PLC0415, PLR2004, PLW2901, E712, B007, PLW0603, TC003, E501.
+
+## Documentation Contract
+Update docs for ANY change:
+- Signature change → Update docstrings.
+- Config/CLI change → Update README + examples.
+- New/Removed feature → Update README.
+- **Pre-commit**: Verify docstrings, README examples run, and remove dead code.
+
+## Error Handling
+- Wrap agent execution in `try/except` with specific exceptions.
+- Log `ERROR` with stack traces for debugging.
+- Use `sys.exit(non-zero)` for unrecoverable errors. Prominently report sandbox failures.
+
+## Git Hygiene (STRICT)
+- ONLY `git add <specific files>` or `git add -p`.
+- NEVER `git add -A` or `git add .`.
+- NEVER delete untracked files unless explicitly requested or part of the feature. Ask if unsure.