@frontmcp/sdk 1.0.0 → 1.0.2

package/esm/index.mjs

@@ -3131,8 +3131,8 @@ var init_job_metadata = __esm({
 
 // libs/sdk/src/common/metadata/workflow.metadata.ts
 import { z as z34 } from "zod";
-function isValidWebhookPath(path) {
-  return WEBHOOK_PATH_PATTERN.test(path);
+function isValidWebhookPath(path2) {
+  return WEBHOOK_PATH_PATTERN.test(path2);
 }
 var workflowStepSchema, WEBHOOK_PATH_PATTERN, workflowWebhookConfigSchema, frontMcpWorkflowMetadataSchema;
 var init_workflow_metadata = __esm({
@@ -4420,8 +4420,8 @@ var init_sdk_errors = __esm({
       }
     };
     ConfigNotFoundError = class extends InternalMcpError {
-      constructor(path, triedPaths) {
-        const msg = triedPaths?.length ? `Config not found at "${path}". Tried: ${triedPaths.join(", ")}` : `Config not found at "${path}"`;
+      constructor(path2, triedPaths) {
+        const msg = triedPaths?.length ? `Config not found at "${path2}". Tried: ${triedPaths.join(", ")}` : `Config not found at "${path2}"`;
         super(msg, "CONFIG_NOT_FOUND");
       }
     };
@@ -4486,8 +4486,8 @@ var init_sdk_errors = __esm({
       }
     };
     AgentConfigKeyNotFoundError = class extends InternalMcpError {
-      constructor(path) {
-        super(`Agent config key not found: "${path}"`, "AGENT_CONFIG_KEY_NOT_FOUND");
+      constructor(path2) {
+        super(`Agent config key not found: "${path2}"`, "AGENT_CONFIG_KEY_NOT_FOUND");
       }
     };
     AgentToolExecutionError = class extends InternalMcpError {
@@ -4514,8 +4514,8 @@ var init_sdk_errors = __esm({
       }
     };
     RequiredConfigUndefinedError = class extends InternalMcpError {
-      constructor(path) {
-        super(`Required configuration path "${path}" is undefined`, "REQUIRED_CONFIG_UNDEFINED");
+      constructor(path2) {
+        super(`Required configuration path "${path2}" is undefined`, "REQUIRED_CONFIG_UNDEFINED");
       }
     };
     RegistryNotInitializedError = class extends InternalMcpError {
@@ -5693,8 +5693,8 @@ ${formattedErrors}`);
       constructor(config) {
         this.config = config;
       }
-      get(path, defaultValue) {
-        const keys = path.split(".");
+      get(path2, defaultValue) {
+        const keys = path2.split(".");
         let result = this.config;
         for (const key of keys) {
           if (result && typeof result === "object" && key in result) {
@@ -5715,18 +5715,18 @@ ${formattedErrors}`);
        * @example
        * config.getOrThrow('database.url') // string (throws if missing)
        */
-      getOrThrow(path) {
-        const value = this.get(path);
+      getOrThrow(path2) {
+        const value = this.get(path2);
         if (value === void 0) {
-          throw new ConfigMissingError(path);
+          throw new ConfigMissingError(path2);
         }
         return value;
       }
       /**
        * Alias for getOrThrow.
        */
-      getRequired(path) {
-        return this.getOrThrow(path);
+      getRequired(path2) {
+        return this.getOrThrow(path2);
       }
       /**
        * Check if a configuration path exists and has a value.
@@ -5734,8 +5734,8 @@ ${formattedErrors}`);
        * @param path - Dot notation path (e.g., 'database.url')
        * @returns True if path exists and has a defined value
        */
-      has(path) {
-        const keys = path.split(".");
+      has(path2) {
+        const keys = path2.split(".");
         let result = this.config;
         for (const key of keys) {
           if (result && typeof result === "object" && key in result) {
@@ -5767,8 +5767,8 @@ ${formattedErrors}`);
        * @param defaultValue - Default value if not found or not a number
        * @returns Number value or NaN
        */
-      getNumber(path, defaultValue) {
-        const value = this.get(path);
+      getNumber(path2, defaultValue) {
+        const value = this.get(path2);
         if (value === void 0) {
           return defaultValue ?? NaN;
         }
@@ -5786,8 +5786,8 @@ ${formattedErrors}`);
        * @param defaultValue - Default value if not found
        * @returns Boolean value
        */
-      getBoolean(path, defaultValue) {
-        const value = this.get(path);
+      getBoolean(path2, defaultValue) {
+        const value = this.get(path2);
         if (value === void 0) {
           return defaultValue ?? false;
         }
@@ -6417,22 +6417,22 @@ var init_provider_registry = __esm({
         const WHITE = 0, GRAY = 1, BLACK = 2;
         const color = /* @__PURE__ */ new Map();
         const order = /* @__PURE__ */ new Set();
-        const path = [];
+        const path2 = [];
         const dfs = (n) => {
           color.set(n, GRAY);
-          path.push(n);
+          path2.push(n);
           for (const dep of this.graph.get(n) ?? []) {
             const c = color.get(dep) ?? WHITE;
             if (c === GRAY) {
-              const idx = path.findIndex((p) => p === dep);
-              const cycle = [...path.slice(idx), dep].map((t) => tokenName2(t)).join(" -> ");
+              const idx = path2.findIndex((p) => p === dep);
+              const cycle = [...path2.slice(idx), dep].map((t) => tokenName2(t)).join(" -> ");
               throw new DependencyCycleError(cycle);
             }
             if (c === WHITE) dfs(dep);
           }
           color.set(n, BLACK);
           order.add(n);
-          path.pop();
+          path2.pop();
         };
         for (const n of this.graph.keys()) if ((color.get(n) ?? WHITE) === WHITE) dfs(n);
         this.order = order;
@@ -14928,11 +14928,63 @@ var init_skill_utils = __esm({
 });
 
 // libs/sdk/src/skill/skill.instance.ts
-import { dirname, pathResolve } from "@frontmcp/utils";
+import { dirname, pathResolve, pathJoin, fileExists as fileExists2, readJSON } from "@frontmcp/utils";
 function createSkillInstance(record, providers, owner) {
   return new SkillInstance(record, providers, owner);
 }
-var SkillInstance;
+async function loadResourceWithManifestFallback(resourcePath, baseDir, skillName, resourceType, loader) {
+  if (!resourcePath) return void 0;
+  let dir = resourcePath.startsWith("/") ? resourcePath : baseDir ? pathResolve(baseDir, resourcePath) : void 0;
+  if (dir) {
+    try {
+      return await loader(dir);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      dir = await resolveResourceFromManifest(skillName, resourceType);
+      if (dir) return await loader(dir);
+    }
+  } else {
+    dir = await resolveResourceFromManifest(skillName, resourceType);
+    if (dir) return await loader(dir);
+  }
+  return void 0;
+}
+async function resolveFromSkillManifest(skillName) {
+  if (skillManifestCache === null) return void 0;
+  if (skillManifestCache === void 0) {
+    try {
+      const mainDir2 = __require.main?.filename ? dirname(__require.main.filename) : process.cwd();
+      const manifestPath = pathJoin(mainDir2, "_skills", "manifest.json");
+      if (await fileExists2(manifestPath)) {
+        skillManifestCache = await readJSON(manifestPath);
+      } else {
+        skillManifestCache = null;
+        return void 0;
+      }
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        skillManifestCache = null;
+        return void 0;
+      }
+      throw err;
+    }
+  }
+  if (!skillManifestCache) return void 0;
+  const entry = skillManifestCache[skillName];
+  if (!entry?.instructions) return void 0;
+  const mainDir = __require.main?.filename ? dirname(__require.main.filename) : process.cwd();
+  return pathResolve(mainDir, entry.instructions);
+}
+async function resolveResourceFromManifest(skillName, resourceType) {
+  await resolveFromSkillManifest(skillName);
+  if (!skillManifestCache) return void 0;
+  const entry = skillManifestCache[skillName];
+  const relPath = entry?.[resourceType];
+  if (!relPath) return void 0;
+  const mainDir = __require.main?.filename ? dirname(__require.main.filename) : process.cwd();
+  return pathResolve(mainDir, relPath);
+}
+var SkillInstance, skillManifestCache;
 var init_skill_instance = __esm({
   "libs/sdk/src/skill/skill.instance.ts"() {
     "use strict";
@@ -14993,7 +15045,20 @@ var init_skill_instance = __esm({
         } else if (this.record.kind === "VALUE" /* VALUE */ && this.record.callerDir) {
           basePath = this.record.callerDir;
         }
-        this.cachedInstructions = await loadInstructions(this.metadata.instructions, basePath);
+        try {
+          this.cachedInstructions = await loadInstructions(this.metadata.instructions, basePath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            const resolved = await resolveFromSkillManifest(this.metadata.name);
+            if (resolved) {
+              this.cachedInstructions = await loadInstructions({ file: resolved }, void 0);
+            } else {
+              throw err;
+            }
+          } else {
+            throw err;
+          }
+        }
         return this.cachedInstructions;
       }
       /**
@@ -15018,22 +15083,20 @@ var init_skill_instance = __esm({
         }
         const instructions = await this.loadInstructions();
         const baseDir = this.getBaseDir();
-        const refsPath = this.metadata.resources?.references;
-        let resolvedRefs;
-        if (refsPath) {
-          const refsDir = refsPath.startsWith("/") ? refsPath : baseDir ? pathResolve(baseDir, refsPath) : void 0;
-          if (refsDir) {
-            resolvedRefs = await resolveReferences(refsDir);
-          }
-        }
-        const examplesPath = this.metadata.resources?.examples;
-        let resolvedExs;
-        if (examplesPath) {
-          const exDir = examplesPath.startsWith("/") ? examplesPath : baseDir ? pathResolve(baseDir, examplesPath) : void 0;
-          if (exDir) {
-            resolvedExs = await resolveExamples(exDir);
-          }
-        }
+        const resolvedRefs = await loadResourceWithManifestFallback(
+          this.metadata.resources?.references,
+          baseDir,
+          this.metadata.name,
+          "references",
+          resolveReferences
+        );
+        const resolvedExs = await loadResourceWithManifestFallback(
+          this.metadata.resources?.examples,
+          baseDir,
+          this.metadata.name,
+          "examples",
+          resolveExamples
+        );
         const baseContent = buildSkillContent(this.metadata, instructions, resolvedRefs, resolvedExs);
         this.cachedContent = {
           ...baseContent,
@@ -17963,8 +18026,8 @@ function generateEnvFallbacks(key, context) {
   ];
 }
 function resolveWithFallbacks(config, paths) {
-  for (const path of paths) {
-    const value = config.get(path);
+  for (const path2 of paths) {
+    const value = config.get(path2);
     if (value !== void 0) {
       return value;
     }
@@ -17973,31 +18036,31 @@ function resolveWithFallbacks(config, paths) {
 }
 function createContextResolver(config, context) {
   return {
-    get(path) {
-      const fallbacks = generateFallbacks(path, context);
+    get(path2) {
+      const fallbacks = generateFallbacks(path2, context);
       const value = resolveWithFallbacks(config, fallbacks);
       if (value === void 0) {
-        throw new ConfigNotFoundError(path, fallbacks);
+        throw new ConfigNotFoundError(path2, fallbacks);
       }
       return value;
     },
-    tryGet(path) {
-      const fallbacks = generateFallbacks(path, context);
+    tryGet(path2) {
+      const fallbacks = generateFallbacks(path2, context);
       return resolveWithFallbacks(config, fallbacks);
     }
   };
 }
 function createDirectResolver(config) {
   return {
-    get(path) {
-      const value = config.get(path);
+    get(path2) {
+      const value = config.get(path2);
       if (value === void 0) {
-        throw new ConfigNotFoundError(path);
+        throw new ConfigNotFoundError(path2);
       }
       return value;
     },
-    tryGet(path) {
-      return config.get(path);
+    tryGet(path2) {
+      return config.get(path2);
     }
   };
 }
@@ -18021,8 +18084,8 @@ function resolveWithConfigValue(withConfig2, configResolver, entityContext) {
   } else {
     paths = [withConfig2.configPath];
   }
-  for (const path of paths) {
-    const value = configResolver.tryGet(path);
+  for (const path2 of paths) {
+    const value = configResolver.tryGet(path2);
     if (value !== void 0) {
       return withConfig2.transform ? withConfig2.transform(value) : value;
     }
@@ -18205,7 +18268,7 @@ var init_config_symbols = __esm({
 });
 
 // libs/sdk/src/builtin/config/providers/env-loader.ts
-import { readFile as readFile3, fileExists as fileExists2, getCwd, getEnv as getEnv2, setEnv, pathResolve as pathResolve2 } from "@frontmcp/utils";
+import { readFile as readFile3, fileExists as fileExists3, getCwd, getEnv as getEnv2, setEnv, pathResolve as pathResolve2 } from "@frontmcp/utils";
 function parseEnvContent(content) {
   const result = {};
   const lines = content.split("\n");
@@ -18234,12 +18297,12 @@ function parseEnvContent(content) {
 async function loadEnvFiles(basePath = getCwd(), envPath = ".env", localEnvPath = ".env.local") {
   const result = {};
   const envFile = pathResolve2(basePath, envPath);
-  if (await fileExists2(envFile)) {
+  if (await fileExists3(envFile)) {
     const content = await readFile3(envFile);
     Object.assign(result, parseEnvContent(content));
   }
   const localFile = pathResolve2(basePath, localEnvPath);
-  if (await fileExists2(localFile)) {
+  if (await fileExists3(localFile)) {
     const content = await readFile3(localFile);
     Object.assign(result, parseEnvContent(content));
   }
@@ -18258,11 +18321,11 @@ function populateProcessEnv(env, override = false) {
 function isSafeKey(key) {
   return !UNSAFE_KEYS.has(key);
 }
-function pathToEnvKey(path) {
-  return path.toUpperCase().replace(/\./g, "_");
+function pathToEnvKey(path2) {
+  return path2.toUpperCase().replace(/\./g, "_");
 }
-function setNestedValue(obj, path, value) {
-  const keys = path.split(".");
+function setNestedValue(obj, path2, value) {
+  const keys = path2.split(".");
   for (const key of keys) {
     if (!isSafeKey(key)) {
       return;
@@ -18285,8 +18348,8 @@ function setNestedValue(obj, path, value) {
   }
   current[finalKey] = value;
 }
-function getNestedValue(obj, path) {
-  const keys = path.split(".");
+function getNestedValue(obj, path2) {
+  const keys = path2.split(".");
   for (const key of keys) {
     if (!isSafeKey(key)) {
       return void 0;
@@ -18341,11 +18404,11 @@ function unwrapZodType(schema) {
 }
 function mapEnvToNestedConfig(env, paths) {
   const result = {};
-  for (const path of paths) {
-    const envKey = pathToEnvKey(path);
+  for (const path2 of paths) {
+    const envKey = pathToEnvKey(path2);
     const value = env[envKey];
     if (value !== void 0) {
-      setNestedValue(result, path, value);
+      setNestedValue(result, path2, value);
     }
   }
   return result;
@@ -18360,7 +18423,7 @@ var init_env_loader = __esm({
 
 // libs/sdk/src/builtin/config/providers/config-loader.ts
 import * as yaml2 from "js-yaml";
-import { readFile as readFile4, fileExists as fileExists3, getCwd as getCwd2, pathResolve as pathResolve3 } from "@frontmcp/utils";
+import { readFile as readFile4, fileExists as fileExists4, getCwd as getCwd2, pathResolve as pathResolve3 } from "@frontmcp/utils";
 async function loadConfig(schema, options = {}) {
   const {
     basePath = getCwd2(),
@@ -18402,7 +18465,7 @@ async function loadYamlConfig(basePath, configPath) {
   const baseName = configPath.replace(/\.(ya?ml)$/, "");
   for (const ext of extensions) {
     const fullPath = pathResolve3(basePath, baseName + ext);
-    if (await fileExists3(fullPath)) {
+    if (await fileExists4(fullPath)) {
       const content = await readFile4(fullPath);
       const parsed = yaml2.load(content);
       if (parsed && typeof parsed === "object") {
@@ -18893,8 +18956,8 @@ var init_flow_instance = __esm({
         this.stages = collectFlowHookMap(this.FlowClass);
         const { middleware } = this.metadata;
         if (middleware) {
-          const path = typeof middleware.path === "string" ? middleware.path : "";
-          server.registerMiddleware(path, async (request, response, next) => {
+          const path2 = typeof middleware.path === "string" ? middleware.path : "";
+          server.registerMiddleware(path2, async (request, response, next) => {
             const canActivate = await this.canActivate(request);
             if (!canActivate) return next();
             const contextStorage = this.getContextStorage();
@@ -19929,8 +19992,8 @@ var init_agent_instance = __esm({
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       createConfigResolver(configService) {
         const config = configService.getAll();
-        const getNestedValue2 = (path) => {
-          const keys = path.split(".");
+        const getNestedValue2 = (path2) => {
+          const keys = path2.split(".");
           let current = config;
           for (const key of keys) {
             if (current && typeof current === "object" && key in current) {
@@ -19942,15 +20005,15 @@ var init_agent_instance = __esm({
           return current;
         };
         return {
-          get(path) {
-            const value = getNestedValue2(path);
+          get(path2) {
+            const value = getNestedValue2(path2);
             if (value === void 0) {
-              throw new AgentConfigKeyNotFoundError(path);
+              throw new AgentConfigKeyNotFoundError(path2);
             }
             return value;
           },
-          tryGet(path) {
-            return getNestedValue2(path);
+          tryGet(path2) {
+            return getNestedValue2(path2);
           }
         };
       }
@@ -22935,21 +22998,21 @@ function getDefaultCacheDir() {
     return "";
   }
   try {
-    const path = __require("node:path");
+    const path2 = __require("node:path");
     try {
-      const nodeModulesDir = path.join(process.cwd(), "node_modules");
-      const fs = __require("node:fs");
-      if (fs.existsSync(nodeModulesDir)) {
-        return path.join(nodeModulesDir, ".cache", "frontmcp-esm");
+      const nodeModulesDir = path2.join(process.cwd(), "node_modules");
+      const fs2 = __require("node:fs");
+      if (fs2.existsSync(nodeModulesDir)) {
+        return path2.join(nodeModulesDir, ".cache", "frontmcp-esm");
       }
     } catch {
     }
     try {
-      const os = __require("node:os");
-      return path.join(os.homedir(), ".frontmcp", "esm-cache");
+      const os2 = __require("node:os");
+      return path2.join(os2.homedir(), ".frontmcp", "esm-cache");
     } catch {
     }
-    return path.join(__require("node:os").tmpdir?.() ?? "/tmp", ".frontmcp-esm-cache");
+    return path2.join(__require("node:os").tmpdir?.() ?? "/tmp", ".frontmcp-esm-cache");
   } catch {
     return "";
   }
@@ -22982,21 +23045,21 @@ var init_esm_cache = __esm({
         }
         if (!this.cacheDir) return void 0;
         try {
-          const path = __require("node:path");
-          const { fileExists: fileExists6, readJSON } = __require("@frontmcp/utils");
+          const path2 = __require("node:path");
+          const { fileExists: fileExists8, readJSON: readJSON2 } = __require("@frontmcp/utils");
           const entryDir = this.getEntryDir(packageName, version);
-          const metaPath = path.join(entryDir, "meta.json");
-          if (!await fileExists6(metaPath)) {
+          const metaPath = path2.join(entryDir, "meta.json");
+          if (!await fileExists8(metaPath)) {
             return void 0;
           }
-          const meta = await readJSON(metaPath);
+          const meta = await readJSON2(metaPath);
           if (!meta) {
             return void 0;
           }
           if (Date.now() - meta.cachedAt > this.maxAgeMs) {
             return void 0;
           }
-          if (!await fileExists6(meta.bundlePath)) {
+          if (!await fileExists8(meta.bundlePath)) {
             return void 0;
           }
           this.memoryStore.set(memKey, meta);
@@ -23016,12 +23079,12 @@ var init_esm_cache = __esm({
         let bundlePath = "";
         if (this.cacheDir) {
           try {
-            const path = __require("node:path");
+            const path2 = __require("node:path");
             const { writeFile, ensureDir, writeJSON } = __require("@frontmcp/utils");
             const entryDir = this.getEntryDir(packageName, version);
             await ensureDir(entryDir);
             const cachedBundle = toCachedBundle(bundleContent);
-            bundlePath = path.join(entryDir, cachedBundle.fileName);
+            bundlePath = path2.join(entryDir, cachedBundle.fileName);
             await writeFile(bundlePath, cachedBundle.content);
             const diskEntry = {
               packageUrl,
@@ -23031,7 +23094,7 @@ var init_esm_cache = __esm({
               bundlePath,
               etag
             };
-            const metaPath = path.join(entryDir, "meta.json");
+            const metaPath = path2.join(entryDir, "meta.json");
             await writeJSON(metaPath, diskEntry);
           } catch {
           }
@@ -23059,10 +23122,10 @@ var init_esm_cache = __esm({
         }
         if (!this.cacheDir) return;
         try {
-          const path = __require("node:path");
-          const { fileExists: fileExists6, readJSON, rm } = __require("@frontmcp/utils");
+          const path2 = __require("node:path");
+          const { fileExists: fileExists8, readJSON: readJSON2, rm } = __require("@frontmcp/utils");
           const { readdir: readdir2 } = __require("@frontmcp/utils");
-          if (!await fileExists6(this.cacheDir)) {
+          if (!await fileExists8(this.cacheDir)) {
             return;
           }
           let entries;
@@ -23072,11 +23135,11 @@ var init_esm_cache = __esm({
             return;
           }
           for (const dirEntry of entries) {
-            const metaPath = path.join(this.cacheDir, dirEntry, "meta.json");
-            if (await fileExists6(metaPath)) {
-              const meta = await readJSON(metaPath);
+            const metaPath = path2.join(this.cacheDir, dirEntry, "meta.json");
+            if (await fileExists8(metaPath)) {
+              const meta = await readJSON2(metaPath);
               if (meta?.packageName === packageName) {
-                await rm(path.join(this.cacheDir, dirEntry), { recursive: true, force: true });
+                await rm(path2.join(this.cacheDir, dirEntry), { recursive: true, force: true });
               }
             }
           }
@@ -23098,10 +23161,10 @@ var init_esm_cache = __esm({
         }
         if (!this.cacheDir) return removed;
         try {
-          const path = __require("node:path");
-          const { fileExists: fileExists6, readJSON, rm } = __require("@frontmcp/utils");
+          const path2 = __require("node:path");
+          const { fileExists: fileExists8, readJSON: readJSON2, rm } = __require("@frontmcp/utils");
           const { readdir: readdir2 } = __require("@frontmcp/utils");
-          if (!await fileExists6(this.cacheDir)) {
+          if (!await fileExists8(this.cacheDir)) {
             return removed;
           }
           let entries;
@@ -23111,11 +23174,11 @@ var init_esm_cache = __esm({
             return removed;
           }
           for (const dirEntry of entries) {
-            const metaPath = path.join(this.cacheDir, dirEntry, "meta.json");
-            if (await fileExists6(metaPath)) {
-              const meta = await readJSON(metaPath);
+            const metaPath = path2.join(this.cacheDir, dirEntry, "meta.json");
+            if (await fileExists8(metaPath)) {
+              const meta = await readJSON2(metaPath);
               if (meta && now - meta.cachedAt > threshold) {
-                await rm(path.join(this.cacheDir, dirEntry), { recursive: true, force: true });
+                await rm(path2.join(this.cacheDir, dirEntry), { recursive: true, force: true });
                 removed++;
               }
             }
@@ -23138,9 +23201,9 @@ var init_esm_cache = __esm({
        * Get the cache directory for a specific package+version combination.
        */
       getEntryDir(packageName, version) {
-        const path = __require("node:path");
+        const path2 = __require("node:path");
         const hash = sha256Hex2(`${packageName}@${version}`);
-        return path.join(this.cacheDir, hash);
+        return path2.join(this.cacheDir, hash);
       }
     };
   }
@@ -25683,8 +25746,8 @@ var init_oauth_authorize_flow = __esm({
        */
       formatZodErrors(error) {
         return error.issues.map((err) => {
-          const path = err.path.length > 0 ? `${err.path.join(".")}: ` : "";
-          return `${path}${err.message}`;
+          const path2 = err.path.length > 0 ? `${err.path.join(".")}: ` : "";
+          return `${path2}${err.message}`;
         });
       }
       /**
@@ -35135,8 +35198,8 @@ var init_skills_api_flow = __esm({
         const basePath = `${entryPrefix}${scopeBase}`;
         const apiPath = options.normalizedApi.path ?? "/skills";
         const fullPath = `${basePath}${apiPath}`;
-        const path = request.path;
-        return path === apiPath || path.startsWith(`${apiPath}/`) || path === fullPath || path.startsWith(`${fullPath}/`);
+        const path2 = request.path;
+        return path2 === apiPath || path2.startsWith(`${apiPath}/`) || path2 === fullPath || path2.startsWith(`${fullPath}/`);
       }
       async checkEnabled() {
         const skillsConfig = this.scope.metadata.skillsConfig;
@@ -35180,11 +35243,11 @@ var init_skills_api_flow = __esm({
         const apiPath = options.normalizedApi.path ?? "/skills";
         const fullPath = `${basePath}${apiPath}`;
         let skillId;
-        const path = request.path;
-        if (path.startsWith(`${fullPath}/`)) {
-          skillId = path.slice(fullPath.length + 1);
-        } else if (path.startsWith(`${apiPath}/`)) {
-          skillId = path.slice(apiPath.length + 1);
+        const path2 = request.path;
+        if (path2.startsWith(`${fullPath}/`)) {
+          skillId = path2.slice(fullPath.length + 1);
+        } else if (path2.startsWith(`${apiPath}/`)) {
+          skillId = path2.slice(apiPath.length + 1);
         }
         const queryRaw = request.query?.["query"];
         const query = Array.isArray(queryRaw) ? queryRaw[0] : queryRaw;
@@ -36797,8 +36860,8 @@ function pathOf(req) {
     return String(raw).split("?")[0] || "/";
   }
 }
-function isLegacySsePath(path) {
-  return path === "/sse" || path.endsWith("/sse");
+function isLegacySsePath(path2) {
+  return path2 === "/sse" || path2.endsWith("/sse");
 }
 function tryDecodeTransportType(sessionId) {
   if (!sessionId) return;
@@ -36823,8 +36886,8 @@ function getQuerySessionId2(req) {
 function computeBitmap(req, cfg) {
   const method = req.method.toUpperCase();
   const accept = h(req, "accept");
-  const path = pathOf(req);
-  const postToMessage = method === "POST" && (path === "/message" || path.endsWith("/message"));
+  const path2 = pathOf(req);
+  const postToMessage = method === "POST" && (path2 === "/message" || path2.endsWith("/message"));
   const headerSessionId = h(req, "mcp-session-id");
   const querySessionId = postToMessage ? getQuerySessionId2(req) : void 0;
   const sessionId = headerSessionId ?? querySessionId;
@@ -36833,7 +36896,7 @@ function computeBitmap(req, cfg) {
   const acceptSSE = wantsSSE(accept);
   const acceptJSON = wantsJSON(accept) || !accept && cfg.tolerateMissingAccept;
   const init = method === "POST" && isInitialize(req.body);
-  const getToSsePath = method === "GET" && isLegacySsePath(path);
+  const getToSsePath = method === "GET" && isLegacySsePath(path2);
   const channel = method === "POST" && postToMessage ? CH_POST_MESSAGE : getToSsePath && acceptSSE ? CH_GET_SSE_PATH : method === "GET" && acceptSSE ? CH_GET_SSE : method === "POST" && init && acceptSSE ? CH_POST_INIT_SSE : method === "POST" && init && acceptJSON ? CH_POST_INIT_JSON : method === "POST" && !init && acceptSSE ? CH_POST_SSE : method === "POST" && !init && acceptJSON ? CH_POST_JSON : CH_OTHER;
   let flags = 0;
   if (sessionId) flags |= B_HAS_SESSION;
@@ -44517,7 +44580,7 @@ var init_base_host_adapter = __esm({
 import * as http from "node:http";
 import express from "express";
 import cors from "cors";
-import { fileExists as fileExists4, unlink } from "@frontmcp/utils";
+import { fileExists as fileExists5, unlink } from "@frontmcp/utils";
 var ExpressHostAdapter;
 var init_express_host_adapter = __esm({
   "libs/sdk/src/server/adapters/express.host.adapter.ts"() {
@@ -44551,8 +44614,8 @@ var init_express_host_adapter = __esm({
           next();
         });
       }
-      registerRoute(method, path, handler) {
-        this.router[method.toLowerCase()](path, this.enhancedHandler(handler));
+      registerRoute(method, path2, handler) {
+        this.router[method.toLowerCase()](path2, this.enhancedHandler(handler));
       }
       registerMiddleware(entryPath, handler) {
         this.router.use(entryPath, handler);
@@ -44594,8 +44657,8 @@ var init_express_host_adapter = __esm({
             server.on("error", reject);
             server.listen(portOrSocketPath, () => {
               try {
-                const fs = __require("node:fs");
-                fs.chmodSync(portOrSocketPath, 432);
+                const fs2 = __require("node:fs");
+                fs2.chmodSync(portOrSocketPath, 432);
               } catch {
               }
               console.log(`MCP HTTP (Express) on unix://${portOrSocketPath}`);
@@ -44614,7 +44677,7 @@ var init_express_host_adapter = __esm({
       }
       async cleanupStaleSocket(socketPath) {
         try {
-          if (await fileExists4(socketPath)) {
+          if (await fileExists5(socketPath)) {
             await unlink(socketPath);
           }
         } catch {
@@ -44666,8 +44729,8 @@ var init_server_instance = __esm({
       registerMiddleware(entryPath, handler) {
         return this.host.registerMiddleware(entryPath, handler);
       }
-      registerRoute(method, path, handler) {
-        return this.host.registerRoute(method, path, handler);
+      registerRoute(method, path2, handler) {
+        return this.host.registerRoute(method, path2, handler);
       }
       enhancedHandler(handler) {
         return this.host.enhancedHandler(handler);
@@ -45064,8 +45127,39 @@ var direct_client_exports = {};
 __export(direct_client_exports, {
   DirectClientImpl: () => DirectClientImpl
 });
-import { randomUUID as randomUUID23 } from "@frontmcp/utils";
+import { randomUUID as randomUUID23, pathResolve as pathResolve5, fileExists as fileExists6 } from "@frontmcp/utils";
 import { Client as Client2 } from "@frontmcp/protocol";
+function findFileFromRoot(root, relativePath) {
+  const fs2 = __require("fs");
+  const path2 = __require("path");
+  const cleanRelative = relativePath.replace(/^\.\//, "");
+  const searchDirs = ["src", "."];
+  for (const srcDir of searchDirs) {
+    const srcRoot = path2.join(root, srcDir);
+    if (!fs2.existsSync(srcRoot)) continue;
+    const found = walkForFile(srcRoot, cleanRelative, fs2, path2);
+    if (found) return found;
+  }
+  return void 0;
+}
+function walkForFile(dir, targetRelative, fs2, path2, maxDepth = 10) {
+  const candidate = path2.join(dir, targetRelative);
+  if (fs2.existsSync(candidate)) {
+    return { absolute: candidate, baseDir: dir };
+  }
+  if (maxDepth <= 0) return void 0;
+  try {
+    const entries = fs2.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "dist") {
+        const result = walkForFile(path2.join(dir, entry.name), targetRelative, fs2, path2, maxDepth - 1);
+        if (result) return result;
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
 var DirectClientImpl;
 var init_direct_client = __esm({
   "libs/sdk/src/direct/direct-client.ts"() {
@@ -45089,6 +45183,8 @@ var init_direct_client = __esm({
       resourceUpdateHandlers = /* @__PURE__ */ new Set();
       // Generic notification handlers
       notificationHandlers = /* @__PURE__ */ new Set();
+      // Scope reference for build-time operations (collectSkillAssets)
+      scopeRef;
       constructor(mcpClient, sessionId, clientInfo, serverInfo, capabilities) {
         this.mcpClient = mcpClient;
         this.sessionId = sessionId;
@@ -45141,6 +45237,7 @@ var init_direct_client = __esm({
           }
           const client = new _DirectClientImpl(mcpClient, sessionId, clientInfo, serverInfo, serverCapabilities);
           client.closeServer = close;
+          client.scopeRef = scope;
           await client.setupNotificationHandlers(mcpClient);
           return client;
         } catch (error) {
@@ -45444,6 +45541,52 @@ var init_direct_client = __esm({
       async getWorkflowStatus(runId) {
         return this.callToolAndParseJson("get-workflow-status", { runId });
       }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Build-Time Asset Collection
+      // ─────────────────────────────────────────────────────────────────────────────
+      async collectSkillAssets() {
+        const scope = this.scopeRef;
+        if (!scope?.skills) return { entries: [] };
+        const skills = scope.skills.getSkills({ includeHidden: true });
+        const entries = [];
+        for (const skill of skills) {
+          const baseDir = skill.getBaseDir?.();
+          const meta = skill.metadata;
+          const entry = {
+            skillName: meta.name,
+            baseDir
+          };
+          if (meta.instructions && typeof meta.instructions === "object" && "file" in meta.instructions) {
+            const filePath = meta.instructions.file;
+            const resolved = filePath.startsWith("/") ? filePath : baseDir ? pathResolve5(baseDir, filePath) : void 0;
+            if (resolved && await fileExists6(resolved)) {
+              entry.instructionFile = resolved;
+            } else if (!filePath.startsWith("/")) {
+              const fromCwd = findFileFromRoot(process.cwd(), filePath);
+              if (fromCwd) {
+                entry.instructionFile = fromCwd.absolute;
+                entry.baseDir = fromCwd.baseDir;
+              }
+            }
+          }
+          const resources = skill.getResources?.();
+          if (resources) {
+            entry.resources = {};
+            for (const key of ["references", "examples", "scripts", "assets"]) {
+              const p = resources[key];
+              if (p) {
+                const base = entry.baseDir || baseDir;
+                const resolved = p.startsWith("/") ? p : base ? pathResolve5(base, p) : void 0;
+                if (resolved && await fileExists6(resolved)) {
+                  entry.resources[key] = resolved;
+                }
+              }
+            }
+          }
+          entries.push(entry);
+        }
+        return { entries };
+      }
     };
   }
 });
@@ -45813,12 +45956,108 @@ var init_direct = __esm({
   }
 });
 
+// libs/sdk/src/logger/instances/instance.file-logger.ts
+import * as path from "path";
+import * as fs from "fs";
+import * as os from "os";
+function stripAnsi(str) {
+  return str.split(ESC).map((s) => s.replace(/\[[0-9;]*m/, "")).join("");
+}
+var LOG_LEVEL_LABELS, ESC, DEFAULT_LOGS_MAX, FileLogTransportInstance;
+var init_instance_file_logger = __esm({
+  "libs/sdk/src/logger/instances/instance.file-logger.ts"() {
+    "use strict";
+    init_common();
+    LOG_LEVEL_LABELS = {
+      [100 /* Off */]: "OFF",
+      [0 /* Debug */]: "DEBUG",
+      [1 /* Verbose */]: "VERBOSE",
+      [2 /* Info */]: "INFO",
+      [3 /* Warn */]: "WARN",
+      [4 /* Error */]: "ERROR"
+    };
+    ESC = String.fromCharCode(27);
+    DEFAULT_LOGS_MAX = 25;
+    FileLogTransportInstance = class extends LogTransportInterface {
+      fd;
+      logDir;
+      appName;
+      constructor() {
+        super();
+        const rawAppName = process.env["FRONTMCP_APP_NAME"] || "frontmcp";
+        const sanitized = rawAppName.replace(/[^a-zA-Z0-9._-]/g, "_");
+        this.appName = sanitized.length > 0 ? sanitized : "frontmcp";
+        this.logDir = process.env["FRONTMCP_LOG_DIR"] || path.join(process.env["FRONTMCP_HOME"] || path.join(os.homedir(), ".frontmcp"), "logs");
+        const logsMax = parseInt(process.env["FRONTMCP_LOGS_MAX"] || "", 10);
+        if (logsMax === 0) {
+          this.fd = void 0;
+          return;
+        }
+        try {
+          fs.mkdirSync(this.logDir, { recursive: true });
+          const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "_");
+          const filePath = path.join(this.logDir, `${this.appName}-${ts}.log`);
+          this.fd = fs.openSync(filePath, "a");
+          this.rotate(isNaN(logsMax) ? DEFAULT_LOGS_MAX : logsMax);
+        } catch {
+          this.fd = void 0;
+        }
+      }
+      /** Close the file descriptor. Call during shutdown to prevent handle leaks. */
+      close() {
+        if (this.fd !== void 0) {
+          try {
+            fs.closeSync(this.fd);
+          } catch {
+          }
+          this.fd = void 0;
+        }
+      }
+      log(rec) {
+        if (this.fd === void 0) return;
+        const ts = rec.timestamp.toISOString();
+        const level = LOG_LEVEL_LABELS[rec.level] ?? "INFO";
+        const prefix = rec.prefix ? ` [${rec.prefix}]` : "";
+        const message = stripAnsi(String(rec.message));
+        const line = `[${ts}] ${level}${prefix} ${message}
+`;
+        try {
+          fs.writeSync(this.fd, line);
+        } catch {
+        }
+      }
+      /** Remove oldest log files when count exceeds max (npm-style rotation). */
+      rotate(maxFiles) {
+        try {
+          const prefix = `${this.appName}-`;
+          const files = fs.readdirSync(this.logDir).filter((f) => f.startsWith(prefix) && f.endsWith(".log")).sort();
+          const excess = files.length - maxFiles;
+          if (excess <= 0) return;
+          for (let i = 0; i < excess; i++) {
+            try {
+              fs.unlinkSync(path.join(this.logDir, files[i]));
+            } catch {
+            }
+          }
+        } catch {
+        }
+      }
+    };
+    FileLogTransportInstance = __decorateClass([
+      FrontMcpLogTransport({
+        name: "FileLogger",
+        description: "Writes logs to a file for CLI mode diagnostics"
+      })
+    ], FileLogTransportInstance);
+  }
+});
+
 // libs/sdk/src/front-mcp/front-mcp.ts
 var front_mcp_exports = {};
 __export(front_mcp_exports, {
   FrontMcpInstance: () => FrontMcpInstance
 });
-import { randomUUID as randomUUID25, fileExists as fileExists5, unlink as unlink2 } from "@frontmcp/utils";
+import { randomUUID as randomUUID25, fileExists as fileExists7, unlink as unlink2 } from "@frontmcp/utils";
 var FrontMcpInstance;
 var init_front_mcp = __esm({
   "libs/sdk/src/front-mcp/front-mcp.ts"() {
@@ -45830,6 +46069,7 @@ var init_front_mcp = __esm({
     init_logger_registry();
     init_direct();
     init_errors();
+    init_instance_file_logger();
     init_health2();
     FrontMcpInstance = class _FrontMcpInstance2 {
       config;
@@ -45970,6 +46210,20 @@ var init_front_mcp = __esm({
       static async createForCli(options) {
         const parsedConfig = parseFrontMcpConfigLite(options);
         parsedConfig["__cliMode"] = true;
+        const verbose = process.env["FRONTMCP_CLI_VERBOSE"] === "1";
+        if (parsedConfig.logging) {
+          parsedConfig.logging.enableConsole = verbose;
+          const transports = parsedConfig.logging.transports ?? [];
+          if (!transports.includes(FileLogTransportInstance)) {
+            transports.push(FileLogTransportInstance);
+          }
+          parsedConfig.logging.transports = transports;
+        } else {
+          parsedConfig["logging"] = {
+            enableConsole: verbose,
+            transports: [FileLogTransportInstance]
+          };
+        }
         const frontMcp = new _FrontMcpInstance2(parsedConfig);
         await frontMcp.ready;
         return frontMcp;
@@ -46087,7 +46341,7 @@ var init_front_mcp = __esm({
         frontMcp.log?.info(`MCP server listening on unix://${socketPath}`);
         const cleanup = async () => {
           try {
-            if (await fileExists5(socketPath)) {
+            if (await fileExists7(socketPath)) {
               await unlink2(socketPath);
             }
           } catch {
@@ -47179,9 +47433,9 @@ var init_flow_entry = __esm({
       scope;
       constructor(scope, record, token, metadata) {
         super(record, token, metadata);
-        const { path, method } = record.metadata.middleware ?? metadata?.middleware ?? {};
+        const { path: path2, method } = record.metadata.middleware ?? metadata?.middleware ?? {};
         this.name = metadata?.name ?? record.metadata?.name;
-        this.path = path;
+        this.path = path2;
         this.method = method;
         this.scope = scope;
       }
@@ -47776,8 +48030,8 @@ var init_base_config_provider = __esm({
       getAll() {
         return this.config;
       }
-      get(path, defaultValue) {
-        const keys = path.split(".");
+      get(path2, defaultValue) {
+        const keys = path2.split(".");
         let result = this.config;
         for (const key of keys) {
           if (result && typeof result === "object" && key in result) {
@@ -47795,8 +48049,8 @@ var init_base_config_provider = __esm({
        * config.has('vm.preset') // returns true
        * config.has('nonexistent.path') // returns false
        */
-      has(path) {
-        const keys = path.split(".");
+      has(path2) {
+        const keys = path2.split(".");
         let result = this.config;
         for (const key of keys) {
           if (result && typeof result === "object" && key in result) {
@@ -47812,8 +48066,8 @@ var init_base_config_provider = __esm({
        * @example
        * config.getOrDefault('vm.timeout', 5000)
        */
-      getOrDefault(path, defaultValue) {
-        const value = this.get(path);
+      getOrDefault(path2, defaultValue) {
+        const value = this.get(path2);
         return value !== void 0 ? value : defaultValue;
       }
       /**
@@ -47822,10 +48076,10 @@ var init_base_config_provider = __esm({
        * config.getRequired('vm.preset')
        * config.getOrThrow('vm.preset')
        */
-      getRequired(path) {
-        const value = this.get(path);
+      getRequired(path2) {
+        const value = this.get(path2);
         if (value === void 0) {
-          throw new RequiredConfigUndefinedError(path);
+          throw new RequiredConfigUndefinedError(path2);
         }
         return value;
       }
@@ -47834,8 +48088,8 @@ var init_base_config_provider = __esm({
        * @example
        * config.getOrThrow('vm.preset')
        */
-      getOrThrow(path) {
-        return this.getRequired(path);
+      getOrThrow(path2) {
+        return this.getRequired(path2);
       }
       /**
        * Get a nested object at a path
@@ -47850,8 +48104,8 @@ var init_base_config_provider = __esm({
        * @example
        * config.matches('vm.preset', 'secure') // returns true/false
        */
-      matches(path, value) {
-        return this.get(path) === value;
+      matches(path2, value) {
+        return this.get(path2) === value;
       }
       /**
        * Get multiple values at once
@@ -47860,8 +48114,8 @@ var init_base_config_provider = __esm({
        */
       getMany(paths) {
         const result = {};
-        for (const path of paths) {
-          result[path] = this.get(path);
+        for (const path2 of paths) {
+          result[path2] = this.get(path2);
         }
         return result;
       }