feat: plugin-ify ?jp=<jsonpath> modifier (#19)

* feat(jsonpath): moved Secret Modifier `?jp=<jsonpath>` under `/plugin`

This is a course-correction, as this modifier uses an external dependency, and so it should have been a plugin from the start.

* feat(tooling): integrate govulncheck and modularize asdf setup

- Add govulncheck to the toolchain and run it automatically during CI.
- Modularize ASDF plugin and tool setup with task commands (tools.plugins, tools.update, tools.install).
- Update developer guides and documentation to match the new bootstrap workflow.

💘 Generated with Crush

Assisted-by: Crush:gemini-3.5-flash

* fix: allow to install asdf plugins off main registry in CI

* chore: fix `examples/viper`

Author: detro

.github/workflows/ci.yaml

@@ -23,8 +23,19 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
-      - name: Install asdf & tools
-        uses: asdf-vm/actions/install@v4
+      - name: Install asdf
+        uses: asdf-vm/actions/setup@v4
+
+      - name: Install Task
+        run: |
+          asdf plugin add task
+          asdf install task
+
+      - name: Install (rest of the) Tools
+        run: task tools.install
+
+      - name: Vulnerability Scan
+        run: task vuln
 
       - name: Build
         run: task build

.tool-versions

@@ -1,3 +1,4 @@
-task 3.50.0
+task 3.51.1
 golang 1.26.3
 golangci-lint 2.12.2
+govulncheck 1.3.0

AGENTS.md

@@ -52,7 +52,11 @@ All development tasks are defined in `Taskfile.yaml`. **Always use `task` instea
 | `task lint-fix` | Run linter and automatically fix issues |
 | `task fmt` | Format code |
 | `task run -- <args>` | Run the project (passes args to `go run .`) |
-| `task update-dependencies` | Update and tidy Go modules |
+| `task dependencies.update` | Update and tidy Go modules |
+| `task tools.plugins` | Install all necessary asdf plugins |
+| `task tools.update` | Update all tools in `.tool-versions` to the latest available version via asdf |
+| `task tools.install` | Install all tools pinned in `.tool-versions` via asdf |
+| `task vuln` | Run govulncheck for vulnerability scanning |
 | `task doc.serve` | Run local godoc server (`pkgsite`) and open in browser |
 
 ## ⚙️ CI/CD
@@ -62,6 +66,7 @@ The project's CI pipeline (`.github/workflows/ci.yaml`) is driven entirely by `t
 - **Build**: `task build`
 - **Test**: `task test.ci` (generates `coverage.out` used for step summary)
 - **Lint & Format**: `task lint-fix` && `task fmt`
+- **Security Check**: `task vuln`
 
 ## 📂 Project Structure
 
@@ -76,11 +81,11 @@ The project's CI pipeline (`.github/workflows/ci.yaml`) is driven entirely by `t
     - **`source/file/`**: `file://` source implementation.
     - **`source/env/`**: `env://` source implementation.
     - **`source/base64/`**: `base64://` source implementation.
-    - **`modifier/jsonpath/`**: `jp` modifier implementation (JSONPath extraction).
     - **`modifier/base64/`**: `b64` modifier implementation (Base64 encoding).
     - **`modifier/base64_encoder/`**: `b64e` alias for `modifier/base64/`.
     - **`modifier/base64_decoder/`**: `b64d` modifier implementation (Base64 decoding).
 - **`plugin/`**: External plugins (opt-in).
+    - **`modifier/jsonpath/`**: `jp` modifier implementation (JSONPath extraction).
     - **`modifier/tomlpath/`**: `tp` modifier implementation (TOML JSONPath extraction).
     - **`modifier/xpath/`**: `xp` modifier implementation (XPath extraction).
     - **`modifier/yamlpath/`**: `yp` modifier implementation (YAML JSONPath extraction).

CHANGELOG.md

@@ -15,8 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
       - WARNING: currently untested due to lack of test environment.
     - `kp://`: Keeper Secrets Manager source implementation (available in `plugin/source/keeper`).
       - WARNING: currently untested due to lack of test environment.
+    - `?jp=`: JSONPath extractor modifier for JSON secrets (available in `plugin/modifier/jsonpath`).
 - **Tooling**:
     - Test tasks in `Taskfile.yaml` (`test`, `test.full`, `test.short`, `test.ci`) now support passing a specific directory path using `-- <path>`.
+    - Added modular `tools.plugins`, `tools.update`, and `tools.install` tasks to `Taskfile.yaml` for robust `asdf`-based toolchain management.
+    - Integrated `govulncheck` (v1.3.0) into `.tool-versions` toolchain and added `task vuln` for local vulnerability scanning.
+    - Integrated `task vuln` check directly into the CI pipeline.
 
 ### Changed
 
@@ -25,6 +29,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Support**: Documented in [README](./README.md) that for now we are not going to support LastPass (`lp://`)
   nor Dashlane (`dl://`) as a source. They both lack a Golang SDK and/or a REST API.
 
+### Removed
+
+- **BREAKING CHANGE**: Removed `jp` (JSONPath) modifier from default built-in modifiers of `Spelunker` to completely free the core root module from any external production dependencies. It has been moved to a plugin under `plugin/modifier/jsonpath/` and must now be explicitly registered using `jsonpath.WithJSONPath()`.
+
+
 ## [1.3.2] - 2026-04-07
 
 ### Changed

CONTRIBUTING.md

@@ -26,16 +26,19 @@ the **human-scale nature of software review**:
 
 ### Install `asdf` and plugins
 
-This repository depends on [asdf]. Once installed, please
-install all the [asdf plugins] used in this repository, by running
-(or something similar):
+This repository depends on [asdf].
+
+Once asdf is installed, you can bootstrap the entire toolchain using the provided task commands:
 
 ```shell
-$ cut -d' ' -f1 .tool-versions | \
-  while read PLUGIN; do
-  	  asdf plugin add $PLUGIN || true
-  done
-$ asdf install
+# 1. Install necessary asdf plugins (including non-default ones)
+$ task tools.plugins
+
+# 2. Update and pin tools in .tool-versions to latest available versions (optional)
+$ task tools.update
+
+# 3. Install all tools pinned in .tool-versions
+$ task tools.install
 ```
 
 ### `task` toolchain

README.md

@@ -193,10 +193,10 @@ will result in this sequence:
 
 | Modifier (of Secrets)             | Type (query)     | Available as | Status |                                           Doc                                            |
 |-----------------------------------|------------------|:------------:|:------:|:----------------------------------------------------------------------------------------:|
-| JSONPath extractor                | `?jp=<JSONPath>` |   built-in   |   ✅    |    [link](https://pkg.go.dev/github.com/detro/spelunk@main/builtin/modifier/jsonpath)    |
 | Base64 encoder                    | `?b64`           |   built-in   |   ✅    |     [link](https://pkg.go.dev/github.com/detro/spelunk@main/builtin/modifier/base64)     |
 | Base64 encoder (alias for `?b64`) | `?b64e`          |   built-in   |   ✅    | [link](https://pkg.go.dev/github.com/detro/spelunk@main/builtin/modifier/base64_encoder) |
 | Base64 decoder                    | `?b64d`          |   built-in   |   ✅    | [link](https://pkg.go.dev/github.com/detro/spelunk@main/builtin/modifier/base64_decoder) |
+| JSONPath extractor                | `?jp=<JSONPath>` |   plug-in    |   ✅    |    [link](https://pkg.go.dev/github.com/detro/spelunk@main/plugin/modifier/jsonpath)     |
 | XPath extractor                   | `?xp=<XPath>`    |   plug-in    |   ✅    |      [link](https://pkg.go.dev/github.com/detro/spelunk@main/plugin/modifier/xpath)      |
 | YAML JSONPath extractor           | `?yp=<JSONPath>` |   plug-in    |   ✅    |    [link](https://pkg.go.dev/github.com/detro/spelunk@main/plugin/modifier/yamlpath)     |
 | TOML JSONPath extractor           | `?tp=<JSONPath>` |   plug-in    |   ✅    |    [link](https://pkg.go.dev/github.com/detro/spelunk@main/plugin/modifier/tomlpath)     |

Taskfile.yaml

@@ -27,6 +27,10 @@ tasks:
   lint:
     cmd: golangci-lint run --allow-parallel-runners --verbose
 
+  vuln:
+    desc: Run govulncheck for vulnerability scanning
+    cmd: govulncheck ./...
+
   lint-fix:
     cmd: golangci-lint run --fix --allow-parallel-runners --verbose
 
@@ -42,11 +46,36 @@ tasks:
   mod.tidy:
     cmd: go mod tidy -v
 
-  update-dependencies:
+  dependencies.update:
     deps:
       - mod.update
       - mod.tidy
 
+  tools.plugins:
+    desc: Install all necessary asdf plugins
+    cmd: |
+      # Install all plugins listed in .tool-versions (will fail but continue for out-of-registry ones)
+      cut -d' ' -f1 .tool-versions | while read -r plugin; do
+        asdf plugin add "$plugin" || true
+      done
+      # Install out-of-registry plugins
+      asdf plugin add govulncheck https://github.com/wizzardich/asdf-govulncheck.git
+
+  tools.update:
+    desc: Update all tools in .tool-versions to latest available versions via asdf
+    deps:
+      - tools.plugins
+    cmd: |
+        cut -d' ' -f1 .tool-versions | while read -r plugin; do
+          asdf set "$plugin" latest || true
+        done
+
+  tools.install:
+    desc: Install all tools in .tool-versions via asdf
+    deps:
+      - tools.plugins
+    cmd: asdf install
+
   doc.serve:
     cmds:
       - go install golang.org/x/pkgsite/cmd/pkgsite@latest

builtin/modifier/base64/base64_test.go

@@ -7,8 +7,8 @@ import (
 
 	"github.com/detro/spelunk"
 	b64mod "github.com/detro/spelunk/builtin/modifier/base64"
-	"github.com/detro/spelunk/builtin/modifier/jsonpath"
 	"github.com/detro/spelunk/internal/testutil"
+	"github.com/detro/spelunk/plugin/modifier/jsonpath"
 	"github.com/detro/spelunk/types"
 	"github.com/stretchr/testify/require"
 )
@@ -61,8 +61,8 @@ func TestSecretModifierBase64_Modify(t *testing.T) {
 
 			spelunker := spelunk.NewSpelunker(
 				spelunk.WithSource(&testutil.MockSource{Typ: "test", Val: tt.val}),
-				spelunk.WithModifier(&jsonpath.SecretModifierJSONPath{}),
 				spelunk.WithModifier(&b64mod.SecretModifierBase64{}),
+				jsonpath.WithJSONPath(),
 			)
 
 			got, err := spelunker.DigUp(ctx, coord)

builtin/modifier/base64_decoder/base64_decoder_test.go

@@ -7,8 +7,8 @@ import (
 
 	"github.com/detro/spelunk"
 	"github.com/detro/spelunk/builtin/modifier/base64_decoder"
-	"github.com/detro/spelunk/builtin/modifier/jsonpath"
 	"github.com/detro/spelunk/internal/testutil"
+	"github.com/detro/spelunk/plugin/modifier/jsonpath"
 	"github.com/detro/spelunk/types"
 	"github.com/stretchr/testify/require"
 )
@@ -67,8 +67,8 @@ func TestSecretModifierBase64Decoder_Modify(t *testing.T) {
 
 			spelunker := spelunk.NewSpelunker(
 				spelunk.WithSource(&testutil.MockSource{Typ: "test", Val: tt.val}),
-				spelunk.WithModifier(&jsonpath.SecretModifierJSONPath{}),
 				spelunk.WithModifier(&base64_decoder.SecretModifierBase64Decoder{}),
+				jsonpath.WithJSONPath(),
 			)
 
 			got, err := spelunker.DigUp(ctx, coord)

examples/viper/main.go

@@ -38,9 +38,9 @@ func main() {
 
 	// 3. Unmarshal with DecodeHook
 	// We need to tell Viper how to handle the types.SecretCoord (TextUnmarshaler).
-	// We use mapstructure.StringToTextUnmarshalerHookFunc() to bridge string -> SecretCoord.
+	// We use mapstructure.TextUnmarshallerHookFunc() to bridge string -> SecretCoord.
 	opts := viper.DecodeHook(mapstructure.ComposeDecodeHookFunc(
-		mapstructure.StringToTextUnmarshalerHookFunc(),
+		mapstructure.TextUnmarshallerHookFunc(),
 		mapstructure.StringToTimeDurationHookFunc(),
 		mapstructure.StringToSliceHookFunc(","),
 	))