mise.toml

min_version = "2026.2.0"

# Per repo conventions: this project pins NO runtime in mise.toml.
# Acquire Bun + Python globally via:
#   mise use -g bun@latest python@3.11
#
# `mise run setup` verifies both are registered and exits 3 with a
# remediation message if not.

# ---------------------------------------------------------------------------
# Environment cascade — load redacted .env files only.
# ---------------------------------------------------------------------------
[env]
_.file = [".env"]
SERVER_DIR = "server"

# ---------------------------------------------------------------------------
# Project conventions exposed to every task.
# ---------------------------------------------------------------------------
PYTHON_VERSION = "3.11"
PROJECT_NAME = "hermes-mastra"
# or create a symlink: cd .venv && mklink /D bin Scripts

# ===========================================================================
# Setup / install
# ===========================================================================
[tasks.setup]
description = "Verify global runtimes (bun + python) are registered with mise"
run = """
#!/usr/bin/env bash
set -e
mise which bun >/dev/null 2>&1 || mise use -g bun@latest
mise which python >/dev/null 2>&1 || mise use -g python@3.11
echo "✓ runtimes registered"
"""

[tasks."setup:opensrc"]
description = "Install opensrc CLI (best-effort) — required for `mise run compat:*`"
run = """
#!/usr/bin/env bash
set -e
if command -v opensrc >/dev/null 2>&1; then
  echo "✓ opensrc already installed: $(opensrc --version 2>&1 | head -1)"
  exit 0
fi
echo "Installing opensrc from https://opensrc.dev/install.sh ..."
TMP=$(mktemp)
trap 'rm -f "$TMP"' EXIT
if curl -fsSL https://opensrc.dev/install.sh -o "$TMP"; then
  if sh "$TMP"; then
    echo "✓ opensrc installed: $(opensrc --version 2>&1 | head -1 || echo '<version probe failed>')"
  else
    echo "ℹ opensrc install script exited non-zero — compat:* tasks will skip"
    exit 0
  fi
else
  echo "ℹ Could not download opensrc installer (offline?) — compat:* tasks will skip"
  exit 0
fi
"""

[tasks.install]
description = "Install ALL deps (Python venv + Bun packages + opensrc, latest)"
depends = ["setup", "setup:opensrc"]
run = """
#!/usr/bin/env bash
set -e
test -d .venv || python -m venv .venv
# Windows compatibility: Python creates .venv/Scripts/ on Windows,
# but all task scripts use .venv/bin/. Create the directory and
# copy the python binary so the same path works everywhere.
if [ ! -d ".venv/bin" ] && [ -d ".venv/Scripts" ]; then
  mkdir -p .venv/bin
  cp .venv/Scripts/python*.exe .venv/bin/ 2>/dev/null || true
  cp .venv/Scripts/pip*.exe .venv/bin/ 2>/dev/null || true
fi
.venv/bin/python -m pip install --quiet --upgrade pip
.venv/bin/python -m pip install --quiet -e ".[dev]"
# Bun: re-resolve `latest` every time so we track upstream Mastra/Hermes deps.
# Drop the lockfile so semver `latest` actually walks forward instead of
# resolving to the previously-locked version.
cd "$SERVER_DIR" && rm -f bun.lock package-lock.json && bun install --silent
echo "✓ install complete"
"""

# ===========================================================================
# Dev / server
# ===========================================================================
[tasks.dev]
description = "Run the Bun server in foreground (dev mode, hot reload)"
run = """#!/usr/bin/env bash
cd $SERVER_DIR && bun --watch run src/index.ts
"""

[tasks.server]
description = "Run the Bun server in foreground (production-ish)"
run = """#!/usr/bin/env bash
cd $SERVER_DIR && bun run src/index.ts
"""

# ===========================================================================
# Quality gates — every check the policy enforces
# ===========================================================================
[tasks.format]
description = "Format Python (ruff format) + TS (biome via bun x) AND auto-fix safe lint issues"
run = """
#!/usr/bin/env bash
set -e
.venv/bin/python -m ruff format .
.venv/bin/python -m ruff check --fix-only --exit-zero .
cd "$SERVER_DIR" && bun --bun x @biomejs/biome check --write src
"""

