@savvy-web/mcp 1.3.5 → 1.5.0

package/content/guides/api-docs-from-api-extractor.md

@@ -1,174 +0,0 @@
----
-id: guides/api-docs-from-api-extractor
-title: Generating API docs from API Extractor
-summary: Configure the meta option, build the model, and render LLM-lean markdown with api-extractor-llms.
-tier: guides
-source: hand
-tags: [api, build]
-priority: 0.5
-related: [standards/api-model-pipeline, packages/bundler/overview]
----
-
-## Overview
-
-The Silk Suite generates API-reference docs from Microsoft API Extractor models
-rather than hand-authoring them. The pipeline has three stages: emit a model,
-render it to markdown, and compile rendered docs into the MCP resource corpus.
-This guide walks through each stage as implemented in this repo.
-
-For the policy contract (what is generated, what must not be edited, where docs
-land), see `silk://standards/api-model-pipeline`.
-
-## Step 1 — Emit the API model from the build
-
-A library built by `@savvy-web/bundler` emits an API Extractor model on its
-production build by default — there is nothing to enable. The model is controlled
-by the `meta` option in `savvy.build.ts`:
-
-```typescript
-import { defineBuild, runBuild } from "@savvy-web/bundler";
-
-const config = defineBuild({
-  // meta omitted → API model is generated with default options on --target prod.
-  // Pass an object only to override defaults, e.g. to register custom TSDoc tags:
-  meta: {
-    tsdoc: {
-      tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
-    },
-  },
-});
-
-export default config;
-
-if (import.meta.main) {
-  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
-}
-```
-
-Omitting `meta` generates the model with defaults; pass `false` to opt out
-entirely (the MCP server itself does this — it is an executable host, not a
-documented API). The entry point and package name are derived from `exports`.
-Only public surfaces are captured; members annotated `@internal` are excluded.
-
-See `silk://packages/bundler/overview` for the full builder surface.
-
-## Step 2 — Build the model
-
-```bash
-pnpm --filter @savvy-web/your-package run build:prod
-```
-
-The production build writes `dist/prod/npm/meta/<unscoped-name>.api.json` and
-stages a copy into each consumer declared in `meta.localPaths` — for the MCP
-corpus that is `packages/mcp/lib/models/<dir>/<unscoped-name>.api.json`. For
-example, `@savvy-web/silk-effects` emits `silk-effects.api.json`. The generator
-reads the staged copy under `lib/models/`, so its inputs stay inside the mcp
-package and Turborepo can cache it.
-
-## Step 3 — Render with `api-extractor-llms`
-
-The rendering library takes a model path, two injectable callbacks, and returns
-one `RenderedDoc` per top-level public member.
-
-### Core API
-
-```typescript
-import { loadApiModel, renderPackage } from "api-extractor-llms";
-import type { FrontmatterRenderer, RouteFormatter } from "api-extractor-llms";
-
-const pkg = await loadApiModel("/path/to/silk-effects.api.json");
-
-const routeFor: RouteFormatter = (ref) =>
-  `silk://packages/silk-effects/api/${ref.kind}/${ref.slug}`;
-
-const frontmatter: FrontmatterRenderer = (meta) =>
-  `---\nid: packages/silk-effects/api/${meta.kind}/${meta.slug}\ntitle: "${meta.name}"\n---\n\n`;
-
-const docs = renderPackage(pkg, { packageName: "@savvy-web/silk-effects", routeFor, frontmatter });
-
-for (const doc of docs) {
-  // doc.markdown = frontmatter block + rendered body
-  // doc.kind, doc.name, doc.slug identify the item
-}
-```
-
-### What `renderPackage` produces
-
-For each top-level public member, the shared body renderer emits:
-
-- An ATX `# Name` heading
-- The TypeScript signature in a fenced `ts` code block (via `TypeSignatureFormatter`)
-- TSDoc summary paragraph
-- `## Parameters` list with types and descriptions (if any)
-- `## Returns` section (if documented)
-- `## Members` section listing class/interface/namespace members with signatures and summaries
-- `## Examples` blocks with language-tagged fences (from `@example` TSDoc tags)
-- Cross-links in prose resolved through the injected `routeFor` (via `CrossLinker`)
-
-The two injectable callbacks — `routeFor` (URL scheme) and `frontmatter` (YAML
-block) — are the only consumer-specific pieces. The body rendering is shared
-across all consumers.
-
-## Step 4 — The MCP generator script
-
-`packages/mcp/lib/scripts/generate-api-docs.ts` is the reference implementation of
-steps 3 and 4 for the MCP resource corpus. It iterates `API_TARGETS` (defined in
-`packages/mcp/lib/scripts/api-targets.ts`), loads each model, injects silk-specific
-frontmatter and `silk://` crosslink routes, writes one page per symbol under
-`public/content/packages/<dir>/api/<kind>/<slug>.md`, and writes a per-package
-index page at `public/content/packages/<dir>/api.md` (served at the bare
-`silk://packages/<dir>/api` URI).
-
-```typescript
-// The silk crosslink scheme
-const routeFor = (target: ApiTarget) => (ref: ApiItemRef) =>
-  `silk://${target.idPrefix}/api/${ref.kind}/${ref.slug}`;
-
-// The silk frontmatter renderer (derives id, title, summary, tags)
-const frontmatter = (meta: DocMeta) => toYaml(frontMatterFor(target, meta));
-
-const docs = renderPackage(pkg, {
-  packageName: target.packageName,
-  routeFor: routeFor(target),
-  frontmatter,
-});
-```
-
-Current targets (from `api-targets.ts`): `silk-effects`, `templates`,
-`github-action-effects`, `github-action-builder`, `bundler`, `tsdown-plugins`,
-`rspress-builder`. The MCP package itself and `cli`/`silk` are excluded (a
-generate→mcp build dependency would create a Turborepo cycle; cli and silk are
-not library APIs).
-
-## Step 5 — Compile into the corpus
-
-After `generate-api-docs.ts` writes the markdown files, `build:catalog` picks them
-up along with hand-authored docs and compiles the unified manifest. Generated docs
-appear in `silk://catalog` marked `(generated)`. The rendered markdown and the
-inflated manifest are committed tracked source — only the raw `.api.json` models
-under `lib/models/` are gitignored — so the published package ships the corpus
-even though a release machine does not regenerate it.
-
-In Turborepo the pipeline is:
-
-```text
-build:prod (each library) → generate-api-docs → build:catalog → mcp build:prod
-```
-
-## Authoring notes
-
-- TSDoc coverage determines output quality. Undocumented public members produce
-  sparse rendered docs with no summary or parameter descriptions.
-- The slug is the lowercased display name. A class `MyService` maps to
-  `silk://packages/foo/api/class/myservice`.
-- Cross-links in prose (`{@link OtherClass}`) resolve only if `OtherClass` is in
-  the same package's rendered set.
-- Do not hand-edit files under `public/content/packages/*/api/` (or the `api.md`
-  index) — they are overwritten on the next `generate-api-docs` run; change the
-  source TSDoc instead.
-
-## See also
-
-- `silk://standards/api-model-pipeline` — policy: what is generated, provenance
-  markers, coverage scope
-- `silk://packages/bundler/overview` — configuring the builder that emits the model

