@frontmcp/adapters 1.2.1 → 1.4.0

package/esm/skills/index.mjs

@@ -702,8 +702,7 @@ var NpmSource = class {
 };
 
 // libs/adapters/src/skills/sources/saas-pull.source.ts
-import { promises as fs } from "node:fs";
-import * as path from "node:path";
+import { dirname, ensureDir, pathResolve, readFile, writeFile } from "@frontmcp/utils";
 var DEFAULT_CACHE_DIR = ".frontmcp/skilled-openapi";
 var DEFAULT_PULL_TIMEOUT_MS = 3e4;
 var SaasPullSource = class {
@@ -805,13 +804,13 @@ var SaasPullSource = class {
   }
   cachePath() {
     const dir = this.cacheDir ?? DEFAULT_CACHE_DIR;
-    return path.resolve(dir, `${this.options.expectedAudience.replace(/[^a-zA-Z0-9_.-]/g, "_")}.json`);
+    return pathResolve(dir, `${this.options.expectedAudience.replace(/[^a-zA-Z0-9_.-]/g, "_")}.json`);
   }
   async persistCache(bundle) {
     try {
       const filePath = this.cachePath();
-      await fs.mkdir(path.dirname(filePath), { recursive: true });
-      await fs.writeFile(filePath, JSON.stringify(bundle), "utf8");
+      await ensureDir(dirname(filePath));
+      await writeFile(filePath, JSON.stringify(bundle));
     } catch (e) {
       this.logger.warn(`[saas-source] cache persist failed: ${e.message}`);
     }
@@ -819,7 +818,7 @@ var SaasPullSource = class {
   async loadCache() {
     try {
       const filePath = this.cachePath();
-      const raw = await fs.readFile(filePath, "utf8");
+      const raw = await readFile(filePath, "utf8");
       return parseOverlay({ kind: "json", content: raw });
     } catch {
       return void 0;
@@ -837,9 +836,7 @@ var SaasPullSource = class {
 };
 
 // libs/adapters/src/skills/sources/static.source.ts
-import { watch as fsWatch } from "node:fs";
-import * as path2 from "node:path";
-import { readFile } from "@frontmcp/utils";
+import { extname, pathResolve as pathResolve2, readFile as readFile2, watchFile } from "@frontmcp/utils";
 var StaticSource = class {
   constructor(options, logger) {
     this.options = options;
@@ -877,9 +874,9 @@ var StaticSource = class {
     this.listeners.clear();
   }
   async fetchOnce() {
-    const absPath = path2.resolve(this.options.path);
-    const raw = await readFile(absPath, "utf8");
-    const ext = path2.extname(absPath).toLowerCase();
+    const absPath = pathResolve2(this.options.path);
+    const raw = await readFile2(absPath, "utf8");
+    const ext = extname(absPath).toLowerCase();
     let input;
     if (ext === ".json") {
       input = { kind: "json", content: raw };
@@ -901,9 +898,9 @@ var StaticSource = class {
     }
   }
   beginWatch() {
-    const absPath = path2.resolve(this.options.path);
+    const absPath = pathResolve2(this.options.path);
     try {
-      this.watcher = fsWatch(absPath, { persistent: false }, () => this.scheduleRefresh());
+      this.watcher = watchFile(absPath, () => this.scheduleRefresh());
     } catch (e) {
       this.logger.warn(`[static-source] fs.watch failed (${e.message}); polling at 2s instead`);
       const tick = () => {
@@ -942,9 +939,17 @@ function createBundleSource(source, cacheDir, logger) {
 }
 
 // libs/adapters/src/skills/sources/filesystem-skills.source.ts
-import { watch as fsWatch2 } from "node:fs";
-import { sep as pathSep } from "node:path";
-import { basename, joinPath, pathResolve, readdir, readFile as readFile2, realpath, stat } from "@frontmcp/utils";
+import {
+  basename,
+  joinPath,
+  pathResolve as pathResolve3,
+  readdir,
+  readFile as readFile3,
+  realpath,
+  sep,
+  stat,
+  watchFile as watchFile2
+} from "@frontmcp/utils";
 var DEFAULT_OPTIONS = {
   skillsDir: "./skills",
   watch: true,
@@ -974,7 +979,7 @@ var FilesystemSkillsSource = class {
     };
   }
   async start() {
-    const absRoot = pathResolve(this.options.skillsDir);
+    const absRoot = pathResolve3(this.options.skillsDir);
     try {
       this.rootResolved = await realpath(absRoot);
     } catch {
@@ -1027,7 +1032,7 @@ var FilesystemSkillsSource = class {
       } catch {
         continue;
       }
-      if (!resolved.startsWith(this.rootResolved + pathSep) && resolved !== this.rootResolved) {
+      if (!resolved.startsWith(this.rootResolved + sep) && resolved !== this.rootResolved) {
         this.logger.warn(`[fs-skills] skipping ${name}: realpath escapes skillsDir`);
         continue;
       }
@@ -1082,18 +1087,22 @@ var FilesystemSkillsSource = class {
   }
   beginWatch() {
     try {
-      this.watcher = fsWatch2(this.rootResolved, { recursive: true, persistent: false }, (_eventType, filename) => {
-        if (this.stopped) return;
-        if (!filename) {
-          this.scheduleRescan();
-          return;
-        }
-        const first = filename.split(pathSep)[0];
-        if (!first || first.startsWith(".")) return;
-        const absDir = joinPath(this.rootResolved, first);
-        this.scheduleRefresh(absDir);
-      });
-      this.watcher.on("error", (e) => {
+      this.watcher = watchFile2(
+        this.rootResolved,
+        (_eventType, filename) => {
+          if (this.stopped) return;
+          if (!filename) {
+            this.scheduleRescan();
+            return;
+          }
+          const first = filename.split(sep)[0];
+          if (!first || first.startsWith(".")) return;
+          const absDir = joinPath(this.rootResolved, first);
+          this.scheduleRefresh(absDir);
+        },
+        { recursive: true }
+      );
+      this.watcher.onError((e) => {
         this.logger.warn(`[fs-skills] fs.watch error: ${e.message}; falling back to polling`);
         this.watcher?.close();
         this.watcher = void 0;
@@ -1162,7 +1171,7 @@ var FilesystemSkillsSource = class {
 };
 async function loadFilesystemSkill(absDir) {
   const skillMdPath = joinPath(absDir, "SKILL.md");
-  const raw = await readFile2(skillMdPath, "utf8");
+  const raw = await readFile3(skillMdPath, "utf8");
   const { frontmatter, body } = parseSkillFrontmatter(raw);
   const dirName = basename(absDir);
   const name = frontmatter["name"] ?? dirName;
@@ -2066,10 +2075,699 @@ var SkillAuditWriterToken = /* @__PURE__ */ Symbol.for(
 
 // libs/adapters/src/skills/index.ts
 import { hasSkillAuditFactory, setSkillAuditFactory } from "@frontmcp/sdk";
+
+// libs/adapters/src/skills/harvester/op-reference.ts
+var SPEC_ID_RE = "[A-Za-z0-9][A-Za-z0-9_.-]*";
+var OPERATION_ID_RE = "[A-Za-z_][A-Za-z0-9_]*";
+var TRAILING_BOUNDARY = String.raw`(?![A-Za-z0-9_\-])(?!\.[A-Za-z0-9_])`;
+var REFERENCE_RE = new RegExp(
+  String.raw`(?<![A-Za-z0-9])op:\/\/(${SPEC_ID_RE})\/(${OPERATION_ID_RE})${TRAILING_BOUNDARY}` + `|` + String.raw`\[\[op:\s?(${SPEC_ID_RE})\/(${OPERATION_ID_RE})\]\]`,
+  "g"
+);
+function extractOpReferences(markdown) {
+  if (typeof markdown !== "string" || markdown.length === 0) return [];
+  const refs = [];
+  const lineStarts = computeLineStarts(markdown);
+  REFERENCE_RE.lastIndex = 0;
+  let match;
+  while ((match = REFERENCE_RE.exec(markdown)) !== null) {
+    const offset = match.index;
+    const [raw, uriSpec, uriOp, wikiSpec, wikiOp] = match;
+    const isWikilink = wikiSpec !== void 0 && wikiOp !== void 0;
+    const spec = isWikilink ? wikiSpec : uriSpec;
+    const operationId = isWikilink ? wikiOp : uriOp;
+    refs.push({
+      spec,
+      operationId,
+      syntax: isWikilink ? "wikilink" : "uri",
+      raw,
+      location: offsetToLocation(offset, lineStarts)
+    });
+  }
+  return refs;
+}
+function buildKnownOps(entries) {
+  const map = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const slash = entry.indexOf("/");
+    if (slash <= 0 || slash === entry.length - 1) continue;
+    const spec = entry.slice(0, slash);
+    const op = entry.slice(slash + 1);
+    let set = map.get(spec);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      map.set(spec, set);
+    }
+    set.add(op);
+  }
+  return map;
+}
+function validateOpReferences(refs, knownOps) {
+  const diagnostics = [];
+  for (const ref of refs) {
+    const specOps = knownOps.get(ref.spec);
+    if (!specOps) {
+      diagnostics.push({
+        ref,
+        kind: "unknown-spec",
+        message: `Unknown OpenAPI spec "${ref.spec}" referenced as ${ref.raw}`,
+        suggestions: Array.from(knownOps.keys()).sort()
+      });
+      continue;
+    }
+    if (!specOps.has(ref.operationId)) {
+      diagnostics.push({
+        ref,
+        kind: "unknown-operation",
+        message: `Unknown operationId "${ref.operationId}" in spec "${ref.spec}" (${ref.raw})`,
+        suggestions: suggestSimilarOps(ref.operationId, specOps)
+      });
+    }
+  }
+  return diagnostics;
+}
+function dedupeOpReferences(refs) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const ref of refs) {
+    const key = `${ref.spec}/${ref.operationId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({ spec: ref.spec, operationId: ref.operationId });
+  }
+  return result;
+}
+function computeLineStarts(source) {
+  const starts = [0];
+  for (let i = 0; i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) starts.push(i + 1);
+  }
+  return starts;
+}
+function offsetToLocation(offset, lineStarts) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = lo + hi + 1 >>> 1;
+    if (lineStarts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  const line = lo + 1;
+  const column = offset - lineStarts[lo] + 1;
+  return { line, column, offset };
+}
+function suggestSimilarOps(query, known) {
+  if (known.size === 0) return [];
+  const q = query.toLowerCase();
+  const candidates = Array.from(known);
+  const prefix = candidates.filter((c) => c.toLowerCase().startsWith(q));
+  const substring = candidates.filter((c) => !prefix.includes(c) && c.toLowerCase().includes(q));
+  const close = candidates.filter((c) => !prefix.includes(c) && !substring.includes(c)).filter((c) => levenshtein(q, c.toLowerCase()) <= Math.max(2, Math.floor(q.length / 4)));
+  return [...prefix, ...substring, ...close].slice(0, 3);
+}
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+// libs/adapters/src/skills/deploy/deploy-manifest.schema.ts
+import { z as z3 } from "@frontmcp/lazy-zod";
+var IDENT_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
+var SPEC_ID_RE2 = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+var SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+var BINDING_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var serverInfoSchema = z3.object({
+  name: z3.string().min(1).max(128),
+  version: z3.string().min(1).max(64),
+  title: z3.string().min(1).max(256).optional()
+}).strict();
+var serverSchema = z3.object({
+  info: serverInfoSchema,
+  /**
+   * Top-level server instructions injected at `initialize` time. Picked up
+   * by the existing `skillsConfig.injectInstructions` machinery (defaults
+   * to `append` so the skill catalog summary follows).
+   */
+  instructions: z3.string().max(16 * 1024).optional()
+}).strict();
+var runtimeSchema = z3.object({
+  /** Only `cloudflare-worker` in v1. Future: `vercel-edge`, `deno-deploy`. */
+  target: z3.literal("cloudflare-worker"),
+  compatibilityDate: z3.string().regex(ISO_DATE_RE, "compatibilityDate must be ISO-8601 (YYYY-MM-DD)"),
+  /** Worker compatibility flags (e.g. `nodejs_compat`). */
+  compatibilityFlags: z3.array(z3.string().min(1).max(128)).max(32).optional()
+}).strict();
+var specSourceSchema = z3.union([
+  /** Local file path or HTTPS URL to a single spec. Spec id = filename stem. */
+  z3.string().min(1).max(2048),
+  z3.object({
+    id: z3.string().min(1).max(128).regex(SPEC_ID_RE2, "spec id must be a URI-safe identifier"),
+    spec: z3.string().min(1).max(2048),
+    baseUrl: z3.string().url("baseUrl must be a valid URL").optional(),
+    /** Optional namespace override for AgentScript bindings (default = `id`). */
+    bindingName: z3.string().min(1).max(64).regex(IDENT_RE).optional()
+  }).strict()
+]);
+var specsSchema = z3.union([
+  /** Single directory path; the loader auto-discovers `*.yaml` / `*.json`. */
+  z3.string().min(1).max(2048),
+  /** Explicit list (mixed strings and detail objects allowed). */
+  z3.array(specSourceSchema).max(64)
+]);
+var skillsSchema = z3.object({
+  /** Directory under the manifest. Defaults to `./skills/`. */
+  source: z3.string().min(1).max(2048).default("./skills/"),
+  /**
+   * IDs of skills the worker pre-loads into every `execute()` regardless
+   * of which skills the agent passed. Mirrors the per-skill
+   * `alwaysLoad: true` frontmatter, but lets the server force it.
+   */
+  alwaysLoad: z3.array(z3.string().min(1).max(128)).max(32).optional(),
+  /** Optional tag filter applied at deploy time. */
+  tags: z3.object({
+    include: z3.array(z3.string().min(1).max(64)).max(64).optional(),
+    exclude: z3.array(z3.string().min(1).max(64)).max(64).optional()
+  }).strict().optional()
+}).strict();
+var tagSchema = z3.object({
+  name: z3.string().min(1).max(64),
+  description: z3.string().min(1).max(512).optional()
+}).strict();
+var classificationRuleSchema = z3.object({
+  /**
+   * Match pattern: METHOD followed by a path-glob, e.g.
+   * `POST <star>/reset-<star>` (where <star> is the literal `*` glob).
+   * Written this way to avoid prematurely closing the JSDoc with star-slash.
+   */
+  match: z3.string().min(1).max(256),
+  /**
+   * Override the MCP surface for matching operations: tool (default for
+   * mutations), resource (default for GET list / GET path-param), or both
+   * (default for GET path-param). Omit to leave the classifier's default.
+   */
+  expose: z3.enum(["tool", "resource", "both"]).optional(),
+  /**
+   * Resource-update emit target. `self` (mutation on its own resource),
+   * `parent` (mutation that affects the parent collection / parent path),
+   * or `none` (suppress). Defaults from the HTTP-semantics classifier.
+   */
+  emits: z3.enum(["self", "parent", "none"]).optional()
+}).strict();
+var classificationSchema = z3.object({
+  rules: z3.array(classificationRuleSchema).max(64).optional()
+}).strict();
+var durableObjectBindingSchema = z3.object({
+  binding: z3.string().min(1).max(128).regex(BINDING_NAME_RE),
+  className: z3.string().min(1).max(128).regex(IDENT_RE),
+  scriptName: z3.string().min(1).max(128).optional()
+}).strict();
+var d1BindingSchema = z3.object({
+  binding: z3.string().min(1).max(128).regex(BINDING_NAME_RE),
+  databaseName: z3.string().min(1).max(256),
+  databaseId: z3.string().min(1).max(128)
+}).strict();
+var kvBindingSchema = z3.object({
+  binding: z3.string().min(1).max(128).regex(BINDING_NAME_RE),
+  id: z3.string().min(1).max(128)
+}).strict();
+var r2BindingSchema = z3.object({
+  binding: z3.string().min(1).max(128).regex(BINDING_NAME_RE),
+  bucketName: z3.string().min(1).max(256)
+}).strict();
+var bindingsSchema = z3.object({
+  durableObjects: z3.array(durableObjectBindingSchema).max(32).optional(),
+  d1Databases: z3.array(d1BindingSchema).max(16).optional(),
+  kvNamespaces: z3.array(kvBindingSchema).max(32).optional(),
+  r2Buckets: z3.array(r2BindingSchema).max(16).optional(),
+  /** Plaintext vars surfaced as `env.<name>` on the Worker. */
+  vars: z3.record(z3.string().min(1).max(128), z3.string().max(4096)).optional()
+}).strict();
+var trustRootSchema = z3.object({
+  /** Key id — matches the JWS `kid` header on the signed bundle. */
+  kid: z3.string().min(1).max(128),
+  /** Name of the secret binding holding the PEM-encoded public key. */
+  publicKeySecret: z3.string().min(1).max(128).regex(SECRET_NAME_RE)
+}).strict();
+var replayGuardSchema = z3.object({
+  /** Acceptable clock skew; rejects bundles older than this. */
+  windowSeconds: z3.number().int().min(10).max(3600).default(300),
+  /** KV binding name that stores nonces for replay protection. */
+  nonceKv: z3.string().min(1).max(128).regex(BINDING_NAME_RE)
+}).strict();
+var signingSchema = z3.object({
+  algorithm: z3.enum(["ed25519", "rs256"]),
+  trustRoots: z3.array(trustRootSchema).min(1).max(8),
+  replay: replayGuardSchema
+}).strict();
+var fronteggAuthSchema = z3.object({
+  tenantResolver: z3.enum(["subdomain", "header", "jwt-claim"]).default("subdomain"),
+  audience: z3.string().min(1).max(256),
+  /** Secret name holding the issuer URL. */
+  issuerSecret: z3.string().min(1).max(128).regex(SECRET_NAME_RE)
+}).strict();
+var oauthAuthSchema = z3.object({
+  issuer: z3.string().url(),
+  audience: z3.string().min(1).max(256),
+  /** Optional secret name for client credentials (machine-to-machine). */
+  credentialsSecret: z3.string().min(1).max(128).regex(SECRET_NAME_RE).optional()
+}).strict();
+var apiKeyAuthSchema = z3.object({
+  /** Header name carrying the key (e.g. `X-API-Key`). */
+  header: z3.string().min(1).max(64).default("X-API-Key"),
+  /** Secret name holding the allowlist (newline-separated keys). */
+  allowlistSecret: z3.string().min(1).max(128).regex(SECRET_NAME_RE)
+}).strict();
+var authSchema = z3.discriminatedUnion("provider", [
+  z3.object({ provider: z3.literal("none") }).strict(),
+  z3.object({ provider: z3.literal("frontegg"), frontegg: fronteggAuthSchema }).strict(),
+  z3.object({ provider: z3.literal("oauth"), oauth: oauthAuthSchema }).strict(),
+  z3.object({ provider: z3.literal("apiKey"), apiKey: apiKeyAuthSchema }).strict()
+]);
+var secretSchema = z3.object({
+  name: z3.string().min(1).max(128).regex(SECRET_NAME_RE),
+  required: z3.boolean().default(true),
+  description: z3.string().min(1).max(512).optional()
+}).strict();
+var environmentOverlaySchema = z3.object({
+  server: serverSchema.partial().optional(),
+  specs: specsSchema.optional(),
+  skills: skillsSchema.partial().optional(),
+  classification: classificationSchema.optional(),
+  bindings: bindingsSchema.optional(),
+  auth: authSchema.optional(),
+  vars: z3.record(z3.string().min(1).max(128), z3.string().max(4096)).optional()
+}).strict();
+var deployManifestSchema = z3.object({
+  /** Optional JSON Schema URL — accepted for editor autocompletion. */
+  $schema: z3.string().url().optional(),
+  /** Schema version. Only `1` accepted in v1.3. */
+  version: z3.literal(1),
+  /** Project name (for logs + the Worker's `worker.name`). */
+  name: z3.string().min(1).max(128).regex(IDENT_RE),
+  runtime: runtimeSchema,
+  server: serverSchema,
+  specs: specsSchema,
+  skills: skillsSchema.default({ source: "./skills/" }),
+  tags: z3.array(tagSchema).max(64).optional(),
+  classification: classificationSchema.optional(),
+  bindings: bindingsSchema,
+  signing: signingSchema,
+  auth: authSchema,
+  secrets: z3.array(secretSchema).max(64).optional(),
+  environments: z3.record(z3.string().min(1).max(64).regex(IDENT_RE), environmentOverlaySchema).optional()
+}).strict();
+function applyEnvironmentOverlay(base, overlay) {
+  const effectiveBindings = overlay.bindings ?? base.bindings;
+  const mergedBindings = overlay.vars !== void 0 ? { ...effectiveBindings, vars: { ...effectiveBindings.vars ?? {}, ...overlay.vars } } : effectiveBindings;
+  return {
+    ...base,
+    server: overlay.server ? { ...base.server, ...overlay.server } : base.server,
+    specs: overlay.specs ?? base.specs,
+    skills: overlay.skills ? { ...base.skills, ...overlay.skills } : base.skills,
+    classification: overlay.classification ?? base.classification,
+    bindings: mergedBindings,
+    auth: overlay.auth ?? base.auth
+  };
+}
+function validateEffectiveManifest(manifest, label, errors) {
+  const declaredSecrets = new Set((manifest.secrets ?? []).map((s) => s.name));
+  const refs = [];
+  if (manifest.auth.provider === "frontegg") {
+    refs.push({ where: "auth.frontegg.issuerSecret", name: manifest.auth.frontegg.issuerSecret });
+  } else if (manifest.auth.provider === "oauth" && manifest.auth.oauth.credentialsSecret) {
+    refs.push({ where: "auth.oauth.credentialsSecret", name: manifest.auth.oauth.credentialsSecret });
+  } else if (manifest.auth.provider === "apiKey") {
+    refs.push({ where: "auth.apiKey.allowlistSecret", name: manifest.auth.apiKey.allowlistSecret });
+  }
+  for (const root of manifest.signing.trustRoots) {
+    refs.push({ where: `signing.trustRoots[kid=${root.kid}].publicKeySecret`, name: root.publicKeySecret });
+  }
+  for (const ref of refs) {
+    if (!declaredSecrets.has(ref.name)) {
+      errors.push(`${label}Secret "${ref.name}" referenced at ${ref.where} is not declared in secrets[]`);
+    }
+  }
+  const declaredKv = new Set((manifest.bindings.kvNamespaces ?? []).map((kv) => kv.binding));
+  if (!declaredKv.has(manifest.signing.replay.nonceKv)) {
+    errors.push(
+      `${label}signing.replay.nonceKv "${manifest.signing.replay.nonceKv}" does not match any bindings.kvNamespaces[].binding`
+    );
+  }
+  for (const id of manifest.skills.alwaysLoad ?? []) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) {
+      errors.push(`${label}skills.alwaysLoad entry "${id}" is not a valid kebab-case skill id`);
+    }
+  }
+  if (manifest.tags) {
+    const declaredTags = new Set(manifest.tags.map((t) => t.name));
+    const tagFilter = manifest.skills.tags;
+    for (const t of [...tagFilter?.include ?? [], ...tagFilter?.exclude ?? []]) {
+      if (!declaredTags.has(t)) {
+        errors.push(`${label}skills.tags references unknown tag "${t}" (not in tags[])`);
+      }
+    }
+  }
+}
+function crossValidateManifest(manifest) {
+  const errors = [];
+  validateEffectiveManifest(manifest, "", errors);
+  for (const [envName, overlay] of Object.entries(manifest.environments ?? {})) {
+    const effective = applyEnvironmentOverlay(manifest, overlay);
+    validateEffectiveManifest(effective, `environments.${envName}: `, errors);
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+// libs/adapters/src/skills/classifier/openapi-classify.ts
+function classifyOperations(specId, ops) {
+  if (!specId || specId.length === 0) {
+    throw new Error("classifyOperations: specId is required");
+  }
+  if (!Array.isArray(ops)) return [];
+  const pathsWithGet = /* @__PURE__ */ new Set();
+  for (const op of ops) {
+    if (op && typeof op.path === "string" && typeof op.method === "string" && op.method.toUpperCase() === "GET") {
+      pathsWithGet.add(op.path);
+    }
+  }
+  return ops.map((op) => classifyOne(specId, op, pathsWithGet));
+}
+function classifyOne(specId, op, pathsWithGet) {
+  const method = normaliseMethod(op.method);
+  const path = op.path;
+  const hasTerminalParam = pathHasTerminalParam(path);
+  const parent = parentPath(path);
+  const thisIsResource = pathsWithGet.has(path);
+  const parentIsResource = parent !== null && pathsWithGet.has(parent);
+  const selfUri = pathToResourceUri(specId, path);
+  const parentUri = parent !== null ? pathToResourceUri(specId, parent) : null;
+  if (method === "GET") {
+    if (hasTerminalParam) {
+      return {
+        operationId: op.operationId,
+        method,
+        path,
+        specId,
+        expose: "both",
+        resourceUriTemplate: selfUri
+      };
+    }
+    return {
+      operationId: op.operationId,
+      method,
+      path,
+      specId,
+      expose: "resource",
+      resourceUriTemplate: selfUri
+    };
+  }
+  const base = {
+    operationId: op.operationId,
+    method,
+    path,
+    specId,
+    expose: "tool"
+    // `resourceUriTemplate` left undefined for mutations — the emit target
+    // is the authoritative thing to look at.
+  };
+  if (method === "POST") {
+    if (thisIsResource && !hasTerminalParam) {
+      return { ...base, emit: { kind: "listChanged", pathTemplate: path, resourceUriTemplate: selfUri } };
+    }
+    if (thisIsResource && hasTerminalParam) {
+      return { ...base, emit: { kind: "updated", pathTemplate: path, resourceUriTemplate: selfUri } };
+    }
+    if (parentIsResource && parentUri !== null && parent !== null) {
+      return { ...base, emit: { kind: "updated", pathTemplate: parent, resourceUriTemplate: parentUri } };
+    }
+    return base;
+  }
+  if (method === "PUT" || method === "PATCH") {
+    if (thisIsResource) {
+      return { ...base, emit: { kind: "updated", pathTemplate: path, resourceUriTemplate: selfUri } };
+    }
+    if (parentIsResource && parentUri !== null && parent !== null) {
+      return { ...base, emit: { kind: "updated", pathTemplate: parent, resourceUriTemplate: parentUri } };
+    }
+    return base;
+  }
+  if (method === "DELETE") {
+    if (hasTerminalParam && parentIsResource && parentUri !== null && parent !== null) {
+      return { ...base, emit: { kind: "listChanged", pathTemplate: parent, resourceUriTemplate: parentUri } };
+    }
+    if (!hasTerminalParam && thisIsResource) {
+      return { ...base, emit: { kind: "listChanged", pathTemplate: path, resourceUriTemplate: selfUri } };
+    }
+    return base;
+  }
+  return base;
+}
+function applyClassificationOverrides(classified, rules) {
+  if (!Array.isArray(rules) || rules.length === 0) return classified.slice();
+  const compiled = rules.map((rule) => ({ rule, matcher: compileMatcher(rule.match) }));
+  return classified.map((op) => {
+    for (const { rule, matcher } of compiled) {
+      if (!matcher(op)) continue;
+      return applyOne(op, rule);
+    }
+    return op;
+  });
+}
+var KNOWN_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"]);
+function normaliseMethod(m) {
+  const up = (m ?? "").toUpperCase();
+  return KNOWN_METHODS.has(up) ? up : up;
+}
+function pathHasTerminalParam(path) {
+  if (typeof path !== "string" || path.length === 0) return false;
+  const segments = path.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) return false;
+  const last = segments[segments.length - 1];
+  return last.startsWith("{") && last.endsWith("}") && last.length >= 3;
+}
+function parentPath(path) {
+  if (typeof path !== "string" || path.length === 0) return null;
+  const segments = path.split("/").filter((s) => s.length > 0);
+  if (segments.length <= 1) return null;
+  return "/" + segments.slice(0, -1).join("/");
+}
+function pathToResourceUri(specId, path) {
+  const cleaned = path.startsWith("/") ? path.slice(1) : path;
+  return `mcp+op://${specId}/${cleaned}`;
+}
+function compileMatcher(match) {
+  const trimmed = (match ?? "").trim();
+  const sep2 = trimmed.indexOf(" ");
+  if (sep2 <= 0 || sep2 === trimmed.length - 1) {
+    return () => false;
+  }
+  const methodPattern = trimmed.slice(0, sep2).toUpperCase();
+  const pathPattern = trimmed.slice(sep2 + 1);
+  const pathRe = globToRegExp(pathPattern);
+  return (op) => {
+    if (methodPattern !== "*" && methodPattern !== op.method) return false;
+    return pathRe.test(op.path);
+  };
+}
+function globToRegExp(glob) {
+  const STAR_STAR = "\0";
+  const STAR = "
";
+  const replaced = glob.replace(/\*\*/g, STAR_STAR).replace(/\*/g, STAR);
+  const escaped = replaced.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const expanded = escaped.split(STAR_STAR).join(".*").split(STAR).join("[^/]*");
+  return new RegExp(`^${expanded}$`);
+}
+function defaultEmitKindForMethod(method) {
+  return method === "DELETE" ? "listChanged" : "updated";
+}
+function applyOne(op, rule) {
+  let next = { ...op };
+  if (rule.expose !== void 0) {
+    next = { ...next, expose: rule.expose };
+  }
+  if (rule.emits !== void 0) {
+    if (rule.emits === "none") {
+      const { emit: _drop, ...rest } = next;
+      next = rest;
+    } else if (rule.emits === "self") {
+      const target = pathToResourceUri(op.specId, op.path);
+      next = {
+        ...next,
+        emit: {
+          // Preserve the classifier's original kind if it set one; otherwise
+          // derive from the HTTP method so a DELETE override doesn't end up
+          // emitting `updated` on its own (now-gone) URI.
+          kind: next.emit?.kind ?? defaultEmitKindForMethod(op.method),
+          pathTemplate: op.path,
+          resourceUriTemplate: target
+        }
+      };
+    } else if (rule.emits === "parent") {
+      const parent = parentPath(op.path);
+      if (parent !== null) {
+        next = {
+          ...next,
+          emit: {
+            kind: next.emit?.kind ?? defaultEmitKindForMethod(op.method),
+            pathTemplate: parent,
+            resourceUriTemplate: pathToResourceUri(op.specId, parent)
+          }
+        };
+      } else {
+        const { emit: _drop, ...rest } = next;
+        next = rest;
+      }
+    }
+  }
+  return next;
+}
+
+// libs/adapters/src/skills/classifier/render-resource-uri.ts
+var TEMPLATE_PLACEHOLDER_RE = /\{([^{}]+)\}/g;
+function renderResourceUri(template, args) {
+  if (typeof template !== "string" || template.length === 0) {
+    return { ok: false, missing: [] };
+  }
+  const argObj = args !== null && typeof args === "object" ? args : {};
+  const missing = [];
+  const uri = template.replace(TEMPLATE_PLACEHOLDER_RE, (_match, name) => {
+    const value = argObj[name];
+    if (value === void 0 || value === null) {
+      missing.push(name);
+      return "";
+    }
+    if (typeof value === "object") {
+      missing.push(name);
+      return "";
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      missing.push(name);
+      return "";
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (missing.length > 0) return { ok: false, missing };
+  return { ok: true, uri };
+}
+
+// libs/adapters/src/skills/classifier/resource-change-notification.ts
+function buildResourceChangeNotification(classification, args) {
+  const emit = classification.emit;
+  if (!emit) return { notification: null, reason: "no-emit" };
+  if (emit.kind === "listChanged") {
+    const rendered2 = renderResourceUri(emit.resourceUriTemplate, args);
+    if (!rendered2.ok) {
+      return { notification: null, reason: "unresolved-template", missing: rendered2.missing };
+    }
+    return { notification: { method: "notifications/resources/list_changed" } };
+  }
+  const rendered = renderResourceUri(emit.resourceUriTemplate, args);
+  if (!rendered.ok) {
+    return { notification: null, reason: "unresolved-template", missing: rendered.missing };
+  }
+  return {
+    notification: {
+      method: "notifications/resources/updated",
+      params: { uri: rendered.uri }
+    }
+  };
+}
+
+// libs/adapters/src/skills/classifier/classification-registry.ts
+var ClassificationRegistry = class {
+  byToolName = /* @__PURE__ */ new Map();
+  /**
+   * Register (or replace) a classification for a tool name. Returns the
+   * previous classification if one existed.
+   *
+   * Useful for hot-reload: the deploy pipeline re-builds classifications
+   * from the new bundle and overwrites in place.
+   */
+  register(toolName, classification) {
+    if (typeof toolName !== "string" || toolName.length === 0) {
+      throw new Error("ClassificationRegistry.register: toolName must be a non-empty string");
+    }
+    const prev = this.byToolName.get(toolName);
+    this.byToolName.set(toolName, classification);
+    return prev;
+  }
+  /**
+   * Bulk-register an array of classifications keyed by `${specId}.${operationId}`.
+   * Returns the count of newly-added entries (existing entries are overwritten
+   * but not counted toward `added`).
+   */
+  registerAll(classifications) {
+    let added = 0;
+    let replaced = 0;
+    for (const c of classifications) {
+      const toolName = `${c.specId}.${c.operationId}`;
+      const prev = this.byToolName.get(toolName);
+      this.byToolName.set(toolName, c);
+      if (prev) replaced++;
+      else added++;
+    }
+    return { added, replaced };
+  }
+  /** Look up the classification for a tool. */
+  lookup(toolName) {
+    return this.byToolName.get(toolName);
+  }
+  /** Remove a single classification. Returns true if it was present. */
+  unregister(toolName) {
+    return this.byToolName.delete(toolName);
+  }
+  /** Drop every registration; used by the loader on full re-deploy. */
+  clear() {
+    this.byToolName.clear();
+  }
+  /** Current size — handy for tests and metrics. */
+  size() {
+    return this.byToolName.size;
+  }
+  /** Snapshot of every (toolName, classification) pair in insertion order. */
+  getAll() {
+    const out = [];
+    for (const [toolName, classification] of this.byToolName.entries()) {
+      out.push({ toolName, classification });
+    }
+    return out;
+  }
+  /**
+   * Convenience: in one step, look up the classification for `toolName`
+   * and build the resource-change notification it should produce after a
+   * successful call with `args`. Returns `{ notification: null }` when the
+   * tool has no classification (e.g. it's not an openapi-derived tool) or
+   * when its classification has no `emit`.
+   *
+   * The dispatcher is expected to call this from a successful-call hook
+   * and forward the resulting notification through whichever notification
+   * channel the host provides.
+   */
+  buildNotificationForCall(toolName, args) {
+    const classification = this.byToolName.get(toolName);
+    if (!classification) return { notification: null, reason: "no-emit" };
+    return buildResourceChangeNotification(classification, args);
+  }
+};
 export {
   BundlePinnedError,
   BundlePushJwtVerifier,
   BundleStore,
+  ClassificationRegistry,
   FilesystemSkillsSource,
   Hs256AuditSigner,
   MemoryAuditStore,
@@ -2089,15 +2787,25 @@ export {
   StaticSource,
   StorageAdapterAuditStore,
   WebhookReplayGuard,
+  applyClassificationOverrides,
+  applyEnvironmentOverlay,
+  buildKnownOps,
+  buildResourceChangeNotification,
   bundleDigest,
   bundleSkillToActions,
   bundleSourceSchema,
   canonicalize,
   canonicalizeRecordForSigning,
+  classifyOne,
+  classifyOperations,
   createBundleSource,
   crossValidate,
+  crossValidateManifest,
+  dedupeOpReferences,
   defaultAuditSignatureVerifier,
+  deployManifestSchema,
   diffBundles,
+  extractOpReferences,
   formatDiffSummary,
   hasSkillAuditFactory,
   linkRecord,
@@ -2106,12 +2814,14 @@ export {
   npmSourceSchema,
   parseOverlay,
   parseSkillFrontmatter,
+  renderResourceUri,
   resolveSkillLoadOrder,
   resolvedBundleSchema,
   saasSourceSchema,
   setSkillAuditFactory,
   signatureKeySchema,
   staticSourceSchema,
+  validateOpReferences,
   verifyBundleSignature,
   verifyChain
 };