@malloy-publisher/server 0.0.235 → 0.0.236

package/src/mcp/skills/skills_bundle.spec.ts

@@ -1,171 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import {
-   buildSkills,
-   isCredible,
-   type SkillEntry,
-} from "./build_skills_bundle";
-import bundle from "./skills_bundle.json";
-
-const skills = (
-   bundle as {
-      skills: { name: string; description: string; body: string }[];
-   }
-).skills;
-
-/** The repo's top-level skills/, which this bundle is generated from. */
-const sourceDir = path.join(
-   import.meta.dir,
-   "..",
-   "..",
-   "..",
-   "..",
-   "..",
-   "skills",
-);
-
-/**
- * Codepoint order. The committed bundle is sorted with localeCompare, which
- * depends on the runtime's locale, and this suite runs on three platforms.
- * Membership and content are what matter here; file order is cosmetic.
- */
-const byName = (a: SkillEntry, b: SkillEntry) =>
-   a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-
-describe("skills_bundle.json (generated dual-channel asset)", () => {
-   it("is in sync with skills/", () => {
-      // Regenerate with:
-      //   bun run src/mcp/skills/build_skills_bundle.ts ../../skills
-      expect([...skills].sort(byName)).toEqual(
-         [...buildSkills(sourceDir)].sort(byName),
-      );
-   });
-
-   it("is not empty", () => {
-      expect(skills.length).toBeGreaterThan(0);
-   });
-
-   it("every skill has a nonempty name, description, and body", () => {
-      for (const s of skills) {
-         expect(s.name.length).toBeGreaterThan(0);
-         expect(s.description.length).toBeGreaterThan(0);
-         expect(s.body.length).toBeGreaterThan(0);
-      }
-   });
-
-   it("skill names are unique", () => {
-      const names = skills.map((s) => s.name);
-      expect(new Set(names).size).toBe(names.length);
-   });
-
-   /**
-    * A skill's reference/ files are its on-demand detail, and this channel is
-    * the only way a host without the skills on disk can reach them. Before they
-    * were bundled, malloy-review told an agent to load rubrics that, over MCP,
-    * did not exist.
-    */
-   describe("reference files", () => {
-      const isReference = (s: SkillEntry) => s.name.includes("/");
-      const referenceEntries = skills.filter(isReference);
-
-      it("bundles every reference/*.md in the tree", () => {
-         // Mirror the builder's own exclusion. A stray credible-* skill with a
-         // reference/ dir is never bundled, so walking without this filter
-         // fails on a correct bundle.
-         const onDisk = fs
-            .readdirSync(sourceDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory() && !isCredible(d.name))
-            .flatMap((d) => {
-               const dir = path.join(sourceDir, d.name, "reference");
-               return fs.existsSync(dir)
-                  ? fs
-                       .readdirSync(dir)
-                       .filter((f) => f.endsWith(".md"))
-                       .map((f) => `${d.name}/${path.basename(f, ".md")}`)
-                  : [];
-            });
-
-         expect(onDisk.length).toBeGreaterThan(0);
-         expect(referenceEntries.map((s) => s.name).sort()).toEqual(
-            onDisk.sort(),
-         );
-      });
-
-      it("names each one under its parent skill", () => {
-         const skillNames = new Set(
-            skills.filter((s) => !isReference(s)).map((s) => s.name),
-         );
-         for (const entry of referenceEntries) {
-            expect(skillNames.has(entry.name.split("/")[0])).toBe(true);
-         }
-      });
-
-      it("gives each one a description drawn from its heading", () => {
-         // Reference files carry no frontmatter, so a listing would otherwise
-         // show them nameless. Every file in the tree has an H1 to use.
-         //
-         // Assert against the no-heading fallback rather than a length floor:
-         // the fallback is itself long enough to clear any such floor, so a
-         // length check alone stays green even if heading extraction breaks
-         // entirely and all of a skill's entries collapse to one string.
-         for (const entry of referenceEntries) {
-            const parent = entry.name.split("/")[0];
-            expect(entry.description).toContain("Reference detail for");
-            expect(entry.description).not.toBe(
-               `Reference detail for the ${parent} skill.`,
-            );
-         }
-      });
-
-      it("tells the parent skill where its reference files went", () => {
-         // The parent body points at them by relative path, which resolves for
-         // a host reading files off disk and not for one given this as a prompt.
-         const parents = new Set(
-            referenceEntries.map((s) => s.name.split("/")[0]),
-         );
-         for (const name of parents) {
-            const parent = skills.find((s) => s.name === name);
-            expect(parent?.body).toContain("Reference files over MCP");
-            expect(parent?.body).toContain(`get the prompt named \`${name}/`);
-         }
-      });
-
-      it("leaves skills without a reference/ directory untouched", () => {
-         const plain = skills.find((s) => s.name === "malloy-getting-started");
-         expect(plain?.body).not.toContain("Reference files over MCP");
-      });
-   });
-
-   /**
-    * Pre-existing drift, bounded rather than exempted. Every SKILL.md honours
-    * the house style; these three reference files never did, because nothing
-    * checked them until they entered the bundle. Fixing 23 prose em-dashes in
-    * three SHARED skills is an upstream-first change of its own, not something
-    * to bundle into the build-time asset that surfaced it.
-    *
-    * Listed by name so a NEW violation still fails: shrink this list as the
-    * files are fixed, and delete it when it is empty.
-    */
-   const EM_DASH_DRIFT = new Set([
-      "malloy-html-data-apps/lazy-load",
-      "malloy-html-data-apps/verification-harness",
-      "malloy-lookml-review/build-derived-tables",
-   ]);
-
-   it("carries no em-dashes (house style)", () => {
-      const offenders = skills
-         .filter((s) => !EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
-         .map((s) => s.name);
-      expect(offenders).toEqual([]);
-   });
-
-   it("the em-dash allowlist names only entries that still need fixing", () => {
-      // Stops the list outliving the drift: an entry that has been cleaned up,
-      // or renamed away, has to leave the list.
-      const stillDrifting = skills
-         .filter((s) => EM_DASH_DRIFT.has(s.name) && s.body.includes("—"))
-         .map((s) => s.name);
-      expect([...EM_DASH_DRIFT].sort()).toEqual(stillDrifting.sort());
-   });
-});

package/src/mcp/tool_response.spec.ts

@@ -1,108 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { formatErrorText, jsonResource, jsonToolError } from "./tool_response";
-
-// Pins the wire shape every malloy_* tool returns. Two properties here are
-// regressions waiting to happen, so they are asserted explicitly rather than
-// left to the tools' own specs:
-//
-//   - the resource carries `mimeType`, not `type`. `type` is not in the MCP
-//     ResourceContents schema; it was accepted by .passthrough() and ignored.
-//   - an error result carries a text block. The structured payload alone is
-//     invisible to a client that renders only text for isError results.
-
-describe("jsonResource", () => {
-   it("puts the resource block first and types it with mimeType", () => {
-      const r = jsonResource("malloy:/x", { a: 1 });
-
-      expect(r.isError).toBe(false);
-      expect(r.content).toHaveLength(1);
-      expect(r.content[0].type).toBe("resource");
-
-      const resource = (r.content[0] as { resource: Record<string, unknown> })
-         .resource;
-      expect(resource.mimeType).toBe("application/json");
-      expect(resource.uri).toBe("malloy:/x");
-      // The pre-fix spelling must not come back.
-      expect(resource.type).toBeUndefined();
-      expect(JSON.parse(resource.text as string)).toEqual({ a: 1 });
-   });
-
-   it("appends an optional text block after the resource", () => {
-      const r = jsonResource("malloy:/x", { a: 1 }, { text: "heads up" });
-
-      expect(r.content).toHaveLength(2);
-      expect(r.content[0].type).toBe("resource");
-      expect(r.content[1]).toEqual({ type: "text", text: "heads up" });
-   });
-
-   it("omits the text block when no text is supplied", () => {
-      expect(jsonResource("malloy:/x", {}).content).toHaveLength(1);
-   });
-
-   it("honours the space option without changing the parsed payload", () => {
-      const compact = jsonResource("malloy:/x", { a: 1 });
-      const pretty = jsonResource("malloy:/x", { a: 1 }, { space: 2 });
-
-      const text = (r: typeof compact) =>
-         (r.content[0] as { resource: { text: string } }).resource.text;
-
-      expect(text(pretty)).toContain("\n");
-      expect(text(compact)).not.toContain("\n");
-      expect(JSON.parse(text(pretty))).toEqual(JSON.parse(text(compact)));
-   });
-});
-
-describe("formatErrorText", () => {
-   it("renders the message and every suggestion", () => {
-      const text = formatErrorText({
-         message: "Resource not found: env/pkg",
-         suggestions: ["Check the spelling.", "Call malloy_getContext."],
-      });
-
-      expect(text).toContain("Resource not found: env/pkg");
-      expect(text).toContain("- Check the spelling.");
-      expect(text).toContain("- Call malloy_getContext.");
-   });
-
-   it("returns the bare message when there are no suggestions", () => {
-      expect(formatErrorText({ message: "boom", suggestions: [] })).toBe(
-         "boom",
-      );
-   });
-});
-
-describe("jsonToolError", () => {
-   const details = {
-      message: "Cannot redefine 'overview'",
-      suggestions: ["Rename the view."],
-   };
-
-   it("sets isError and carries the message in BOTH blocks", () => {
-      const r = jsonToolError("error://compile", details);
-
-      expect(r.isError).toBe(true);
-      expect(r.content).toHaveLength(2);
-
-      const payload = JSON.parse(
-         (r.content[0] as { resource: { text: string } }).resource.text,
-      );
-      expect(payload.error).toBe("Cannot redefine 'overview'");
-      expect(payload.suggestions).toEqual(["Rename the view."]);
-
-      // The whole point of the change: a text-only client still sees it.
-      const textBlock = r.content[1] as { type: string; text: string };
-      expect(textBlock.type).toBe("text");
-      expect(textBlock.text).toContain("Cannot redefine 'overview'");
-      expect(textBlock.text).toContain("- Rename the view.");
-   });
-
-   it("merges extraPayload so getContext keeps its results key", () => {
-      const r = jsonToolError("error://ctx", details, { results: [] });
-
-      const payload = JSON.parse(
-         (r.content[0] as { resource: { text: string } }).resource.text,
-      );
-      expect(payload.results).toEqual([]);
-      expect(payload.error).toBe("Cannot redefine 'overview'");
-   });
-});

package/src/mcp/tool_response.ts

@@ -1,138 +0,0 @@
-import type { ErrorDetails } from "./error_messages";
-
-/**
- * Shared construction of the MCP content blocks every malloy_* tool returns.
- *
- * Two things here are load-bearing and were previously wrong at every call site:
- *
- * 1. The resource block carries `mimeType`, not `type`. The MCP
- *    ResourceContents schema is `z.object({uri, mimeType?, _meta?}).passthrough()`,
- *    so a `type: "application/json"` field was accepted by passthrough and then
- *    ignored by every client, leaving the payload untyped on the wire.
- *
- * 2. An error result also emits a plain text block. A client that renders only
- *    text blocks when `isError` is set sees nothing at all in an embedded
- *    resource, and reports a bare "Unknown error" while the server's real
- *    message and suggestions sit unread in the resource. The text block is what
- *    makes a diagnostic legible; the resource block is what keeps it parseable.
- *
- * Ordering matters: the resource block stays at index 0 so callers (and specs)
- * can keep reading `content[0].resource.text` for the structured payload.
- */
-
-const JSON_MIME_TYPE = "application/json";
-
-// The index signatures mirror the MCP SDK's CallToolResult types, which declare
-// `[x: string]: unknown` on the result and on every content block. Without them
-// these are not assignable to the SDK's tool-callback return type.
-type ResourceBlock = {
-   [x: string]: unknown;
-   type: "resource";
-   resource: {
-      [x: string]: unknown;
-      uri: string;
-      mimeType: string;
-      text: string;
-   };
-};
-
-type TextBlock = { [x: string]: unknown; type: "text"; text: string };
-
-export type ToolContent = ResourceBlock | TextBlock;
-
-export interface ToolResult {
-   [x: string]: unknown;
-   isError: boolean;
-   content: ToolContent[];
-}
-
-function resourceBlock(
-   uri: string,
-   payload: unknown,
-   space?: number,
-   replacer?: (key: string, value: unknown) => unknown,
-): ResourceBlock {
-   return {
-      type: "resource" as const,
-      resource: {
-         uri,
-         mimeType: JSON_MIME_TYPE,
-         text: JSON.stringify(payload, replacer, space),
-      },
-   };
-}
-
-/**
- * Renders ErrorDetails as the prose a client will actually show the agent.
- *
- * The suggestions are included, not just the message: they carry the part that
- * makes an error actionable (which source was denied, which view to look for,
- * that a reload is needed), and a client that cannot read the resource block
- * has no other way to reach them. They are a short, bounded list by
- * construction in error_messages.ts.
- *
- * Exported so a spec can pin the rendering rather than merely its presence.
- */
-export function formatErrorText(details: ErrorDetails): string {
-   if (details.suggestions.length === 0) {
-      return details.message;
-   }
-   const suggestions = details.suggestions.map((s) => `- ${s}`).join("\n");
-   return `${details.message}\n\nSuggestions:\n${suggestions}`;
-}
-
-/**
- * Wraps a JSON payload in the resource-content shape, optionally adding a text
- * block alongside it.
- *
- * `text` is deliberately opt-in rather than automatic on success: a query result
- * is already size-capped (assertWithinModelResponseLimits), and duplicating it
- * as prose would double the payload for no gain. Success paths that have
- * something short and useful to say (render-tag warnings) pass it explicitly.
- *
- * @param space JSON.stringify indentation. Left undefined (compact) except for
- *   query results, which have always been pretty-printed for readability.
- */
-export function jsonResource(
-   uri: string,
-   payload: unknown,
-   options?: {
-      isError?: boolean;
-      text?: string;
-      space?: number;
-      /** Needed when the payload can carry BigInt: see json_utils.bigIntReplacer. */
-      replacer?: (key: string, value: unknown) => unknown;
-   },
-): ToolResult {
-   const content: ToolContent[] = [
-      resourceBlock(uri, payload, options?.space, options?.replacer),
-   ];
-   if (options?.text !== undefined) {
-      content.push({ type: "text" as const, text: options.text });
-   }
-   return { isError: options?.isError ?? false, content };
-}
-
-/**
- * Builds the standard error result: the {error, suggestions} JSON a parsing
- * client wants, plus the same information as text so every client can read it.
- *
- * @param extraPayload Merged into the JSON payload. malloy_getContext uses it
- *   to keep its `results: []` contract on the error path, which its callers
- *   (and specs) rely on to treat every tier's response shape uniformly.
- */
-export function jsonToolError(
-   uri: string,
-   details: ErrorDetails,
-   extraPayload?: Record<string, unknown>,
-): ToolResult {
-   return jsonResource(
-      uri,
-      {
-         error: details.message,
-         suggestions: details.suggestions,
-         ...extraPayload,
-      },
-      { isError: true, text: formatErrorText(details) },
-   );
-}