@savvy-web/mcp 1.3.5 → 1.4.0

package/content/standards/dependency-conventions.md

@@ -1,82 +0,0 @@
----
-id: standards/dependency-conventions
-title: Dependency conventions
-summary: When to use catalog:silk vs catalog:silkPeers, and how the pnpm-plugin-silk config dependency pins versions.
-tier: standards
-source: hand
-tags: [dependencies, catalog]
-priority: 0.5
-related: [standards/catalog-usage]
----
-
-## Rule
-
-All Silk Suite packages pin dependencies through the named catalogs provided by
-`@savvy-web/pnpm-plugin-silk`:
-
-- Use `catalog:silk` for `dependencies` and `devDependencies` (current pinned versions).
-- Use `catalog:silkPeers` for `peerDependencies` (permissive ranges).
-
-Do not hard-code version strings for catalog-managed packages.
-
-### How the plugin works
-
-`@savvy-web/pnpm-plugin-silk` is installed as a pnpm config dependency:
-
-```yaml
-configDependencies:
-  "@savvy-web/pnpm-plugin-silk": "0.3.0+sha512-..."
-```
-
-During `pnpm install` the plugin merges its catalog definitions, security overrides,
-and build configuration into the consuming repo's `pnpm-workspace.yaml`. The merge
-is non-destructive — local definitions always take precedence, and divergences are
-printed as warnings.
-
-The plugin ships:
-
-- `catalog:silk` — current/latest pinned versions for direct use
-- `catalog:silkPeers` — permissive ranges for peer declarations
-- `silkOverrides` — centralized CVE fixes propagated to all consumers
-- Shared `onlyBuiltDependencies`, `publicHoistPattern`, and `peerDependencyRules`
-
-### Effect ecosystem note
-
-The 26 `@effect/*` packages are updated together as one batch to preserve
-cross-package compatibility. For `@effect/*` packages (all at `0.x`),
-`catalog:silkPeers` uses `>=` floor-only ranges rather than `^` caret ranges,
-because `^0.x.y` restricts to patch-only and would not overlap with the `silk`
-pinned version one minor ahead. For `effect` itself (at `3.x`) the standard `^`
-caret works.
-
-## Why
-
-Centralizing versions in the plugin keeps every repo in the ecosystem on one
-coordinated set and lets security overrides for transitive CVEs land without
-per-repo edits. The dual-catalog strategy balances two needs: direct consumers get a
-predictable pinned version; peer consumers stay compatible with a wider range of
-host environments without forcing lockstep upgrades.
-
-## Examples
-
-```json
-{
-  "devDependencies": {
-    "typescript": "catalog:silk",
-    "vitest": "catalog:silk"
-  },
-  "peerDependencies": {
-    "typescript": "catalog:silkPeers"
-  }
-}
-```
-
-To override a catalog entry for a single repo, add it under `catalogs.silk` in
-`pnpm-workspace.yaml`; the local value wins and the plugin prints a warning. Remove
-the local entry to revert to the Silk default.
-
-## See also
-
-Detailed catalog usage rules (including when to add a local override) are at
-`silk://standards/catalog-usage`. Publishability and registry targets that determine
-which packages enter the release pipeline are at `silk://standards/publishability`.

package/content/standards/linting-conventions.md

