@terreno/mcp 0.21.0 → 0.22.1

package/dist/docs/versioned/0.21.0/README.md

@@ -0,0 +1,29 @@
+# Terreno Documentation
+
+Documentation for the Terreno monorepo: shared packages for full-stack applications with React Native and Express/Mongoose.
+
+## Structure
+
+- **[Tutorials](tutorials/)** — Learning-oriented, hands-on lessons
+- **[How-to guides](how-to/)** — Problem-oriented, practical steps
+- **[Reference](reference/)** — Technical reference for APIs and packages
+- **[Explanation](explanation/)** — Concepts and context
+- **[Implementation Plans](implementationPlans/)** — Forward-looking plans for major features
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@terreno/api](reference/api.md) | REST API framework (Express/Mongoose) |
+| [@terreno/ui](reference/ui.md) | React Native UI component library |
+| [@terreno/rtk](reference/rtk.md) | RTK Query utilities for API backends |
+| [@terreno/admin-backend](reference/admin-backend.md) | Admin panel backend plugin |
+| [@terreno/admin-frontend](reference/admin-frontend.md) | Admin panel frontend screens |
+| [@terreno/api-health](reference/api-health.md) | Health check endpoint plugin |
+| [@terreno/mcp](reference/mcp-server.md) | AI coding assistant integration (MCP) |
+
+## Quick links
+
+- [Getting started](tutorials/getting-started.md)
+- [AGENTS.md](../AGENTS.md) — Onboarding context for AI assistants
+- [.cursorrules](../.cursorrules) — Project and code style rules

package/dist/docs/versioned/0.21.0/explanation/README.md