package/content/guides/building-a-github-action.md

@@ -1,233 +0,0 @@
----
-id: guides/building-a-github-action
-title: Building a GitHub Action
-summary: Scaffold a Node.js 24 GitHub Action with @savvy-web/github-action-builder and the github-action-effects services.
-tier: guides
-source: hand
-tags: [github-actions, build]
-priority: 0.5
-related: [guides/choosing-a-builder, standards/api-model-pipeline]
----
-
-## Overview
-
-Two packages work together to build and power Node.js 24 GitHub Actions in the
-Silk Suite:
-
-- **`@savvy-web/github-action-builder`** — zero-config rsbuild-based build tool
-  that bundles TypeScript source into self-contained ESM files and validates
-  `action.yml`
-- **`@savvy-web/github-action-effects`** — Effect service library replacing all
-  `@actions/*` packages with native ESM implementations
-
-Neither package depends on the other at build time. The builder bundles whatever
-action code you write; the effects library provides the services that code uses.
-
-For choosing the right builder, see `silk://guides/choosing-a-builder`. The
-github-action-builder is separate from the library bundler — it targets a
-different output shape (single-file committed ESM bundles, not npm-published
-libraries).
-
-## Step 1 — Project structure
-
-```text
-my-action/
-├── src/
-│   ├── main.ts      # Required — main action logic
-│   ├── pre.ts       # Optional — pre-action hook
-│   └── post.ts      # Optional — post-action hook
-├── action.yml       # GitHub metadata; must have runs.using: "node24"
-└── package.json
-```
-
-The builder auto-detects `src/pre.ts` and `src/post.ts` if they exist. Only
-`src/main.ts` is required.
-
-`action.yml` must declare `runs.using: "node24"`. The builder validates this and
-fails if any other value is present.
-
-## Step 2 — Install and configure the builder
-
-```bash
-pnpm add -D @savvy-web/github-action-builder
-```
-
-Zero-config usage — no config file needed:
-
-```bash
-github-action-builder build
-```
-
-Or create an optional `action.config.ts` for customization:
-
-```typescript
-import { defineConfig } from "@savvy-web/github-action-builder";
-
-export default defineConfig({
-  build: {
-    minify: true,        // default: true
-    sourceMap: false,    // default: false
-    externals: [],       // exclude from bundle (must be available at runtime)
-    ignore: [],          // replace with a throwing stub
-  },
-  validation: {
-    requireActionYml: true,
-    strict: undefined,   // auto-detects CI; warn locally, error in CI
-  },
-  persistLocal: {
-    enabled: true,       // auto-copy to .github/actions/local/ after build
-    path: ".github/actions/local",
-  },
-});
-```
-
-### Build output
-
-Each detected entry emits one flat ESM file:
-
-| Input | Output |
-| --- | --- |
-| `src/main.ts` | `dist/main.js` |
-| `src/pre.ts` | `dist/pre.js` |
-| `src/post.ts` | `dist/post.js` |
-| (generated) | `dist/package.json` |
-
-All output files are self-contained ESM bundles. Dynamic `import()` calls are
-folded back into the parent file (`asyncChunks: false`), so `action.yml` can
-always reference a known single-file path.
-
-The builder also copies output to `.github/actions/local/` for local testing with
-[nektos/act](https://github.com/nektos/act) unless `persistLocal.enabled: false`.
-
-## Step 3 — Write action logic with `github-action-effects`
-
-```bash
-pnpm add @savvy-web/github-action-effects
-```
-
-The library provides 37 Effect service interfaces across six domains:
-
-| Domain | Services cover |
-| --- | --- |
-| Core action I/O | Outputs, state, logging, environment, cache |
-| Git operations | Branches, commits, tags via Git Data API |
-| GitHub API | REST client, GraphQL, releases, issues, PR lifecycle, check runs, rate limiting |
-| Build tooling | Command execution, npm registry, workspace detection, changeset analysis |
-| Attestation | SLSA statement construction, Sigstore signing, CycloneDX SBOM generation |
-| Runtime layer | GitHub Actions workflow command protocol, `ActionsConfigProvider`, `ActionsLogger`, `Step` |
-
-### Runtime layer
-
-The runtime layer replaces all `@actions/*` packages with native ESM implementations:
-
-```typescript
-import { Effect, Config } from "effect";
-import { ActionsRuntime, Action, Step } from "@savvy-web/github-action-effects";
-
-const program = Effect.gen(function* () {
-  // Inputs via Effect's Config API (reads INPUT_* env vars)
-  const name = yield* Config.string("name");
-  const count = yield* Config.integer("count");
-
-  // Logging maps to workflow commands
-  yield* Effect.log("Processing...");        // plain stdout
-  yield* Effect.logDebug("detail");          // ::debug::detail
-  yield* Effect.logWarning("heads up");      // ::warning::heads up
-
-  // Step buffering: one success line on pass, spills debug buffer on fail
-  yield* Step.withStep("fetch data", fetchData(name));
-});
-
-// Provide the runtime layer
-Action.run(program);
-// or: program.pipe(Effect.provide(ActionsRuntime.Default))
-```
-
-### Reading inputs
-
-Action inputs are read via Effect's `Config` API backed by `ActionsConfigProvider`,
-which translates config keys to `INPUT_*` environment variables:
-
-```typescript
-const repoName = yield* Config.string("repo-name"); // reads INPUT_REPO-NAME
-```
-
-### Composing services
-
-Services are provided via Effect Layers. The programmatic pattern:
-
-```typescript
-import { Effect } from "effect";
-import {
-  ActionsRuntime,
-  GitHubClient,
-  GitHubClientLive,
-} from "@savvy-web/github-action-effects";
-
-const program = Effect.gen(function* () {
-  const client = yield* GitHubClient;
-  // use client ...
-});
-
-program.pipe(
-  Effect.provide(GitHubClientLive),
-  Effect.provide(ActionsRuntime.Default),
-  Effect.runPromise,
-);
-```
-
-### Testing
-
-The library exports a `./testing` subpath that excludes `GitHubClientLive` and
-`OctokitAuthAppLive` (which import `@octokit/rest`/`@octokit/auth-app`). Use this
-in test files to avoid pulling in those dependencies:
-
-```typescript
-import { ... } from "@savvy-web/github-action-effects/testing";
-```
-
-## Step 4 — Validate and CI
-
-```bash
-# Validate action.yml and entry structure without building
-github-action-builder validate
-
-# Full build with validation
-github-action-builder build
-```
-
-In CI (`CI=true` or `GITHUB_ACTIONS=true`), validation warnings become errors and
-fail the build. Locally they are displayed as warnings and the build continues.
-
-Add to `package.json`:
-
-```json
-{
-  "scripts": {
-    "build": "github-action-builder build",
-    "validate": "github-action-builder validate"
-  }
-}
-```
-
-## Step 5 — Reference the built output in `action.yml`
-
-```yaml
-name: My Action
-description: Does something useful
-runs:
-  using: node24
-  main: dist/main.js
-  post: dist/post.js    # if you have a post step
-```
-
-The `dist/` directory must be committed to the repository so GitHub runners can
-execute it. The builder's `persistLocal` feature also syncs to
-`.github/actions/local/` for local `act` runs.
-
-## See also
-
-- `silk://guides/choosing-a-builder` — when to use github-action-builder vs the
-  library builders
-- `silk://standards/api-model-pipeline` — if your action repo also publishes a
-  library whose API is documented

package/content/guides/choosing-a-builder.md

@@ -1,93 +0,0 @@
----
-id: guides/choosing-a-builder
-title: Choosing a builder
-summary: When to reach for @savvy-web/bundler, @savvy-web/rspress-builder, or @savvy-web/github-action-builder for a Silk package.
-tier: guides
-source: hand
-tags: [build]
-priority: 0.5
-related: [packages/bundler/overview, guides/building-a-github-action]
----
-
-## Overview
-
-The Silk Suite has three zero-config build tools, each targeting a different
-output shape. Pick by what the package produces, not by personal preference.
-
-| Package | Builds | Output |
-| --- | --- | --- |
-| `@savvy-web/bundler` | TypeScript libraries | npm-published `dist/dev` + `dist/prod` |
-| `@savvy-web/rspress-builder` | RSPress doc-site plugins | npm-published plugin package |
-| `@savvy-web/github-action-builder` | Node.js 24 GitHub Actions | committed single-file ESM bundles |
-
-All three auto-detect their inputs, emit a transformed publish-ready
-`package.json` where applicable, and resolve `catalog:` and `workspace:` protocol
-references. They differ in what they emit and how it is consumed.
-
-## `@savvy-web/bundler`
-
-The **default** for any TypeScript library inside `savvy-web/systems` (or any
-pnpm-managed Silk Suite package). It is the tsdown-based build orchestrator: it
-reads `exports` to discover entry points, builds `dist/dev/` and per-target
-`dist/prod/<target>/`, emits a bundled self-contained `.d.ts` per public entry,
-and on `--target prod` emits an API Extractor model for MCP and website doc
-generation.
-
-A package opts in with a self-executing `savvy.build.ts` that calls `defineBuild`
-and `runBuild`, with `node savvy.build.ts --target dev` / `--target prod` build
-scripts. See `silk://packages/bundler/overview` for the full surface.
-
-### When to use it
-
-- You are building a library inside `savvy-web/systems` (or a pnpm-based Silk repo)
-- You publish to npm and want bundled type declarations
-- You want API Extractor model emission for MCP doc generation
-- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
-
-## `@savvy-web/rspress-builder`
-
-A thin sibling to the bundler for **RSPress documentation-site plugins**. It
-applies the same entry-point discovery and publish transform, tuned for the
-shape an RSPress plugin package ships. Reach for it only when the package is an
-RSPress plugin; for every other library, use the bundler.
-
-## `@savvy-web/github-action-builder`
-
-For **Node.js 24 GitHub Actions**, whose output is a different shape entirely:
-self-contained ESM bundles committed to the repository (not an npm package) so a
-runner can execute them directly. It bundles `src/main.ts` (plus optional
-`pre.ts`/`post.ts`) into flat `dist/*.js` files and validates `action.yml`. See
-`silk://guides/building-a-github-action`.
-
-### When to use it
-
-- You are building a GitHub Action, not a published library
-- The output must be a committed single-file bundle referenced from `action.yml`
-
-## Decision guide
-
-```text
-Is the package a GitHub Action (committed Node.js 24 bundle)?
-  Yes → github-action-builder
-
-Is the package an RSPress doc-site plugin?
-  Yes → rspress-builder
-
-Otherwise (any npm-published TypeScript library)
-  → bundler
-```
-
-## Common pitfalls
-
-**bundler / rspress-builder:** Relative imports inside source must use `.js`
-extensions (the ESM requirement). The build reports "cannot find module" on a
-missing extension.
-
-**github-action-builder:** The `dist/` bundle must be committed so GitHub runners
-can execute it; `action.yml` must declare `runs.using: "node24"`.
-
-## See also
-
-- `silk://packages/bundler/overview` — the library build front door in full
-- `silk://guides/building-a-github-action` — GitHub Actions use a separate builder
-- `silk://standards/api-model-pipeline` — how the bundler's prod API model becomes docs

package/content/guides/llm-friendly-json-schemas.md

@@ -1,64 +0,0 @@
----
-id: guides/llm-friendly-json-schemas
-title: LLM-friendly JSON Schemas for tool outputs
-summary: Load when designing the output schema of an MCP tool or a GitHub Action.
-tier: guides
-source: hand
-tags: [mcp]
-priority: 0.5
-related: [packages/mcp/resource-taxonomy]
----
-
-A coding agent consumes a tool's structured output by reading it, not by running a
-parser against it. The schema you choose is a prompt: it decides how reliably the
-model can locate a value, follow a reference, and reason about what it got back.
-Read this when designing a new MCP tool's output schema or a GitHub Action's
-`outputs`, where the same constraints apply.
-
-## Prefer flat, named fields over deep nesting
-
-A model retrieves a value by following a path it has to hold in working memory.
-`result.targets[0].registry` is harder to reference reliably than a flat
-`registries: string[]`. Keep the shape shallow. When you must nest, name every
-level with a descriptive key rather than relying on positional structure, so the
-path reads like prose.
-
-## Avoid recursive and open-ended shapes
-
-A schema that can nest itself arbitrarily (a tree of the same node type) forces the
-model to track depth it cannot see. Where the domain is genuinely recursive,
-flatten it: emit a list of nodes plus a parent-id field rather than a literal tree.
-
-## Use enums and literals for closed sets
-
-When a field can only take a handful of values, type it as a union of literals, not
-an open string. An enum tells the model the complete option set up front, which
-both narrows its generation and lets it reason exhaustively ("if not `public`, then
-`restricted`"). This mirrors how the Silk schemas type `access` as
-`"public" | "restricted"` and `tier` as `standards | packages | guides`.
-
-## Collapse relations to identifier arrays
-
-Do not inline a related entity's full record where a reference will do. Emit an
-array of stable identifiers (the `related: string[]` pattern in the resource
-corpus) and let the consumer fetch the target if it needs more. This keeps each
-payload small and the relationship explicit, and it survives the related record
-changing shape.
-
-## Pair the structured payload with a short human-readable summary
-
-A model orients faster on one sentence than on a field-by-field scan. Return both:
-the structured object for precise extraction, and a brief natural-language summary
-for orientation. The MCP tools in this ecosystem follow this dual-channel
-convention — a structured result alongside a lean markdown transcript — so the
-agent gets a fast "what is this" read and an exact "what are the values" read from
-the same call.
-
-## Putting it together
-
-When you sketch a new output schema, ask: can the model name every value in one
-short path; is every closed set an enum; are relations references rather than
-inlined records; and is there a one-line summary to orient on? If so, the schema
-is doing its job as a prompt. The resource taxonomy
-(`silk://packages/mcp/resource-taxonomy`) applies these same rules to the
-documentation corpus's own front-matter.