@savvy-web/mcp 0.3.0 → 0.4.0

package/public/content/standards/turbo/best-practices.md

@@ -0,0 +1,76 @@
+---
+id: standards/turbo/best-practices
+title: Turborepo task-graph best practices
+summary: dependsOn topology, transit tasks, declaring outputs, and the prebuild/parallel anti-patterns.
+tier: standards
+source: hand
+tags: [turbo, build, workspace]
+priority: 0.7
+related: [standards/turbo/environment, standards/turbo/filtering, standards/dependency-conventions]
+---
+
+## ^build vs build in dependsOn
+
+The caret matters and is the single most misread part of `dependsOn`:
+
+- `"^build"` — run **build in this package's dependencies first** (topological).
+  This is what a normal build wants: `dist/dev` of upstream packages must exist
+  before this one compiles.
+- `"build"` — run **another task in the same package first** (e.g. a `test` that
+  `dependsOn: ["build"]`). No caret means same-package only.
+
+```jsonc
+{
+  "tasks": {
+    "build:prod": { "dependsOn": ["^build:prod"], "outputs": ["dist/prod/**"] },
+    "test": { "dependsOn": ["build"] }
+  }
+}
+```
+
+Mixing these up gives you either packages compiling against unbuilt dependencies
+(forgot the caret) or a needless full-topology rebuild (added one you didn't
+need).
+
+## Transit tasks for parallel-but-correct invalidation
+
+A "transit" task is a near-empty task that exists only to carry dependency edges:
+it declares `dependsOn: ["^transit"]` and no real work. Downstream tasks depend on
+it so they invalidate when any upstream source changes, while the actual heavy
+tasks still run in parallel rather than serializing behind each other. Use this
+when you want correct cache invalidation across the graph without forcing a
+strict topological chain through every real task.
+
+## Always declare outputs
+
+If a task writes files but its `outputs` glob is missing or wrong, turbo caches
+**nothing** to restore — the next "cache hit" replays the log but leaves the
+working tree without the artifacts, and the following task fails on a missing
+`dist/`. Every build task here declares its real output dir (`dist/dev/**`,
+`dist/prod/**`, `meta/**`). The `build:catalog`/`build:meta` tasks are the
+exceptions that are deliberately uncached.
+
+## Don't over-broaden globalDependencies
+
+Listing a frequently-touched file (a top-level `README`, a changelog) in
+`globalDependencies` busts every package's cache on every unrelated edit. Scope
+shared inputs to the configs that genuinely affect output.
+
+## Avoid --parallel for ordered work
+
+`--parallel` ignores `dependsOn` entirely and runs everything at once. It is only
+correct for independent tasks (linting every package). Using it for builds races
+dependencies and produces flaky, order-dependent failures — let the dependency
+graph schedule instead.
+
+## prebuild lifecycle scripts defeat caching
+
+npm `prebuild`/`postbuild` lifecycle scripts run **outside** turbo's hash and
+ordering, so their effects are neither cached nor invalidated correctly. Silk
+forbids build-in-install hooks for exactly this reason; keep every build step as
+a named turbo task, not a lifecycle shim.
+
+## See also
+
+Env-hash correctness is at `silk://standards/turbo/environment`. Dependency
+declaration rules are at `silk://standards/dependency-conventions`.

package/public/content/standards/turbo/boundaries.md

