nerftools 0.3.1__tar.gz

nerftools-0.3.1/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "nerftools-marketplace",
+  "owner": {
+    "name": "Wayfarer Labs"
+  },
+  "plugins": [
+    {
+      "name": "nerftools",
+      "description": "Limited scope wrappers for common CLI utilities, allows for fine-grained control over agent execution",
+      "source": "./out/claude-plugin"
+    }
+  ]
+}

nerftools-0.3.1/.cspell.json

@@ -0,0 +1,57 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "agentic",
+    "Agentworks",
+    "bunx",
+    "dataclass",
+    "dataclasses",
+    "defanged",
+    "elif",
+    "esac",
+    "execdir",
+    "exitcode",
+    "frontmatter",
+    "gwat",
+    "invokable",
+    "metacharacter",
+    "metacharacters",
+    "myapp",
+    "mypy",
+    "mywi",
+    "nerfctl",
+    "nerfed",
+    "nerftools",
+    "noprofile",
+    "norc",
+    "okdir",
+    "oneline",
+    "permissioning",
+    "pipefail",
+    "pkgrun",
+    "pnpx",
+    "pyproject",
+    "pytest",
+    "pytestmark",
+    "rulesync",
+    "Rulesync",
+    "stdutils",
+    "subshell",
+    "tmpl",
+    "upgen",
+    "uppercased",
+    "usecases",
+    "variadics",
+    "wiql",
+    "WIQL"
+  ],
+  "ignoreRegExpList": [
+    "`[^`\\r\\n]+`"
+  ],
+  "ignorePaths": [
+    "node_modules",
+    "out/",
+    "CHANGELOG.md"
+  ]
+}

nerftools-0.3.1/.editorconfig

@@ -0,0 +1,24 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 120
+
+[*.yml]
+indent_size = 2
+
+[*.toml]
+indent_size = 4
+
+[*.md]
+indent_size = 2
+max_line_length = 100
+trim_trailing_whitespace = false
+
+[*.json]
+indent_size = 2

nerftools-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Ruff check
+        run: uv run ruff check nerftools/ tests/
+
+      - name: Mypy
+        run: uv run mypy nerftools/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Pytest
+        run: uv run pytest tests/ -v
+
+  markdown:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: markdownlint
+        uses: DavidAnson/markdownlint-cli2-action@v23
+        with:
+          globs: "**/*.md"
+
+  spelling:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: cspell
+        uses: streetsidesoftware/cspell-action@v8
+        with:
+          files: "**/*.{md,py,yaml}"

nerftools-0.3.1/.github/workflows/release-please.yml

@@ -0,0 +1,78 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    env:
+      # release-please-action@v4 still declares node20; force node24 on the runner.
+      # Remove once the action publishes a node24 release (see googleapis/release-please-action#1192).
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+    outputs:
+      pr_branch: ${{ steps.extract.outputs.pr_branch }}
+      app_token: ${{ steps.app-token.outputs.token }}
+    steps:
+      # Use a GitHub App token so the release PR (and any subsequent pushes
+      # to its branch) trigger CI workflows. The default GITHUB_TOKEN creates
+      # events as github-actions[bot], which GitHub won't run workflows for.
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      - name: Extract release PR branch
+        id: extract
+        if: steps.release.outputs.pr
+        run: |
+          branch=$(echo '${{ steps.release.outputs.pr }}' | jq -r .headBranchName)
+          echo "pr_branch=$branch" >> "$GITHUB_OUTPUT"
+
+  regenerate-dist:
+    needs: release-please
+    if: needs.release-please.outputs.pr_branch
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v2
+        id: app-token
+        with:
+          app-id: ${{ vars.RELEASE_APP_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.release-please.outputs.pr_branch }}
+          token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Regenerate Claude Code plugin
+        run: uv run nerf generate --target claude-plugin --plugin-config nerf-plugin.yaml --outdir ./out/claude-plugin
+
+      - name: Commit updated plugin
+        run: |
+          git config user.name "nerftools-release[bot]"
+          git config user.email "nerftools-release[bot]@users.noreply.github.com"
+          git add out/claude-plugin/
+          if git diff --cached --quiet; then
+            echo "No changes to plugin output"
+          else
+            git commit -m "build: regenerate Claude Code plugin for release"
+            git push
+          fi

nerftools-0.3.1/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing via OIDC
+
+jobs:
+  verify-tag-on-main:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Verify tag is reachable from main
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "${{ github.sha }}" origin/main; then
+            echo "Error: tag ${{ github.ref_name }} is not an ancestor of main"
+            exit 1
+          fi
+
+  test:
+    needs: verify-tag-on-main
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Ruff check
+        run: uv run ruff check nerftools/ tests/
+
+      - name: Mypy
+        run: uv run mypy nerftools/
+
+      - name: Pytest
+        run: uv run pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build package
+        run: uv build --out-dir pypi-dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: pypi-dist/

nerftools-0.3.1/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# out/ contains pre-built targets (auto-generated, committed for distribution)
+
+# Virtual environments
+.venv/
+venv/
+
+# uv.lock is committed for reproducible CI builds
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Secrets / env files
+*.env*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# pytest
+.pytest_cache/
+htmlcov/
+.coverage