@@ -1,47 +0,0 @@
----
-id: standards/linting-conventions
-title: Linting and formatting
-summary: Load when writing TypeScript or markdown that must pass Biome and markdownlint.
-tier: standards
-source: hand
-tags: [lint]
-priority: 0.8
-related: [standards/test-classification]
----
-
-## Rule
-
-TypeScript is formatted and linted with Biome; markdown with markdownlint-cli2.
-Both run in pre-commit through `@savvy-web/lint-staged` composable handlers, so
-code that violates these rules does not commit.
-
-## Why
-
-A single shared config means contributors and agents follow the project's style
-without being told it each session, and CI enforces the same rules locally and
-remotely. The lint-staged plugin injects the active rules into Claude Code at
-session start for exactly this reason.
-
-## Examples
-
-Biome enforcements that bite most often:
-
-- `useImportExtensions` — relative imports MUST use `.js` extensions (ESM).
-- `useImportType` — type-only imports use `import type { Foo }`, not `import { type Foo }`.
-- `useNodejsImportProtocol` — Node built-ins use the `node:` protocol (`node:fs`).
-- `useConsistentTypeDefinitions` — prefer interfaces.
-- `noUnusedVariables` and `noImportCycles` are errors. Imports auto-sort.
-- Test files relax `noUndeclaredDependencies`.
-
-markdownlint rules that bite most often:
-
-- No line-length limit (MD013 disabled).
-- Duplicate headings allowed only among siblings (MD024).
-- HTML restricted to `br`, `details`, `summary`, `img`, `sup`, `sub`.
-- Code fences MUST carry a language identifier (MD040).
-- Tables use compact style — single space around cell content (MD060).
-- Files end with a single trailing newline (MD047).
-
-## See also
-
-Test file naming and discovery is at `silk://standards/test-classification`.

package/content/standards/publishability.md

@@ -1,57 +0,0 @@
----
-id: standards/publishability
-title: Publishability rules
-summary: Load when deciding whether a package publishes and how private vs publishConfig interact.
-tier: standards
-source: hand
-tags: [publishability]
-priority: 0.8
-related: [packages/silk-effects/, standards/catalog-usage]
----
-
-## Rule
-
-A package's publishability is resolved from its `package.json` by applying these
-rules in order; the first match wins:
-
-1. `publishConfig.targets` is a non-empty array → one target per surviving entry.
-2. `publishConfig.access` is `public` or `restricted` → a single target.
-3. `private !== true` → a single default target.
-4. otherwise → not publishable (empty).
-
-`publishConfig.targets` takes precedence over the `private` flag: a package with
-`private: true` and a `publishConfig.targets` array still publishes. The `private`
-flag is consulted only as the last-resort default in rule 3.
-
-## Why
-
-In the Silk ecosystem `private: true` is the norm on source `package.json` files,
-and `publishConfig` declares publish intent. The builder flips `private` based on
-`publishConfig.access` at build time, so a source package with `private: true` and
-`publishConfig.access: "public"` is publishable. Encoding intent in `publishConfig`
-rather than the bare `private` flag lets a workspace keep packages private during
-development and publish them deliberately.
-
-`SilkPublishability.detect` is the pure entry point. Shorthand string targets
-expand to registries: `"npm"` → npmjs, `"github"` → GitHub Packages, `"jsr"` →
-jsr; an `http(s)://…` value is verbatim. String targets inherit the parent
-`publishConfig.access`; object targets use their own access else the parent's.
-
-## Examples
-
-```text
-{ private: true, publishConfig: { access: "public", targets: ["npm", "github"] } }
-  → publishes to both npm and GitHub Packages
-
-{ private: true }
-  → not publishable (empty)
-```
-
-The adaptive detector additionally short-circuits changeset-ignored packages to
-empty and dispatches on changeset mode (`none` → empty, `silk` → Silk rules,
-`vanilla` → upstream default).
-
-## See also
-
-The detector services and layers are documented at `silk://packages/silk-effects/`.
-Dependency pinning is at `silk://standards/catalog-usage`.

package/content/standards/semver.md

