@savvy-web/mcp 1.3.3 → 1.3.5

package/content/packages/bundler/api.md

@@ -0,0 +1,28 @@
+---
+id: packages/bundler/api
+title: "@savvy-web/bundler — API reference"
+summary: "@savvy-web/bundler API reference: 10 documented symbols."
+tier: packages
+source: generated
+tags: [bundler, api]
+priority: 0.4
+related: []
+---
+
+# @savvy-web/bundler — API reference
+
+## function
+
+- [`build`](silk://packages/bundler/api/function/build) — Sugar front door: define + run in one call, deriving `cwd`/`argv` from process globals. `cwd` is the directory of the entry script (`process.argv[1]`) — the faithful equivalent of the old `import.meta.dirname`, correct even when invoked by an explicit path from another directory. `argv` is `process.argv.slice(2)`, so `--target` and friends are read internally; the package.json build scripts stay `node savvy.build.ts --target <t>`. `overrides` merges last as the test/advanced IO seam (the same injectables as RunOptions).
+- [`defineBuild`](silk://packages/bundler/api/function/definebuild) — Normalize + validate a defineBuild config. Pure when imported; self-runs when entry (see run.ts).
+- [`parseArgs`](silk://packages/bundler/api/function/parseargs) — Parse the build CLI argv into the normalized target/flags shape.
+- [`runBuild`](silk://packages/bundler/api/function/runbuild) — Run a build from a normalized config. Pure orchestration; all IO injectable.
+
+## interface
+
+- [`BuildConfig`](silk://packages/bundler/api/interface/buildconfig)
+- [`BuildConfigInput`](silk://packages/bundler/api/interface/buildconfiginput)
+- [`BuildEntryOverride`](silk://packages/bundler/api/interface/buildentryoverride)
+- [`OutputConfig`](silk://packages/bundler/api/interface/outputconfig)
+- [`ParsedArgs`](silk://packages/bundler/api/interface/parsedargs)
+- [`RunOptions`](silk://packages/bundler/api/interface/runoptions)

package/content/packages/bundler/overview.md

@@ -0,0 +1,89 @@
+---
+id: packages/bundler/overview
+title: bundler overview
+summary: Load when setting up or understanding the @savvy-web/bundler build for a Silk library package.
+tier: packages
+source: hand
+tags: [bundler, build]
+priority: 0.5
+related: [standards/catalog-usage, standards/publishability, standards/api-model-pipeline]
+---
+
+## What
+
+`@savvy-web/bundler` is the tsdown-based build orchestrator for Silk Suite
+TypeScript libraries. It reads a package's `exports` field to discover entry
+points, builds dev and production outputs, emits a bundled self-contained
+`.d.ts` per public entry, and transforms the output `package.json` for
+publishing. It drives tsdown programmatically over `@savvy-web/tsdown-plugins`.
+A package opts in with a one-line self-executing `savvy.build.ts`.
+
+## API
+
+The front door is `defineBuild` (pure config normalization + validation) and
+`runBuild` (the orchestrator). A package's `savvy.build.ts` defines a config and
+self-runs when invoked directly:
+
+```typescript
+import { defineBuild, runBuild } from "@savvy-web/bundler";
+
+const config = defineBuild({
+  // format defaults to esm-only; minify defaults false (prod-only).
+});
+
+export default config;
+
+if (import.meta.main) {
+  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
+}
+```
+
+Entry points come from `package.json` `exports`. `defineBuild` options include
+`format`, `jsx`, `bundle`, `overrides` (per-entry format and bundling
+partitions), `define`, `looseFiles`, `bundleNodeModules`, `plugins` (custom
+rolldown plugins), and `meta` (API-model generation — see below). Imported by
+the cli or the silk plugin, the config object is side-effect-free; run directly,
+it parses `process.argv` and builds.
+
+## Layer
+
+Build scripts invoke the file directly with Node's native type-stripping:
+
+```json
+{
+  "scripts": {
+    "build:dev": "node savvy.build.ts --target dev",
+    "build:prod": "node savvy.build.ts --target prod"
+  }
+}
+```
+
+`--target dev` writes `dist/dev/` (bundled JS, source maps, declarations, a
+transformed `package.json`). `--target prod` writes `dist/prod/<target>/` for
+each `publishConfig.targets` key, emits the API model and meta release asset, and
+strips declaration source maps from the published bytes.
+
+## Usage
+
+The output `package.json` is transformed from source by `defaultManifestTransform`:
+export paths move from `.ts` to `.js`, type conditions are added, pnpm `catalog:`
+and `workspace:` references resolve to concrete versions, and `private` is flipped
+to publish-ready based on `publishConfig.access`. This is the mechanism behind the
+convention that a source `package.json` is `private: true` while its
+`publishConfig` declares publish intent.
+
+The `meta` option is tri-state: omit it to generate the API model with default
+options on `--target prod`, pass an object to override (`localPaths`, `tsdoc`,
+`optimistic`), or pass `false` to opt out. Custom TSDoc tags are registered via
+`meta.tsdoc.tagDefinitions`. The package also ships the shared TS base config at
+`@savvy-web/bundler/tsconfig/ecma.json`, which every Silk library extends.
+
+A common pitfall: relative imports must use `.js` extensions (the ESM
+requirement), or the build reports "cannot find module".
+
+## Related
+
+The symbol-level API reference: `silk://packages/bundler/api`. Dependency
+pinning the build resolves: `silk://standards/catalog-usage`. How `private` and
+`publishConfig` decide what publishes: `silk://standards/publishability`. How the
+prod build's API model becomes generated docs: `silk://standards/api-model-pipeline`.

package/content/packages/github-action-builder/api/class/actionymlmissing.md

@@ -0,0 +1,30 @@
+---
+id: packages/github-action-builder/api/class/actionymlmissing
+title: "ActionYmlMissing — github-action-builder class"
+summary: "Error when action.yml file is missing."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ActionYmlMissing
+
+Error when action.yml file is missing.
+
+```ts
+class ActionYmlMissing extends ActionYmlMissingBase<{
+  readonly cwd: string;
+}>
+```
+
+## Members
+
+### cwd
+
+```ts
+readonly cwd: string;
+```
+
+The working directory that was searched.

package/content/packages/github-action-builder/api/class/actionymlpatherror.md

@@ -0,0 +1,48 @@
+---
+id: packages/github-action-builder/api/class/actionymlpatherror
+title: "ActionYmlPathError — github-action-builder class"
+summary: "Error when action.yml runs paths don't resolve correctly in destination."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ActionYmlPathError
+
+Error when action.yml runs paths don't resolve correctly in destination.
+
+```ts
+class ActionYmlPathError extends ActionYmlPathErrorBase<{
+  readonly entryType: string;
+  readonly specifiedPath: string;
+  readonly expectedPath: string;
+}>
+```
+
+## Members
+
+### entryType
+
+```ts
+readonly entryType: string;
+```
+
+The entry type whose path failed validation (main, pre, post).
+
+### expectedPath
+
+```ts
+readonly expectedPath: string;
+```
+
+The expected resolved path.
+
+### specifiedPath
+
+```ts
+readonly specifiedPath: string;
+```
+
+The path specified in action.yml.

package/content/packages/github-action-builder/api/class/actionymlschemaerror.md

@@ -0,0 +1,45 @@
+---
+id: packages/github-action-builder/api/class/actionymlschemaerror
+title: "ActionYmlSchemaError — github-action-builder class"
+summary: "Error when action.yml fails schema validation."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ActionYmlSchemaError
+
+Error when action.yml fails schema validation.
+
+```ts
+class ActionYmlSchemaError extends ActionYmlSchemaErrorBase<{
+  readonly path: string;
+  readonly errors: ReadonlyArray<{
+    readonly path: string;
+    readonly message: string;
+  }>;
+}>
+```
+
+## Members
+
+### errors
+
+```ts
+readonly errors: ReadonlyArray<{
+    readonly path: string;
+    readonly message: string;
+  }>;
+```
+
+List of schema validation errors.
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path to the action.yml file.

package/content/packages/github-action-builder/api/class/actionymlsyntaxerror.md

@@ -0,0 +1,57 @@
+---
+id: packages/github-action-builder/api/class/actionymlsyntaxerror
+title: "ActionYmlSyntaxError — github-action-builder class"
+summary: "Error when action.yml has invalid YAML syntax."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ActionYmlSyntaxError
+
+Error when action.yml has invalid YAML syntax.
+
+```ts
+class ActionYmlSyntaxError extends ActionYmlSyntaxErrorBase<{
+  readonly path: string;
+  readonly message: string;
+  readonly line?: number;
+  readonly column?: number;
+}>
+```
+
+## Members
+
+### column
+
+```ts
+readonly column?: number;
+```
+
+Column number where the error occurred, if available.
+
+### line
+
+```ts
+readonly line?: number;
+```
+
+Line number where the error occurred, if available.
+
+### message
+
+```ts
+readonly message: string;
+```
+
+The syntax error message.
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path to the action.yml file.

package/content/packages/github-action-builder/api/class/buildfailed.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/buildfailed
+title: "BuildFailed — github-action-builder class"
+summary: "Error when the build process fails overall."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# BuildFailed
+
+Error when the build process fails overall.
+
+```ts
+class BuildFailed extends BuildFailedBase<{
+  readonly message: string;
+  readonly failedEntries: number;
+}>
+```
+
+## Members
+
+### failedEntries
+
+```ts
+readonly failedEntries: number;
+```
+
+Number of entries that failed.
+
+### message
+
+```ts
+readonly message: string;
+```
+
+Summary message of the build failure.

package/content/packages/github-action-builder/api/class/bundlefailed.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/bundlefailed
+title: "BundleFailed — github-action-builder class"
+summary: "Error when bundling with rsbuild fails."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# BundleFailed
+
+Error when bundling with rsbuild fails.
+
+```ts
+class BundleFailed extends BundleFailedBase<{
+  readonly entry: string;
+  readonly cause: unknown;
+}>
+```
+
+## Members
+
+### cause
+
+```ts
+readonly cause: unknown;
+```
+
+The underlying error or error message.
+
+### entry
+
+```ts
+readonly entry: string;
+```
+
+The entry file that failed to bundle.

package/content/packages/github-action-builder/api/class/cleanerror.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/cleanerror
+title: "CleanError — github-action-builder class"
+summary: "Error when cleaning the output directory fails."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# CleanError
+
+Error when cleaning the output directory fails.
+
+```ts
+class CleanError extends CleanErrorBase<{
+  readonly directory: string;
+  readonly cause: unknown;
+}>
+```
+
+## Members
+
+### cause
+
+```ts
+readonly cause: unknown;
+```
+
+The underlying error or error message.
+
+### directory
+
+```ts
+readonly directory: string;
+```
+
+The directory that failed to clean.

package/content/packages/github-action-builder/api/class/configinvalid.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/configinvalid
+title: "ConfigInvalid — github-action-builder class"
+summary: "Error when configuration file exists but contains invalid content."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ConfigInvalid
+
+Error when configuration file exists but contains invalid content.
+
+```ts
+class ConfigInvalid extends ConfigInvalidBase<{
+  readonly path: string;
+  readonly errors: ReadonlyArray<string>;
+}>
+```
+
+## Members
+
+### errors
+
+```ts
+readonly errors: ReadonlyArray<string>;
+```
+
+List of validation errors.
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path to the invalid config file.

package/content/packages/github-action-builder/api/class/configloadfailed.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/configloadfailed
+title: "ConfigLoadFailed — github-action-builder class"
+summary: "Error when configuration file fails to load (import error, syntax error, etc.)."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ConfigLoadFailed
+
+Error when configuration file fails to load (import error, syntax error, etc.).
+
+```ts
+class ConfigLoadFailed extends ConfigLoadFailedBase<{
+  readonly path: string;
+  readonly cause: unknown;
+}>
+```
+
+## Members
+
+### cause
+
+```ts
+readonly cause: unknown;
+```
+
+The underlying error or error message.
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path to the config file that failed to load.

package/content/packages/github-action-builder/api/class/confignotfound.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/confignotfound
+title: "ConfigNotFound — github-action-builder class"
+summary: "Error when configuration file is not found."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# ConfigNotFound
+
+Error when configuration file is not found.
+
+```ts
+class ConfigNotFound extends ConfigNotFoundBase<{
+  readonly path: string;
+  readonly message?: string;
+}>
+```
+
+## Members
+
+### message
+
+```ts
+readonly message?: string;
+```
+
+Additional context about the search.
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path that was searched for the config file.

package/content/packages/github-action-builder/api/class/entryfilemissing.md

@@ -0,0 +1,39 @@
+---
+id: packages/github-action-builder/api/class/entryfilemissing
+title: "EntryFileMissing — github-action-builder class"
+summary: "Error when an explicitly specified entry file is missing."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# EntryFileMissing
+
+Error when an explicitly specified entry file is missing.
+
+```ts
+class EntryFileMissing extends EntryFileMissingBase<{
+  readonly entryType: "main" | "pre" | "post";
+  readonly path: string;
+}>
+```
+
+## Members
+
+### entryType
+
+```ts
+readonly entryType: "main" | "pre" | "post";
+```
+
+The type of entry (main, pre, post).
+
+### path
+
+```ts
+readonly path: string;
+```
+
+The path that was specified but not found.

package/content/packages/github-action-builder/api/class/githubaction.md

@@ -0,0 +1,101 @@
+---
+id: packages/github-action-builder/api/class/githubaction
+title: "GitHubAction — github-action-builder class"
+summary: "Main API class for building GitHub Actions."
+tier: packages
+source: generated
+tags: [github-action-builder, api]
+priority: 0.3
+related: []
+---
+
+# GitHubAction
+
+Main API class for building GitHub Actions.
+
+```ts
+class GitHubAction
+```
+
+## Members
+
+### build
+
+```ts
+build(): Promise<GitHubActionBuildResult>;
+```
+
+Build the GitHub Action.
+
+### create
+
+```ts
+static create(options?: GitHubActionOptions): GitHubAction;
+```
+
+Create a new [GitHubAction](silk://packages/github-action-builder/api/class/githubaction) builder instance.
+
+### dispose
+
+```ts
+dispose(): Promise<void>;
+```
+
+Dispose the runtime and release resources.
+
+### loadConfig
+
+```ts
+loadConfig(): Promise<Config>;
+```
+
+Load and resolve configuration.
+
+### validate
+
+```ts
+validate(options?: ValidateOptions): Promise<ValidationResult>;
+```
+
+Validate the action configuration and action.yml.
+
+## Examples
+
+```typescript
+import { GitHubAction } from "@savvy-web/github-action-builder";
+
+async function buildAction(): Promise<void> {
+  const action = GitHubAction.create();
+  const result = await action.build();
+
+  if (result.success) {
+    console.log(`Built ${result.build?.entries.length} entry points`);
+  } else {
+    console.error(`Build failed: ${result.error}`);
+    process.exit(1);
+  }
+}
+
+buildAction();
+
+```
+
+```typescript
+import { GitHubAction } from "@savvy-web/github-action-builder";
+
+async function main(): Promise<void> {
+  const action = GitHubAction.create({
+    config: {
+      entries: { main: "src/action.ts" },
+      build: { minify: true },
+    },
+    cwd: "/path/to/project",
+  });
+
+  const result = await action.build();
+  console.log(result.success ? "Success" : result.error);
+}
+
+main();
+
+```