🔧 Switch to mise for ENV management

- with direnvy crate

Author: pboling

.env.local.example

@@ -3,29 +3,30 @@
 #
 # COPY THIS FILE TO .env.local
 #
-# That file is ignored by .gitignore.  This file is not.
+# That file is ignored by .gitignore. This file is not.
+# mise loads .env.local via dotenvy, so use KEY=value lines (not shell `export` statements).
 #
-export DEBUG=false # do not allow byebug statements (override in .env.local)
-export FLOSS_FUNDING_DEBUG=false # extra logging to help diagnose issues (override in .env.local)
-export AUTOGEN_FIXTURE_CLEANUP=false # autogenerated gem fixture cleanup after every RSpec run
-export GIT_HOOK_FOOTER_APPEND=false
-export GIT_HOOK_FOOTER_APPEND_DEBUG=false
-export GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI"
+DEBUG=false # do not allow byebug statements (override in .env.local)
+FLOSS_FUNDING_DEBUG=false # extra logging to help diagnose issues (override in .env.local)
+AUTOGEN_FIXTURE_CLEANUP=false # autogenerated gem fixture cleanup after every RSpec run
+GIT_HOOK_FOOTER_APPEND=false
+GIT_HOOK_FOOTER_APPEND_DEBUG=false
+GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI"
 
 # Tokens used by ci:act and CI helpers for reading workflow/pipeline status via APIs
 # GitHub (either GITHUB_TOKEN or GH_TOKEN will be used; fine-grained recommended)
 # - Scope/permissions: For fine-grained tokens, grant repository access (Read) and Actions: Read
 # - For classic tokens, public repos need no scopes; private repos typically require repo
-export GITHUB_TOKEN=<your GH token for GHA status; NEVER COMMIT>
+GITHUB_TOKEN="<your GH token for GHA status; NEVER COMMIT>"
 # Alternatively:
-# export GH_TOKEN=<your GH token>
+# GH_TOKEN="<your GH token>"
 
 # GitLab (either GITLAB_TOKEN or GL_TOKEN will be used)
 # - Scope: read_api is sufficient to read pipelines
-export GITLAB_TOKEN=<your GitLab token for pipeline status; NEVER COMMIT>
+GITLAB_TOKEN="<your GitLab token for pipeline status; NEVER COMMIT>"
 # Alternatively:
-# export GL_TOKEN=<your GitLab token>
+# GL_TOKEN="<your GitLab token>"
 
 # If this gem does not have an open source collective uncomment and set these to false.
-# export OPENCOLLECTIVE_HANDLE=false
-# export FUNDING_ORG=false
+# OPENCOLLECTIVE_HANDLE=false
+# FUNDING_ORG=false

.envrc

@@ -1,70 +1,4 @@
-# Run any command in this library's bin/ without the bin/ prefix!
-
-# Prefer exe version over binstub
-
-PATH_add exe
-PATH_add bin
-
-# Only add things to this file that should be shared with the team.
-
-# **dotenv** (See end of file for .env.local integration)
-
-# .env would override anything in this file, if enabled.
-
-# .env is a DOCKER standard, and if we use it, it would be in deployed, or DOCKER, environments.
-
-# Override and customize anything below in your own .env.local
-
-# If you are using dotenv and not direnv,
-
-#   copy the following `export` statements to your own .env file.
-
-### General Ruby ###
-
-# Turn off Ruby Warnings about deprecated code
-
-# export RUBYOPT="-W0"
-
-### External Testing Controls
-
-export K_SOUP_COV_DO=true # Means you want code coverage
-export K_SOUP_COV_COMMAND_NAME="Test Coverage"
-
-# Available formats are html, xml, rcov, lcov, json, tty
-
-export K_SOUP_COV_FORMATTERS="html,xml,rcov,lcov,json,tty"
-export K_SOUP_COV_MIN_BRANCH=76 # Means you want to enforce X% branch coverage
-export K_SOUP_COV_MIN_LINE=92 # Means you want to enforce X% line coverage
-export K_SOUP_COV_MIN_HARD=true # Means you want the build to fail if the coverage thresholds are not met
-export K_SOUP_COV_MULTI_FORMATTERS=true
-export K_SOUP_COV_OPEN_BIN= # Means don't try to open coverage results in browser
-export MAX_ROWS=1 # Setting for simplecov-console gem for tty output, limits to the worst N rows of bad coverage
-export KETTLE_TEST_SILENT=true
-export KETTLE_DEV_DEBUG=false
-
-# Internal Debugging Controls
-
-export DEBUG=false # do not allow byebug statements (override in .env.local)
-export FLOSS_CFG_FUND_DEBUG=false # extra logging to help diagnose issues (override in .env.local)
-export FLOSS_CFG_FUND_LOGFILE=tmp/log/debug.log
-
-# Concurrently developing the rubocop-lts suite?
-
-export RUBOCOP_LTS_LOCAL=false
-
-# If token-resolver does not have an open source collective set these to false.
-
-export OPENCOLLECTIVE_HANDLE=kettle-rb
-export FUNDING_ORG=kettle-rb
-
-# .env would override anything in this file, if `dotenv` is uncommented below.
-
-# .env is a DOCKER standard, and if we use it, it would be in deployed, or DOCKER, environments,
-
-#   and that is why we generally want to leave it commented out.
-
-# dotenv
-
-# .env.local will override anything in this file.
-
-dotenv_if_exists .env.local
+# Deprecated: this project uses mise.toml for environment management.
+# Install/activate mise, or run commands with:
+#   mise exec -C /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver -- <command>
+true