@@ -1,51 +0,0 @@
----
-id: standards/semver
-title: Strict SemVer (no v-prefix)
-summary: Strict SemVer 2.0.0 everywhere; git tags carry no leading v.
-tier: standards
-source: hand
-tags: [semver]
-priority: 0.5
-related: [standards/changeset-discipline]
----
-
-## Rule
-
-Silk uses strict SemVer 2.0.0 for all version numbers. Git tags carry **no
-leading `v` prefix**. This applies everywhere — package versions, git tags, and
-version ranges authored by hand.
-
-| Context | Correct | Incorrect |
-| :--- | :--- | :--- |
-| `package.json` `"version"` | `"1.2.3"` | `"v1.2.3"` |
-| git tag for a release | `foo@1.2.3` or `1.2.3` | `vfoo@1.2.3` or `v1.2.3` |
-| changeset bump result | `1.2.3` | `v1.2.3` |
-
-## Why
-
-The `v` prefix is noise that breaks strict SemVer parsers. Many tools (including
-the Node.js SemVer library in strict mode) treat `v1.2.3` as an invalid version.
-Consistent, tool-parseable versions across every surface — npm registry, git tags,
-changelog entries, and API references — removes an entire class of subtle breakage
-where one tool normalizes the prefix and another does not.
-
-## Examples
-
-A release of `@savvy-web/foo` at version `1.2.3` is tagged `foo@1.2.3` (or
-`1.2.3` for single-package repos). The `package.json` carries `"version": "1.2.3"`.
-The CHANGELOG entry title reads `1.2.3`. No `v` anywhere.
-
-```bash
-# correct
-git tag foo@1.2.3
-
-# incorrect — never do this
-git tag vfoo@1.2.3
-git tag v1.2.3
-```
-
-## See also
-
-Changesets and bump mechanics are at `silk://standards/changeset-discipline`.
-Publishability rules (which determine when a tag triggers a release) are at
-`silk://standards/publishability`.

package/content/standards/test-classification.md

@@ -1,49 +0,0 @@
----
-id: standards/test-classification
-title: Test classification
-summary: Load when naming a test file or wondering why Vitest classifies it as unit, e2e, or int.
-tier: standards
-source: hand
-tags: [test]
-priority: 0.8
-related: [standards/linting-conventions]
----
-
-## Rule
-
-`VitestConfig.create()` discovers workspace packages and classifies each test file
-by its **filename**, not its directory. The first matching pattern wins:
-
-- `*.e2e.(test|spec).(ts|tsx|js|jsx)` → e2e
-- `*.int.(test|spec).(ts|tsx|js|jsx)` → integration
-- `*.(test|spec).(ts|tsx|js|jsx)` → unit (catch-all; `*.unit.test.ts` lands here)
-
-Files matching none are ignored. Tests live in `src/` and an optional `__test__/`
-directory beside it; only packages with a `src/` directory are scanned.
-
-## Why
-
-Filename-driven classification keeps the directory layout free and the kind
-unambiguous — `foo.e2e.test.ts` is never double-counted as a unit test because the
-e2e pattern is checked first. A package with one test kind gets a bare project name
-(`@scope/pkg`); two or more kinds get suffixed names (`@scope/pkg:unit`,
-`@scope/pkg:e2e`). A package with `src/` but no tests still gets a unit project as
-a forward-looking placeholder.
-
-## Examples
-
-`parser.test.ts` and `parser.unit.test.ts` → unit. `auth.e2e.test.ts` → e2e.
-`db.int.test.ts` → integration.
-
-Helper and fixture directories are excluded from discovery at conventional
-locations only: `__test__/fixtures/`, `__test__/utils/`, and the same under
-`__test__/{unit,e2e,integration}/`. A `vitest.setup.{ts,tsx,js,jsx}` at the
-package root is auto-detected and added to `setupFiles`.
-
-Coverage defaults to the `"strict"` level (lines 80, branches 75, functions 80,
-statements 80). Passing `--project` flags scopes coverage to the union of the
-matched packages.
-
-## See also
-
-Lint and format rules are at `silk://standards/linting-conventions`.

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

@@ -1,76 +0,0 @@
----
-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/content/standards/turbo/boundaries.md

@@ -1,72 +0,0 @@
----
-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/content/standards/turbo/ci.md

@@ -1,69 +0,0 @@
----
-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/content/standards/turbo/environment.md

@@ -1,64 +0,0 @@
----
-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/content/standards/turbo/filtering.md

@@ -1,72 +0,0 @@
----
-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`.