aico-cli 2.1.7 → 2.1.23

package/templates/skills/turborepo/references/caching/README.md

@@ -0,0 +1,107 @@
+# How Turborepo Caching Works
+
+Turborepo's core principle: **never do the same work twice**.
+
+## The Cache Equation
+
+```
+fingerprint(inputs) → stored outputs
+```
+
+If inputs haven't changed, restore outputs from cache instead of re-running the task.
+
+## What Determines the Cache Key
+
+### Global Hash Inputs
+
+These affect ALL tasks in the repo:
+
+- `package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`
+- Files listed in `globalDependencies`
+- Environment variables in `globalEnv`
+- `turbo.json` configuration
+
+```json
+{
+  "globalDependencies": [".env", "tsconfig.base.json"],
+  "globalEnv": ["CI", "NODE_ENV"]
+}
+```
+
+### Task Hash Inputs
+
+These affect specific tasks:
+
+- All files in the package (unless filtered by `inputs`)
+- `package.json` contents
+- Environment variables in task's `env` key
+- Task configuration (command, outputs, dependencies)
+- Hashes of dependent tasks (`dependsOn`)
+
+```json
+{
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["src/**", "package.json", "tsconfig.json"],
+      "env": ["API_URL"]
+    }
+  }
+}
+```
+
+## What Gets Cached
+
+1. **File outputs** - files/directories specified in `outputs`
+2. **Task logs** - stdout/stderr for replay on cache hit
+
+```json
+{
+  "tasks": {
+    "build": {
+      "outputs": ["dist/**", ".next/**"]
+    }
+  }
+}
+```
+
+## Local Cache Location
+
+```
+.turbo/cache/
+├── <hash1>.tar.zst    # compressed outputs
+├── <hash2>.tar.zst
+└── ...
+```
+
+Add `.turbo` to `.gitignore`.
+
+## Cache Restoration
+
+On cache hit, Turborepo:
+
+1. Extracts archived outputs to their original locations
+2. Replays the logged stdout/stderr
+3. Reports the task as cached (shows `FULL TURBO` in output)
+
+## Example Flow
+
+```bash
+# First run - executes build, caches result
+turbo build
+# → packages/ui: cache miss, executing...
+# → packages/web: cache miss, executing...
+
+# Second run - same inputs, restores from cache
+turbo build
+# → packages/ui: cache hit, replaying output
+# → packages/web: cache hit, replaying output
+# → FULL TURBO
+```
+
+## Key Points
+
+- Cache is content-addressed (based on input hash, not timestamps)
+- Empty `outputs` array means task runs but nothing is cached
+- Tasks without `outputs` key cache nothing (use `"outputs": []` to be explicit)
+- Cache is invalidated when ANY input changes

package/templates/skills/turborepo/references/caching/gotchas.md

