@savvy-web/mcp 1.3.5 → 1.5.0

package/content/standards/turbo/watch.md

@@ -1,64 +0,0 @@
----
-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/content/tags.json

@@ -1,32 +0,0 @@
-{
-	"changeset": ["changesets"],
-	"release": [],
-	"commit": ["commits", "conventional-commits"],
-	"dco": [],
-	"tdd": [],
-	"catalog": ["version-catalog"],
-	"dependencies": ["deps", "peer-dependencies"],
-	"lint": ["linting", "biome", "markdownlint"],
-	"test": ["testing", "vitest"],
-	"publishability": ["publish", "publishConfig", "private"],
-	"silk-effects": [],
-	"effect": ["layers", "context-tag"],
-	"managed-section": ["sections", "husky"],
-	"cli": ["savvy"],
-	"init": ["setup", "scaffold"],
-	"silk": ["install"],
-	"mcp": ["resources", "savvy-mcp"],
-	"build": ["rslib", "esm"],
-	"workspace": ["monorepo", "workspaces"],
-	"api": ["api-reference", "reference"],
-	"templates": ["scaffolding"],
-	"github-action-effects": ["gha-effects"],
-	"github-action-builder": ["gha-builder"],
-	"bundler": ["tsdown", "build-orchestrator"],
-	"tsdown-plugins": ["rolldown", "plugins"],
-	"rspress-builder": ["rspress", "docs-builder"],
-	"semver": ["versioning"],
-	"github-actions": ["gha", "actions"],
-	"turbo": ["turborepo"],
-	"ci": ["continuous-integration", "remote-cache"]
-}

package/resources/catalog.js

@@ -1,29 +0,0 @@
-//#region src/resources/catalog.ts
-const TIER_HEADINGS = [
-	["standards", "Standards"],
-	["packages", "Packages"],
-	["guides", "Guides"]
-];
-function renderCatalogMarkdown(manifest) {
-	const lines = [
-		"# silk://catalog",
-		"",
-		"Read this first to orient. To fetch a doc, call `resources/read` with its `silk://` URI.",
-		"To search by intent, use the `silk_docs_search` tool.",
-		""
-	];
-	for (const [tier, heading] of TIER_HEADINGS) {
-		const entries = manifest.entries.filter((e) => e.tier === tier && e.status !== "deprecated");
-		if (entries.length === 0) continue;
-		lines.push(`## ${heading}`, "");
-		for (const e of entries) {
-			const gen = e.source === "generated" ? " (generated)" : "";
-			lines.push(`- \`${e.uri}\`${gen} — ${e.title}. load when: ${e.summary}`);
-		}
-		lines.push("");
-	}
-	return lines.join("\n");
-}
-
-//#endregion
-export { renderCatalogMarkdown };

package/resources/doc-index.js