.gitignore

@@ -37,7 +37,7 @@ Appraisal.*.gemfile.lock
 # Debugger detritus
 .byebug_history
 
-# direnv - brew install direnv
+# Local environment overrides (loaded by mise and passed off to the direnvy crate)
 .env.local
 
 # OS Detritus

AGENTS.md

@@ -25,37 +25,49 @@ lib/token/resolver/
 └── version.rb      — Version information
 ```
 
-## Key Design Decisions
-
-1. **Grammar never fails** — Any input is valid. Unrecognized content becomes text nodes.
-2. **Single-pass resolution** — Replacement values are NOT re-scanned for tokens.
-3. **Config is frozen and hashable** — Grammar classes are cached per config.
-4. **Fast-path** — If input doesn't contain the `pre` delimiter, no parslet invocation.
-
 ## Running Tests
 
 ```bash
-bundle exec rspec
+mise exec -C /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver -- bundle exec rspec
 ```
 
-## Critical AI Agent Terminal Limitations
+## Critical AI Agent Terminal Guidance
+
+### Terminal Output Is Available, but Each Command Is Isolated
+
+**IMPORTANT**: AI agents can reliably read terminal output when commands run in the background and the output is polled afterward. However, every terminal command should be treated as a fresh shell with no shared state.
 
-**IMPORTANT**: AI agents (Copilot, etc.) almost never can see terminal output from `run_in_terminal`.
+### Use `mise` for Project Environment
 
-**Workarounds:**
-1. **ALWAYS redirect output to a file** in the project's local `tmp/` directory, then read it back:
-   ```bash
-   bundle exec rspec 2>&1 > tmp/rspec-output.txt
-   ```
-   Then use `read_file` tool on `tmp/rspec-output.txt`.
+**IMPORTANT**: The canonical project environment now lives in `mise.toml`, with local overrides in `.env.local` loaded via `dotenvy`.
 
-2. **NEVER chain `cd` with other commands via `&&`** — `direnv` won't initialize until after
-   all commands finish. Run `cd` alone first, then run subsequent commands separately.
+✅ **CORRECT**:
+```bash
+mise exec -C /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver -- bundle exec rspec
+```
+
+✅ **CORRECT**:
+```bash
+eval "$(mise env -C /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver -s bash)" && bundle exec rspec
+```
+
+❌ **WRONG**:
+```bash
+cd /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver
+bundle exec rspec
+```
+
+❌ **WRONG**:
+```bash
+cd /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver && bundle exec rspec
+```
 
-3. **NEVER use `head`, `tail`, or any output truncation** with test commands.
+### Additional Rules
 
-4. **Use internal tools** (`grep_search`, `read_file`, `list_dir`) instead of terminal for
+1. **NEVER use `head`, `tail`, or any output truncation** with test commands.
+2. **Use internal tools** (`grep_search`, `read_file`, `list_dir`) instead of terminal for
    information gathering whenever possible.
+3. **Do NOT rely on prior shell state** — Previous `cd`, `export`, aliases, and functions are not available to the next command.
 
 ## API Conventions
 

CONTRIBUTING.md

@@ -52,7 +52,7 @@ General/runtime
 - CI: When set to true, adjusts default rake tasks toward CI behavior
 
 Coverage (kettle-soup-cover / SimpleCov)
-- K_SOUP_COV_DO: Enable coverage collection (default: true in .envrc)
+- K_SOUP_COV_DO: Enable coverage collection (default: true in `mise.toml`)
 - K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty)
 - K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100)
 - K_SOUP_COV_MIN_BRANCH: Minimum branch coverage threshold (integer, e.g., 100)
@@ -78,7 +78,7 @@ Git hooks and commit message helpers (exe/kettle-commit-msg)
 - GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates
 - GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false)
 
-For a quick starting point, this repository’s `.envrc` shows sane defaults, and `.env.local` can override them locally.
+For a quick starting point, this repository’s `mise.toml` defines the shared defaults, and `.env.local` can override them locally. Copy `.env.local.example` to `.env.local`, use `KEY=value` lines, and either activate `mise` in your shell or run commands through `mise exec -C /home/pboling/src/kettle-rb/ast-merge/vendor/token-resolver -- ...`.
 
 ## Appraisals
 

mise.toml

@@ -0,0 +1,23 @@
+# Shared development environment for token-resolver.
+# Local overrides belong in .env.local (loaded via dotenvy through mise).
+
+[env]
+K_SOUP_COV_DO = "true"
+K_SOUP_COV_COMMAND_NAME = "Test Coverage"
+K_SOUP_COV_FORMATTERS = "html,xml,rcov,lcov,json,tty"
+K_SOUP_COV_MIN_BRANCH = "76"
+K_SOUP_COV_MIN_LINE = "92"
+K_SOUP_COV_MIN_HARD = "true"
+K_SOUP_COV_MULTI_FORMATTERS = "true"
+K_SOUP_COV_OPEN_BIN = ""
+MAX_ROWS = "1"
+KETTLE_TEST_SILENT = "true"
+KETTLE_DEV_DEBUG = "false"
+DEBUG = "false"
+FLOSS_CFG_FUND_DEBUG = "false"
+FLOSS_CFG_FUND_LOGFILE = "tmp/log/debug.log"
+RUBOCOP_LTS_LOCAL = "false"
+OPENCOLLECTIVE_HANDLE = "kettle-rb"
+FUNDING_ORG = "kettle-rb"
+_.path = ["exe", "bin"]
+_.file = { path = ".env.local", redact = true }