diff --git a/.agents/skills/cssforge b/.agents/skills/cssforge new file mode 120000 index 0000000..2e01389 --- /dev/null +++ b/.agents/skills/cssforge @@ -0,0 +1 @@ +../../skills/cssforge \ No newline at end of file diff --git a/.agents/skills/moon/SKILL.md b/.agents/skills/moon/SKILL.md new file mode 100644 index 0000000..04ced25 --- /dev/null +++ b/.agents/skills/moon/SKILL.md @@ -0,0 +1,325 @@ +--- +name: moon +description: This skill should be used when the user asks to "configure moon", "set up moonrepo", "create moon tasks", "run moon commands", "configure moon workspace", "add moon project", "moon ci setup", "moon docker", "moon query", "migrate to moon v2", or mentions moon.yml, .moon/workspace.yml, .moon/toolchains.yml, moon run, moon ci, or moonrepo in general. +--- + +# moon - Polyglot Monorepo Build System + +moon is a Rust-based repository management, task orchestration, and build system for polyglot monorepos. It provides smart caching, dependency-aware task execution, and unified toolchain management. + +> **moon v2 is now available.** Run `moon migrate v2` to migrate. See `references/v2-migration.md` for breaking changes. + +## When to Use moon + +- Managing monorepos with multiple projects/packages +- Orchestrating tasks across projects with dependencies +- Caching build outputs for faster CI/local builds +- Managing toolchain versions (Node.js, Rust, Python, Go, etc.) +- Generating project and action graphs + +## Quick Reference + +### Core Commands + +```bash +moon run # Run task(s) +moon run :lint # Run in all projects +moon run '#tag:test' # Run by tag +moon ci # CI-optimized execution +moon check --all # Run all build/test tasks +moon query projects # List projects +moon project-graph # Visualize dependencies +``` + +### Target Syntax + +| Pattern | Description | +| -------------- | ------------------------------- | +| `project:task` | Specific project and task | +| `:task` | All projects with this task | +| `#tag:task` | Projects with tag | +| `^:task` | Upstream dependencies (in deps) | +| `~:task` | Current project (in configs) | + +### Configuration Files + +| File | Purpose | +| ---------------------- | ---------------------------------------- | +| `.moon/workspace.yml` | Workspace settings, project discovery | +| `.moon/toolchains.yml` | Language versions, package managers (v2) | +| `.moon/tasks/*.yml` | Global inherited tasks (v2) | +| `moon.yml` | Project-level config and tasks | + +> **v2 Note:** `.moon/toolchain.yml` → `.moon/toolchains.yml` (plural), `.moon/tasks.yml` → `.moon/tasks/*.yml` + +## Workspace Configuration + +```yaml +# .moon/workspace.yml +$schema: "https://moonrepo.dev/schemas/workspace.json" + +projects: + - "apps/*" + - "packages/*" + +vcs: + client: "git" + defaultBranch: "main" + +pipeline: + archivableTargets: + - ":build" + cacheLifetime: "7 days" +``` + +## Project Configuration + +```yaml +# moon.yml +$schema: "https://moonrepo.dev/schemas/project.json" + +language: "typescript" +layer: "application" # v2: 'type' renamed to 'layer' +stack: "frontend" +tags: ["react", "graphql"] + +dependsOn: + - "shared-utils" + - id: "api-client" + scope: "production" + +fileGroups: + sources: + - "src/**/*" + tests: + - "tests/**/*" + +tasks: + build: + command: "vite build" + inputs: + - "@group(sources)" + outputs: + - "dist" + deps: + - "^:build" + + dev: + command: "vite dev" + preset: "server" + + # v2: Use 'script' for shell features (pipes, redirects) + lint: + script: "eslint . && prettier --check ." + + test: + command: "vitest run" + inputs: + - "@group(sources)" + - "@group(tests)" +``` + +### Layer Types (v2) + +| Layer | Description | +| --------------- | --------------------- | +| `application` | Apps, services | +| `library` | Shareable code | +| `tool` | CLIs, scripts | +| `automation` | E2E/integration tests | +| `scaffolding` | Templates, generators | +| `configuration` | Infra, config | + +## Task Configuration + +### Task Fields + +| Field | Description | +| --------- | ------------------------------------ | +| `command` | Command to execute (string or array) | +| `args` | Additional arguments | +| `deps` | Task dependencies | +| `inputs` | Files for cache hashing | +| `outputs` | Files to cache | +| `env` | Environment variables | +| `extends` | Inherit from another task | +| `preset` | `server` or `utility` | + +### Task Inheritance + +Tasks can be inherited globally via `.moon/tasks/*.yml`: + +```yaml +# .moon/tasks/node.yml +inheritedBy: + toolchains: ["javascript", "typescript"] + +fileGroups: + sources: ["src/**/*"] + +tasks: + lint: + command: "eslint ." + inputs: ["@group(sources)"] +``` + +Projects control inheritance: + +```yaml +# moon.yml +workspace: + inheritedTasks: + include: ["lint", "test"] + exclude: ["deploy"] + rename: + buildApp: "build" +``` + +### Task Options + +```yaml +tasks: + example: + command: "cmd" + options: + cache: true # Enable caching + runInCI: "affected" # affected, always, only, false + persistent: true # Long-running process + retryCount: 2 # Retry on failure + timeout: 300 # Seconds + mutex: "resource" # Exclusive lock + priority: "high" # critical, high, normal, low +``` + +### Input Tokens + +```yaml +inputs: + - "@group(sources)" # File group + - "@globs(tests)" # Glob patterns + - "/tsconfig.base.json" # Workspace root file + - "$NODE_ENV" # Environment variable +``` + +## Toolchain Configuration + +```yaml +# .moon/toolchains.yml (v2: plural) +$schema: "https://moonrepo.dev/schemas/toolchains.json" + +# JavaScript ecosystem (v2: required for node/bun/deno) +javascript: + packageManager: "pnpm" + inferTasksFromScripts: false + +node: + version: "20.10.0" + +pnpm: + version: "8.12.0" + +# Alternative runtimes +bun: + version: "1.0.0" + +deno: + version: "1.40.0" + +typescript: + syncProjectReferences: true + routeOutDirToCache: true + +rust: + version: "1.75.0" + bins: ["cargo-nextest", "cargo-llvm-cov"] + +go: + version: "1.21.0" + +python: + version: "3.12.0" +``` + +### Toolchain Tiers + +| Tier | Description | Examples | +| ---- | ---------------------- | ------------------------------------ | +| 3 | Full management | Node.js, Bun, Deno, Rust, Go, Python | +| 2 | Ecosystem integration | PHP, Ruby | +| 1 | Project categorization | Bash, Batch | +| 0 | System execution | Custom tools | + +## CI Integration + +```yaml +# GitHub Actions +- uses: actions/checkout@v4 + with: + fetch-depth: 0 # Required for affected detection + +- uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + +- run: moon ci :build :test + +- uses: moonrepo/run-report-action@v1 + if: success() || failure() + with: + access-token: ${{ secrets.GITHUB_TOKEN }} +``` + +### Parallelization with Matrix + +```yaml +strategy: + matrix: + shard: [0, 1, 2, 3] + +steps: + - run: moon ci --job ${{ matrix.shard }} --job-total 4 +``` + +### Affected Detection + +```bash +moon run :test --affected # Only affected projects +moon run :lint --affected --status staged # Only staged files +moon ci :test --base origin/main # Compare against base +moon query changed-files # v2: renamed from touched-files +``` + +## Docker Support + +```bash +moon docker scaffold # Generate Docker layers +moon docker setup # Install toolchain in Docker +moon docker prune # Prune for production +moon docker file # Generate Dockerfile +``` + +## Moon Query Language (MQL) + +```bash +# Filter projects +moon query projects "language=typescript && projectType=library" +moon run :build --query "tag=react" + +# Operators: =, !=, ~, !~, &&, || +# Fields: project, language, stack, tag, task, taskType +``` + +## Additional Resources + +For detailed configuration options, consult: + +- **`references/workspace-config.md`** - Complete workspace.yml reference +- **`references/task-config.md`** - Task configuration and inheritance patterns +- **`references/v2-migration.md`** - v1 to v2 migration guide +- **`references/cli-reference.md`** - Full CLI command reference + +### Examples + +- **`examples/workspace.yml`** - Complete workspace configuration +- **`examples/moon.yml`** - Full project configuration +- **`examples/ci-workflow.yml`** - GitHub Actions CI workflow diff --git a/.agents/skills/moon/examples/ci-workflow.yml b/.agents/skills/moon/examples/ci-workflow.yml new file mode 100644 index 0000000..dc8f68b --- /dev/null +++ b/.agents/skills/moon/examples/ci-workflow.yml @@ -0,0 +1,186 @@ +# .github/workflows/ci.yml +# Complete moon CI workflow with matrix parallelization and run reports + +name: CI Pipeline + +on: + push: + branches: ['main', 'develop'] + pull_request: + types: [opened, synchronize, reopened] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + ci: + name: 'CI (${{ matrix.shard }})' + runs-on: 'ubuntu-latest' + strategy: + fail-fast: false + matrix: + shard: [0, 1, 2, 3] + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Required for affected detection + + - name: Setup Toolchain + uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + + - name: Run CI + run: moon ci --job ${{ matrix.shard }} --job-total 4 + + - name: Report Results + uses: moonrepo/run-report-action@v1 + if: success() || failure() + with: + access-token: ${{ secrets.GITHUB_TOKEN }} + matrix: ${{ toJSON(matrix) }} + +--- + +# Alternative: Split by task type +# .github/workflows/ci-split.yml + +name: CI Pipeline (Split) + +on: + push: + branches: ['main'] + pull_request: + +jobs: + build: + name: Build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + - run: moon ci :build + + lint: + name: Lint & Format + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + - run: moon ci :lint :format + + test: + name: Test + runs-on: ubuntu-latest + needs: [build] + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + - run: moon ci :test + +--- + +# Open source multi-platform testing +# .github/workflows/ci-matrix.yml + +name: CI Matrix + +on: + push: + branches: ['main'] + pull_request: + +jobs: + ci: + name: 'CI (Node ${{ matrix.node }}, ${{ matrix.os }})' + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + node: [18, 20, 22] + + env: + MOON_NODE_VERSION: ${{ matrix.node }} + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + + - uses: moonrepo/setup-toolchain@v0 + with: + auto-install: true + + - run: moon ci + + - uses: moonrepo/run-report-action@v1 + if: success() || failure() + with: + access-token: ${{ secrets.GITHUB_TOKEN }} + matrix: ${{ toJSON(matrix) }} + +--- + +# CircleCI configuration +# .circleci/config.yml + +version: 2.1 +orbs: + node: circleci/node@5.0.2 + +jobs: + ci: + docker: + - image: cimg/base:stable + parallelism: 10 + steps: + - checkout + - node/install: + install-yarn: true + node-version: '20' + - node/install-packages: + check-cache: always + pkg-manager: yarn-berry + - run: | + curl -fsSL https://moonrepo.dev/install/proto.sh | bash + export PATH="$HOME/.proto/bin:$PATH" + moon ci --job $CIRCLE_NODE_INDEX --job-total $CIRCLE_NODE_TOTAL + +workflows: + ci: + jobs: + - ci + +--- + +# Buildkite configuration +# .buildkite/pipeline.yml + +steps: + - label: 'CI' + parallelism: 10 + commands: + - curl -fsSL https://moonrepo.dev/install/proto.sh | bash + - export PATH="$HOME/.proto/bin:$PATH" + - proto install + - moon ci --job $$BUILDKITE_PARALLEL_JOB --job-total $$BUILDKITE_PARALLEL_JOB_COUNT diff --git a/.agents/skills/moon/examples/moon.yml b/.agents/skills/moon/examples/moon.yml new file mode 100644 index 0000000..ecc330e --- /dev/null +++ b/.agents/skills/moon/examples/moon.yml @@ -0,0 +1,178 @@ +# moon.yml - Complete project configuration example +$schema: 'https://moonrepo.dev/schemas/project.json' + +# Project classification +language: 'typescript' +layer: 'application' +stack: 'frontend' + +# Metadata +project: + name: 'Web Application' + description: 'Main customer-facing web application' + owner: 'frontend-team' + maintainers: + - 'alice' + - 'bob' + channel: '#web-app' + metadata: + tier: 1 + public: true + +# Tags for querying and constraints +tags: + - 'react' + - 'next' + - 'customer-facing' + +# Explicit project dependencies +dependsOn: + - 'ui-components' + - 'shared-utils' + - id: 'api-client' + scope: 'production' + - id: 'test-fixtures' + scope: 'development' + +# Environment variables for all tasks +env: + NEXT_PUBLIC_API_URL: 'https://api.example.com' + NODE_ENV: 'production' + +# Per-project toolchain overrides +toolchain: + default: 'node' + node: + version: '20.10.0' + typescript: + includeProjectReferenceSources: true + routeOutDirToCache: true + +# File groups for reuse in tasks +fileGroups: + sources: + - 'src/**/*' + - 'app/**/*' + - 'components/**/*' + tests: + - 'tests/**/*' + - '**/*.test.{ts,tsx}' + - '**/__tests__/**/*' + configs: + - 'next.config.js' + - 'tailwind.config.js' + - 'tsconfig.json' + - 'postcss.config.js' + assets: + - 'public/**/*' + +# Control task inheritance +workspace: + inheritedTasks: + exclude: + - 'deploy-staging' + rename: + buildApp: 'build' + +# Task definitions +tasks: + build: + command: 'next build' + inputs: + - '@group(sources)' + - '@group(configs)' + - '@group(assets)' + outputs: + - '.next' + deps: + - 'ui-components:build' + - 'api-client:build' + env: + NODE_ENV: 'production' + options: + cache: true + priority: 'high' + + dev: + command: 'next dev' + preset: 'server' + deps: + - '~:codegen' + env: + NODE_ENV: 'development' + + start: + command: 'next start' + preset: 'server' + deps: + - '~:build' + + test: + command: 'vitest run' + inputs: + - '@group(sources)' + - '@group(tests)' + deps: + - '^:build' + options: + retryCount: 2 + runInCI: 'affected' + + test-watch: + command: 'vitest' + preset: 'watcher' + + lint: + command: 'eslint' + args: + - '.' + - '--ext' + - '.ts,.tsx' + inputs: + - '@group(sources)' + - '.eslintrc.js' + + lint-fix: + extends: 'lint' + args: '--fix' + options: + runInCI: false + + typecheck: + command: 'tsc --noEmit' + inputs: + - '@group(sources)' + - '@group(configs)' + + codegen: + command: 'graphql-codegen' + outputs: + - 'src/generated/' + options: + internal: true + cache: 'local' + + e2e: + command: 'playwright test' + inputs: + - 'e2e/**/*' + - 'playwright.config.ts' + deps: + - target: '~:build' + env: + NODE_ENV: 'test' + options: + interactive: true + runInCI: 'always' + timeout: 600 + retryCount: 2 + + deploy: + command: './scripts/deploy.sh' + deps: + - '~:build' + - '~:test' + - '~:e2e' + options: + runInCI: 'only' + mutex: 'deployment' diff --git a/.agents/skills/moon/examples/workspace.yml b/.agents/skills/moon/examples/workspace.yml new file mode 100644 index 0000000..69d6df4 --- /dev/null +++ b/.agents/skills/moon/examples/workspace.yml @@ -0,0 +1,67 @@ +# .moon/workspace.yml - Complete example (v2 format) +$schema: 'https://moonrepo.dev/schemas/workspace.json' + +# Project discovery +projects: + - 'apps/*' + - 'packages/*' + - 'tools/*' + +# Version control +vcs: + client: 'git' # v2: 'manager' renamed to 'client' + provider: 'github' + defaultBranch: 'main' + remoteCandidates: + - 'origin' + - 'upstream' + hooks: + pre-commit: + - 'moon run :lint --affected --status staged' + pre-push: + - 'moon run :test --affected' + +# Task pipeline (v2: 'runner' renamed to 'pipeline') +pipeline: + archivableTargets: + - ':build' + - ':test' + cacheLifetime: '7 days' + inheritColorsForPipedTasks: true + logRunningCommand: true + autoCleanCache: true + +# Hashing +hasher: + optimization: 'performance' + walkStrategy: 'vcs' + +# Code ownership +codeowners: + globalPaths: + '/*': ['@platform-team'] + orderBy: 'project-source' + sync: true # v2: 'syncOnRun' renamed to 'sync' + +# Constraints +constraints: + enforceProjectTypeRelationships: true + tagRelationships: + frontend: + requires: ['shared'] + backend: + requires: ['shared'] + +# Code generation +generator: + templates: + - './templates' + +# Remote caching (optional) +# remote: # v2: 'unstable_remote' renamed to 'remote' +# host: 'grpcs://cache.example.com' +# auth: +# token: 'CACHE_TOKEN' + +# Telemetry +telemetry: true diff --git a/.agents/skills/moon/references/cli-reference.md b/.agents/skills/moon/references/cli-reference.md new file mode 100644 index 0000000..5e03886 --- /dev/null +++ b/.agents/skills/moon/references/cli-reference.md @@ -0,0 +1,222 @@ +# Moon CLI Reference + +Complete reference for all moon CLI commands. + +## Task Execution + +### moon run + +Execute targets and their dependencies. + +```bash +moon run ... [-- ] +``` + +**Options:** + +| Flag | Description | +| ---------------------- | ------------------------------- | +| `--affected` | Only run if affected by changes | +| `--dependents` | Also run downstream dependents | +| `--force` | Bypass cache | +| `--interactive`, `-i` | Interactive task selection | +| `--no-bail` | Continue on failure | +| `--query ` | Filter with MQL | +| `--remote` | Compare against remote | +| `--status ` | Filter by status | +| `--summary` | Show execution summary | +| `--update-cache`, `-u` | Force cache update | + +**Examples:** + +```bash +moon run app:build +moon run :lint --affected +moon run '#frontend:test' +moon run app:test -- --coverage +moon run :build --query "language=typescript" +``` + +### moon check + +Run all build/test tasks for projects. + +```bash +moon check [project...] +moon check --all +``` + +### moon ci + +CI-optimized task execution with job distribution. + +```bash +moon ci [target...] +``` + +**Options:** + +| Flag | Description | +| --------------------- | ----------------------- | +| `--base ` | Base to compare against | +| `--head ` | Head revision | +| `--job ` | Job index (0-based) | +| `--job-total ` | Total parallel jobs | + +**Examples:** + +```bash +moon ci :build :test +moon ci :test --job 0 --job-total 4 +moon ci --base origin/main --head HEAD +``` + +## Query Commands + +### moon query projects + +```bash +moon query projects [mql] +moon query projects --affected +moon query projects --tags frontend +moon query projects "language=typescript" +``` + +### moon query tasks + +```bash +moon query tasks [mql] +moon query tasks --affected +moon query tasks "task~dev-*" +``` + +### moon query touched-files + +```bash +moon query touched-files +moon query touched-files --status modified,staged +moon query touched-files --base main --head HEAD +``` + +### moon query hash + +```bash +moon query hash +moon query hash-diff +``` + +## Graph Visualization + +### moon project-graph + +```bash +moon project-graph [project] +moon project-graph --dot > graph.dot +moon project-graph app --dependents +``` + +### moon action-graph + +```bash +moon action-graph [target] +moon action-graph app:build --dot +``` + +## Workspace Management + +### moon init + +```bash +moon init +moon init node +moon init --minimal +moon init --to ./app +``` + +### moon sync + +```bash +moon sync projects # Sync all projects +moon sync hooks # Sync VCS hooks +``` + +### moon setup + +```bash +moon setup # Install toolchain +``` + +### moon generate + +```bash +moon generate