@@ -1,112 +0,0 @@
-import Fuse from "fuse.js";
-
-//#region src/resources/doc-index.ts
-const STOP_WORDS = /* @__PURE__ */ new Set([
-	"how",
-	"do",
-	"i",
-	"the",
-	"a",
-	"an",
-	"to",
-	"of",
-	"in",
-	"for",
-	"is",
-	"what",
-	"when",
-	"use"
-]);
-const FUSE_THRESHOLD = .6;
-const confidenceLabel = (confidence) => confidence >= .6 ? "high" : confidence >= .4 ? "medium" : "low";
-const toRanked = (item, score, matches) => ({
-	item,
-	confidence: 1 - (score ?? 1),
-	matchedOn: matches.map((m) => m.key ?? "")
-});
-var DocIndex = class DocIndex {
-	fuse;
-	entries;
-	byUri;
-	constructor(fuse, entries, byUri) {
-		this.fuse = fuse;
-		this.entries = entries;
-		this.byUri = byUri;
-	}
-	static fromManifest(manifest, bodies) {
-		const entries = manifest.entries.filter((e) => e.status !== "deprecated").map((e) => ({
-			...e,
-			body: bodies[e.uri] ?? ""
-		}));
-		return new DocIndex(new Fuse(entries, {
-			useExtendedSearch: true,
-			ignoreLocation: true,
-			includeScore: true,
-			includeMatches: true,
-			minMatchCharLength: 2,
-			threshold: FUSE_THRESHOLD,
-			keys: [
-				{
-					name: "title",
-					weight: .55
-				},
-				{
-					name: "tags",
-					weight: .3
-				},
-				{
-					name: "summary",
-					weight: .12
-				},
-				{
-					name: "body",
-					weight: .03
-				}
-			]
-		}), entries, new Map(entries.map((e) => [e.uri, e])));
-	}
-	search(query, opts = {}) {
-		const limit = opts.limit ?? 10;
-		const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2 && !STOP_WORDS.has(t));
-		const raw = tokens.length > 0 ? this.fuse.search(tokens.map((t) => `'${t}`).join(" | ")) : [];
-		const filteredByTier = opts.tier ? raw.filter((r) => r.item.tier === opts.tier) : raw;
-		const ranked = filteredByTier.length > 0 ? filteredByTier.map((r) => toRanked(r.item, r.score, r.matches ?? [])) : tokens.length === 0 ? this.fallback(opts.tier) : [];
-		ranked.sort((a, b) => b.confidence - a.confidence || (b.item.priority ?? .5) - (a.item.priority ?? .5));
-		const present = new Set(ranked.map((r) => r.item.uri));
-		const seeAlso = [];
-		for (const r of ranked.slice(0, 3)) for (const rel of r.item.related) {
-			const uri = rel.startsWith("silk://") ? rel : `silk://${rel}`;
-			if (present.has(uri)) continue;
-			const neighbor = this.byUri.get(uri);
-			if (!neighbor) continue;
-			present.add(uri);
-			seeAlso.push({
-				item: neighbor,
-				confidence: 0,
-				matchedOn: ["related"]
-			});
-		}
-		return [...ranked, ...seeAlso].slice(0, limit).map(({ item, confidence, matchedOn }) => ({
-			uri: item.uri,
-			title: item.title,
-			summary: item.summary,
-			tags: item.tags,
-			tier: item.tier,
-			confidence: Number(confidence.toFixed(3)),
-			confidenceLabel: confidenceLabel(confidence),
-			matchedOn: [...new Set(matchedOn)].filter(Boolean),
-			related: item.related
-		}));
-	}
-	/** Browse fallback: surface the top entries (by priority) as low-confidence. */
-	fallback(tier) {
-		return this.entries.filter((e) => tier ? e.tier === tier : true).slice().sort((a, b) => (b.priority ?? .5) - (a.priority ?? .5)).slice(0, 5).map((item) => ({
-			item,
-			confidence: 0,
-			matchedOn: []
-		}));
-	}
-};
-
-//#endregion
-export { DocIndex };

package/resources/index.js

@@ -1,57 +0,0 @@
-import { renderCatalogMarkdown } from "./catalog.js";
-import { readDocBody } from "./load.js";
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
-
-//#region src/resources/index.ts
-const resourceName = (entry) => `silk_${entry.id.replace(/[^A-Za-z0-9]/g, "_")}`;
-const toSdkAnnotations = (e) => ({
-	audience: [...e.audience],
-	priority: e.priority,
-	...e.lastModified ? { lastModified: e.lastModified } : {}
-});
-function registerAllResources(server, deps) {
-	const { manifest, bodies, contentRoot } = deps;
-	server.registerResource("silk_catalog", "silk://catalog", {
-		title: "Silk resource catalog",
-		description: "Read this first. Lists every Silk resource grouped by tier with a 'load when' hint. Fetch a doc with resources/read <uri>; search by intent with silk_docs_search.",
-		mimeType: "text/markdown"
-	}, async (uri) => ({ contents: [{
-		uri: uri.href,
-		mimeType: "text/markdown",
-		text: renderCatalogMarkdown(manifest)
-	}] }));
-	const byUri = new Map(manifest.entries.map((e) => [e.uri, e]));
-	const readBody = (uri, relPath) => {
-		if (bodies) return bodies[uri] ?? "";
-		try {
-			return readDocBody(contentRoot, relPath);
-		} catch (err) {
-			if (err?.code === "ENOENT") throw new McpError(ErrorCode.InvalidParams, `Resource not found: ${uri}`);
-			throw new McpError(ErrorCode.InternalError, `Failed to read resource: ${uri}`);
-		}
-	};
-	server.registerResource("silk_doc", new ResourceTemplate("silk://{+path}", { list: async () => ({ resources: manifest.entries.filter((e) => e.status !== "deprecated").map((e) => ({
-		name: resourceName(e),
-		uri: e.uri,
-		title: e.title,
-		description: e.summary,
-		mimeType: "text/markdown",
-		annotations: toSdkAnnotations(e)
-	})) }) }), {
-		title: "Silk documentation resource",
-		mimeType: "text/markdown"
-	}, async (uri, variables) => {
-		const relPath = String(variables.path ?? "");
-		const entry = byUri.get(uri.href);
-		return { contents: [{
-			uri: uri.href,
-			mimeType: "text/markdown",
-			text: readBody(uri.href, relPath),
-			...entry ? { annotations: toSdkAnnotations(entry) } : {}
-		}] };
-	});
-}
-
-//#endregion
-export { registerAllResources };