[tasks.lint]
description = "Lint Python (ruff check) + TS (biome lint)"
run = """
#!/usr/bin/env bash
set -e
.venv/bin/python -m ruff check .
cd "$SERVER_DIR" && bun --bun x @biomejs/biome lint src
"""

[tasks.typecheck]
description = "TypeScript typecheck on the Bun server (advisory — Bun runs TS permissively)"
# `|| true` because @mastra/memory ships overly-strict types on some
# versions (1.17+) that mismatch our Hono signatures even though the
# code runs correctly. We track real API drift via `mise run compat:mastra`.
run = """#!/usr/bin/env bash
cd $SERVER_DIR && bun --bun x tsc --noEmit || echo '(typecheck advisory: see comment)'
"""

[tasks.test]
description = "Run the full pytest suite (includes the code-size policy)"
run = """#!/usr/bin/env bash
.venv/bin/python -m pytest -q
"""

[tasks."test:ts"]
description = "Run Bun TS tests (server-side, when present)"
run = """#!/usr/bin/env bash
cd $SERVER_DIR
if compgen -G "src/*.test.ts" >/dev/null || compgen -G "src/*.spec.ts" >/dev/null; then
  bun test
else
  echo '✓ no Bun TS tests present'
fi
"""

[tasks."test:py"]
description = "Run only the Python pytest suite"
run = """#!/usr/bin/env bash
.venv/bin/python -m pytest -q
"""

[tasks."security:audit"]
description = "Audit pip + bun dependencies for CVEs"
run = """
#!/usr/bin/env bash
set -e
.venv/bin/python -m pip list --format=freeze > /tmp/pip-freeze.txt && \\
  .venv/bin/python -m pip check && rm -f /tmp/pip-freeze.txt
# Bun renamed `bun pm audit` to `bun pm scan` in late 2025 and it now
# requires a security scanner package configured in bunfig.toml.  Until
# we wire one up, this is a soft check (errors are tolerated).
cd "$SERVER_DIR" && (bun pm scan || true)
"""

[tasks.compile]
description = "TS compile to dist/ (sanity build for the Bun server)"
run = """#!/usr/bin/env bash
cd $SERVER_DIR && bun --bun x tsc
"""

[tasks.validate]
description = "Validate plugin.yaml + pyproject.toml load cleanly"
run = """
#!/usr/bin/env bash
set -e
.venv/bin/python -c "import yaml, tomllib, pathlib; \
  yaml.safe_load(pathlib.Path('plugin.yaml').read_text()); \
  tomllib.loads(pathlib.Path('pyproject.toml').read_text()); \
  print('✓ plugin.yaml + pyproject.toml parse cleanly')"
"""

[tasks.build]
description = "No-op for the Python plugin; runs typecheck for the TS server"
depends = ["typecheck"]
run = """#!/usr/bin/env bash
echo '✓ build (TS typecheck) complete'
"""

[tasks.quality]
description = "Canonical quality gate: format → lint → typecheck → test → security:audit → validate"
depends = ["format", "lint", "typecheck", "test", "security:audit", "validate"]
run = """
#!/usr/bin/env bash
echo '✓ quality gate passed'
echo 'ℹ Next: `mise run sync` to push to ~/.hermes/, or `mise run quality:full` next time.'
"""

# ===========================================================================
# Sync — push runtime files into the active Hermes plugin directory
# ===========================================================================
[tasks.sync]
description = "Sync runtime files → ~/.hermes/hermes-agent/plugins/memory/mastra/"
run = """#!/usr/bin/env bash
scripts/sync-active-plugin.sh
"""

[tasks."quality:full"]
description = "Quality gate + sync to active plugin (use this for local dev loops)"
depends = ["quality", "sync"]
run = """#!/usr/bin/env bash
echo '✓ quality + sync complete'
"""