@@ -0,0 +1,72 @@
+---
+id: standards/turbo/boundaries
+title: Turborepo boundaries
+summary: Tags and allow/deny rules for enforcing package dependency layering.
+tier: standards
+source: hand
+tags: [turbo, workspace, dependencies]
+priority: 0.5
+related: [standards/dependency-conventions, standards/turbo/best-practices]
+---
+
+## Rule
+
+`turbo boundaries` enforces **who may depend on whom** by tagging packages and
+declaring allow/deny rules between tags. It turns an architectural invariant —
+"the CLI must not import silk," "mcp depends on neither cli nor silk" — into a
+checked rule rather than a convention people remember.
+
+## Tagging packages
+
+Tag each package in its `turbo.json` (or the package's `turbo` config):
+
+```jsonc
+// packages/cli/turbo.json
+{ "tags": ["app"] }
+
+// packages/silk-effects/turbo.json
+{ "tags": ["lib"] }
+```
+
+## Allow / deny rules
+
+Declare the permitted dependency directions at the root:
+
+```jsonc
+{
+  "boundaries": {
+    "tags": {
+      "app": { "dependencies": { "allow": ["lib"] } },
+      "lib": { "dependencies": { "deny": ["app"] } }
+    }
+  }
+}
+```
+
+Run the check with:
+
+```bash
+turbo boundaries
+```
+
+It fails when an import crosses a denied edge — catching, for example, a stray
+`@savvy-web/silk` import inside `@savvy-web/cli` that would violate the cli↔silk
+non-import invariant, or an attempt to import cli/silk from mcp.
+
+## Why encode it
+
+The cli↔silk↔mcp non-import invariant is load-bearing: the three packages depend
+only on silk-effects within the repo. A reviewer can miss a new import; a
+boundaries rule cannot. Encoding the layering also documents intent — the tag
+graph is the dependency policy, version-controlled next to the code.
+
+## Anti-patterns
+
+Do not tag packages so loosely that every package can depend on every other —
+that yields green checks with zero protection. Tag by architectural layer
+(`app`, `lib`, `tooling`) so the deny rules actually constrain the graph.
+
+## See also
+
+The underlying import rules are at `silk://standards/dependency-conventions`.
+Graph-correctness practices are at `silk://standards/turbo/best-practices`.

package/public/content/standards/turbo/ci.md

@@ -0,0 +1,69 @@
+---
+id: standards/turbo/ci
+title: Turborepo in CI
+summary: Remote caching, --affected, turbo prune, and turbo-ignore in the Silk install→build→checks pipeline.
+tier: standards
+source: hand
+tags: [turbo, ci, github-actions, build]
+priority: 0.6
+related: [standards/turbo/filtering, standards/turbo/environment, standards/turbo/best-practices]
+---
+
+## Rule
+
+CI runs tasks through `turbo`, never by hand-iterating packages. The Silk job
+order is fixed: **install → build → checks**. Install (`pnpm install
+--frozen-lockfile`) never builds — there are no `prepare` build scripts — so an
+explicit `pnpm build` (turbo `build:dev` + `build:prod`) must run before any
+check that imports a `@savvy-web/*` package, because consumers resolve the built
+`dist/dev` via `linkDirectory`.
+
+## Remote caching
+
+Set `TURBO_TOKEN` and `TURBO_TEAM` in the job environment. With those present,
+`turbo` reads and writes the remote cache automatically. In CI use
+`--remote-only` so the run never trusts a stale local `.turbo` directory that a
+runner image might carry:
+
+```bash
+turbo run build --remote-only
+turbo run lint test typecheck --remote-only
+```
+
+A populated remote cache turns a no-change `build:prod` into a restore, which is
+what makes the `build:prod → generate:api-docs → build:catalog → build` chain
+cheap on unaffected PRs.
+
+## Only build what changed
+
+Use `--affected` to scope a run to packages touched since the merge base. Turbo
+auto-detects the base/head refs in GitHub Actions; locally pass them explicitly:
+
+```bash
+turbo run test --affected
+turbo run test --affected --filter=...[origin/main...HEAD]   # explicit refs
+```
+
+Pair this with a full-history checkout (`fetch-depth: 0` or a known base ref) so
+the diff is accurate. A shallow clone makes `--affected` over-select.
+
+## Docker and skipping runs
+
+For container builds, `turbo prune <pkg> --docker` emits a pruned subset
+(`out/json` lockfile layer + `out/full` source layer) so the image only installs
+and builds that package's slice — keep the two layers separate to preserve Docker
+layer caching. To skip an entire workflow when nothing relevant changed, gate the
+job on `turbo-ignore`, which exits non-zero only when the target package (and its
+dependencies) changed.
+
+## Anti-patterns
+
+Do not build inside an install hook to "warm" CI — mcp's `build:dev` pulls the
+libraries' `build:prod`, which resolves `catalog:silkPeers` from the workspace
+state file pnpm writes only after install scripts, so an install-time build fails
+with `Catalog(s) not found: silkPeers`. Keep build a post-install turbo step.
+
+## See also
+
+Scoping syntax is at `silk://standards/turbo/filtering`. Cache-correct env
+declarations are at `silk://standards/turbo/environment`.

package/public/content/standards/turbo/environment.md

@@ -0,0 +1,64 @@
+---
+id: standards/turbo/environment
+title: Turborepo environment hashing
+summary: env/globalEnv, passThroughEnv, globalDependencies, and why missing declarations corrupt the cache.
+tier: standards
+source: hand
+tags: [turbo, ci, build]
+priority: 0.7
+related: [standards/turbo/best-practices, standards/turbo/ci]
+---
+
+## Rule
+
+Any environment variable that changes a task's **output** must be declared in
+that task's `env`, or the cache will hand back output built under a different
+value. Turbo only hashes env vars you declare; an undeclared var is invisible to
+the cache and is the most common source of "it worked on my machine, the cache
+gave me stale bytes" bugs.
+
+## env vs globalEnv
+
+- `env` (per task): vars that affect that task's output — e.g. `NODE_ENV` for a
+  build, registry tokens for a publish step.
+- `globalEnv` (root `pipeline`/`globalEnv`): vars that affect **every** task's
+  hash. Use sparingly; an over-broad `globalEnv` busts every cache entry whenever
+  it changes.
+
+```jsonc
+{
+  "globalEnv": ["NODE_ENV"],
+  "tasks": {
+    "build:prod": { "env": ["TURBO_TOKEN", "TURBO_TEAM"], "outputs": ["dist/prod/**"] }
+  }
+}
+```
+
+## passThroughEnv
+
+`passThroughEnv` / `globalPassThroughEnv` make a var **available to the task
+process without adding it to the hash**. Use it for things that must reach the
+process but must not invalidate the cache — e.g. `GITHUB_TOKEN` during a
+network-only step. Pass-through is the deliberate escape hatch; reaching for it
+to hide a genuine input is how you reintroduce the stale-cache bug.
+
+## globalDependencies
+
+`globalDependencies` lists files outside any package whose contents should feed
+every task hash — `tsconfig.base.json`, the root `biome.jsonc`, `.nvmrc`. When a
+shared config changes, every cache entry should miss; that only happens if the
+file is declared here.
+
+## The root .env anti-pattern
+
+Turbo does not read a root `.env` into task hashes. A var set only in `.env`
+silently changes output while the hash stays constant, so the cache returns bytes
+built under the old value. If a value must affect a build, declare it in `env`
+and let CI inject it — do not rely on a loose `.env`. Silk's install and build
+are decoupled, so there is no install hook quietly sourcing env either; CI sets
+exactly what each task declares.
+
+## See also
+
+The anti-pattern catalog is at `silk://standards/turbo/best-practices`.
+Remote-cache env wiring is at `silk://standards/turbo/ci`.

package/public/content/standards/turbo/filtering.md

@@ -0,0 +1,72 @@
+---
+id: standards/turbo/filtering
+title: Turborepo task filtering
+summary: --filter syntax, dependency/dependent expansion, changed-since filters, and --affected.
+tier: standards
+source: hand
+tags: [turbo, workspace, build]
+priority: 0.6
+related: [standards/turbo/ci, standards/turbo/best-practices]
+---
+
+## Rule
+
+`--filter` selects which packages a task runs in. Stack filters (each `--filter`
+is a union) and lean on the dependency-expansion operators so you never have to
+list packages by hand.
+
+## Package selectors
+
+```bash
+turbo run build --filter=@savvy-web/mcp          # one package
+turbo run build --filter='./packages/*'          # by directory glob
+turbo run build --filter='@savvy-web/*'          # by name glob
+```
+
+## Dependency / dependent expansion
+
+The `...` operator pulls in the rest of the graph relative to a package:
+
+| Selector | Meaning |
+| :--- | :--- |
+| `@savvy-web/mcp...` | mcp **and everything it depends on** |
+| `...@savvy-web/mcp` | mcp **and everything that depends on it** |
+| `...@savvy-web/silk-effects...` | the package plus dependents and dependencies |
+| `@savvy-web/mcp^...` | mcp's dependencies only (exclude mcp itself) |
+
+`...@savvy-web/silk-effects` is the practical way to rebuild the four libraries'
+downstream consumers (cli, silk, mcp) after a shared-library edit, without
+naming each one.
+
+## Changed-since filters
+
+`[<git-ref>]` restricts to packages changed since a ref, and composes with `...`:
+
+```bash
+turbo run test --filter='[origin/main]'              # changed vs main
+turbo run test --filter='...[origin/main...HEAD]'    # changed + their dependents
+turbo run build --filter='@savvy-web/mcp[HEAD^1]'    # mcp, only if it changed
+```
+
+## --affected
+
+`--affected` is the ergonomic shorthand for "changed vs the merge base, plus
+dependents," with the base/head auto-detected in CI:
+
+```bash
+turbo run lint test typecheck --affected
+```
+
+Prefer `--affected` in CI and reserve explicit `[<ref>]` filters for cases where
+you need a non-default base. Both need real git history — a shallow checkout
+over-selects.
+
+## Anti-patterns
+
+Do not chain `cd packages/foo && pnpm build` to scope a build; you lose turbo's
+cache and topological ordering. Use `--filter` so dependencies still build first
+and cache hits still count.
+
+## See also
+
+Using filters in CI is at `silk://standards/turbo/ci`.

package/public/content/standards/turbo/watch.md

@@ -0,0 +1,64 @@
+---
+id: standards/turbo/watch
+title: Turborepo watch and persistent tasks
+summary: turbo watch, persistent/dev tasks, interactive tasks, and watch-mode caveats.
+tier: standards
+source: hand
+tags: [turbo, build, workspace]
+priority: 0.5
+related: [standards/turbo/best-practices, standards/turbo/filtering]
+---
+
+## Rule
+
+`turbo watch <task>` re-runs a task across the workspace whenever its inputs
+change, respecting the dependency graph — an edit in a library re-triggers its
+dependents in topological order. This is distinct from a framework's own watcher:
+turbo watch coordinates the **graph**, the per-package tool handles incremental
+recompilation inside one package.
+
+```bash
+turbo watch build:dev          # rebuild dev artifacts on change, in dep order
+turbo watch test --filter=@savvy-web/mcp...
+```
+
+## Persistent (dev) tasks
+
+A long-running process — a dev server, a `tsc --watch`, a sidecar — is a
+**persistent** task. Mark it so turbo never treats its exit as task completion
+and never tries to cache it:
+
+```jsonc
+{
+  "tasks": {
+    "dev": { "persistent": true, "cache": false }
+  }
+}
+```
+
+A persistent task may not appear in another task's `dependsOn` (it never
+finishes, so nothing downstream could ever start). Model a needed background
+service as a separate persistent task you start alongside, not as a dependency
+edge.
+
+## Interactive tasks
+
+Tasks that need a TTY (prompts, REPLs) must opt in with `"interactive": true` so
+turbo gives them stdin and does not multiplex their output. Reserve this for
+genuinely interactive tooling; most CI tasks should stay non-interactive so logs
+stream cleanly.
+
+## Caveats
+
+- Watch mode shines for iteration, not validation. CI still runs discrete
+  `turbo run` tasks so every step is hashed and cacheable.
+- Newly added or deleted files may need a watcher restart if a tool's own
+  watcher does not pick up tree changes.
+- `cache: false` on persistent tasks is required; a cached "dev server" is
+  meaningless and turbo will warn.
+
+## See also
+
+The persistent-task / `dependsOn` interaction is covered under outputs and
+parallelism at `silk://standards/turbo/best-practices`. Scoping watch to a subset
+uses the syntax at `silk://standards/turbo/filtering`.

package/{resources → public}/content/tags.json

@@ -23,5 +23,7 @@
 	"github-action-effects": ["gha-effects"],
 	"github-action-builder": ["gha-builder"],
 	"semver": ["versioning"],
-	"github-actions": ["gha", "actions"]
+	"github-actions": ["gha", "actions"],
+	"turbo": ["turborepo"],
+	"ci": ["continuous-integration", "remote-cache"]
 }