@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/turborepo/turborepo/references/configuration/RULE.md

@@ -0,0 +1,211 @@
+# turbo.json Configuration Overview
+
+Configuration reference for Turborepo. Full docs: https://turborepo.dev/docs/reference/configuration
+
+## File Location
+
+Root `turbo.json` lives at repo root, sibling to root `package.json`:
+
+```
+my-monorepo/
+├── turbo.json        # Root configuration
+├── package.json
+└── packages/
+    └── web/
+        ├── turbo.json  # Package Configuration (optional)
+        └── package.json
+```
+
+## Always Prefer Package Tasks Over Root Tasks
+
+**Always use package tasks. Only use Root Tasks if you cannot succeed with package tasks.**
+
+Package tasks enable parallelization, individual caching, and filtering. Define scripts in each package's `package.json`:
+
+```json
+// packages/web/package.json
+{
+  "scripts": {
+    "build": "next build",
+    "lint": "eslint .",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}
+
+// packages/api/package.json
+{
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint .",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+```json
+// Root package.json - delegates to turbo
+{
+  "scripts": {
+    "build": "turbo run build",
+    "lint": "turbo run lint",
+    "test": "turbo run test",
+    "typecheck": "turbo run typecheck"
+  }
+}
+```
+
+When you run `turbo run lint`, Turborepo finds all packages with a `lint` script and runs them **in parallel**.
+
+**Root Tasks are a fallback**, not the default. Only use them for tasks that truly cannot run per-package (e.g., repo-level CI scripts, workspace-wide config generation).
+
+```json
+// AVOID: Task logic in root defeats parallelization
+{
+  "scripts": {
+    "lint": "eslint apps/web && eslint apps/api && eslint packages/ui"
+  }
+}
+```
+
+## Basic Structure
+
+```json
+{
+  "$schema": "https://v2-8-15-canary-3.turborepo.dev/schema.json",
+  "globalEnv": ["CI"],
+  "globalDependencies": ["tsconfig.json"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}
+```
+
+The `$schema` key enables IDE autocompletion and validation.
+
+## Configuration Sections
+
+**Global options** - Settings affecting all tasks:
+
+- `globalEnv`, `globalDependencies`, `globalPassThroughEnv`
+- `cacheDir`, `daemon`, `envMode`, `ui`, `remoteCache`
+
+**Task definitions** - Per-task settings in `tasks` object:
+
+- `dependsOn`, `outputs`, `inputs`, `env`
+- `cache`, `persistent`, `interactive`, `outputLogs`
+
+## Package Configurations
+
+Use `turbo.json` in individual packages to override root settings:
+
+```json
+// packages/web/turbo.json
+{
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      "outputs": [".next/**", "!.next/cache/**"]
+    }
+  }
+}
+```
+
+The `"extends": ["//"]` is required - it references the root configuration.
+
+**When to use Package Configurations:**
+
+- Framework-specific outputs (Next.js, Vite, etc.)
+- Package-specific env vars
+- Different caching rules for specific packages
+- Keeping framework config close to the framework code
+
+### Extending from Other Packages
+
+You can extend from config packages instead of just root:
+
+```json
+// packages/web/turbo.json
+{
+  "extends": ["//", "@repo/turbo-config"]
+}
+```
+
+### Adding to Inherited Arrays with `$TURBO_EXTENDS$`
+
+By default, array fields in Package Configurations **replace** root values. Use `$TURBO_EXTENDS$` to **append** instead:
+
+```json
+// Root turbo.json
+{
+  "tasks": {
+    "build": {
+      "outputs": ["dist/**"]
+    }
+  }
+}
+```
+
+```json
+// packages/web/turbo.json
+{
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      // Inherits "dist/**" from root, adds ".next/**"
+      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"]
+    }
+  }
+}
+```
+
+Without `$TURBO_EXTENDS$`, outputs would only be `[".next/**", "!.next/cache/**"]`.
+
+**Works with:**
+
+- `dependsOn`
+- `env`
+- `inputs`
+- `outputs`
+- `passThroughEnv`
+- `with`
+
+### Excluding Tasks from Packages
+
+Use `extends: false` to exclude a task from a package:
+
+```json
+// packages/ui/turbo.json
+{
+  "extends": ["//"],
+  "tasks": {
+    "e2e": {
+      "extends": false // UI package doesn't have e2e tests
+    }
+  }
+}
+```
+
+## `turbo.jsonc` for Comments
+
+Use `turbo.jsonc` extension to add comments with IDE support:
+
+```jsonc
+// turbo.jsonc
+{
+  "tasks": {
+    "build": {
+      // Next.js outputs
+      "outputs": [".next/**", "!.next/cache/**"]
+    }
+  }
+}
+```

package/dist/skills/frameworks/turborepo/turborepo/references/configuration/global-options.md

@@ -0,0 +1,187 @@
+# Global Options Reference
+
+Options that affect all tasks. Full docs: https://turborepo.dev/docs/reference/configuration
+
+## globalEnv
+
+Environment variables affecting all task hashes.
+
+```json
+{
+  "globalEnv": ["CI", "NODE_ENV", "VERCEL_*"]
+}
+```
+
+Use for variables that should invalidate all caches when changed.
+
+## globalDependencies
+
+Files that affect all task hashes.
+
+```json
+{
+  "globalDependencies": ["tsconfig.json", ".env", "pnpm-lock.yaml"]
+}
+```
+
+Lockfile is included by default. Add shared configs here.
+
+## globalPassThroughEnv
+
+Variables available to tasks but not included in hash.
+
+```json
+{
+  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
+}
+```
+
+Use for credentials that shouldn't affect cache keys.
+
+## cacheDir
+
+Custom cache location. Default: `node_modules/.cache/turbo`.
+
+```json
+{
+  "cacheDir": ".turbo/cache"
+}
+```
+
+## daemon
+
+**Deprecated**: The daemon is no longer used for `turbo run` and this option will be removed in version 3.0. The daemon is still used by `turbo watch` and the Turborepo LSP.
+
+## envMode
+
+How unspecified env vars are handled. Default: `"strict"`.
+
+```json
+{
+  "envMode": "strict"  // Only specified vars available
+  // or
+  "envMode": "loose"   // All vars pass through
+}
+```
+
+Strict mode catches missing env declarations.
+
+## ui
+
+Terminal UI mode. Default: `"stream"`.
+
+```json
+{
+  "ui": "tui"     // Interactive terminal UI
+  // or
+  "ui": "stream"  // Traditional streaming logs
+}
+```
+
+TUI provides better UX for parallel tasks.
+
+## remoteCache
+
+Configure remote caching.
+
+```json
+{
+  "remoteCache": {
+    "enabled": true,
+    "signature": true,
+    "timeout": 30,
+    "uploadTimeout": 60
+  }
+}
+```
+
+| Option          | Default                | Description                                            |
+| --------------- | ---------------------- | ------------------------------------------------------ |
+| `enabled`       | `true`                 | Enable/disable remote caching                          |
+| `signature`     | `false`                | Sign artifacts with `TURBO_REMOTE_CACHE_SIGNATURE_KEY` |
+| `preflight`     | `false`                | Send OPTIONS request before cache requests             |
+| `timeout`       | `30`                   | Timeout in seconds for cache operations                |
+| `uploadTimeout` | `60`                   | Timeout in seconds for uploads                         |
+| `apiUrl`        | `"https://vercel.com"` | Remote cache API endpoint                              |
+| `loginUrl`      | `"https://vercel.com"` | Login endpoint                                         |
+| `teamId`        | -                      | Team ID (must start with `team_`)                      |
+| `teamSlug`      | -                      | Team slug for querystring                              |
+
+See https://turborepo.dev/docs/core-concepts/remote-caching for setup.
+
+## concurrency
+
+Default: `"10"`
+
+Limit parallel task execution.
+
+```json
+{
+  "concurrency": "4"     // Max 4 tasks at once
+  // or
+  "concurrency": "50%"   // 50% of available CPUs
+}
+```
+
+## futureFlags
+
+Enable experimental features that will become default in future versions.
+
+```json
+{
+  "futureFlags": {
+    "errorsOnlyShowHash": true
+  }
+}
+```
+
+### `errorsOnlyShowHash`
+
+When using `outputLogs: "errors-only"`, show task hashes on start/completion:
+
+- Cache miss: `cache miss, executing <hash> (only logging errors)`
+- Cache hit: `cache hit, replaying logs (no errors) <hash>`
+
+### `longerSignatureKey`
+
+Enforce a minimum key length of 32 bytes for `TURBO_REMOTE_CACHE_SIGNATURE_KEY` when `remoteCache.signature` is enabled. Short keys weaken HMAC-SHA256 signatures. Fails the run immediately if the key is too short.
+
+## noUpdateNotifier
+
+Disable update notifications when new turbo versions are available.
+
+```json
+{
+  "noUpdateNotifier": true
+}
+```
+
+## dangerouslyDisablePackageManagerCheck
+
+Bypass the `packageManager` field requirement. Use for incremental migration.
+
+```json
+{
+  "dangerouslyDisablePackageManagerCheck": true
+}
+```
+
+**Warning**: Unstable lockfiles can cause unpredictable behavior.
+
+## Git Worktree Cache Sharing
+
+When working in Git worktrees, Turborepo automatically shares local cache between the main worktree and linked worktrees.
+
+**How it works:**
+
+- Detects worktree configuration
+- Redirects cache to main worktree's `.turbo/cache`
+- Works alongside Remote Cache
+
+**Benefits:**
+
+- Cache hits across branches
+- Reduced disk usage
+- Faster branch switching
+
+**Disabled by**: Setting explicit `cacheDir` in turbo.json.