moosestack: Instructions file for Codex

AGENTS.md

Multi-language monorepo (Rust CLI + TypeScript/Python libraries) using PNPM workspaces, Turbo Repo, and Cargo workspace.

CRITICAL: When changing MooseStack functionality, ALWAYS run end-to-end tests. When changing user-facing features, add E2E tests to python-tests/typescript-tests templates AND audit documentation. Logs: ~/.moose/*-cli.log. Always format the code.

Build & Development Commands

All Languages

• Build all: pnpm build (Turbo orchestrates builds)
• Dev mode: pnpm dev (starts dev servers)
• Clean: pnpm clean
• Lint all: pnpm lint
• Format: pnpm format (Prettier for TS/JS)

Rust

• Build: cargo build
• Debug CLI: Use debug build with verbose logging for ALL moose CLI commands:

  RUST_LOG=debug RUST_BACKTRACE=1 MOOSE_LOGGER__LEVEL=Debug ~/repos/moosestack/target/debug/moose-cli <command>
  

  Example: RUST_LOG=debug RUST_BACKTRACE=1 MOOSE_LOGGER__LEVEL=Debug ~/repos/moosestack/target/debug/moose-cli init my-app typescript
• Test all: cargo test
• Test single: cargo test <test_name> or cargo test --package <package_name> --test <test_file>
• Lint: cargo clippy --all-targets -- -D warnings (REQUIRED pre-commit, no warnings allowed)
• Format: cargo fmt

TypeScript

• Test lib: cd packages/ts-moose-lib && pnpm test (runs mocha tests)
• Test single: cd packages/ts-moose-lib && pnpm test --grep "test name pattern"
• Typecheck: cd packages/ts-moose-lib && pnpm typecheck

Python

• Test lib: cd packages/py-moose-lib && pytest
• Test single: cd packages/py-moose-lib && pytest tests/test_file.py::test_function_name
• Test pattern: cd packages/py-moose-lib && pytest -k "test_pattern"

End-to-End Tests

• Run E2E: cd apps/framework-cli-e2e && pnpm test (includes pretest: cargo build, pnpm build, package templates)
• Single E2E test: cd apps/framework-cli-e2e && pnpm test --grep "test name"

Testing Templates Manually

Templates cannot be run directly from within the repo—they must be initialized in a temp directory first. To test a template using the current branch's CLI and moose-lib versions:

# 1. Build the CLI
cargo build --package moose-cli

# 2. Package templates (creates tgz files with current template content)
node scripts/package-templates.js

# 3. Initialize template in a temp directory (outside the repo)
cd /tmp && ~/repos/moosestack/target/debug/moose-cli init my-test-app <template-name>

# 4. Verify the lockfile is up-to-date
cd /tmp/my-test-app && pnpm install
git status  # Should show "nothing to commit, working tree clean"

If the lockfile changes after pnpm install, regenerate it in the template source directory:

cd ~/repos/moosestack/templates/<template-name>
rm -rf node_modules && pnpm install
# Commit the updated pnpm-lock.yaml