package/resources/load.js

@@ -1,38 +0,0 @@
-import { resolveResourcePath } from "./paths.js";
-import { Manifest } from "./schema.js";
-import { Schema } from "effect";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-//#region src/resources/load.ts
-/**
-* Resolve the content root across source/built layouts and load the manifest
-* + a doc body by relative path.
-*
-* @packageDocumentation
-*/
-/**
-* Locate the directory holding `manifest.json` + the content markdown. The
-* built bundle flattens `public/` to the package root, so the content lands at
-* `<pkg>/content`; the source layout keeps it under `packages/mcp/public/content`.
-* Probe both and fail loudly if neither has a manifest, so a broken build surfaces a
-* clear path list instead of an opaque ENOENT later in {@link loadManifest}.
-*/
-function resolveContentRoot() {
-	const here = dirname(fileURLToPath(import.meta.url));
-	const candidates = [join(here, "..", "content"), join(here, "..", "..", "public", "content")];
-	for (const candidate of candidates) if (existsSync(join(candidate, "manifest.json"))) return candidate;
-	throw new Error(`[savvy-mcp] cannot locate content with a manifest.json (tried: ${candidates.join(", ")})`);
-}
-function loadManifest(contentRoot) {
-	const raw = JSON.parse(readFileSync(join(contentRoot, "manifest.json"), "utf8"));
-	return Schema.decodeUnknownSync(Manifest)(raw);
-}
-/** Read a doc body markdown by its relative path (the `{+path}` template var). */
-function readDocBody(contentRoot, relPath) {
-	return readFileSync(resolveResourcePath(contentRoot, relPath), "utf8");
-}
-
-//#endregion
-export { loadManifest, readDocBody, resolveContentRoot };

package/resources/paths.js

@@ -1,23 +0,0 @@
-import { isAbsolute, normalize, resolve, sep } from "node:path";
-
-//#region src/resources/paths.ts
-/**
-* Resolve a relative content path against the content root, appending `.md`
-* (or `index.md` for a trailing slash) and rejecting traversal. Operates on
-* the manifest-resolved relative path, never on URL components.
-*
-* @packageDocumentation
-*/
-function resolveResourcePath(root, relativePath) {
-	if (relativePath.includes("\0")) throw new Error("path contains null byte");
-	if (isAbsolute(relativePath)) throw new Error("absolute path not allowed");
-	const stripped = relativePath.replace(/^\/+/, "");
-	const withIndex = stripped === "" || stripped.endsWith("/") ? `${stripped}index` : stripped;
-	const resolved = resolve(root, normalize(withIndex.endsWith(".md") ? withIndex : `${withIndex}.md`));
-	const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
-	if (!resolved.startsWith(rootWithSep) && resolved !== root) throw new Error("path escapes content root");
-	return resolved;
-}
-
-//#endregion
-export { resolveResourcePath };

package/resources/query-log.js

@@ -1,20 +0,0 @@
-//#region src/resources/query-log.ts
-/** Build the structured stderr line for one search (pure; no I/O). */
-function formatQueryLogLine(query, results) {
-	const top = results.slice(0, 3);
-	const belowThreshold = results.length === 0 || results.every((r) => r.confidenceLabel === "low");
-	const payload = {
-		query,
-		topResults: top.map((r) => r.uri),
-		topConfidence: results[0]?.confidence ?? 0,
-		belowThreshold
-	};
-	return `[savvy-mcp] docs-search ${JSON.stringify(payload)}`;
-}
-/** Write a query log line to stderr. */
-const stderrQueryLogger = (line) => {
-	process.stderr.write(`${line}\n`);
-};
-
-//#endregion
-export { formatQueryLogLine, stderrQueryLogger };

package/resources/schema.js