@@ -0,0 +1,169 @@
+# Debugging Cache Issues
+
+## Diagnostic Tools
+
+### `--summarize`
+
+Generates a JSON file with all hash inputs. Compare two runs to find differences.
+
+```bash
+turbo build --summarize
+# Creates .turbo/runs/<run-id>.json
+```
+
+The summary includes:
+
+- Global hash and its inputs
+- Per-task hashes and their inputs
+- Environment variables that affected the hash
+
+**Comparing runs:**
+
+```bash
+# Run twice, compare the summaries
+diff .turbo/runs/<first-run>.json .turbo/runs/<second-run>.json
+```
+
+### `--dry` / `--dry=json`
+
+See what would run without executing anything:
+
+```bash
+turbo build --dry
+turbo build --dry=json  # machine-readable output
+```
+
+Shows cache status for each task without running them.
+
+### `--force`
+
+Skip reading cache, re-execute all tasks:
+
+```bash
+turbo build --force
+```
+
+Useful to verify tasks actually work (not just cached results).
+
+## Unexpected Cache Misses
+
+**Symptom:** Task runs when you expected a cache hit.
+
+### Environment Variable Changed
+
+Check if an env var in the `env` key changed:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["API_URL", "NODE_ENV"]
+    }
+  }
+}
+```
+
+Different `API_URL` between runs = cache miss.
+
+### .env File Changed
+
+`.env` files aren't tracked by default. Add to `inputs`:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.local"]
+    }
+  }
+}
+```
+
+Or use `globalDependencies` for repo-wide env files:
+
+```json
+{
+  "globalDependencies": [".env"]
+}
+```
+
+### Lockfile Changed
+
+Installing/updating packages changes the global hash.
+
+### Source Files Changed
+
+Any file in the package (or in `inputs`) triggers a miss.
+
+### turbo.json Changed
+
+Config changes invalidate the global hash.
+
+## Incorrect Cache Hits
+
+**Symptom:** Cached output is stale/wrong.
+
+### Missing Environment Variable
+
+Task uses an env var not listed in `env`:
+
+```javascript
+// build.js
+const apiUrl = process.env.API_URL;  // not tracked!
+```
+
+Fix: add to task config:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "env": ["API_URL"]
+    }
+  }
+}
+```
+
+### Missing File in Inputs
+
+Task reads a file outside default inputs:
+
+```json
+{
+  "tasks": {
+    "build": {
+      "inputs": [
+        "$TURBO_DEFAULT$",
+        "../../shared-config.json"  // file outside package
+      ]
+    }
+  }
+}
+```
+
+## Useful Flags
+
+```bash
+# Only show output for cache misses
+turbo build --output-logs=new-only
+
+# Show output for everything (debugging)
+turbo build --output-logs=full
+
+# See why tasks are running
+turbo build --verbosity=2
+```
+
+## Quick Checklist
+
+Cache miss when expected hit:
+
+1. Run with `--summarize`, compare with previous run
+2. Check env vars with `--dry=json`
+3. Look for lockfile/config changes in git
+
+Cache hit when expected miss:
+
+1. Verify env var is in `env` array
+2. Verify file is in `inputs` array
+3. Check if file is outside package directory

package/templates/skills/turborepo/references/caching/remote-cache.md

@@ -0,0 +1,127 @@
+# Remote Caching
+
+Share cache artifacts across your team and CI pipelines.
+
+## Benefits
+
+- Team members get cache hits from each other's work
+- CI gets cache hits from local development (and vice versa)
+- Dramatically faster CI runs after first build
+- No more "works on my machine" rebuilds
+
+## Vercel Remote Cache
+
+Free, zero-config when deploying on Vercel. For local dev and other CI:
+
+### Local Development Setup
+
+```bash
+# Authenticate with Vercel
+npx turbo login
+
+# Link repo to your Vercel team
+npx turbo link
+```
+
+This creates `.turbo/config.json` with your team info (gitignored by default).
+
+### CI Setup
+
+Set these environment variables:
+
+```bash
+TURBO_TOKEN=<your-token>
+TURBO_TEAM=<your-team-slug>
+```
+
+Get your token from Vercel dashboard → Settings → Tokens.
+
+**GitHub Actions example:**
+
+```yaml
+- name: Build
+  run: npx turbo build
+  env:
+    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+```
+
+## Configuration in turbo.json
+
+```json
+{
+  "remoteCache": {
+    "enabled": true,
+    "signature": false
+  }
+}
+```
+
+Options:
+
+- `enabled`: toggle remote cache (default: true when authenticated)
+- `signature`: require artifact signing (default: false)
+
+## Artifact Signing
+
+Verify cache artifacts haven't been tampered with:
+
+```bash
+# Set a secret key (use same key across all environments)
+export TURBO_REMOTE_CACHE_SIGNATURE_KEY="your-secret-key"
+```
+
+Enable in config:
+
+```json
+{
+  "remoteCache": {
+    "signature": true
+  }
+}
+```
+
+Signed artifacts can only be restored if the signature matches.
+
+## Self-Hosted Options
+
+Community implementations for running your own cache server:
+
+- **turbo-remote-cache** (Node.js) - supports S3, GCS, Azure
+- **turborepo-remote-cache** (Go) - lightweight, S3-compatible
+- **ducktape** (Rust) - high-performance option
+
+Configure with environment variables:
+
+```bash
+TURBO_API=https://your-cache-server.com
+TURBO_TOKEN=your-auth-token
+TURBO_TEAM=your-team
+```
+
+## Cache Behavior Control
+
+```bash
+# Disable remote cache for a run
+turbo build --remote-cache-read-only  # read but don't write
+turbo build --no-cache                # skip cache entirely
+
+# Environment variable alternative
+TURBO_REMOTE_ONLY=true  # only use remote, skip local
+```
+
+## Debugging Remote Cache
+
+```bash
+# Verbose output shows cache operations
+turbo build --verbosity=2
+
+# Check if remote cache is configured
+turbo config
+```
+
+Look for:
+
+- "Remote caching enabled" in output
+- Upload/download messages during runs
+- "cache hit, replaying output" with remote cache indicator

package/templates/skills/turborepo/references/ci/README.md

@@ -0,0 +1,79 @@
+# CI/CD with Turborepo
+
+General principles for running Turborepo in continuous integration environments.
+
+## Core Principles
+
+### Always Use `turbo run` in CI
+
+**Never use the `turbo <tasks>` shorthand in CI or scripts.** Always use `turbo run`:
+
+```bash
+# CORRECT - Always use in CI, package.json, scripts
+turbo run build test lint
+
+# WRONG - Shorthand is only for one-off terminal commands
+turbo build test lint
+```
+
+The shorthand `turbo <tasks>` is only for one-off invocations typed directly in terminal by humans or agents. Anywhere the command is written into code (CI, package.json, scripts), use `turbo run`.
+
+### Enable Remote Caching
+
+Remote caching dramatically speeds up CI by sharing cached artifacts across runs.
+
+Required environment variables:
+
+```bash
+TURBO_TOKEN=your_vercel_token
+TURBO_TEAM=your_team_slug
+```
+
+### Use --affected for PR Builds
+
+The `--affected` flag only runs tasks for packages changed since the base branch:
+
+```bash
+turbo run build test --affected
+```
+
+This requires Git history to compute what changed.
+
+## Git History Requirements
+
+### Fetch Depth
+
+`--affected` needs access to the merge base. Shallow clones break this.
+
+```yaml
+# GitHub Actions
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 2  # Minimum for --affected
+    # Use 0 for full history if merge base is far
+```
+
+### Why Shallow Clones Break --affected
+
+Turborepo compares the current HEAD to the merge base with `main`. If that commit isn't fetched, `--affected` falls back to running everything.
+
+For PRs with many commits, consider:
+
+```yaml
+fetch-depth: 0  # Full history
+```
+
+## Environment Variables Reference
+
+| Variable            | Purpose                              |
+| ------------------- | ------------------------------------ |
+| `TURBO_TOKEN`       | Vercel access token for remote cache |
+| `TURBO_TEAM`        | Your Vercel team slug                |
+| `TURBO_REMOTE_ONLY` | Skip local cache, use remote only    |
+| `TURBO_LOG_ORDER`   | Set to `grouped` for cleaner CI logs |
+
+## See Also
+
+- [github-actions.md](./github-actions.md) - GitHub Actions setup
+- [vercel.md](./vercel.md) - Vercel deployment
+- [patterns.md](./patterns.md) - CI optimization patterns

package/templates/skills/turborepo/references/ci/github-actions.md

@@ -0,0 +1,162 @@
+# GitHub Actions
+
+Complete setup guide for Turborepo with GitHub Actions.
+
+## Basic Workflow Structure
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build and Test
+        run: turbo run build test lint
+```
+
+## Package Manager Setup
+
+### pnpm
+
+```yaml
+- uses: pnpm/action-setup@v3
+  with:
+    version: 9
+
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: 'pnpm'
+
+- run: pnpm install --frozen-lockfile
+```
+
+### Yarn
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 20
+    cache: 'yarn'
+
+- run: yarn install --frozen-lockfile
+```
+
+### Bun
+
+```yaml
+- uses: oven-sh/setup-bun@v1
+  with:
+    bun-version: latest
+
+- run: bun install --frozen-lockfile
+```
+
+## Remote Cache Setup
+
+### 1. Create Vercel Access Token
+
+1. Go to [Vercel Dashboard](https://vercel.com/account/tokens)
+2. Create a new token with appropriate scope
+3. Copy the token value
+
+### 2. Add Secrets and Variables
+
+In your GitHub repository settings:
+
+**Secrets** (Settings > Secrets and variables > Actions > Secrets):
+
+- `TURBO_TOKEN`: Your Vercel access token
+
+**Variables** (Settings > Secrets and variables > Actions > Variables):
+
+- `TURBO_TEAM`: Your Vercel team slug
+
+### 3. Add to Workflow
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+```
+
+## Alternative: actions/cache
+
+If you can't use remote cache, cache Turborepo's local cache directory:
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: .turbo
+    key: turbo-${{ runner.os }}-${{ hashFiles('**/turbo.json', '**/package-lock.json') }}
+    restore-keys: |
+      turbo-${{ runner.os }}-
+```
+
+Note: This is less effective than remote cache since it's per-branch.
+
+## Complete Example
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: turbo run build --affected
+
+      - name: Test
+        run: turbo run test --affected
+
+      - name: Lint
+        run: turbo run lint --affected
+```