@savvy-web/mcp 1.3.5 → 1.4.0

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.