@@ -1,40 +0,0 @@
-import { Schema } from "effect";
-
-//#region src/resources/schema.ts
-/**
-* Front-matter and manifest schemas for the Silk resource corpus.
-*
-* @packageDocumentation
-*/
-/** `id` = the stable URI suffix: tier-prefixed, slash-separated slug segments. */
-const ID_PATTERN = /^(standards|packages|guides)\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\/?$/;
-const Tier = Schema.Literal("standards", "packages", "guides");
-const Audience = Schema.Array(Schema.Literal("user", "assistant"));
-const Source = Schema.Literal("hand", "generated");
-const Status = Schema.Literal("draft", "stable", "deprecated");
-/** YAML front-matter on every content markdown file. */
-const DocFrontMatter = Schema.Struct({
-	id: Schema.String.pipe(Schema.pattern(ID_PATTERN)),
-	title: Schema.NonEmptyString,
-	summary: Schema.NonEmptyString,
-	tier: Tier,
-	source: Source,
-	status: Schema.optionalWith(Status, { default: () => "stable" }),
-	supersededBy: Schema.optional(Schema.String),
-	tags: Schema.Array(Schema.NonEmptyString),
-	audience: Schema.optionalWith(Audience, { default: () => ["assistant"] }),
-	priority: Schema.optionalWith(Schema.Number.pipe(Schema.between(0, 1)), { default: () => .5 }),
-	related: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] })
-});
-/** A manifest entry = decoded front-matter + the derived uri + lastModified. */
-const ManifestEntry = Schema.Struct({
-	...DocFrontMatter.fields,
-	uri: Schema.String,
-	lastModified: Schema.optional(Schema.String)
-});
-const Manifest = Schema.Struct({ entries: Schema.Array(ManifestEntry) });
-const decodeDocFrontMatter = Schema.decodeUnknown(DocFrontMatter);
-const decodeManifest = Schema.decodeUnknown(Manifest);
-
-//#endregion
-export { Audience, DocFrontMatter, Manifest, ManifestEntry, Source, Status, Tier };

package/tools/docs-search.js

@@ -1,59 +0,0 @@
-import { formatQueryLogLine } from "../resources/query-log.js";
-import { ParseResult, Schema } from "effect";
-
-//#region src/tools/docs-search.ts
-/**
-* The `silk_docs_search` MCP tool: a read-only Fuse-backed search over the
-* resource corpus. Takes a plain keyword/phrase query (no operator DSL),
-* returns ranked results with normalized higher-is-better confidence, and
-* returns an empty result set for a real query that matches nothing.
-*
-* @packageDocumentation
-*/
-const DocsSearchHit = Schema.Struct({
-	uri: Schema.String,
-	title: Schema.String,
-	summary: Schema.String,
-	tags: Schema.Array(Schema.String),
-	tier: Schema.Literal("standards", "packages", "guides"),
-	confidence: Schema.Number,
-	confidenceLabel: Schema.Literal("high", "medium", "low"),
-	matchedOn: Schema.Array(Schema.String),
-	related: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] })
-}).annotations({ identifier: "DocsSearchHit" });
-const DocsSearchResult = Schema.Struct({
-	query: Schema.String,
-	results: Schema.Array(DocsSearchHit)
-}).annotations({
-	identifier: "DocsSearchResult",
-	title: "silk_docs_search result",
-	description: "Ranked Silk documentation matches. Fetch a hit with resources/read <uri>."
-});
-const formatDocsSearchMarkdown = (data) => {
-	const lines = [`# silk_docs_search: ${data.query}`, ""];
-	if (data.results.length === 0) {
-		lines.push("No results. Read `silk://catalog` and select a doc by reasoning.");
-		return lines.join("\n");
-	}
-	if (data.results.every((r) => r.confidenceLabel === "low")) lines.push("_No high-confidence match — read `silk://catalog` and pick by reasoning._", "");
-	for (const r of data.results) lines.push(`- \`${r.uri}\` (${r.confidenceLabel}) — ${r.title}. ${r.summary}`);
-	lines.push("", "Fetch any hit with `resources/read <uri>`.");
-	return lines.join("\n");
-};
-const DocsSearchResultAsMarkdown = Schema.transformOrFail(DocsSearchResult, Schema.String, {
-	strict: true,
-	decode: (data) => ParseResult.succeed(formatDocsSearchMarkdown(data)),
-	encode: (text, _opts, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "DocsSearchResultAsMarkdown is one-way."))
-});
-/** Run a search against the in-memory index (synchronous; no Effect runtime). */
-const runDocsSearch = (index, query, opts, logger) => {
-	const results = index.search(query, opts);
-	if (logger) logger(formatQueryLogLine(query, results));
-	return {
-		query,
-		results
-	};
-};
-
-//#endregion
-export { DocsSearchHit, DocsSearchResult, DocsSearchResultAsMarkdown, formatDocsSearchMarkdown, runDocsSearch };