nerftools-0.3.1/.markdownlint-cli2.jsonc

@@ -0,0 +1,16 @@
+{
+  "config": {
+    "default": true,
+    "MD013": {
+      "line_length": 100,
+      "code_blocks": false,
+      "tables": false
+    },
+    "MD024": {
+      "siblings_only": true
+    },
+    "MD033": false,
+    "MD060": false
+  },
+  "ignores": ["out/**", "CHANGELOG.md"]
+}

nerftools-0.3.1/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "proseWrap": "always"
+      }
+    }
+  ]
+}

nerftools-0.3.1/.python-version

@@ -0,0 +1 @@
+3.12

nerftools-0.3.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.1"
+}

nerftools-0.3.1/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## [0.3.1](https://github.com/WayfarerLabs/nerftools/compare/v0.3.0...v0.3.1) (2026-04-14)
+
+
+### Bug Fixes
+
+* use app token for regenerate-dist pushes so CI triggers on release PRs ([e78ae87](https://github.com/WayfarerLabs/nerftools/commit/e78ae875208a100d77cde6cb0881186e61b83e60))
+
+## [0.3.0](https://github.com/WayfarerLabs/nerftools/compare/v0.2.0...v0.3.0) (2026-04-14)
+
+
+### Features
+
+* add --embed-marketplace option for standalone plugin deployment ([d00ae28](https://github.com/WayfarerLabs/nerftools/commit/d00ae28170857702a29141f24bec15c62e034c8b))
+* initial nerftools repo with Python package and pre-built Claude Code plugin ([55eee79](https://github.com/WayfarerLabs/nerftools/commit/55eee79eb462dfb996568d42e05b86fe3a11ce3a))
+* templatize plugin metadata via nerf-plugin.yaml config ([05086d6](https://github.com/WayfarerLabs/nerftools/commit/05086d63214351f2f9cef21fd4b6dc0679a52bd4))
+
+
+### Bug Fixes
+
+* doc update as fix to trigger release pipeline ([79ede3c](https://github.com/WayfarerLabs/nerftools/commit/79ede3c0f7fad1446e960bef3f943c5ca83e1a08))
+* drop component prefix from release-please tags to match release … ([ac70693](https://github.com/WayfarerLabs/nerftools/commit/ac70693efa1e418348e5b7f10b964ebed82258db))
+* drop component prefix from release-please tags to match release workflow ([6f92386](https://github.com/WayfarerLabs/nerftools/commit/6f92386f6fdc3dab9b63cc12ad9fcfead327382b))
+
+
+### Documentation
+
+* additional readme tweaks ([4f7267f](https://github.com/WayfarerLabs/nerftools/commit/4f7267f8112c215ffc0fd50d0cdd2a9d6430ea87))
+* document the release process in CONTRIBUTING.md ([cfd29c8](https://github.com/WayfarerLabs/nerftools/commit/cfd29c8b144d17d58232c6b8677451c427627d8a))
+* fix manifest spec link and split threat model content between README and spec ([60493c8](https://github.com/WayfarerLabs/nerftools/commit/60493c846bb9fbffde8875a576a4698e4ae2e461))
+* move manifest guide and ref from readme ([6392c0b](https://github.com/WayfarerLabs/nerftools/commit/6392c0b716892080137b133487f3a536650590b3))
+* polish README intro and update quick start with --plugin-config ([6cd3dde](https://github.com/WayfarerLabs/nerftools/commit/6cd3dde8c3b98dc8be7c57b1d0a3de84429bd9d0))
+* update readme with additional context ([a93632d](https://github.com/WayfarerLabs/nerftools/commit/a93632dd217d5dad44ee4df3c86a31c282640636))
+
+## [0.2.0](https://github.com/WayfarerLabs/nerftools/compare/nerftools-v0.1.0...nerftools-v0.2.0) (2026-04-14)
+
+
+### Features
+
+* add --embed-marketplace option for standalone plugin deployment ([d00ae28](https://github.com/WayfarerLabs/nerftools/commit/d00ae28170857702a29141f24bec15c62e034c8b))
+* initial nerftools repo with Python package and pre-built Claude Code plugin ([55eee79](https://github.com/WayfarerLabs/nerftools/commit/55eee79eb462dfb996568d42e05b86fe3a11ce3a))
+* templatize plugin metadata via nerf-plugin.yaml config ([05086d6](https://github.com/WayfarerLabs/nerftools/commit/05086d63214351f2f9cef21fd4b6dc0679a52bd4))
+
+
+### Bug Fixes
+
+* doc update as fix to trigger release pipeline ([79ede3c](https://github.com/WayfarerLabs/nerftools/commit/79ede3c0f7fad1446e960bef3f943c5ca83e1a08))
+
+
+### Documentation
+
+* additional readme tweaks ([4f7267f](https://github.com/WayfarerLabs/nerftools/commit/4f7267f8112c215ffc0fd50d0cdd2a9d6430ea87))
+* document the release process in CONTRIBUTING.md ([cfd29c8](https://github.com/WayfarerLabs/nerftools/commit/cfd29c8b144d17d58232c6b8677451c427627d8a))
+* fix manifest spec link and split threat model content between README and spec ([60493c8](https://github.com/WayfarerLabs/nerftools/commit/60493c846bb9fbffde8875a576a4698e4ae2e461))
+* move manifest guide and ref from readme ([6392c0b](https://github.com/WayfarerLabs/nerftools/commit/6392c0b716892080137b133487f3a536650590b3))
+* polish README intro and update quick start with --plugin-config ([6cd3dde](https://github.com/WayfarerLabs/nerftools/commit/6cd3dde8c3b98dc8be7c57b1d0a3de84429bd9d0))
+* update readme with additional context ([a93632d](https://github.com/WayfarerLabs/nerftools/commit/a93632dd217d5dad44ee4df3c86a31c282640636))

nerftools-0.3.1/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing
+
+This is designed to be an opinionated project with high standards for code quality, documentation,
+and design. Contributions must meet these standards and follow the guidelines outlined in this
+document. I highly recommend creating discussions or issues to propose and discuss changes before
+putting in the work to implement them, especially for larger changes.
+
+All that said, I'd love to see high-quality contributions of all sizes, from fixing typos to adding
+major features.
+
+## Conventional Commits
+
+All commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/)
+specification. This is not just a style preference -- commit types drive automated versioning
+(see [Releases](#releases) below).
+
+Commit types that trigger version bumps:
+
+- `feat:` -> minor version bump
+- `fix:` / `perf:` -> patch version bump
+- `feat!:` / `fix!:` / any commit with `BREAKING CHANGE:` in the body -> major version bump
+
+Other types (`docs:`, `chore:`, `refactor:`, `test:`, `ci:`, `build:`, `style:`, `revert:`) do not
+trigger a release on their own but still appear in the changelog.
+
+When squash-merging a PR, set the PR title to the desired conventional commit message -- GitHub
+uses that as the squash commit message, which is what `release-please` reads.
+
+## Code Quality
+
+- **Python**: ruff (linting + formatting), mypy (type checking), pytest
+- **Markdown**: markdownlint, prettier, cspell
+- Custom dictionaries are maintained in `.cspell.json`
+
+## Rebuilding the Claude Code Plugin Locally
+
+After changing manifests or plugin generation code, you can rebuild the pre-built plugin locally
+to preview the output:
+
+```bash
+uv run nerf generate --target claude-plugin --plugin-config nerf-plugin.yaml --outdir ./out/claude-plugin
+```
+
+You don't need to commit the regenerated `out/` -- CI regenerates it as part of the release PR.
+But committing it can be useful so reviewers can see the exact generated output in your PR diff.
+
+## Releases
+
+Releases are fully automated via [`release-please`](https://github.com/googleapis/release-please)
+and conventional commits. No one manually bumps versions or creates tags.
+
+### How a release happens
+
+1. Feature PRs land on `main` with conventional commit messages.
+2. The `release-please` workflow keeps an open PR titled `chore(main): release X.Y.Z` that
+   accumulates changes. On each push to `main` it:
+   - Computes the next version from the conventional commits since the last release.
+   - Updates the version in `pyproject.toml`, `nerf-plugin.yaml`, and `.release-please-manifest.json`.
+   - Updates `CHANGELOG.md`.
+   - Regenerates `out/claude-plugin/` with the new version baked into `plugin.json`.
+3. When you're ready to release, merge the release PR.
+4. On merge, `release-please` creates the git tag (`vX.Y.Z`) and a GitHub Release.
+5. The tag push triggers the `release` workflow, which verifies the tag is on `main`, runs the
+   test suite, and publishes to PyPI via trusted publishing.
+
+### What you do as a maintainer
+
+- Review and merge feature PRs normally.
+- When you want to cut a release, review the release PR (check the version bump and the changelog)
+  and merge it. That's it.
+
+### What you *don't* do
+
+- Don't edit version numbers by hand in any file. `release-please` owns them.
+- Don't create tags by hand. `release-please` creates tags on merge of the release PR.
+- Don't edit `CHANGELOG.md` by hand. It's regenerated from commit messages.
+- Don't edit `out/claude-plugin/` by hand. Edit the source (`nerftools/`, manifests, or
+  `nerf-plugin.yaml`) and the release PR will regenerate it.
+
+### Breaking changes
+
+To signal a breaking change, use `!` in the commit type or add a `BREAKING CHANGE:` footer:
+
+```text
+feat!: rename --embed-marketplace to --standalone
+
+BREAKING CHANGE: the --embed-marketplace flag has been replaced with --standalone.
+```
+
+Either form bumps the major version.

nerftools-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Scot Hastings
+
+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.

nerftools-0.3.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: nerftools
+Version: 0.3.1
+Summary: Build and manage nerf tools -- defanged, scoped wrappers for agent use
+Project-URL: Homepage, https://github.com/WayfarerLabs/nerftools
+Project-URL: Repository, https://github.com/WayfarerLabs/nerftools
+Project-URL: Issues, https://github.com/WayfarerLabs/nerftools/issues
+Author: Robert Scot Hastings
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.24.1