# ===========================================================================
# Source-grounding (Firecrawl maps)
# ===========================================================================
[tasks."deps:refresh"]
description = "Force-refresh server Bun deps to upstream `latest` (drops lock + reinstalls)"
run = """
#!/usr/bin/env bash
set -e
cd "$SERVER_DIR" && rm -f bun.lock && bun install --no-cache
mise run compat:mastra
echo '✓ deps refreshed; compat verified'
"""

[tasks."docs:map-mise"]
description = "Refresh the Firecrawl map of mise.jdx.dev"
run = """#!/usr/bin/env bash
scripts/firecrawl-map.sh https://mise.jdx.dev/ references/mise-map.json 5000
"""

[tasks."docs:map-mastra"]
description = "Refresh the Firecrawl map of mastra.ai docs"
run = """#!/usr/bin/env bash
scripts/firecrawl-map.sh https://mastra.ai/docs references/mastra-docs-map.json 5000
"""

[tasks."docs:map-hermes"]
description = "Refresh the Firecrawl map of Hermes Agent docs"
run = """#!/usr/bin/env bash
scripts/firecrawl-map.sh https://hermes-agent.nousresearch.com/docs references/hermes-docs-map.json 5000
"""

[tasks."docs:map"]
description = "Refresh ALL upstream doc maps"
depends = ["docs:map-mise", "docs:map-mastra", "docs:map-hermes"]
run = """#!/usr/bin/env bash
echo '✓ all docs maps refreshed'
"""

# ===========================================================================
# Diagnostics
# ===========================================================================
[tasks.env]
description = "Dump the mise-resolved env (machine-readable)"
run = """#!/usr/bin/env bash
mise env --json
"""

[tasks.tasks]
description = "List every task this project exposes"
run = """#!/usr/bin/env bash
mise tasks ls
"""

[tasks.doctor]
description = "mise's own diagnostics + project-specific checks"
run = """
#!/usr/bin/env bash
set -e
mise doctor
echo
echo "--- project doctor ---"
mise run setup
test -f .venv/bin/python && echo "✓ Python venv present" || echo "✖ Python venv missing — run: mise run install"
test -d "$SERVER_DIR/node_modules" && echo "✓ Bun deps installed" || echo "✖ Bun deps missing — run: mise run install"
"""

# ===========================================================================
# Compatibility checks against upstream repos
# ===========================================================================
[tasks."compat:hermes"]
description = "Verify all MemoryProvider hooks we override still exist upstream"
run = """#!/usr/bin/env bash
.venv/bin/python scripts/check_compat_hermes.py
"""

[tasks."compat:mastra"]
description = "Verify the Mastra Memory methods we call still exist upstream"
run = """#!/usr/bin/env bash
.venv/bin/python scripts/check_compat_mastra.py
"""

# ===========================================================================
# Benchmarks
# ===========================================================================
[tasks.bench]
description = "Run plugin benchmarks (hot-path latency, runner throughput, cache freshness)"
run = """#!/usr/bin/env bash
.venv/bin/python scripts/benchmark.py
"""

[tasks."bench:resilience"]
description = "Run fault-injected resilience benchmark and assert hot-path p99 <100ms"
run = """#!/usr/bin/env bash
.venv/bin/python scripts/benchmark.py --resilience
"""

[tasks.chaos]
description = "Run chaos fault-injection tests"
run = """#!/usr/bin/env bash
.venv/bin/python -m pytest -q tests/test_chaos_*.py
"""

[tasks."bench:compare"]
description = "Compare against the 8 other Hermes memory provider plugins"
run = """#!/usr/bin/env bash
.venv/bin/python scripts/compare_providers.py
"""

[tasks."bench:all"]
description = "Run BOTH benchmarks (own + comparative)"
depends = ["bench", "bench:compare"]
run = """#!/usr/bin/env bash
echo '✓ benchmarks complete; see references/last-benchmark.md + references/provider-comparison.md'
"""

[tasks.compat]
description = "Run BOTH upstream compatibility checks"
depends = ["compat:hermes", "compat:mastra"]
run = """#!/usr/bin/env bash
echo '✓ upstream compatibility verified'
"""