@@ -0,0 +1,13 @@
+# Explanation
+
+Understanding-oriented documentation: concepts, architecture, and context.
+
+## Contents
+
+- [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
+- [Authentication architecture](authentication.md) — How JWT, OAuth, and token refresh work
+- [Configuration system](configuration-system.md) — Runtime configuration with database persistence
+- [Dependency management](dependency-management.md) — Dependabot, auto-merge, and security practices
+- [GCP hosting architecture](gcp-hosting-architecture.md) — Static site hosting with GCS and Cloud CDN
+- [Modular API design](modular-api-design.md) — 🚧 Why TerrenoApp replaces setupServer
+- [modelRouter actions](model-router-actions.md) — Named collection and instance operations on modelRouter

package/dist/docs/versioned/0.21.0/explanation/ai-workflows.md

@@ -0,0 +1,270 @@
+# AI-Powered Workflows
+
+Understanding Terreno's autonomous AI workflows for continuous improvement.
+
+## Overview
+
+Terreno uses GitHub Actions with AI agents to maintain code quality, documentation, and developer experience. These workflows run automatically and create pull requests when improvements are needed.
+
+## Workflow Categories
+
+### Documentation Workflows
+
+#### Update Docs
+**Trigger:** Push to master  
+**Purpose:** Keeps documentation synchronized with code changes
+
+Analyzes code diffs after each merge to identify:
+- New or changed APIs, functions, classes
+- Missing or outdated documentation
+- Documentation gaps that need attention
+
+**Output:** Draft pull requests with documentation updates following the Diátaxis framework (tutorials, how-to guides, reference, explanation).
+
+**Philosophy:** Treats documentation gaps like failing tests — they must be fixed.
+
+#### Update Rules
+**Trigger:** Push to master  
+**Purpose:** Keeps AI assistant rules synchronized with codebase changes
+
+Maintains the single source of truth in `.rulesync/rules/` and ensures:
+- `.cursorrules` (Cursor IDE)
+- `.windsurfrules` (Windsurf IDE)
+- `AGENTS.md` (Claude Code, Copilot)
+- `.github/copilot-instructions.md` (GitHub Copilot)
+
+**Workflow:**
+1. Detects package changes, new APIs, or convention updates
+2. Updates source files in `.rulesync/rules/`
+3. Creates PR with instructions to run `bun run rules` to regenerate outputs
+4. Ensures `rulesync-check` CI passes
+
+**Key insight:** Rule files are code — they must be kept in sync with implementation.
+
+### Code Quality Workflows
+
+#### Daily JSDoc Improver
+**Trigger:** Daily schedule + push to master  
+**Purpose:** Systematically improves JSDoc documentation across the codebase
+
+**Two modes:**
+- **Targeted (on push):** Improves JSDoc for files changed in recent commits
+- **Systematic (daily):** Three-phase approach covering entire codebase
+
+**Output:** Draft PRs with improved JSDoc comments on exported functions, methods, and classes.
+
+#### Daily Test Improver
+**Trigger:** Daily schedule  
+**Purpose:** Enhances test coverage and test quality
+
+Analyzes test files and implementation to:
+- Add missing test cases
+- Improve test clarity and coverage
+- Identify edge cases that need testing
+- Ensure tests follow best practices
+
+**Output:** Draft PRs with test improvements.
+
+### Maintenance Workflows
+
+#### Agentic Maintenance
+**Trigger:** Daily at 00:37 UTC  
+**Purpose:** Cleans up expired issues, discussions, and pull requests
+
+Automatically closes expired entities based on the `expires` field in safe-outputs configuration. Schedule is determined by the shortest expiration time across all workflows.
+
+**Prevents:** Stale issues and PRs from accumulating.
+
+#### RulesSync Check
+**Trigger:** Pull request  
+**Purpose:** Validates that generated rule files are synchronized with sources
+
+**Validation steps:**
+1. Runs `bun run rules` to regenerate outputs
+2. Checks for uncommitted changes
+3. Fails if generated files don't match committed versions
+
+**Prevents:** Merging PRs with out-of-sync rule files.
+
+## CI/CD Workflows
+
+### Package Testing
+
+Each package has its own CI workflow that runs on pull requests and pushes:
+
+| Workflow | Package | Tests |
+|----------|---------|-------|
+| `api-ci.yml` | @terreno/api | Unit tests, type checking, linting |
+| `ui-ci.yml` | @terreno/ui | Component tests, type checking, linting |
+| `rtk-ci.yml` | @terreno/rtk | Unit tests, type checking, linting |
+| `mcp-server-ci.yml` | @terreno/mcp | Integration tests, type checking, linting |
+| `example-backend-ci.yml` | example-backend | Integration tests, type checking |
+| `example-frontend-ci.yml` | example-frontend | Build verification, type checking |
+| `ui-demo-ci.yml` | demo | Build verification, type checking |
+
+### Deployment Workflows
+
+#### Demo Deploy
+**Trigger:** Push to master  
+**Purpose:** Deploys UI demo to Google Cloud Storage with Cloud CDN
+
+**Architecture:** Static site hosting with custom domain, SSL, and CDN acceleration.
+
+**Learn more:** [GCP Hosting Architecture](gcp-hosting-architecture.md), [Deploy to GCP](../how-to/deploy-to-gcp.md)
+
+#### Frontend Example Deploy
+**Trigger:** Push to master, pull request  
+**Purpose:** Deploys example frontend with preview environments
+
+**Features:**
+- **Production:** Deploys to production GCS bucket on master
+- **Preview:** Creates preview environments for pull requests
+- **Cleanup:** Automatically removes preview environments when PRs close
+
+#### MCP Server Deploy
+**Trigger:** Push to master  
+**Purpose:** Deploys Model Context Protocol server
+
+Builds and deploys the MCP server for AI coding assistant integration.
+
+#### Preview Cleanup
+**Trigger:** Pull request close  
+**Purpose:** Removes preview deployments when PRs are closed or merged
+
+Ensures preview environments don't accumulate and waste resources.
+
+### Security & Quality
+
+#### CodeQL Analysis
+**Trigger:** Push to master, pull request, schedule (weekly)  
+**Purpose:** Security vulnerability scanning with GitHub CodeQL
+
+**Languages analyzed:** JavaScript, TypeScript
+
+**Output:** Security alerts in the Security tab when vulnerabilities are found.
+
+#### Dependabot Auto-merge
+**Trigger:** Dependabot pull request opened  
+**Purpose:** Automatically merges dependency updates after CI passes
+
+**Requirements for auto-merge:**
+- All CI checks pass
+- Dependabot PR (created by Dependabot)
+- No conflicts
+- 7-day cooldown for security (see Dependency Management)
+
+**Learn more:** [Dependency Management](dependency-management.md)
+
+### Publishing
+
+#### Publish on Tag
+**Trigger:** Tag push matching `v*.*.*`  
+**Purpose:** Publishes packages to npm registry
+
+**Workflow:**
+1. Validates tag format and package versions match
+2. Runs full test suite
+3. Publishes to npm with appropriate tags (`latest` or `next`)
+4. Creates GitHub release with changelog
+
+**Packages published:**
+- @terreno/api
+- @terreno/ui
+- @terreno/rtk
+- @terreno/mcp
+
+## Workflow Philosophy
+
+### Single Source of Truth
+- **Documentation:** Code is truth, docs must reflect it
+- **Rules:** `.rulesync/rules/` is truth, generated files derive from it
+- **Tests:** Implementation is truth, tests verify it
+
+### Fail Fast
+- All checks must pass before merge
+- Generated files must be committed (no drift)
+- Documentation gaps are treated like failing tests
+
+### Autonomous Improvement
+- Workflows create PRs, not commits
+- PRs are drafts requiring human review
+- Workflow agents make suggestions, humans make decisions
+
+### Continuous Sync
+- Documentation syncs on every master push
+- Rules sync on every master push
+- Dependencies update daily (Dependabot)
+- Quality improvements run daily (JSDoc, tests)
+
+## Working with AI Workflows
+
+### When a Workflow Creates a PR
+
+1. **Review the changes** — AI is helpful but not perfect
+2. **Run suggested commands** — E.g., `bun run rules` for rule updates
+3. **Test locally** — Ensure changes work as intended
+4. **Approve or close** — Merge if valuable, close if not
+
+### When a Workflow Fails
+
+Check the workflow run logs in the Actions tab:
+- **Documentation updates:** May need manual clarification
+- **Rule updates:** May need manual fixes to `.rulesync/rules/`
+- **JSDoc/test improvements:** May need guidance on conventions
+
+### Customizing Workflows
+
+Workflow definitions live in `.github/workflows/*.md` files. These are compiled into `.github/workflows/*.lock.yml` by the GitHub Agentic Workflows CLI.
+
+**To customize:**
+1. Edit the `.md` source file (e.g., `update-docs.md`)
+2. Run `gh aw compile` (if using gh-aw CLI)
+3. Commit both the `.md` and regenerated `.lock.yml`
+
+**Note:** Never edit `.lock.yml` files directly — they are generated.
+
+## Best Practices
+
+### For Maintainers
+- **Review workflow PRs regularly** — Don't let them accumulate
+- **Provide feedback** — If a workflow generates bad suggestions, close with a comment explaining why
+- **Tune prompts** — If a workflow consistently misses the mark, update the `.md` file
+
+### For Contributors
+- **Run CI before pushing** — `bun run lint && bun run test`
+- **Update rules if needed** — `bun run rules` after changing `.rulesync/rules/`
+- **Check workflow status** — Ensure your PR doesn't break workflows
+
+### For Users
+- **Check Actions tab** — See what's running and what's pending
+- **Review draft PRs** — Workflow-generated PRs may contain useful improvements
+- **Report issues** — If a workflow behaves unexpectedly, open an issue
+
+## Troubleshooting
+
+### Workflow doesn't run when expected
+- Check `.github/workflows/*.yml` trigger configuration
+- Verify branch name matches (usually `master`)
+- Check workflow permissions and safe-outputs limits
+
+### RulesSync check fails on PR
+- Run `bun run rules` locally
+- Commit any generated file changes
+- Ensure `.rulesync/rules/` files have valid YAML frontmatter
+
+### Dependabot PR doesn't auto-merge
+- Verify all CI checks pass (green checkmarks)
+- Check 7-day cooldown hasn't been violated
+- Ensure no merge conflicts exist
+
+### AI workflow creates poor quality PR
+- Review the workflow definition in `.github/workflows/*.md`
+- Consider customizing the prompt or instructions
+- Close the PR with feedback for future improvements
+
+## Related Documentation
+
+- [Dependency Management](dependency-management.md) — Dependabot configuration and auto-merge
+- [Deploy to GCP](../how-to/deploy-to-gcp.md) — Manual deployment guide
+- [GCP Hosting Architecture](gcp-hosting-architecture.md) — Static site hosting design
+- [Environment Variables](../reference/environment-variables.md) — Configuration reference